Prologue

Now that we’ve covered the basics of writing a working addon and making it installable, let’s add some refinements to its functionality.

To start with, users normally add new objects via the Add menu which pops up when pressing  SHIFT + A , rather than via a custom panel. Can our script add a new “Tetrahedron” item to that menu? Yes it can.

Also, our script currently requires us to adjust its setting (the “Upside-Down” checkbox) before it performs its action. In user-interface parlance, this is the ordering “Object→Setting→Action”: select an object, specify the settings for the action, then perform the action. Whereas the preferred order in Blender 2.5x is “Object→Action→Setting”: which means the action is performed with some initial settings, which the user is then free to modify while observing their effect. This gives a much smoother workflow, rather than the user having to guess what the effects will be before applying them, and then undoing and trying again if they guessed wrong.

(Of course, since our example script creates a new object rather than modifying an existing one, the initial “Object” step is not relevant here. But it is to other operators.)

So the modifications we need to make to our script are:

• Get rid of the existing Panel subclass.
• Our register function will add a new entry to the Add menu (specifically, the mesh-add submenu) to invoke our Operator subclass.
• When our operator is invoked, a panel will appear, with all the settings controls we previously had, except for the “Add” button. The user can play with these settings, and observe the effect on the newly-created object immediately.

The nice thing is, Blender does most of the hard work for us, so we only need to edit a few lines of code to achieve all the above!

Adding To The Add Menu

This needs to be done in two steps. First we need a function which will be invoked when Blender creates its Add menu: this will add an entry that invokes our custom operator by its name. Specifically, we will add our custom item to the “Mesh” submenu of the “Add” menu. We can also assign an icon to the menu item; here I’m using the generic plugin icon:

def add_to_menu(self, context) :
    self.layout.operator("mesh.make_tetrahedron", icon = "PLUGIN")
#end add_to_menu

# version 2.72b only allows for the icon value from the set:
# ("NONE", "QUESTION", "ERROR", "CANCEL", "TRIA_RIGHT", "TRIA_DOWN", 
#  "TRIA_LEFT", "TRIA_UP", "ARROW_LEFTRIGHT", "PLUS", "DISCLOSURE_TRI_DOWN", 
#  "DISCLOSURE_TRI_RIGHT", "RADIOBUT_OFF", "RADIOBUT_ON", "MENU")

Having done that, we change our register function to add our add_to_menu item to a list that Blender uses to create its Add→Mesh menu:

def register() :
    bpy.utils.register_class(MakeTetrahedron)
    bpy.types.INFO_MT_mesh_add.append(add_to_menu)
#end register

Note this bpy.types.INFO_MT_mesh_add object is not currently mentioned in the API documentation; I found it by examining the scripts that come bundled with Blender.

And of course we should clean up ourselves, so the unregister function needs to remove the item we added:

def unregister() :
    bpy.utils.unregister_class(MakeTetrahedron)
    bpy.types.INFO_MT_mesh_add.remove(add_to_menu)
#end unregister

Fixing Up The UI

Note that previously, our register and unregister functions were attaching a custom property to Blender’s Scene class to hold our setting value. That code is now gone, but we still need the property. Instead, it will now be attached directly to our MakeTetrahedron class.

Also, remember we said we were getting rid of the TetrahedronMakerPanel class? In fact we keep the draw method from that, and move it to our MakeTetrahedron operator, only getting rid of the last button in the panel for invoking the operator. This is because by the time the panel is being drawn, the operator has already been invoked.

We also need to tell Blender that we are conforming to the Object→Action→Settings convention, by adding the "REGISTER" item to our bl_options.

So the header of our operator class now looks like this:

class MakeTetrahedron(bpy.types.Operator) :
    bl_idname = "mesh.make_tetrahedron"
    bl_label = "Tetrahedron"
    bl_options = {"REGISTER", "UNDO"}

    inverted = bpy.props.BoolProperty \
      (
        name = "Upside Down",
        description = "Generate the tetrahedron upside down",
        default = False
      )

    def draw(self, context) :
        TheCol = self.layout.column(align = True)
        TheCol.prop(self, "inverted")
    #end draw

Previously our custom property was called make_tetrahedron_inverted, but here I just call it inverted, because after all it is being attached to our own class, so there should be no worry about name clashes.

