bpy_msgbus.c File Reference

#include <Python.h>
#include "../generic/py_capi_rna.h"
#include "../generic/py_capi_utils.h"
#include "../generic/python_utildefines.h"
#include "../mathutils/mathutils.h"
#include "BLI_utildefines.h"
#include "BKE_context.h"
#include "WM_api.h"
#include "WM_message.h"
#include "WM_types.h"
#include "RNA_access.h"
#include "RNA_define.h"
#include "RNA_enum_types.h"
#include "bpy_capi_utils.h"
#include "bpy_gizmo_wrap.h"
#include "bpy_intern_string.h"
#include "bpy_rna.h"
#include "bpy_msgbus.h"

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 *UNUSED(msg_key), wmMsgSubscribeValue *msg_val)
static void	bpy_msgbus_subscribe_value_free_data (struct wmMsgSubscribeKey *UNUSED(msg_key), struct wmMsgSubscribeValue *msg_val)

Public Message Bus API
static struct PyMethodDef	BPy_msgbus_methods []
static struct 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 type.\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 of 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 *UNUSED(self), 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 *UNUSED(self), 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 *UNUSED(self), PyObject *py_owner)
PyObject *	BPY_msgbus_module (void)

Detailed Description

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

Definition in file bpy_msgbus.c.

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" \
  "      - :class:`bpy.types.Property` instance.\n" \
  "      - :class:`bpy.types.Struct` type.\n" \
  "      - (:class:`bpy.types.Struct`, str) type and property name.\n" \
  "   :type key: Muliple\n"

Definition at line 38 of file bpy_msgbus.c.

BPY_MSGBUS_USER_DATA_LEN

#define BPY_MSGBUS_USER_DATA_LEN   2

Definition at line 137 of file bpy_msgbus.c.

Function Documentation

bpy_msgbus_clear_by_owner()

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

static

Definition at line 370 of file bpy_msgbus.c.

BPY_msgbus_module()

PyObject* BPY_msgbus_module

(

void

)

Definition at line 400 of file bpy_msgbus.c.

References _bpy_msgbus_def.

Referenced by BPy_init_modules().

bpy_msgbus_notify()

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

static

Definition at line 140 of file bpy_msgbus.c.

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

Referenced by bpy_msgbus_subscribe_rna().

bpy_msgbus_publish_rna()

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

static

Definition at line 329 of file bpy_msgbus.c.

References BPY_context_get(), C, CTX_wm_message_bus(), NULL, py_msgbus_rna_key_from_py(), and WM_msg_publish_rna_params().

bpy_msgbus_subscribe_rna()

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

static

Definition at line 213 of file bpy_msgbus.c.

References BPY_context_get(), bpy_msgbus_notify(), bpy_msgbus_subscribe_value_free_data(), C, CTX_wm_message_bus(), wmMsgSubscribeValue::free_data, wmMsgSubscribeValue::is_persistent, wmMsgSubscribeValue::notify, NULL, options, wmMsgSubscribeValue::owner, py_msgbus_rna_key_from_py(), pyrna_enum_bitfield_from_set(), PyTuple_SET_ITEMS, user_data, 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 ( struct wmMsgSubscribeKey *  UNUSEDmsg_key, struct wmMsgSubscribeValue *  msg_val  )

static

Definition at line 179 of file bpy_msgbus.c.

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.c.

References BaseMathObject_CheckExact, BPy_PropertyRNA_Check, BPy_StructRNA_Check, NULL, BPy_PropertyRNA::prop, wmMsgParams_RNA::prop, BPy_StructRNA::ptr, BPy_PropertyRNA::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 type.\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 of 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"
	)

Variable Documentation

_bpy_msgbus_def

struct PyModuleDef _bpy_msgbus_def

static

Initial value:

= {
    PyModuleDef_HEAD_INIT,
    .m_name = "msgbus",
    .m_methods = BPy_msgbus_methods,
}

Definition at line 370 of file bpy_msgbus.c.

Referenced by BPY_msgbus_module().

BPy_msgbus_methods

struct 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},
    {NULL, NULL, 0, NULL},
}

Definition at line 370 of file bpy_msgbus.c.