Debian Codegraph @

docs/rst/scripting/lua_api/lua_object_manager_api.rst

raw
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>`