diff options
author | Julian Eisel <julian@blender.org> | 2022-09-01 16:01:51 +0300 |
---|---|---|
committer | Julian Eisel <julian@blender.org> | 2022-09-01 16:03:51 +0300 |
commit | 00d2bda2418b3ac4ae66c716d01ead4562615f1c (patch) | |
tree | 439e228e73049fd555c8c89e8ac2a65490c150af /doc | |
parent | 06d2dc6be2834b80af26a59783222b565a6ca8b8 (diff) |
Py Docs: Document delayed setting of UI data
Blender may not apply certain UI data changes immediately when done via BPY.
This is a rather typical gotcha, better to have it documented.
Reviewed By: campbellbarton
Differential Revision: https://developer.blender.org/D15614
Diffstat (limited to 'doc')
-rw-r--r-- | doc/python_api/examples/bpy.types.Operator.5.py | 2 | ||||
-rw-r--r-- | doc/python_api/rst/info_gotcha.rst | 32 |
2 files changed, 33 insertions, 1 deletions
diff --git a/doc/python_api/examples/bpy.types.Operator.5.py b/doc/python_api/examples/bpy.types.Operator.5.py index 90c899f222e..0b6035fc3da 100644 --- a/doc/python_api/examples/bpy.types.Operator.5.py +++ b/doc/python_api/examples/bpy.types.Operator.5.py @@ -1,4 +1,6 @@ """ +.. _modal_operator: + Modal Execution +++++++++++++++ diff --git a/doc/python_api/rst/info_gotcha.rst b/doc/python_api/rst/info_gotcha.rst index d3067eb0518..2dd6c3c92b1 100644 --- a/doc/python_api/rst/info_gotcha.rst +++ b/doc/python_api/rst/info_gotcha.rst @@ -86,7 +86,8 @@ No updates after setting values Sometimes you want to modify values from Python and immediately access the updated values, e.g: Once changing the objects :class:`bpy.types.Object.location` you may want to access its transformation right after from :class:`bpy.types.Object.matrix_world`, -but this doesn't work as you might expect. +but this doesn't work as you might expect. There are similar issues with changes to the UI, that +are covered in the next section. Consider the calculations that might contribute to the object's final transformation, this includes: @@ -110,6 +111,35 @@ Now all dependent data (child objects, modifiers, drivers, etc.) have been recalculated and are available to the script within the active view layer. +No updates after changing UI context +------------------------------------ + +Similar to the previous issue, some changes to the UI may also not have an immediate effect. For example, setting +:class:`bpy.types.Window.workspace` doesn't seem to cause an observable effect in the immediately following code +(:class:`bpy.types.Window.workspace` is still the same), but the UI will in fact reflect the change. Some of the +properties that behave that way are: + +- :class:`bpy.types.Window.workspace` +- :class:`bpy.types.Window.screen` +- :class:`bpy.types.Window.scene` +- :class:`bpy.types.Area.type` +- :class:`bpy.types.Area.uitype` + +Such changes impact the UI, and with that the context (:class:`bpy.context`) quite drastically. This can break +Blender's context management. So Blender delays this change until after operators have run and just before the UI is +redrawn, making sure that context can be changed safely. + +If you rely on executing code with an updated context this can be worked around by executing the code in a delayed +fashion as well. Possible options include: + + - :ref:`Modal Operator <modal_operator>`. + - :class:`bpy.app.handlers`. + - :class:`bpy.app.timer`. + +It's also possible to depend on drawing callbacks although these should generally be avoided as failure to draw a +hidden panel, region, cursor, etc. could cause your script to be unreliable + + Can I redraw during script execution? ------------------------------------- |