From f438344cf243632e497772cf1f855b9c8856fd37 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Wed, 13 Apr 2022 16:40:07 +1000 Subject: PyAPI: temporary context override support Support a way to temporarily override the context from Python. - Added method `Context.temp_override` context manager. - Special support for windowing variables "window", "area" and "region", other context members such as "active_object". - Nesting context overrides is supported. - Previous windowing members are restored when the context exists unless they have been removed. - Overriding context members by passing a dictionary into operators in `bpy.ops` has been deprecated and warns when used. This allows the window in a newly loaded file to be used, see: T92464 Reviewed by: mont29 Ref D13126 --- .../examples/bpy.types.Context.temp_override.1.py | 19 +++++++++++++++++++ .../examples/bpy.types.Context.temp_override.2.py | 15 +++++++++++++++ .../examples/bpy.types.Context.temp_override.3.py | 16 ++++++++++++++++ 3 files changed, 50 insertions(+) create mode 100644 doc/python_api/examples/bpy.types.Context.temp_override.1.py create mode 100644 doc/python_api/examples/bpy.types.Context.temp_override.2.py create mode 100644 doc/python_api/examples/bpy.types.Context.temp_override.3.py (limited to 'doc/python_api') diff --git a/doc/python_api/examples/bpy.types.Context.temp_override.1.py b/doc/python_api/examples/bpy.types.Context.temp_override.1.py new file mode 100644 index 00000000000..68f0eef93c3 --- /dev/null +++ b/doc/python_api/examples/bpy.types.Context.temp_override.1.py @@ -0,0 +1,19 @@ +""" +Overriding the context can be used to temporarily activate another ``window`` / ``area`` & ``region``, +as well as other members such as the ``active_object`` or ``bone``. + +Notes: + +- When overriding window, area and regions: the arguments must be consistent, + so any region argument that's passed in must be contained by the current area or the area passed in. + The same goes for the area needing to be contained in the current window. + +- Temporary context overrides may be nested, when this is done, members will be added to the existing overrides. + +- Context members are restored outside the scope of the context. + The only exception to this is when the data is no longer available. + + In the event windowing data was removed (for example), the state of the context is left as-is. + While this isn't likely to happen, explicit window operation such as closing windows or loading a new file + remove the windowing data that was set before the temporary context was created. +""" diff --git a/doc/python_api/examples/bpy.types.Context.temp_override.2.py b/doc/python_api/examples/bpy.types.Context.temp_override.2.py new file mode 100644 index 00000000000..ce3e1594baa --- /dev/null +++ b/doc/python_api/examples/bpy.types.Context.temp_override.2.py @@ -0,0 +1,15 @@ +""" +Overriding the context can be useful to set the context after loading files +(which would otherwise by None). For example: +""" + +import bpy +from bpy import context + +# Reload the current file and select all. +bpy.ops.wm.open_mainfile(filepath=bpy.data.filepath) +window = context.window_manager.windows[0] +with context.temp_override(window=window): + bpy.ops.mesh.primitive_uv_sphere_add() + # The context override is needed so it's possible to set edit-mode. + bpy.ops.object.mode_set(mode='EDIT') diff --git a/doc/python_api/examples/bpy.types.Context.temp_override.3.py b/doc/python_api/examples/bpy.types.Context.temp_override.3.py new file mode 100644 index 00000000000..e670bb7bafa --- /dev/null +++ b/doc/python_api/examples/bpy.types.Context.temp_override.3.py @@ -0,0 +1,16 @@ +""" +This example shows how it's possible to add an object to the scene in another window. +""" +import bpy +from bpy import context + +win_active = context.window +win_other = None +for win_iter in context.window_manager.windows: + if win_iter != win_active: + win_other = win_iter + break + +# Add cube in the other window. +with context.temp_override(window=win_other): + bpy.ops.mesh.primitive_cube_add() -- cgit v1.2.3