Blender 3D: Noob to Pro/Advanced Tutorials/Blender Scripting/A User Interface For Your Addon

From Wikibooks, open books for an open world
Jump to navigation Jump to search

Start[edit | edit source]

So you’ve defined a new operator in your addon. Now it would be nice to give that addon a proper interface, so the user doesn’t have to hunt through the spacebar menu to find that operator.

The nicest way to do this is to define a panel that shows up in a window somewhere, with controls in it that the user can click on to operate your addon. You can put the panel in all kinds of places, but here we will insert it in the Tool Shelf (which can be hidden or shown on the left side of the 3D View by pressing  T .

Your First Panel[edit | edit source]

A panel is defined by subclassing the bpy.types.Panel class. You set the value of various attributes (bl_space_type, bl_region_type, bl_category and bl_context) to determine the context in which the panel will appear, and also give a title to the panel (bl_label):

class TetrahedronMakerPanel(bpy.types.Panel):
    bl_space_type = "VIEW_3D"
    bl_region_type = "TOOLS"
    bl_context = "objectmode"
    bl_category = "Create"
    bl_label = "Add Tetrahedron"

Those first three attributes cause the panel to appear in the Tool Shelf, but only while the 3D View is in Object mode.The bl_category line determines the toolbar tab the addon is placed in, and only applies to the toolbars with tabs (added 2.7). Specify any existing tab, or define a new one.

Your class also needs to define a draw method, which defines the items that go into the panel. This example creates a new column of UI elements for the panel, and inserts a single UI element which is a button that will invoke the operator with the name you previously defined when clicked:

    def draw(self, context):
        TheCol = self.layout.column(align=True)
        TheCol.operator("mesh.make_tetrahedron", text="Add Tetrahedron")
    #end draw

Adding Undo Support[edit | edit source]

While we’re at it, go back and add the following line to the operator definition:

    bl_options = {"UNDO"}

This allows the user to undo the addition of the tetrahedron in the usual way with  CTRL + Z , and redo it with  CTRL + SHIFT + Z .

Put It All Together[edit | edit source]

Here is the complete script for the addon as it stands now:

import math
import bpy
import mathutils

class TetrahedronMakerPanel(bpy.types.Panel):
    bl_space_type = "VIEW_3D"
    bl_region_type = "TOOLS"
    bl_context = "objectmode"
    bl_category = "Create"
    bl_label = "Add Tetrahedron"

    def draw(self, context):
        TheCol = self.layout.column(align=True)
        TheCol.operator("mesh.make_tetrahedron", text="Add Tetrahedron")
    #end draw

#end TetrahedronMakerPanel

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

    def invoke(self, context, event):
        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, math.sqrt(2 / 3))),
          ]
        NewMesh = bpy.data.meshes.new("Tetrahedron")
        NewMesh.from_pydata \
          (
            Vertices,
            [],
            [[0, 2, 1], [0, 1, 3], [1, 2, 3], [2, 0, 3]]
          )
        NewMesh.update()
        NewObj = bpy.data.objects.new("Tetrahedron", NewMesh)
        context.scene.objects.link(NewObj)
        return {"FINISHED"}
    #end invoke

#end MakeTetrahedron

bpy.utils.register_class(MakeTetrahedron)
bpy.utils.register_class(TetrahedronMakerPanel)

Note the addition of another register_class call for our custom panel.

As before, hit  ALT + P  to execute it. Nothing should appear to happen; Blender processes your subclass definitions, and registers them for use, as requested, in the appropriate places.

But now, go back to the 3D View. Make sure you are in Object mode. Bring up the Tool Shelf if it isn’t visible, by pressing  T . At the bottom; in the tab you have specified, you should see your new panel appear:

Note the triangle next to the title that Blender automatically gives you, to collapse or expand the panel without any extra work on your part. Get rid of any tetrahedron object that might have been created by following the tutorial on the previous page; now click your new “Add Tetrahedron” button, and watch the object be created again!

Space Types, Region Types, Contexts, Oh My![edit | edit source]

Those values for bl_space_type, bl_region_type and bl_context are (partially) listed here in the Blender API documentation, but not fully explained. Here’s a list of permissible values for each that I found from looking at source code:

Attribute Permissible Values Source Reference
bl_space_type "EMPTY", "VIEW_3D", "TIMELINE", "GRAPH_EDITOR", "DOPESHEET_EDITOR", "NLA_EDITOR", "IMAGE_EDITOR", "SEQUENCE_EDITOR", "CLIP_EDITOR", "TEXT_EDITOR", "NODE_EDITOR", "LOGIC_EDITOR", "PROPERTIES", "OUTLINER", "USER_PREFERENCES", "INFO", "FILE_BROWSER", "CONSOLE" space_type_items in rna_space.c
bl_region_type "WINDOW", "HEADER", "CHANNELS", "TEMPORARY", "UI", "TOOLS", "TOOL_PROPS", "PREVIEW" region_type_items in rna_screen.c
bl_context "mesh_edit", "curve_edit", "surface_edit", "text_edit", "armature_edit", "mball_edit", "lattice_edit", "posemode", "sculpt_mode", "weightpaint", "vertexpaint", "imagepaint", "particlemode", "objectmode" data_mode_strings in context.c

Presumably, not all combinations will make sense.