forked from bartvdbraak/blender
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.
This commit is contained in:
parent
07c5ca7f2c
commit
2d5773d11a
44
doc/python_api/examples/bpy.msgbus.1.py
Normal file
44
doc/python_api/examples/bpy.msgbus.1.py
Normal file
@ -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,
|
||||
)
|
6
doc/python_api/examples/bpy.msgbus.2.py
Normal file
6
doc/python_api/examples/bpy.msgbus.2.py
Normal file
@ -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)
|
5
doc/python_api/examples/bpy.msgbus.3.py
Normal file
5
doc/python_api/examples/bpy.msgbus.3.py
Normal file
@ -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")
|
@ -1756,6 +1756,7 @@ def write_rst_contents(basepath):
|
||||
app_modules = (
|
||||
"bpy.context", # note: not actually a module
|
||||
"bpy.data", # note: not actually a module
|
||||
"bpy.msgbus", # note: not actually a module
|
||||
"bpy.ops",
|
||||
"bpy.types",
|
||||
|
||||
@ -1846,6 +1847,29 @@ def write_rst_ops_index(basepath):
|
||||
file.close()
|
||||
|
||||
|
||||
def write_rst_msgbus(basepath):
|
||||
"""
|
||||
Write the rst files of bpy.msgbus module
|
||||
"""
|
||||
if 'bpy.msgbus' in EXCLUDE_MODULES:
|
||||
return
|
||||
|
||||
# Write the index.
|
||||
filepath = os.path.join(basepath, "bpy.msgbus.rst")
|
||||
file = open(filepath, "w", encoding="utf-8")
|
||||
fw = file.write
|
||||
fw(title_string("Message Bus (bpy.msgbus)", "="))
|
||||
write_example_ref("", fw, "bpy.msgbus")
|
||||
fw(".. toctree::\n")
|
||||
fw(" :glob:\n\n")
|
||||
fw(" bpy.msgbus.*\n\n")
|
||||
file.close()
|
||||
|
||||
# Write the contents.
|
||||
pymodule2sphinx(basepath, 'bpy.msgbus', bpy.msgbus, 'Message Bus')
|
||||
EXAMPLE_SET_USED.add("bpy.msgbus")
|
||||
|
||||
|
||||
def write_rst_data(basepath):
|
||||
'''
|
||||
Write the rst file of bpy.data module
|
||||
@ -2000,6 +2024,7 @@ def rna2sphinx(basepath):
|
||||
write_rst_bpy(basepath) # bpy, disabled by default
|
||||
write_rst_types_index(basepath) # bpy.types
|
||||
write_rst_ops_index(basepath) # bpy.ops
|
||||
write_rst_msgbus(basepath) # bpy.msgbus
|
||||
pyrna2sphinx(basepath) # bpy.types.* and bpy.ops.*
|
||||
write_rst_data(basepath) # bpy.data
|
||||
write_rst_importable_modules(basepath)
|
||||
|
Loading…
Reference in New Issue
Block a user