bpy_msgbus.cc File Reference

#include <Python.h>
#include "../generic/py_capi_rna.hh"
#include "../generic/py_capi_utils.hh"
#include "../generic/python_compat.hh"
#include "../generic/python_utildefines.hh"
#include "../mathutils/mathutils.hh"
#include "BLI_utildefines.h"
#include "BKE_context.hh"
#include "WM_message.hh"
#include "RNA_access.hh"
#include "bpy_capi_utils.hh"
#include "bpy_rna.hh"
#include "bpy_msgbus.hh"

Go to the source code of this file.

Internal Utils
#define	BPY_MSGBUS_RNA_MSGKEY_DOC
static int	py_msgbus_rna_key_from_py (PyObject *py_sub, wmMsgParams_RNA *msg_key_params, const char *error_prefix)

Internal Callbacks
#define	BPY_MSGBUS_USER_DATA_LEN   2
static void	bpy_msgbus_notify (bContext *C, wmMsgSubscribeKey *, wmMsgSubscribeValue *msg_val)
static void	bpy_msgbus_subscribe_value_free_data (wmMsgSubscribeKey *, wmMsgSubscribeValue *msg_val)

Public Message Bus API
static PyMethodDef	BPy_msgbus_methods []
static PyModuleDef	_bpy_msgbus_def
	PyDoc_STRVAR (bpy_msgbus_subscribe_rna_doc, ".. function:: subscribe_rna(key, owner, args, notify, options=set())\n" "\n" " Register a message bus subscription. It will be cleared when another blend file is\n" " loaded, or can be cleared explicitly via :func:`bpy.msgbus.clear_by_owner`.\n" "\n" BPY_MSGBUS_RNA_MSGKEY_DOC " :arg owner: Handle for this subscription (compared by identity).\n" " :type owner: Any\n" " :arg options: Change the behavior of the subscriber.\n" "\n" " - ``PERSISTENT`` when set, the subscriber will be kept when remapping ID data.\n" "\n" " :type options: set[str]\n" "\n" ".. note::\n" "\n" " All subscribers will be cleared on file-load. Subscribers can be re-registered on load,\n" " see :mod:`bpy.app.handlers.load_post`.\n")
static PyObject *	bpy_msgbus_subscribe_rna (PyObject *, PyObject *args, PyObject *kw)
	PyDoc_STRVAR (bpy_msgbus_publish_rna_doc, ".. function:: publish_rna(key)\n" "\n" BPY_MSGBUS_RNA_MSGKEY_DOC "\n" " Notify subscribers of changes to this property\n" " (this typically doesn't need to be called explicitly since changes will automatically " "publish updates).\n" " In some cases it may be useful to publish changes explicitly using more general keys.\n")
static PyObject *	bpy_msgbus_publish_rna (PyObject *, PyObject *args, PyObject *kw)
	PyDoc_STRVAR (bpy_msgbus_clear_by_owner_doc, ".. function:: clear_by_owner(owner)\n" "\n" " Clear all subscribers using this owner.\n")
static PyObject *	bpy_msgbus_clear_by_owner (PyObject *, PyObject *py_owner)
PyObject *	BPY_msgbus_module ()

Detailed Description

This file defines '_bpy_msgbus' module, exposed as 'bpy.msgbus'.

Definition in file bpy_msgbus.cc.

Macro Definition Documentation

BPY_MSGBUS_RNA_MSGKEY_DOC

#define BPY_MSGBUS_RNA_MSGKEY_DOC

Value:

  "   :arg key: Represents the type of data being subscribed to\n" \
  "\n" \
  "      Arguments include\n" \
  "      - A property instance.\n" \
  "      - A struct type.\n" \
  "      - A tuple representing a (struct, property name) pair.\n" \
  "   :type key: :class:`bpy.types.Property` | " \
  ":class:`bpy.types.Struct` | " \
  "tuple[:class:`bpy.types.Struct`, str]\n"

Definition at line 36 of file bpy_msgbus.cc.

BPY_MSGBUS_USER_DATA_LEN

#define BPY_MSGBUS_USER_DATA_LEN   2

Definition at line 137 of file bpy_msgbus.cc.

Referenced by bpy_msgbus_notify().

Function Documentation

bpy_msgbus_clear_by_owner()

static PyObject * bpy_msgbus_clear_by_owner ( PyObject * , PyObject * py_owner )

static

Definition at line 378 of file bpy_msgbus.cc.

References BPY_context_get(), CTX_wm_message_bus(), and WM_msgbus_clear_by_owner().

BPY_msgbus_module()

PyObject * BPY_msgbus_module

(

)

Definition at line 423 of file bpy_msgbus.cc.

References _bpy_msgbus_def.

Referenced by BPy_init_modules().

bpy_msgbus_notify()

static void bpy_msgbus_notify ( bContext * C, wmMsgSubscribeKey * , wmMsgSubscribeValue * msg_val )

static

Definition at line 140 of file bpy_msgbus.cc.

References BLI_assert, bpy_context_clear(), bpy_context_set(), BPY_MSGBUS_USER_DATA_LEN, PyC_Err_PrintWithFunc(), pyrna_write_check(), pyrna_write_set(), ret, and wmMsgSubscribeValue::user_data.

Referenced by bpy_msgbus_subscribe_rna().

bpy_msgbus_publish_rna()

static PyObject * bpy_msgbus_publish_rna ( PyObject * , PyObject * args, PyObject * kw )

static

Definition at line 334 of file bpy_msgbus.cc.

