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'}
# Only needed if you want to add into a dynamic menu
def menu_func(self, context):
self.layout.operator(HelloWorldOperator.bl_idname, text="Hello World Operator")
# Register and add to the view menu (required to also use F3 search "Hello World Operator" for quick access)
bpy.utils.register_class(HelloWorldOperator)
bpy.types.VIEW3D_MT_view.append(menu_func)
# 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)
# Only needed if you want to add into a dynamic menu
def menu_func(self, context):
self.layout.operator(SimpleMouseOperator.bl_idname, text="Simple Mouse Operator")
# Register and add to the view menu (required to also use F3 search "Simple Mouse Operator" for quick access)
bpy.utils.register_class(SimpleMouseOperator)
bpy.types.VIEW3D_MT_view.append(menu_func)
# 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 (required to also use F3 search "Text Export Operator" for quick access)
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)
# Only needed if you want to add into a dynamic menu
def menu_func(self, context):
self.layout.operator(DialogOperator.bl_idname, text="Dialog Operator")
# Register and add to the object menu (required to also use F3 search "Dialog Operator" for quick access)
bpy.utils.register_class(DialogOperator)
bpy.types.VIEW3D_MT_object.append(menu_func)
# 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")
# Only needed if you want to add into a dynamic menu
def menu_func(self, context):
self.layout.operator(CustomDrawOperator.bl_idname, text="Custom Draw Operator")
# Register and add to the object menu (required to also use F3 search "Custom Draw Operator" for quick access)
bpy.utils.register_class(CustomDrawOperator)
bpy.types.VIEW3D_MT_object.append(menu_func)
# 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'}
# Only needed if you want to add into a dynamic menu
def menu_func(self, context):
self.layout.operator(ModalOperator.bl_idname, text="Modal Operator")
# Register and add to the object menu (required to also use F3 search "Modal Operator" for quick access)
bpy.utils.register_class(ModalOperator)
bpy.types.VIEW3D_MT_object.append(menu_func)
# 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'}
# Only needed if you want to add into a dynamic menu
def menu_func(self, context):
self.layout.operator(SearchEnumOperator.bl_idname, text="Search Enum Operator")
# Register and add to the object menu (required to also use F3 search "Search Enum Operator" for quick access)
bpy.utils.register_class(SearchEnumOperator)
bpy.types.VIEW3D_MT_object.append(menu_func)
# 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_cursor_pending
Cursor to use when waiting for the user to select a location to activate the operator (when
bl_options
hasDEPENDS_ON_CURSOR
set)- Type
enum in [‘DEFAULT’, ‘NONE’, ‘WAIT’, ‘CROSSHAIR’, ‘MOVE_X’, ‘MOVE_Y’, ‘KNIFE’, ‘TEXT’, ‘PAINT_BRUSH’, ‘PAINT_CROSS’, ‘DOT’, ‘ERASER’, ‘HAND’, ‘SCROLL_X’, ‘SCROLL_Y’, ‘SCROLL_XY’, ‘EYEDROPPER’, ‘PICK_AREA’, ‘STOP’, ‘COPY’, ‘CROSS’, ‘MUTE’, ‘ZOOM_IN’, ‘ZOOM_OUT’], default ‘DEFAULT’
- bl_description
- Type
string, default “”, (never None)
- 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 repeated 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.DEPENDS_ON_CURSOR
Depends on Cursor – The initial cursor location is used, when running from a menus or buttons the user is prompted to place the cursor before beginning the operation.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’, ‘DEPENDS_ON_CURSOR’, ‘PRESET’, ‘INTERNAL’}, default {‘REGISTER’}
- bl_translation_context
- Type
string, default “Operator”, (never None)
- bl_undo_group
- Type
string, default “”, (never None)
- has_reports
Operator has a set of reports (warnings and errors) from last execution
- Type
boolean, default False, (readonly)
- macros
- Type
bpy_prop_collection
ofMacro
, (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
- poll_message_set(message, *args)
Set the message to show in the tool-tip when poll fails.
When message is callable, additional user defined positional arguments are passed to the message function.
- Parameters
message (string or a callable that returns a string or None.) – The message or a function that returns the message.
Inherited Properties
Inherited Functions
References