Operator(bpy_struct)

Basic Operator Example

This script shows simple operator which prints a message.

Since the operator only has an Operator.execute function it takes no user input.

Note

Operator subclasses must be registered before accessing them from blender.

import bpy


class HelloWorldOperator(bpy.types.Operator):
    bl_idname = "wm.hello_world"
    bl_label = "Minimal Operator"

    def execute(self, context):
        print("Hello World")
        return {'FINISHED'}


bpy.utils.register_class(HelloWorldOperator)

# test call to the newly defined operator
bpy.ops.wm.hello_world()

Invoke Function

Operator.invoke is used to initialize the operator from the context at the moment the operator is called. invoke() is typically used to assign properties which are then used by execute(). Some operators don’t have an execute() function, removing the ability to be repeated from a script or macro.

This example shows how to define an operator which gets mouse input to execute a function and that this operator can be invoked or executed from the python api.

Also notice this operator defines its own properties, these are different to typical class properties because blender registers them with the operator, to use as arguments when called, saved for operator undo/redo and automatically added into the user interface.

import bpy


class SimpleMouseOperator(bpy.types.Operator):
    """ This operator shows the mouse location,
        this string is used for the tooltip and API docs
    """
    bl_idname = "wm.mouse_position"
    bl_label = "Invoke Mouse Operator"

    x: bpy.props.IntProperty()
    y: bpy.props.IntProperty()

    def execute(self, context):
        # rather than printing, use the report function,
        # this way the message appears in the header,
        self.report({'INFO'}, "Mouse coords are %d %d" % (self.x, self.y))
        return {'FINISHED'}

    def invoke(self, context, event):
        self.x = event.mouse_x
        self.y = event.mouse_y
        return self.execute(context)


bpy.utils.register_class(SimpleMouseOperator)

# Test call to the newly defined operator.
# Here we call the operator and invoke it, meaning that the settings are taken
# from the mouse.
bpy.ops.wm.mouse_position('INVOKE_DEFAULT')

# Another test call, this time call execute() directly with pre-defined settings.
bpy.ops.wm.mouse_position('EXEC_DEFAULT', x=20, y=66)

Calling a File Selector

This example shows how an operator can use the file selector.

Notice the invoke function calls a window manager method and returns {'RUNNING_MODAL'}, this means the file selector stays open and the operator does not exit immediately after invoke finishes.

The file selector runs the operator, calling Operator.execute when the user confirms.

The Operator.poll function is optional, used to check if the operator can run.

import bpy


class ExportSomeData(bpy.types.Operator):
    """Test exporter which just writes hello world"""
    bl_idname = "export.some_data"
    bl_label = "Export Some Data"

    filepath: bpy.props.StringProperty(subtype="FILE_PATH")

    @classmethod
    def poll(cls, context):
        return context.object is not None

    def execute(self, context):
        file = open(self.filepath, 'w')
        file.write("Hello World " + context.object.name)
        return {'FINISHED'}

    def invoke(self, context, event):
        context.window_manager.fileselect_add(self)
        return {'RUNNING_MODAL'}


# Only needed if you want to add into a dynamic menu
def menu_func(self, context):
    self.layout.operator_context = 'INVOKE_DEFAULT'
    self.layout.operator(ExportSomeData.bl_idname, text="Text Export Operator")


# Register and add to the file selector
bpy.utils.register_class(ExportSomeData)
bpy.types.TOPBAR_MT_file_export.append(menu_func)


# test call
bpy.ops.export.some_data('INVOKE_DEFAULT')

Dialog Box

This operator uses its Operator.invoke function to call a popup.

import bpy


class DialogOperator(bpy.types.Operator):
    bl_idname = "object.dialog_operator"
    bl_label = "Simple Dialog Operator"

    my_float: bpy.props.FloatProperty(name="Some Floating Point")
    my_bool: bpy.props.BoolProperty(name="Toggle Option")
    my_string: bpy.props.StringProperty(name="String Value")

    def execute(self, context):
        message = (
            "Popup Values: %f, %d, '%s'" %
            (self.my_float, self.my_bool, self.my_string)
        )
        self.report({'INFO'}, message)
        return {'FINISHED'}

    def invoke(self, context, event):
        wm = context.window_manager
        return wm.invoke_props_dialog(self)


bpy.utils.register_class(DialogOperator)

# Test call.
bpy.ops.object.dialog_operator('INVOKE_DEFAULT')

Custom Drawing

By default operator properties use an automatic user interface layout. If you need more control you can create your own layout with a Operator.draw function.

This works like the Panel and Menu draw functions, its used for dialogs and file selectors.

import bpy


