# 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.INFO_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 which running, handling events until it returns `{'FINISHED'}` or `{'CANCELLED'}`.

Grab, Rotate, Scale and Fly-Mode are examples of modal operators. They are especially useful for interactive tools, your operator can have its own state where keys toggle options as the operator runs.

`Operator.invoke` is used to initialize the operator as being 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')

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).
    - `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.
    - `PRESET` Preset, Display a preset button with the operators settings.
    - `INTERNAL` Internal, Removes the operator from search results.

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

  `bl_translation_context`

    Type: | string, default “Operator”

  `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

  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, When no action has been taken, operator exits. `FINISHED` Finished, When the operator is complete, operator exits. `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, When no action has been taken, operator exits. `FINISHED` Finished, When the operator is complete, operator exits. `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, When no action has been taken, operator exits. `FINISHED` Finished, When the operator is complete, operator exits. `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

  `as_keywords`(ignore=())

    Return a copy of the properties as a dictionary

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_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.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`