diff options
author | Sybren A. Stüvel <sybren@blender.org> | 2020-03-06 16:28:54 +0300 |
---|---|---|
committer | Sybren A. Stüvel <sybren@blender.org> | 2020-03-06 16:29:03 +0300 |
commit | 2d5773d11a0698f1cf421d7fc7c7d823be601124 (patch) | |
tree | 10bbb31759a15292875794d47b271d5e2a56c274 /doc/python_api/examples | |
parent | 07c5ca7f2cfc1e9bd898d88f7ed84d24cfc105c2 (diff) |
Documentation: added bpy.msgbus description and examples
The `bpy.msgbus` namespace was not included in the documentation generation.
I've added it, and ported Campbell's examples from P563.
Diffstat (limited to 'doc/python_api/examples')
-rw-r--r-- | doc/python_api/examples/bpy.msgbus.1.py | 44 | ||||
-rw-r--r-- | doc/python_api/examples/bpy.msgbus.2.py | 6 | ||||
-rw-r--r-- | doc/python_api/examples/bpy.msgbus.3.py | 5 |
3 files changed, 55 insertions, 0 deletions
diff --git a/doc/python_api/examples/bpy.msgbus.1.py b/doc/python_api/examples/bpy.msgbus.1.py new file mode 100644 index 00000000000..21198471ffa --- /dev/null +++ b/doc/python_api/examples/bpy.msgbus.1.py @@ -0,0 +1,44 @@ +""" +The message bus system can be used to receive notifications when properties of +Blender datablocks are changed via the data API. + + +Limitations +----------- + +The message bus system is triggered by updates via the RNA system. This means +that the following updates will result in a notification on the message bus: + +- Changes via the Python API, for example ``some_object.location.x += 3``. +- Changes via the sliders, fields, and buttons in the user interface. + +The following updates do **not** trigger message bus notifications: + +- Moving objects in the 3D Viewport. +- Changes performed by the animation system. + + +Example Use +----------- + +Below is an example of subscription to changes in the active object's location. +""" + +import bpy + +# Any Python object can act as the subscription's owner. +owner = object() + +subscribe_to = bpy.context.object.location + +def msgbus_callback(*args): + # This will print: + # Something changed! (1, 2, 3) + print("Something changed!", args) + +bpy.msgbus.subscribe_rna( + key=subscribe_to, + owner=owner, + args=(1, 2, 3), + notify=msgbus_callback, +) diff --git a/doc/python_api/examples/bpy.msgbus.2.py b/doc/python_api/examples/bpy.msgbus.2.py new file mode 100644 index 00000000000..5ac2187f7f9 --- /dev/null +++ b/doc/python_api/examples/bpy.msgbus.2.py @@ -0,0 +1,6 @@ +""" +Some properties are converted to Python objects when you retrieve them. This +needs to be avoided in order to create the subscription, by using +``datablock.path_resolve("property_name", False)``: +""" +subscribe_to = bpy.context.object.path_resolve("name", False) diff --git a/doc/python_api/examples/bpy.msgbus.3.py b/doc/python_api/examples/bpy.msgbus.3.py new file mode 100644 index 00000000000..3af5660eff6 --- /dev/null +++ b/doc/python_api/examples/bpy.msgbus.3.py @@ -0,0 +1,5 @@ +""" +It is also possible to create subscriptions on a property of all instances of a +certain type: +""" +subscribe_to = (bpy.types.Object, "location") |