class CustomDrawOperator(bpy.types.Operator):
    bl_idname = "object.custom_draw"
    bl_label = "Simple Modal Operator"

    filepath: bpy.props.StringProperty(subtype="FILE_PATH")

    my_float: bpy.props.FloatProperty(name="Float")
    my_bool: bpy.props.BoolProperty(name="Toggle Option")
    my_string: bpy.props.StringProperty(name="String Value")

    def execute(self, context):
        print("Test", self)
        return {'FINISHED'}

    def invoke(self, context, event):
        wm = context.window_manager
        return wm.invoke_props_dialog(self)

    def draw(self, context):
        layout = self.layout
        col = layout.column()
        col.label(text="Custom Interface!")

        row = col.row()
        row.prop(self, "my_float")
        row.prop(self, "my_bool")

        col.prop(self, "my_string")


bpy.utils.register_class(CustomDrawOperator)

# test call
bpy.ops.object.custom_draw('INVOKE_DEFAULT')

Modal Execution

This operator defines a Operator.modal function that will keep being run to handle events until it returns {'FINISHED'} or {'CANCELLED'}.

Modal operators run every time a new event is detected, such as a mouse click or key press. Conversely, when no new events are detected, the modal operator will not run. Modal operators are especially useful for interactive tools, an operator can have its own state where keys toggle options as the operator runs. Grab, Rotate, Scale, and Fly-Mode are examples of modal operators.

Operator.invoke is used to initialize the operator as being active by returning {'RUNNING_MODAL'}, initializing the modal loop.

Notice __init__() and __del__() are declared. For other operator types they are not useful but for modal operators they will be called before the Operator.invoke and after the operator finishes.

import bpy


class ModalOperator(bpy.types.Operator):
    bl_idname = "object.modal_operator"
    bl_label = "Simple Modal Operator"

    def __init__(self):
        print("Start")

    def __del__(self):
        print("End")

    def execute(self, context):
        context.object.location.x = self.value / 100.0
        return {'FINISHED'}

    def modal(self, context, event):
        if event.type == 'MOUSEMOVE':  # Apply
            self.value = event.mouse_x
            self.execute(context)
        elif event.type == 'LEFTMOUSE':  # Confirm
            return {'FINISHED'}
        elif event.type in {'RIGHTMOUSE', 'ESC'}:  # Cancel
            context.object.location.x = self.init_loc_x
            return {'CANCELLED'}

        return {'RUNNING_MODAL'}

    def invoke(self, context, event):
        self.init_loc_x = context.object.location.x
        self.value = event.mouse_x
        self.execute(context)

        context.window_manager.modal_handler_add(self)
        return {'RUNNING_MODAL'}


bpy.utils.register_class(ModalOperator)

# test call
bpy.ops.object.modal_operator('INVOKE_DEFAULT')

Enum Search Popup

You may want to have an operator prompt the user to select an item from a search field, this can be done using bpy.types.Operator.invoke_search_popup.

import bpy
from bpy.props import EnumProperty


class SearchEnumOperator(bpy.types.Operator):
    bl_idname = "object.search_enum_operator"
    bl_label = "Search Enum Operator"
    bl_property = "my_search"

    my_search: EnumProperty(
        name="My Search",
        items=(
            ('FOO', "Foo", ""),
            ('BAR', "Bar", ""),
            ('BAZ', "Baz", ""),
        ),
    )

    def execute(self, context):
        self.report({'INFO'}, "Selected:" + self.my_search)
        return {'FINISHED'}

    def invoke(self, context, event):
        context.window_manager.invoke_search_popup(self)
        return {'RUNNING_MODAL'}


bpy.utils.register_class(SearchEnumOperator)

# test call
bpy.ops.object.search_enum_operator('INVOKE_DEFAULT')

base class — bpy_struct

class bpy.types.Operator(bpy_struct)

Storage of an operator being executed, or registered after execution

bl_description

Type:string, default “”

bl_idname

Type:string, default “”, (never None)

bl_label

Type:string, default “”, (never None)

bl_options

Options for this operator type

• REGISTER Register, Display in the info window and support the redo toolbar panel.
• UNDO Undo, Push an undo event (needed for operator redo).
• UNDO_GROUPED Grouped Undo, Push a single undo event for repetead instances of this operator.
• BLOCKING Blocking, Block anything else from using the cursor.
• MACRO Macro, Use to check if an operator is a macro.
• GRAB_CURSOR Grab Pointer, Use so the operator grabs the mouse focus, enables wrapping when continuous grab is enabled.
• GRAB_CURSOR_X Grab Pointer X, Grab, only warping the X axis.
• GRAB_CURSOR_Y Grab Pointer Y, Grab, only warping the Y axis.
• PRESET Preset, Display a preset button with the operators settings.
• INTERNAL Internal, Removes the operator from search results.

