[Bf-blender-cvs] [00d2bda2418] master: Py Docs: Document delayed setting of UI data

[Julian Eisel]

Commit: 00d2bda2418b3ac4ae66c716d01ead4562615f1c
Author: Julian Eisel
Date:   Thu Sep 1 15:01:51 2022 +0200
Branches: master
https://developer.blender.org/rB00d2bda2418b3ac4ae66c716d01ead4562615f1c

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

===================================================================

M	doc/python_api/examples/bpy.types.Operator.5.py
M	doc/python_api/rst/info_gotcha.rst

===================================================================

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?
 -------------------------------------