From 7be5ca63aee8de3cfeabdb9bdd8bb5613defd824 Mon Sep 17 00:00:00 2001 From: Alexander Gavrilov Date: Mon, 26 Dec 2022 14:42:01 +0200 Subject: [PATCH] Python API Docs: explain the CANCELLED return code of operators. The effect of CANCELLED on the undo stack is quite obscure, and mistakenly using it after doing some changes causes confusing behavior. It's better to describe it explicitly in the docs. --- doc/python_api/examples/bpy.ops.py | 5 +++-- doc/python_api/examples/bpy.types.Operator.5.py | 1 + doc/python_api/examples/bpy.types.Operator.py | 7 +++++++ 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/python_api/examples/bpy.ops.py b/doc/python_api/examples/bpy.ops.py index e8d545fc855..aa51c6c5162 100644 --- a/doc/python_api/examples/bpy.ops.py +++ b/doc/python_api/examples/bpy.ops.py @@ -10,8 +10,9 @@ Only keyword arguments can be used to pass operator properties. Operators don't have return values as you might expect, instead they return a set() which is made up of: ``{'RUNNING_MODAL', 'CANCELLED', 'FINISHED', 'PASS_THROUGH'}``. -Common return values are ``{'FINISHED'}`` and ``{'CANCELLED'}``. - +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. 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.Operator.5.py b/doc/python_api/examples/bpy.types.Operator.5.py index 0b6035fc3da..6f912f863f1 100644 --- a/doc/python_api/examples/bpy.types.Operator.5.py +++ b/doc/python_api/examples/bpy.types.Operator.5.py @@ -44,6 +44,7 @@ class ModalOperator(bpy.types.Operator): elif event.type == 'LEFTMOUSE': # Confirm return {'FINISHED'} elif event.type in {'RIGHTMOUSE', 'ESC'}: # Cancel + # Revert all changes that have been made context.object.location.x = self.init_loc_x return {'CANCELLED'} diff --git a/doc/python_api/examples/bpy.types.Operator.py b/doc/python_api/examples/bpy.types.Operator.py index 41b96ac402f..19cd08b018f 100644 --- a/doc/python_api/examples/bpy.types.Operator.py +++ b/doc/python_api/examples/bpy.types.Operator.py @@ -7,9 +7,16 @@ This script shows simple operator which prints a message. Since the operator only has an :class:`Operator.execute` function it takes no user input. +The function should return ``{'FINISHED'}`` or ``{'CANCELLED'}``, the latter +meaning that operator execution was aborted without making any changes, and +saving an undo entry isn't neccesary. If an error is detected after some changes +have already been made, use the ``{'FINISHED'}`` return code, or the behavior +of undo will be confusing for the user. + .. note:: Operator subclasses must be registered before accessing them from blender. + """ import bpy