mirror of
https://github.com/libratbag/libratbag.git
synced 2026-11-08 07:33:53 +01:00
Tidy up the dbus documentation
Use more sectioning and more precise descriptions of the function signatures. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer
committed by
Benjamin Tissoires
Benjamin Tissoires
parent
c14ffe36e3
commit
8380e1686b
398
DBusInterface.md
398
DBusInterface.md
@@ -11,93 +11,327 @@ Interfaces:
|
||||
- org.freedesktop.ratbag1.Button
|
||||
- org.freedesktop.ratbag1.Led
|
||||
|
||||
The **org.freedesktop.ratbag1.Manager** interface provides:
|
||||
- Properties:
|
||||
- Devices -> array of object paths with interface Device
|
||||
- Themes -> array of strings with theme names. The theme 'default' is
|
||||
guaranteed to be available.
|
||||
- Signals:
|
||||
- DeviceNew -> new device available, carries object path
|
||||
- DeviceRemoved -> device removed, carries object path
|
||||
For a list of dbus types as used below, see https://dbus.freedesktop.org/doc/dbus-specification.html
|
||||
|
||||
The **org.freedesktop.ratbag1.Device** interface provides:
|
||||
- Properties:
|
||||
- Id -> unique ID of this device
|
||||
- Capabilities -> array of uints with the capabilities enum from libratbag
|
||||
- Description -> device name
|
||||
- Svg -> device SVG name (file only)
|
||||
- SvgPath -> device SVG name (full absolute path)
|
||||
- Profiles -> array of object paths with interface Profile
|
||||
- ActiveProfile -> index of the currently active profile in Profiles
|
||||
- Methods:
|
||||
- GetProfileByIndex(uint) -> returns the object path for the given index
|
||||
- Commit() -> commit the changes to the device
|
||||
- GetSvg(string) -> 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
|
||||
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.
|
||||
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.
|
||||
|
||||
The **org.freedesktop.ratbag1.Profile** interface provides:
|
||||
- Properties:
|
||||
- Index -> index of the profile
|
||||
- Resolutions -> array of object paths with interface Resolution
|
||||
- Buttons -> array of object paths with interface Button
|
||||
- Leds -> array of object paths with interface Led
|
||||
- ActiveResolution -> index of the currently active resolution in Resolutions
|
||||
- DefaultResolution -> index of the default resolution in Resolutions
|
||||
- Methods:
|
||||
- SetActive(void) -> set this profile to be the active profile
|
||||
- GetResolutionByIndex(uint) -> returns the object path for the given index
|
||||
- Signals:
|
||||
- ActiveProfileChanged -> active profile changed, carries index of the new active profile
|
||||
org.freedesktop.ratbag1.Manager
|
||||
===============================
|
||||
|
||||
The **org.freedesktop.ratbag1.Resolution** interface provides:
|
||||
- Properties:
|
||||
- Index -> index of the resolution
|
||||
- Capabilities -> array of uints with the capabilities enum from libratbag
|
||||
- XResolution -> uint for the x resolution assigned to this entry
|
||||
- YResolution -> uint for the y resolution assigned to this entry
|
||||
- ReportRate -> uint for the report rate in Hz assigned to this entry
|
||||
- Maximum -> uint for the maximum possible resolution
|
||||
- Minimum -> uint for the minimum possible resolution
|
||||
- Methods:
|
||||
- SetResolution(uint, uint) -> x/y resolution to assign
|
||||
- SetReportRate(uint) -> uint for the report rate to assign
|
||||
- SetDefault -> set this resolution to be the default
|
||||
- Signals:
|
||||
- ActiveResolutionChanged -> active resolution changed, carries index of the new active resolution
|
||||
- DefaultResolutionChanged -> default resolution changed, carries index of the new default resolution
|
||||
The **org.freedesktop.ratbag1.Manager** interface is the entry point to
|
||||
interact with ratbagd.
|
||||
|
||||
The **org.freedesktop.ratbag1.Button** interface provides:
|
||||
- Properties:
|
||||
- Index -> index of the button
|
||||
- Type -> string describing the button type
|
||||
- ButtonMapping -> uint of the current button mapping (if mapping to button)
|
||||
- SpecialMapping -> string of the current special mapping (if mapped to special)
|
||||
- KeyMapping -> array of uints, first entry is the keycode, other entries, if any, are modifiers (if mapped to key)
|
||||
- ActionType -> string describing the action type of the button ("none", "button", "key", "special", "macro", "unknown"). This decides which \*Mapping property has a value
|
||||
- ActionTypes -> array of strings, possible values for ActionType
|
||||
- Methods:
|
||||
- SetButtonMapping(uint) -> set the button mapping to the given button
|
||||
- SetSpecialMapping(string) -> set the button mapping to the given special entry
|
||||
- SetKeyMapping(uint[]) -> set the key mapping, first entry is the keycode, other entries, if any, are modifier keycodes
|
||||
- Disable(void) -> disable this button
|
||||
### Properties
|
||||
|
||||
The **org.freedesktop.ratbag1.Led** interface provides:
|
||||
- Properties:
|
||||
- Index -> index of the LED
|
||||
- Mode -> uint mapping to the mode enum from libratbag
|
||||
- Type -> string describing the LED type
|
||||
- Color -> uint triplet (RGB) of the LED's color
|
||||
- EffectRate -> the effect rate in Hz, possible values are in the range 100 - 20000
|
||||
- Brightness -> the brightness of the LED, possible values are in the range 0 - 255
|
||||
- Methods:
|
||||
- SetMode(uint) -> set the mode to the given mode enum value from libratbag
|
||||
- SetColor((uuu)) -> set the color to the given uint triplet (RGB)
|
||||
- SetEffectRate(uint) -> set the effect rate in Hz, possible values are in the range 100 - 20000
|
||||
- SetBrightness(int) -> set the brightness, possible values are in the range 0 - 255
|
||||
#### `Devices`
|
||||
- type `ao`, read-only, mutable
|
||||
|
||||
Provides the object paths of all current devices, see **org.freedesktop.ratbag1.Device**
|
||||
|
||||
#### `Themes`
|
||||
- type `as`, 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.
|
||||
|
||||
This list is static for the lifetime of ratbagd.
|
||||
|
||||
### Signals
|
||||
|
||||
#### `DeviceNew(o)`
|
||||
Notifies the client that a new device is available. The new device's
|
||||
object path is provided as argument in the signal.
|
||||
|
||||
This signal is auxilary to the
|
||||
`org.freedesktop.DBus.Properties.PropertyChanged` signal for the `Devices`
|
||||
property.
|
||||
|
||||
#### `DeviceRemoved(o)`
|
||||
|
||||
Notifies the client that a device has been removed. The device's old
|
||||
object path is provided as argument in the signal.
|
||||
|
||||
When this signal is received, all references to this device have been
|
||||
dropped by ratbagd. Further attempts at querying or modifying this
|
||||
device will fail.
|
||||
|
||||
This signal is auxilary to the
|
||||
`org.freedesktop.DBus.Properties.PropertyChanged` signal for the `Devices`
|
||||
property.
|
||||
|
||||
org.freedesktop.ratbag1.Device
|
||||
==============================
|
||||
|
||||
The **org.freedesktop.ratbag1.Device** interface describes a single device
|
||||
known to ratbagd.
|
||||
|
||||
### Properties
|
||||
|
||||
#### `Id`
|
||||
- type: `s`, read-only, constant
|
||||
|
||||
An ID describing this device. This ID should not be used for presentation to
|
||||
the user.
|
||||
|
||||
#### `Description`
|
||||
- type: `s`, read-only, constant
|
||||
|
||||
The device's name, suitable for presentation to the user.
|
||||
|
||||
#### `Capabilities`
|
||||
- type: `au`, read-only, constant
|
||||
|
||||
The capabilities supported by this device. see `enum
|
||||
ratbag_device_capability` in libratbag.h for the list of permissible
|
||||
capabilities.
|
||||
|
||||
|
||||
#### `Svg`
|
||||
- type: `s`, read-only, constant
|
||||
|
||||
The device's SVG file name, without path.
|
||||
|
||||
#### `SvgPath`
|
||||
- type: `s`, read-only, constant
|
||||
|
||||
The device's SVG file name including the absolute path.
|
||||
|
||||
#### `Profiles`
|
||||
- type: `ao`, read-only, mutable
|
||||
|
||||
This property is mutable if the device supports adding and removing
|
||||
profiles.
|
||||
|
||||
Provides the list of profile paths for all profiles on this device, see
|
||||
**org.freedesktop.ratbag1.Profile**.
|
||||
|
||||
#### `ActiveProfile`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
The index of the currently active profile in `Profiles`.
|
||||
|
||||
### Methods
|
||||
|
||||
#### `GetProfileByIndex(u) → (o)`
|
||||
|
||||
Returns the object path for the profile with the given index
|
||||
|
||||
#### `Commit() → ()`
|
||||
|
||||
Commits the changes to the device. Changes to the device are batched; they
|
||||
are not written to the hardware until `Commit()` is invoked.
|
||||
|
||||
#### `GetSvg(s) → (s)`
|
||||
|
||||
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
|
||||
**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.
|
||||
|
||||
org.freedesktop.ratbag1.Profile
|
||||
===============================
|
||||
|
||||
### Properties
|
||||
|
||||
#### `Index`
|
||||
- type: `u`, read-only, constant
|
||||
|
||||
The index of this profile
|
||||
|
||||
#### `Resolutions`
|
||||
- type: `ao`, read-only, mutable
|
||||
|
||||
This property is mutable if the device supports adding and removing
|
||||
resolutions.
|
||||
|
||||
Provides the object paths of all resolutions in this profile, see
|
||||
**org.freedesktop.ratbag1.Resolution**
|
||||
|
||||
#### `Buttons`
|
||||
- type: `ao`, read-only, constant
|
||||
|
||||
Provides the object paths of all buttons in this profile, see
|
||||
**org.freedesktop.ratbag1.Button**
|
||||
|
||||
#### `Leds`
|
||||
- type: `ao`, read-only, constant
|
||||
|
||||
Provides the object paths of all LEDs in this profile, see
|
||||
**org.freedesktop.ratbag1.Led**
|
||||
|
||||
#### `ActiveResolution`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
Index of the currently active resolution in `Resolutions`
|
||||
|
||||
#### `DefaultResolution`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
Index of the default resolution in `Resolutions`
|
||||
|
||||
### Methods
|
||||
|
||||
#### `SetActive() → ()`
|
||||
Set this profile to be the active profile
|
||||
|
||||
#### `GetResolutionByIndex(u) → (o)`
|
||||
Returns the object path for the given index
|
||||
|
||||
### Signals
|
||||
|
||||
#### `ActiveProfileChanged(u)`
|
||||
Active profile changed, carries index of the new active profile
|
||||
|
||||
org.freedesktop.ratbag1.Resolution
|
||||
==================================
|
||||
|
||||
### Properties:
|
||||
#### `Index`
|
||||
- type: `u`, read-only, constant
|
||||
|
||||
Index of the resolution
|
||||
#### `Capabilities`
|
||||
- type: `au`, read-only, constant
|
||||
|
||||
Array of uints with the capabilities enum from libratbag
|
||||
#### `XResolution`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
uint for the x resolution assigned to this entry
|
||||
|
||||
#### `YResolution`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
uint for the y resolution assigned to this entry
|
||||
#### `ReportRate`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
uint for the report rate in Hz assigned to this entry
|
||||
#### `Maximum`
|
||||
- type: `u`, read-only, constant
|
||||
|
||||
uint for the maximum possible resolution
|
||||
#### `Minimum`
|
||||
- type: `u`, read-only, constant
|
||||
|
||||
uint for the minimum possible resolution
|
||||
|
||||
### Methods:
|
||||
|
||||
#### `SetResolution(u, u) → ()`
|
||||
x/y resolution to assign
|
||||
|
||||
#### `SetReportRate(uint) → ()`
|
||||
uint for the report rate to assign
|
||||
#### `SetDefault() → () `
|
||||
|
||||
Set this resolution to be the default
|
||||
|
||||
### Signals:
|
||||
|
||||
#### `ActiveResolutionChanged(u)`
|
||||
Active resolution changed, carries index of the new active resolution
|
||||
#### `DefaultResolutionChanged(u)`
|
||||
Default resolution changed, carries index of the new default resolution
|
||||
|
||||
org.freedesktop.ratbag1.Button
|
||||
==============================
|
||||
|
||||
### Properties:
|
||||
#### `Index`
|
||||
- type: `u`, read-only, constant
|
||||
|
||||
Index of the button
|
||||
#### `Type`
|
||||
- type: `s`, read-only, constant
|
||||
|
||||
String describing the button type
|
||||
#### `ButtonMapping`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
uint of the current button mapping (if mapping to button)
|
||||
#### `SpecialMapping`
|
||||
- type: `s`, read-only, mutable
|
||||
|
||||
String of the current special mapping (if mapped to special)
|
||||
#### `KeyMapping`
|
||||
- type: `au`, read-only, mutable
|
||||
|
||||
Array of uints, first entry is the keycode, other entries, if any, are
|
||||
modifiers (if mapped to key)
|
||||
#### `ActionType`
|
||||
- type: `s`, read-only, mutable
|
||||
|
||||
String describing the action type of the button ("none", "button", "key",
|
||||
"special", "macro", "unknown"). This decides which Mapping property has a
|
||||
value
|
||||
|
||||
#### `ActionTypes`
|
||||
- type: `as`, read-only, constant
|
||||
Array of strings, possible values for ActionType
|
||||
|
||||
### Methods:
|
||||
#### `SetButtonMapping(u) → ()`
|
||||
Set the button mapping to the given button
|
||||
#### `SetSpecialMapping(s) → ()`
|
||||
Set the button mapping to the given special entry
|
||||
#### `SetKeyMapping(au) → ()`
|
||||
Set the key mapping, first entry is the keycode, other entries, if any, are
|
||||
modifier keycodes
|
||||
#### `Disable() → ()`
|
||||
Disable this button
|
||||
|
||||
org.freedesktop.ratbag1.Led
|
||||
===========================
|
||||
|
||||
### Properties:
|
||||
#### `Index`
|
||||
- type: `u`, read-only, constant
|
||||
|
||||
Index of the LED
|
||||
|
||||
#### `Mode`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
uint mapping to the mode enum from libratbag
|
||||
|
||||
#### `Type`
|
||||
- type: `s`, read-only, mutable
|
||||
|
||||
String describing the LED type
|
||||
|
||||
#### `Color`
|
||||
- type: `(uuu)`, read-only, mutable
|
||||
uint triplet (RGB) of the LED's color
|
||||
|
||||
#### `EffectRate`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
The effect rate in Hz, possible values are in the range 100 - 20000
|
||||
|
||||
#### `Brightness`
|
||||
- type: `u`, read-only, mutable
|
||||
|
||||
The brightness of the LED, possible values are in the range 0 - 255
|
||||
|
||||
### Methods:
|
||||
#### `SetMode(u) → ()`
|
||||
Set the mode to the given mode enum value from libratbag
|
||||
#### `SetColor((uuu)) → ()`
|
||||
Set the color to the given uint triplet (RGB)
|
||||
#### `SetEffectRate(u) → ()`
|
||||
Set the effect rate in Hz, possible values are in the range 100 - 20000
|
||||
#### `SetBrightness(i) → ()`
|
||||
Set the brightness, 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
|
||||
|
||||
Reference in New Issue
Block a user