diff --git a/doc/dbus.rst b/doc/dbus.rst index e11d988d..29ee2464 100644 --- a/doc/dbus.rst +++ b/doc/dbus.rst @@ -6,86 +6,129 @@ Note: **the DBus interface is subject to change** Interfaces: -* org.freedesktop.ratbag1.Manager -* org.freedesktop.ratbag1.Device -* org.freedesktop.ratbag1.Profile -* org.freedesktop.ratbag1.Resolution -* org.freedesktop.ratbag1.Button -* org.freedesktop.ratbag1.Led +* :ref:`manager` +* :ref:`device` +* :ref:`profile` +* :ref:`resolution` +* :ref:`button` +* :ref:`led` -For a list of dbus types as used below, see https://dbus.freedesktop.org/doc/dbus-specification.html +Changing settings on a device is a three-step process: + +#. Change the various properties to the desired value +#. Invoke :func:`org.freedesktop.ratbag1.Device.Commit() ` +#. Optional: if an error occured writing the new data to the device, + a :func:`org.freedesktop.ratbag1.Resync ` signal is emitted on the device and + all properties are updated accordingly. + +The time it takes to write settings to a device varies greatly, any caller +must be prepared to receive a :func:`org.freedesktop.ratbag1.Resync +` signal several seconds after +:func:`org.freedesktop.ratbag1.Device.Commit() `. + +Notes on the DBus API +--------------------- +Values listed as enums are defined in `libratbag-enums.h +`_ + +For easier debugging, objects paths are constructed from the device. e.g. +``/org/freedesktop/ratbag/button/event5/p0/b10`` is the button interface for +button 10 on profile 0 on event5. The naming is subject to change. Do not +rely on a constructed object path in your application. + +Types +..... + +Types used by these interfaces: + ++----------+-----------------------------------+ +| Type | Description | ++==========+===================================+ +| ``b`` | Bool | ++----------+-----------------------------------+ +| ``o`` | Object path | ++----------+-----------------------------------+ +| ``s`` | String | ++----------+-----------------------------------+ +| ``u`` | Unsigned 32-bit integer | ++----------+-----------------------------------+ +|``(uuu)`` | Three 32-bit integers | ++----------+-----------------------------------+ +| ``ao`` | Array of object paths | ++----------+-----------------------------------+ +| ``as`` | Array of strings | ++----------+-----------------------------------+ +| ``au`` | Array of 32-bit integers | ++----------+-----------------------------------+ +| ``a(uu)``| Array of 2 32-bit integer tuples | ++----------+-----------------------------------+ + +For details on each type, see the `DBus Specification +`_. + +Flags +..... Properties marked as **constant** do not change for the lifetime of the object. Properties marked as **mutable** may change, and a ``org.freedesktop.DBus.Properties.PropertyChanged`` signal is sent for those unless otherwise specified. -Changing settings on a device is a three-step process: - -- change the various properties to the desired value -- invoke ``org.freedesktop.ratbag1.Device.Commit()`` -- optional: if an error occured writing the new data to the device, - a ``org.freedesktop.ratbag1.Resync`` signal is emitted on the device and - all properties are updated accordingly. - -Values listed as enums are defined in `libratbag-enums.h `_ +.. _manager: org.freedesktop.ratbag1.Manager ------------------------------- -.. js:class:: Manager +The **org.freedesktop.ratbag1.Manager** interface is the entry point to +interact with ratbagd. - The **org.freedesktop.ratbag1.Manager** interface is the entry point to - interact with ratbagd. +.. attribute:: Devices - .. js:attribute:: Devices + :type: ao - :type: ao + An array of read-only **object paths** referencing the available + devices. The devices implement the :ref:`device` interface. - An array of read-only **object paths** to :js:class:`Device` objects - - .. js:attribute:: Themes +.. attribute:: Themes :type: as - :flags: read-only, constant - Provides the list of available theme names. This list is guaranteed to have - one theme available ('default'). Other themes are implementation defined. - A theme listed here is only a guarantee that the theme is known to libratbag - and that SVGs *may* exist, it is not a guarantee that the SVG for any - specific device exists. In other words, a device may not have an SVG for a - specific theme. + The list of available theme names. This list is guaranteed to have + at least one theme available ('default'). Other themes are + implementation defined. A theme listed here is only a guarantee + that the theme is known to libratbag and that SVGs *may* exist, it + is not a guarantee that the SVG for any specific device exists. In + other words, a device may not have an SVG for a specific theme. This list is static for the lifetime of ratbagd. +.. _device: + org.freedesktop.ratbag1.Device ------------------------------- -.. js:class:: Device +The **org.freedesktop.ratbag1.Device** interface describes a single device +known to ratbagd. - The **org.freedesktop.ratbag1.Device** interface describes a single device - known to ratbagd. - - .. js:attribute:: Id +.. attribute:: Id :type: as - :flags: read-only, constant - An ID describing this device. This ID should not be used for presentation to - the user. This ID is unique for the device for the lifetime of the device - but may be recycled when the device is removed. No guarantee is given for - the content of the ID, the client should treat it as an opaque string. + A unique ID describing this device. This ID should not be used for presentation to + the user. This ID may be recycled when the device is removed. The + content of the ID is undefined, the client should treat it as an + opaque string. - .. js:attribute:: Description +.. attribute:: Description :type: s :flags: read-only, constant The device's name, suitable for presentation to the user. - .. js:attribute:: Capabilities +.. attribute:: Capabilities :type: au :flags: read-only, constant @@ -95,14 +138,14 @@ org.freedesktop.ratbag1.Device capabilities. - .. js:attribute:: Svg +.. attribute:: Svg :type: s :flags: read-only, constant The device's SVG file name, without path. - .. js:attribute:: Profiles +.. attribute:: Profiles :type: ao :flags: read-only, mutable @@ -111,70 +154,71 @@ org.freedesktop.ratbag1.Device profiles. Provides the list of profile paths for all profiles on this device, see - :js:class:`Profile`. + :ref:`profile` - .. js:function:: Commit() → () +.. function:: Commit() → () Commits the changes to the device. Changes to the device are batched; they - are not written to the hardware until :js:func:`Commit()` is invoked. + are not written to the hardware until :func:`Commit` is invoked. - .. js:function:: GetSvg(s) → (s) +.. function:: GetSvg(s) → (s) :param s: the theme name :returns: A full path to the SVG for the given theme Returns the full path to the SVG for the given theme or an empty string if none is available. The theme must be one of - :js:attr:`Themes`. + :func:`org.freedesktop.ratbag1.Manager.Themes `. The theme **'default'** is guaranteed to be available. ratbagd may return the path to a file that doesn't exist. This is the case if the device has SVGs available but not for the given theme. - .. js:function:: GetSvgFd(s) → (h) +.. function:: GetSvgFd(s) → (h) :param s: the theme name :returns: An open file descriptor to the SVG for the given theme Returns an open file descriptor to the SVG for the given theme or an - errno on error. The theme must be one of :js:attr:`Manager.Themes`. + errno on error. The theme must be one of + :func:`org.freedesktop.ratbag1.Manager.Themes `. The theme **'default'** is guaranteed to be available. ratbagd may return ENOENT if a file doesn't exist. This is the case if the device has SVGs available but not for the given theme. - .. js:function:: Resync() +.. exception:: Resync() :type: Signal Emitted when an internal error occurs, usually on writing values to - the device after :js:func:`Commit()`. Upon receiving this + the device after :func:`Commit()`. Upon receiving this signal, clients are expected to resync their property values with ratbagd. +.. _profile: + org.freedesktop.ratbag1.Profile ------------------------------- -.. js:class:: Profile - - .. js:attribute:: Index +.. attribute:: Index :type: u :flags: read-only, constant The zero-based index of this profile - .. js:attribute:: Name +.. attribute:: Name :type: s :flags: read-write, mutable The name of this profile. - .. js:attribute:: Enabled +.. attribute:: Enabled :type: b :flags: read-write, mutable @@ -183,9 +227,9 @@ org.freedesktop.ratbag1.Profile Note that a disabled profile might not have correct bindings, so it's a good thing to rebind everything before calling - :js:func:`Device.Commit()`. + :func:`Commit`. - .. js:attribute:: Resolutions +.. attribute:: Resolutions :type: ao :flags: read-only, mutable @@ -194,25 +238,25 @@ org.freedesktop.ratbag1.Profile resolutions. Provides the object paths of all resolutions in this profile, see - :js:class:`Resolution` + :ref:`resolution`. - .. js:attribute:: Buttons +.. attribute:: Buttons :type: ao :flags: read-only, constant Provides the object paths of all buttons in this profile, see - :js:class:`Button` + :ref:`button`. - .. js:attribute:: Leds +.. attribute:: Leds :type: ao :flags: read-only, constant Provides the object paths of all LEDs in this profile, see - :js:class:`Led` + :ref:`led`. - .. js:attribute:: IsActive +.. attribute:: IsActive :type: b :flags: read-only, mutable @@ -221,32 +265,33 @@ org.freedesktop.ratbag1.Profile Profiles can only be set to active, but never to not active - at least one profile must be active at all times. This property is read-only, use the - :js:func:`SetActive()` method to activate a profile. + :func:`SetActive` method to activate a profile. - .. js:function:: SetActive() → () +.. function:: SetActive() → () Set this profile to be the active profile +.. _resolution: + org.freedesktop.ratbag1.Resolution ---------------------------------- -.. js:class:: Resolution - - .. js:attribute:: Index +.. attribute:: Index :type: u :flags: read-only, constant Index of the resolution - .. js:attribute:: Capabilities +.. attribute:: Capabilities :type: au :flags: read-only, constant - Array of uints from the ratbag\_resolution\_capability from libratbag.h. + Array of uints from the :cpp:enum:`ratbag_resolution_capability` + from libratbag.h. - .. js:attribute:: IsActive +.. attribute:: IsActive :type: b :flags: read-only, mutable @@ -256,10 +301,10 @@ org.freedesktop.ratbag1.Resolution Resolutions can only be set to active, but never to not active - at least one resoultion must be active at all times. This property is read-only, use the - :js:func:`SetActive()` method to set a resolution as the + :func:`SetActive` method to set a resolution as the active resolution. - .. js:attribute:: IsDefault +.. attribute:: IsDefault :type: b :flags: read-only, mutable @@ -271,34 +316,34 @@ org.freedesktop.ratbag1.Resolution Resolutions can only be set to default, but never to not default - at least one resolution must be default at all times. This property is read-only, use the - :js:func:`SetDefault()` method to set a resolution as + :func:`SetDefault` method to set a resolution as the default resolution. - .. js:attribute:: Resolution +.. attribute:: Resolution :type: uu :flags: read-write, mutable uint for the x and y resolution assigned to this entry, respectively. The value for the resolution must be equal to - one of the values in :js:attr:`Resolutions`. + one of the values in :attr:`Resolutions`. If the resolution does not support separate x/y resolutions, x and y must be the same value. - .. js:attribute:: Resolutions +.. attribute:: Resolutions :type: au :flags: read-only, constant A list of permitted resolutions. Values in this list may be used in - the :js:attr:`Resolution` property. This list is always sorted + the :attr:`Resolution` property. This list is always sorted ascending, the lowest resolution is the first item in the list. This list may be empty if the device does not support reading and/or writing to resolutions. - .. js:attribute:: ReportRate +.. attribute:: ReportRate :type: u :flags: read-write, mutable @@ -309,39 +354,39 @@ org.freedesktop.ratbag1.Resolution capability, changing the report rate on one resolution will change the report rate on all resolutions. - .. js:attribute:: ReportRates +.. attribute:: ReportRates :type: au :flags: read-write, constant A list of permitted report rates. Values in this list may be used - in the :js:attr:`ReportRate` property. This list is always sorted + in the :attr:`ReportRate` property. This list is always sorted ascending, the lowest report rate is the first item in the list. This list may be empty if the device does not support reading and/or writing to resolutions. - .. js:function:: SetDefault() → () +.. function:: SetDefault() → () Set this resolution to be the default - .. js:function:: SetActive() → () +.. function:: SetActive() → () Set this resolution to be the active one +.. _button: + org.freedesktop.ratbag1.Button ------------------------------ -.. js:class:: Button - - .. js:attribute:: Index +.. attribute:: Index :type: u :flags: read-only, constant Index of the button - .. js:attribute:: Type +.. attribute:: Type :type: u :flags: read-only, constant @@ -351,21 +396,21 @@ org.freedesktop.ratbag1.Button logical button mapping and serves to easily identify the button on the device. - .. js:attribute:: ButtonMapping +.. attribute:: ButtonMapping :type: u :flags: read-write, mutable uint of the current button mapping (if mapping to button) - .. js:attribute:: SpecialMapping +.. attribute:: SpecialMapping :type: u :flags: read-write, mutable Enum describing the current special mapping (if mapped to special) - .. js:attribute:: Macro +.. attribute:: Macro :type: a(uu) :flags: read-write, mutable @@ -374,17 +419,17 @@ org.freedesktop.ratbag1.Button :cpp:enumerator:`RATBAG_MACRO_EVENT_KEY_PRESSED` or :cpp:enumerator:`RATBAG_MACRO_EVENT_KEY_RELEASED`. - .. js:attribute:: ActionType +.. attribute:: ActionType :type: u :flags: read-only, mutable An enum describing the action type of the button, see :cpp:enum:`ratbag_button_action_type` for the list of enums. - This decides which one of :js:attr:`ButtonMapping`, - :js:attr:`SpecialMapping` and :js:attr:`Macro` has a value. + This decides which one of :attr:`ButtonMapping`, + :attr:`SpecialMapping` and :attr:`Macro` has a value. - .. js:attribute:: ActionTypes +.. attribute:: ActionTypes :type: au :flags: read-only, constant @@ -392,72 +437,68 @@ org.freedesktop.ratbag1.Button Array of :cpp:enum:`ratbag_button_action_type`, possible values for ActionType on the current device - .. js:function:: Disable() → () +.. function:: Disable() → () Disable this button +.. _led: + org.freedesktop.ratbag1.Led --------------------------- -.. js:class:: Led - - .. js:attribute:: Index +.. attribute:: Index :type: u :flags: read-only, constant Index of the LED - .. js:attribute:: Mode +.. attribute:: Mode :type: u :flags: read-write, mutable uint mapping to the mode enum from libratbag - .. js:attribute:: Modes +.. attribute:: Modes :type: au :flags: read-only, constant A list of modes supported by this LED - .. js:attribute:: Type +.. attribute:: Type :type: u :flags: read-only, mutable enum describing the LED type - .. js:attribute:: Color +.. attribute:: Color :type: (uuu) :flags: read-write, mutable uint triplet (RGB) of the LED's color - .. js:attribute:: ColorDepth +.. attribute:: ColorDepth :type: u :flags: read-only, constant The color depth of this LED as one of the constants in libratbag-enums.h - .. js:attribute:: EffectDuration +.. attribute:: EffectDuration :type: u :flags: read-write, mutable The effect duration in ms, possible values are in the range 0 - 10000 - .. js:attribute:: Brightness +.. attribute:: Brightness :type: u :flags: read-write, mutable The brightness of the LED, possible values are in the range 0 - 255 -For easier debugging, objects paths are constructed from the device. e.g. -`/org/freedesktop/ratbag/button/event5/p0/b10` is the button interface for -button 10 on profile 0 on event5. The naming is subject to change. Do not -rely on a constructed object path in your application.