| 1 |
.. _lua_object_manager_api: |
| 2 |
|
| 3 |
Object Manager |
| 4 |
============== |
| 5 |
|
| 6 |
The ObjectManager (binding for :c:struct:`WpObjectManager`) provides a way to |
| 7 |
collect a set of objects and be notified when objects that fulfill a certain |
| 8 |
set of criteria are created or destroyed. |
| 9 |
|
| 10 |
To start an object manager, you first need to declare interest in a certain |
| 11 |
kind of object specifying a set of :ref:`Interests <lua_object_interest_api>` |
| 12 |
in the constructor and then you need to activate it by calling |
| 13 |
:func:`ObjectManager.activate` |
| 14 |
|
| 15 |
Upon activating an ObjectManager, any pre-existing objects that match the |
| 16 |
specified interests will immediately become available to get through |
| 17 |
:func:`ObjectManager.iterate` and the :c:struct:`WpObjectManager` "object-added" |
| 18 |
signal will be emitted for all of them. |
| 19 |
|
| 20 |
Constructors |
| 21 |
~~~~~~~~~~~~ |
| 22 |
|
| 23 |
.. function:: ObjectManager(interest_list) |
| 24 |
|
| 25 |
Constructs a new object manager. |
| 26 |
|
| 27 |
Combines :c:func:`wp_object_manager_new` and |
| 28 |
:c:func:`wp_object_manager_add_interest_full` |
| 29 |
|
| 30 |
The argument needs to be a table that contains one or more |
| 31 |
:ref:`Interest <lua_object_interest_api>` objects. The object manager |
| 32 |
will then contain all objects that match any one of the supplied interests. |
| 33 |
|
| 34 |
Example: |
| 35 |
|
| 36 |
.. code-block:: lua |
| 37 |
|
| 38 |
streams_om = ObjectManager { |
| 39 |
-- match stream nodes |
| 40 |
Interest { |
| 41 |
type = "node", |
| 42 |
Constraint { "media.class", "matches", "Stream/*", type = "pw-global" }, |
| 43 |
}, |
| 44 |
-- and device nodes that are not associated with any routes |
| 45 |
Interest { |
| 46 |
type = "node", |
| 47 |
Constraint { "media.class", "matches", "Audio/*", type = "pw-global" }, |
| 48 |
Constraint { "device.routes", "equals", "0", type = "pw" }, |
| 49 |
}, |
| 50 |
Interest { |
| 51 |
type = "node", |
| 52 |
Constraint { "media.class", "matches", "Audio/*", type = "pw-global" }, |
| 53 |
Constraint { "device.routes", "is-absent", type = "pw" }, |
| 54 |
}, |
| 55 |
} |
| 56 |
|
| 57 |
The above example will create an ObjectManager that matches all nodes with |
| 58 |
a "media.class" global property that starts with the string "Stream/" |
| 59 |
and additionally all those whose "media.class" starts with "Audio/" and |
| 60 |
they have either a "device.routes" property that equals zero or they |
| 61 |
don't have a "device.routes" property at all. |
| 62 |
|
| 63 |
:param table interest_list: a list of :ref:`interests <lua_object_interest_api>` |
| 64 |
to objects |
| 65 |
:returns: a new object manager |
| 66 |
:rtype: ObjectManager (:c:struct:`WpObjectManager`) |
| 67 |
|
| 68 |
Methods |
| 69 |
~~~~~~~ |
| 70 |
|
| 71 |
.. function:: ObjectManager.activate(self) |
| 72 |
|
| 73 |
Activates the object manager. |
| 74 |
Binds :c:func:`wp_core_install_object_manager`. |
| 75 |
|
| 76 |
:param self: the object manager |
| 77 |
|
| 78 |
.. function:: ObjectManager.get_n_objects(self) |
| 79 |
|
| 80 |
Binds :c:func:`wp_object_manager_get_n_objects` |
| 81 |
|
| 82 |
:param self: the object manager |
| 83 |
:returns: the number of objects managed by the object manager |
| 84 |
:rtype: integer |
| 85 |
|
| 86 |
.. function:: ObjectManager.iterate(self, interest) |
| 87 |
|
| 88 |
Binds :c:func:`wp_object_manager_new_filtered_iterator_full` |
| 89 |
|
| 90 |
:param self: the object manager |
| 91 |
:param interest: an interest to filter objects |
| 92 |
:type interest: :ref:`Interest <lua_object_interest_api>` or nil or none |
| 93 |
:returns: all the managed objects that match the interest |
| 94 |
:rtype: Iterator; the iteration items are of type :ref:`GObject <lua_gobject>` |
| 95 |
|
| 96 |
.. function:: ObjectManager.lookup(self, interest) |
| 97 |
|
| 98 |
Binds :c:func:`wp_object_manager_lookup` |
| 99 |
|
| 100 |
:param self: the object manager |
| 101 |
:param interest: the interest to use for the lookup |
| 102 |
:type interest: :ref:`Interest <lua_object_interest_api>` or nil or none |
| 103 |
:returns: the first managed object that matches the interest |
| 104 |
:rtype: :ref:`GObject <lua_gobject>` |