References BPY_context_get(), CTX_wm_message_bus(), PY_ARG_PARSER_HEAD_COMPAT, py_msgbus_rna_key_from_py(), and WM_msg_publish_rna_params().

bpy_msgbus_subscribe_rna()

static PyObject * bpy_msgbus_subscribe_rna ( PyObject * , PyObject * args, PyObject * kw )

static

Definition at line 214 of file bpy_msgbus.cc.

References BPY_context_get(), bpy_msgbus_notify(), bpy_msgbus_subscribe_value_free_data(), CTX_wm_message_bus(), wmMsgSubscribeValue::free_data, wmMsgSubscribeValue::is_persistent, wmMsgSubscribeValue::notify, options, wmMsgSubscribeValue::owner, PY_ARG_PARSER_HEAD_COMPAT, py_msgbus_rna_key_from_py(), pyrna_enum_bitfield_from_set(), PyTuple_SET_ITEMS, wmMsgSubscribeValue::user_data, WM_msg_dump(), and WM_msg_subscribe_rna_params().

bpy_msgbus_subscribe_value_free_data()

static void bpy_msgbus_subscribe_value_free_data ( wmMsgSubscribeKey * , wmMsgSubscribeValue * msg_val )

static

Definition at line 179 of file bpy_msgbus.cc.

References wmMsgSubscribeValue::owner, and wmMsgSubscribeValue::user_data.

Referenced by bpy_msgbus_subscribe_rna().

py_msgbus_rna_key_from_py()

static int py_msgbus_rna_key_from_py ( PyObject * py_sub, wmMsgParams_RNA * msg_key_params, const char * error_prefix )

static

There are multiple ways we can get RNA from Python, it's also possible to register a type instead of an instance.

This function handles converting Python to RNA subscription information.

Parameters

py_sub	See BPY_MSGBUS_RNA_MSGKEY_DOC for description.
msg_key_params	Message key with all members zeroed out.

Returns

-1 on failure, 0 on success.

Definition at line 57 of file bpy_msgbus.cc.

References BaseMathObject_CheckExact, BPy_PropertyRNA_Check, BPy_StructRNA_Check, BPy_PropertyRNA::prop, wmMsgParams_RNA::prop, BPy_PropertyRNA::ptr, BPy_StructRNA::ptr, wmMsgParams_RNA::ptr, PYRNA_PROP_CHECK_INT, pyrna_struct_as_srna(), PYRNA_STRUCT_CHECK_INT, RNA_struct_find_property(), RNA_struct_identifier(), and PointerRNA::type.

Referenced by bpy_msgbus_publish_rna(), and bpy_msgbus_subscribe_rna().

PyDoc_STRVAR() [1/3]

PyDoc_STRVAR	(	bpy_msgbus_clear_by_owner_doc	,
		".. function:: clear_by_owner(owner)\n" "\n" " Clear all subscribers using this owner.\n"	)

PyDoc_STRVAR() [2/3]

PyDoc_STRVAR	(	bpy_msgbus_publish_rna_doc	,
		".. function:: publish_rna(key)\n" "\n" BPY_MSGBUS_RNA_MSGKEY_DOC "\n" " Notify subscribers of changes to this property\n" " (this typically doesn't need to be called explicitly since changes will automatically " "publish updates).\n" " In some cases it may be useful to publish changes explicitly using more general keys.\n"	)

PyDoc_STRVAR() [3/3]

PyDoc_STRVAR	(	bpy_msgbus_subscribe_rna_doc	,
		".. function:: subscribe_rna(key, owner, args, notify, options=set())\n" "\n" " Register a message bus subscription. It will be cleared when another blend file is\n" "	loaded,
		or can be cleared explicitly via :func:`bpy.msgbus.clear_by_owner`.\n" "\n" BPY_MSGBUS_RNA_MSGKEY_DOC " :arg owner:Handle for this subscription(compared by identity).\n" " :type owner:Any\n" " :arg options:Change the behavior of the subscriber.\n" "\n" " - ``PERSISTENT`` when	set,
		the subscriber will be kept when remapping ID data.\n" "\n" " :type options:set\n" "\n" ".. note::\n" "\n" " All subscribers will be cleared on file-load. Subscribers can be re-registered on	load[str],
		\n" " see :mod:`bpy.app.handlers.load_post`.\n"	)

Variable Documentation

_bpy_msgbus_def

PyModuleDef _bpy_msgbus_def

static

Initial value:

= {
     PyModuleDef_HEAD_INIT,
     "msgbus",
     nullptr,
     0,
     BPy_msgbus_methods,
     nullptr,
     nullptr,
     nullptr,
     nullptr,
}

Definition at line 411 of file bpy_msgbus.cc.

Referenced by BPY_msgbus_module().

BPy_msgbus_methods

PyMethodDef BPy_msgbus_methods[]

static

Initial value:

= {
    {"subscribe_rna",
     (PyCFunction)bpy_msgbus_subscribe_rna,
     METH_VARARGS | METH_KEYWORDS,
     bpy_msgbus_subscribe_rna_doc},
    {"publish_rna",
     (PyCFunction)bpy_msgbus_publish_rna,
     METH_VARARGS | METH_KEYWORDS,
     bpy_msgbus_publish_rna_doc},
    {"clear_by_owner",
     (PyCFunction)bpy_msgbus_clear_by_owner,
     METH_O,
     bpy_msgbus_clear_by_owner_doc},
    {nullptr, nullptr, 0, nullptr},
}

Definition at line 391 of file bpy_msgbus.cc.