Welcome to mirror list, hosted at ThFree Co, Russian Federation.

git.blender.org/blender.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSybren A. Stüvel <sybren@blender.org>2020-03-06 16:28:54 +0300
committerSybren A. Stüvel <sybren@blender.org>2020-03-06 16:29:03 +0300
commit2d5773d11a0698f1cf421d7fc7c7d823be601124 (patch)
tree10bbb31759a15292875794d47b271d5e2a56c274 /doc/python_api/examples
parent07c5ca7f2cfc1e9bd898d88f7ed84d24cfc105c2 (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.py44
-rw-r--r--doc/python_api/examples/bpy.msgbus.2.py6
-rw-r--r--doc/python_api/examples/bpy.msgbus.3.py5
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")