Note that I also changed the bl_label text, taking out the word “Add”. This is redundant, because our label will be appearing in a menu that is already titled “Add”.

invoke Versus execute

The last thing to do is rearrange the code for actually creating the tetrahedron object. Previously we had it in a method called invoke, and that method will still be called when our operator is selected from the Add→Mesh menu. Then our draw method will be called, so our panel will also appear. But then, if the user makes adjustments to the controls in our panel, Blender will invoke a different operator method, called execute.

To the user, it looks like they are making adjustments to an already-created object. But in fact our execute method can do exactly the same thing as invoke, namely create a new object every time it’s called! Blender will take care of getting rid of previously-created objects, so the user won’t know the difference.

Nice, isn’t it? But in order for this to work, our code needs to do one thing more: ensure that our newly-created object is the only selected, active object. So the following is added after NewObj has been created and linked into the scene:

        bpy.ops.object.select_all(action = "DESELECT")
        NewObj.select = True
        context.scene.objects.active = NewObj

Put It All Together

Note that the object-creation code has been moved into a common routine that I have called action_common. This can then be called from both the invoke and execute methods.

import math
import bpy
import mathutils

class MakeTetrahedron(bpy.types.Operator) :
    bl_idname = "mesh.make_tetrahedron"
    bl_label = "Tetrahedron"
    bl_options = {"REGISTER", "UNDO"}

    inverted = bpy.props.BoolProperty \
      (
        name = "Upside Down",
        description = "Generate the tetrahedron upside down",
        default = False
      )

    def draw(self, context) :
        TheCol = self.layout.column(align = True)
        TheCol.prop(self, "inverted")
    #end draw

    def action_common(self, context) :
        Scale = -1 if self.inverted else 1
        Vertices = \
          [
            mathutils.Vector((0, -1 / math.sqrt(3),0)),
            mathutils.Vector((0.5, 1 / (2 * math.sqrt(3)), 0)),
            mathutils.Vector((-0.5, 1 / (2 * math.sqrt(3)), 0)),
            mathutils.Vector((0, 0, Scale * math.sqrt(2 / 3))),
          ]
        NewMesh = bpy.data.meshes.new("Tetrahedron")
        NewMesh.from_pydata \
          (
            Vertices,
            [],
            [[0, 1, 2], [0, 1, 3], [1, 2, 3], [2, 0, 3]]
          )
        NewMesh.update()
        NewObj = bpy.data.objects.new("Tetrahedron", NewMesh)
        context.scene.objects.link(NewObj)
        bpy.ops.object.select_all(action = "DESELECT")
        NewObj.select = True
        context.scene.objects.active = NewObj
    #end action_common

    def execute(self, context) :
        self.action_common(context)
        return {"FINISHED"}
    #end execute

    def invoke(self, context, event) :
        self.action_common(context)
        return {"FINISHED"}
    #end invoke

#end MakeTetrahedron

def add_to_menu(self, context) :
    self.layout.operator("mesh.make_tetrahedron", icon = "PLUGIN")
#end add_to_menu

def register() :
    bpy.utils.register_class(MakeTetrahedron)
    bpy.types.INFO_MT_mesh_add.append(add_to_menu)
#end register

def unregister() :
    bpy.utils.unregister_class(MakeTetrahedron)
    bpy.types.INFO_MT_mesh_add.remove(add_to_menu)
#end unregister

if __name__ == "__main__" :
    register()
#end if

Undocumented Blender

That INFO_MT_mesh_add object is one of a bunch of undocumented things lurking in the bpy.types module. They all have names of the form prefix_type_restofname, where prefix is an all-uppercase mnemonic for the category of object (mostly a window type, e.g. INFO for the Info window, which is where the main menu bar appears, though there are also names for major object categories like MESH and LAMP), and type indicates the class of object: HT for a window header UI object (bpy.types.Header), MT for a menu (bpy.types.Menu), OT for an operator, and PT for a panel (bpy.types.Panel). The OT ones seem to correspond directly to objects in bpy.ops, but at a lower level; it’s probably easier just to use the official bpy.ops objects. As for the HT, MT and PT objects, these all have append, prepend and remove methods that you can use to customize them: append adds a widget at the end (right or bottom), while prepend puts it at the front (left or top).

Since they aren’t (yet) mentioned in the official Blender documentation, here is a list of all the ones I’ve been able to find: