68 lines
2.2 KiB
ReStructuredText
68 lines
2.2 KiB
ReStructuredText
.. _lua_gobject:
|
|
|
|
GObject Integration
|
|
===================
|
|
|
|
The Lua engine that powers WirePlumber's scripts provides direct integration
|
|
with `GObject`_. Most of the objects that you will deal with in the lua scripts
|
|
are wrapping GObjects. In order to work with the scripts, you will first need
|
|
to have a basic understanding of GObject's basic concepts, such as signals and
|
|
properties.
|
|
|
|
Properties
|
|
..........
|
|
|
|
All GObjects have the ability to have `properties`_.
|
|
In C we normally use `g_object_get`_ to retrieve them and `g_object_set`_
|
|
to set them.
|
|
|
|
In WirePlumber's lua engine, these properties are exposed as object members
|
|
of the Lua object.
|
|
|
|
For example:
|
|
|
|
.. code-block:: lua
|
|
|
|
-- read the "bound-id" GObject property from the proxy
|
|
local proxy = function_that_returns_a_wp_proxy()
|
|
local proxy_id = proxy["bound-id"]
|
|
print("Bound ID: " .. proxy_id)
|
|
|
|
Writable properties can also be set in a similar fashion:
|
|
|
|
.. code-block:: lua
|
|
|
|
-- set the "scale" GObject property to the enum value "cubic"
|
|
local mixer = ...
|
|
mixer["scale"] = "cubic"
|
|
|
|
Signals
|
|
.......
|
|
|
|
GObjects also have a generic mechanism to deliver events to external callbacks.
|
|
These events are called `signals`_
|
|
|
|
All lua objects that wrap a GObject contain the following methods:
|
|
|
|
.. function:: connect(detailed_signal, callback)
|
|
|
|
Connects the signal to a callback. When the signal is emitted by the
|
|
underlying object, the callback will be executed.
|
|
|
|
:param detailed_signal: the signal name to listen to
|
|
(of the form "signal-name::detail")
|
|
:param callback: a lua function that will be called when the signal is emitted
|
|
|
|
.. function:: call(action_signal, ...)
|
|
|
|
Calls an action signal on this object.
|
|
|
|
:param action_signal: the signal name to call
|
|
:param ...: a list of arguments that will be passed to the signal
|
|
|
|
.. _GObject: https://developer.gnome.org/gobject/stable/
|
|
.. _properties: https://developer.gnome.org/gobject/stable/gobject-properties.html
|
|
.. _g_object_get: https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-get
|
|
.. _g_object_set: https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-set
|
|
.. _signals: https://developer.gnome.org/gobject/stable/signal.html
|