f3f89b8fc1
Also: - rename some files to remove redundant information from the filenames - rename many labels to match the filename and its place in the hierarchy - move lua_api under the scripting section
105 lines
3.6 KiB
ReStructuredText
105 lines
3.6 KiB
ReStructuredText
.. _lua_object_manager_api:
|
|
|
|
Object Manager
|
|
==============
|
|
|
|
The ObjectManager (binding for :c:struct:`WpObjectManager`) provides a way to
|
|
collect a set of objects and be notified when objects that fulfill a certain
|
|
set of criteria are created or destroyed.
|
|
|
|
To start an object manager, you first need to declare interest in a certain
|
|
kind of object specifying a set of :ref:`Interests <lua_object_interest_api>`
|
|
in the constructor and then you need to activate it by calling
|
|
:func:`ObjectManager.activate`
|
|
|
|
Upon activating an ObjectManager, any pre-existing objects that match the
|
|
specified interests will immediately become available to get through
|
|
:func:`ObjectManager.iterate` and the :c:struct:`WpObjectManager` "object-added"
|
|
signal will be emitted for all of them.
|
|
|
|
Constructors
|
|
~~~~~~~~~~~~
|
|
|
|
.. function:: ObjectManager(interest_list)
|
|
|
|
Constructs a new object manager.
|
|
|
|
Combines :c:func:`wp_object_manager_new` and
|
|
:c:func:`wp_object_manager_add_interest_full`
|
|
|
|
The argument needs to be a table that contains one or more
|
|
:ref:`Interest <lua_object_interest_api>` objects. The object manager
|
|
will then contain all objects that match any one of the supplied interests.
|
|
|
|
Example:
|
|
|
|
.. code-block:: lua
|
|
|
|
streams_om = ObjectManager {
|
|
-- match stream nodes
|
|
Interest {
|
|
type = "node",
|
|
Constraint { "media.class", "matches", "Stream/*", type = "pw-global" },
|
|
},
|
|
-- and device nodes that are not associated with any routes
|
|
Interest {
|
|
type = "node",
|
|
Constraint { "media.class", "matches", "Audio/*", type = "pw-global" },
|
|
Constraint { "device.routes", "equals", "0", type = "pw" },
|
|
},
|
|
Interest {
|
|
type = "node",
|
|
Constraint { "media.class", "matches", "Audio/*", type = "pw-global" },
|
|
Constraint { "device.routes", "is-absent", type = "pw" },
|
|
},
|
|
}
|
|
|
|
The above example will create an ObjectManager that matches all nodes with
|
|
a "media.class" global property that starts with the string "Stream/"
|
|
and additionally all those whose "media.class" starts with "Audio/" and
|
|
they have either a "device.routes" property that equals zero or they
|
|
don't have a "device.routes" property at all.
|
|
|
|
:param table interest_list: a list of :ref:`interests <lua_object_interest_api>`
|
|
to objects
|
|
:returns: a new object manager
|
|
:rtype: ObjectManager (:c:struct:`WpObjectManager`)
|
|
|
|
Methods
|
|
~~~~~~~
|
|
|
|
.. function:: ObjectManager.activate(self)
|
|
|
|
Activates the object manager.
|
|
Binds :c:func:`wp_core_install_object_manager`.
|
|
|
|
:param self: the object manager
|
|
|
|
.. function:: ObjectManager.get_n_objects(self)
|
|
|
|
Binds :c:func:`wp_object_manager_get_n_objects`
|
|
|
|
:param self: the object manager
|
|
:returns: the number of objects managed by the object manager
|
|
:rtype: integer
|
|
|
|
.. function:: ObjectManager.iterate(self, interest)
|
|
|
|
Binds :c:func:`wp_object_manager_new_filtered_iterator_full`
|
|
|
|
:param self: the object manager
|
|
:param interest: an interest to filter objects
|
|
:type interest: :ref:`Interest <lua_object_interest_api>` or nil or none
|
|
:returns: all the managed objects that match the interest
|
|
:rtype: Iterator; the iteration items are of type :ref:`GObject <lua_gobject>`
|
|
|
|
.. function:: ObjectManager.lookup(self, interest)
|
|
|
|
Binds :c:func:`wp_object_manager_lookup`
|
|
|
|
:param self: the object manager
|
|
:param interest: the interest to use for the lookup
|
|
:type interest: :ref:`Interest <lua_object_interest_api>` or nil or none
|
|
:returns: the first managed object that matches the interest
|
|
:rtype: :ref:`GObject <lua_gobject>`
|