diff --git a/doc/python_api/examples/bpy.ops.py b/doc/python_api/examples/bpy.ops.py index c4b04936c87..77fac36aa0c 100644 --- a/doc/python_api/examples/bpy.ops.py +++ b/doc/python_api/examples/bpy.ops.py @@ -14,6 +14,10 @@ Common return values are ``{'FINISHED'}`` and ``{'CANCELLED'}``, the latter meaning that the operator execution was aborted without making any changes or saving an undo history entry. +If operator was cancelled but there wasn't any reports from it with ``{'ERROR'}`` type, +it will just return ``{'CANCELLED'}`` without raising any exceptions. +If it had error reports, then it will raise a ``RuntimeError`` including all report messages. + Calling an operator in the wrong context will raise a ``RuntimeError``, there is a poll() method to avoid this problem. diff --git a/doc/python_api/examples/bpy.types.Menu.py b/doc/python_api/examples/bpy.types.Menu.py index 295c108abe3..c1a5b3581e4 100644 --- a/doc/python_api/examples/bpy.types.Menu.py +++ b/doc/python_api/examples/bpy.types.Menu.py @@ -14,10 +14,12 @@ convention for menus. .. note:: - Menus have their :class:`Layout.operator_context` initialized as - 'EXEC_REGION_WIN' rather than 'INVOKE_DEFAULT' (see :ref:`Execution Context `). + Menus have their :class:`UILayout.operator_context` initialized as + 'EXEC_REGION_WIN' rather than 'INVOKE_REGION_WIN' (see :ref:`Execution Context `). If the operator context needs to initialize inputs from the :class:`Operator.invoke` function, then this needs to be explicitly set. + When a menu is added to UI elements such as a panel or header, + the operator execution context will be inherited from them. """ import bpy diff --git a/doc/python_api/examples/bpy.types.Operator.2.py b/doc/python_api/examples/bpy.types.Operator.2.py index dbdf009a3be..f1a5fe27777 100644 --- a/doc/python_api/examples/bpy.types.Operator.2.py +++ b/doc/python_api/examples/bpy.types.Operator.2.py @@ -9,6 +9,13 @@ execute(). Some operators don't have an execute() function, removing the ability to be repeated from a script or macro. +When an operator is called via :mod:`bpy.ops`, the execution context depends +on the argument provided to :mod:`bpy.ops`. By default, it uses execute(). +When an operator is activated from a button or menu item, it follows +the setting in :class:`UILayout.operator_context`. In most cases, invoke() is used. +Running an operator via a key shortcut always uses invoke(), +and this behavior cannot be changed. + 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. diff --git a/source/blender/makesrna/intern/rna_ui.cc b/source/blender/makesrna/intern/rna_ui.cc index 0ef301ee6a6..6b666e12e30 100644 --- a/source/blender/makesrna/intern/rna_ui.cc +++ b/source/blender/makesrna/intern/rna_ui.cc @@ -1706,6 +1706,10 @@ static void rna_def_ui_layout(BlenderRNA *brna) RNA_def_property_enum_items(prop, rna_enum_operator_context_items); RNA_def_property_enum_funcs( prop, "rna_UILayout_op_context_get", "rna_UILayout_op_context_set", nullptr); + RNA_def_property_ui_text(prop, + "Operator Context", + "Typically set to 'INVOKE_REGION_WIN', except some cases " + "in :class:`bpy.types.Menu` when it's set to 'EXEC_REGION_WIN'."); prop = RNA_def_property(srna, "enabled", PROP_BOOLEAN, PROP_NONE); RNA_def_property_boolean_funcs(prop, "rna_UILayout_enabled_get", "rna_UILayout_enabled_set");