Type:enum set in {‘REGISTER’, ‘UNDO’, ‘UNDO_GROUPED’, ‘BLOCKING’, ‘MACRO’, ‘GRAB_CURSOR’, ‘GRAB_CURSOR_X’, ‘GRAB_CURSOR_Y’, ‘PRESET’, ‘INTERNAL’}, default {‘REGISTER’}

bl_translation_context

Type:string, default “Operator”

bl_undo_group

Type:string, default “”

has_reports

Operator has a set of reports (warnings and errors) from last execution

Type:boolean, default False, (readonly)

layout

Type:UILayout, (readonly)

macros

Type:bpy_prop_collection of Macro, (readonly)

name

Type:string, default “”, (readonly, never None)

options

Runtime options

Type:OperatorOptions, (readonly, never None)

properties

Type:OperatorProperties, (readonly, never None)

bl_property

The name of a property to use as this operators primary property. Currently this is only used to select the default property when expanding an operator into a menu. :type: string

report(type, message)

report

Parameters:

• type (enum set in {'DEBUG', 'INFO', 'OPERATOR', 'PROPERTY', 'WARNING', 'ERROR', 'ERROR_INVALID_INPUT', 'ERROR_INVALID_CONTEXT', 'ERROR_OUT_OF_MEMORY'}) – Type
• message (string, (never None)) – Report Message

is_repeat()

is_repeat

Returns:result Return type:boolean

classmethod poll(context)

Test if the operator can be called or not

Return type:boolean

execute(context)

Execute the operator

Returns:result

• RUNNING_MODAL Running Modal, Keep the operator running with blender.
• CANCELLED Cancelled, The operator exited without doing anything, so no undo entry should be pushed.
• FINISHED Finished, The operator exited after completing its action.
• PASS_THROUGH Pass Through, Do nothing and pass the event on.
• INTERFACE Interface, Handled but not executed (popup menus).

Return type:enum set in {‘RUNNING_MODAL’, ‘CANCELLED’, ‘FINISHED’, ‘PASS_THROUGH’, ‘INTERFACE’}

check(context)

Check the operator settings, return True to signal a change to redraw

Returns:result Return type:boolean

invoke(context, event)

Invoke the operator

Returns:result

• RUNNING_MODAL Running Modal, Keep the operator running with blender.
• CANCELLED Cancelled, The operator exited without doing anything, so no undo entry should be pushed.
• FINISHED Finished, The operator exited after completing its action.
• PASS_THROUGH Pass Through, Do nothing and pass the event on.
• INTERFACE Interface, Handled but not executed (popup menus).

Return type:enum set in {‘RUNNING_MODAL’, ‘CANCELLED’, ‘FINISHED’, ‘PASS_THROUGH’, ‘INTERFACE’}

modal(context, event)

Modal operator function

Returns:result

• RUNNING_MODAL Running Modal, Keep the operator running with blender.
• CANCELLED Cancelled, The operator exited without doing anything, so no undo entry should be pushed.
• FINISHED Finished, The operator exited after completing its action.
• PASS_THROUGH Pass Through, Do nothing and pass the event on.
• INTERFACE Interface, Handled but not executed (popup menus).

Return type:enum set in {‘RUNNING_MODAL’, ‘CANCELLED’, ‘FINISHED’, ‘PASS_THROUGH’, ‘INTERFACE’}

draw(context)

Draw function for the operator

cancel(context)

Called when the operator is canceled

classmethod description(context, properties)

Compute a description string that depends on parameters

Returns:result Return type:string

as_keywords(ignore=())

Return a copy of the properties as a dictionary

classmethod bl_rna_get_subclass(id, default=None)

Parameters:id (string) – The RNA type identifier. Returns:The RNA type or default when not found. Return type:bpy.types.Struct subclass

classmethod bl_rna_get_subclass_py(id, default=None)

Parameters:id (string) – The RNA type identifier. Returns:The class or default when not found. Return type:type

Inherited Properties

bpy_struct.id_data

Inherited Functions

bpy_struct.as_pointer bpy_struct.driver_add bpy_struct.driver_remove bpy_struct.get bpy_struct.is_property_hidden bpy_struct.is_property_overridable_library bpy_struct.is_property_readonly bpy_struct.is_property_set bpy_struct.items bpy_struct.keyframe_delete

bpy_struct.keyframe_insert bpy_struct.keys bpy_struct.path_from_id bpy_struct.path_resolve bpy_struct.pop bpy_struct.property_overridable_library_set bpy_struct.property_unset bpy_struct.type_recast bpy_struct.values

References

bpy.context.active_operator SpaceFileBrowser.active_operator SpaceFileBrowser.operator WindowManager.fileselect_add WindowManager.invoke_confirm WindowManager.invoke_popup

WindowManager.invoke_props_dialog WindowManager.invoke_props_popup WindowManager.invoke_search_popup WindowManager.modal_handler_add WindowManager.operators