mirror of
https://github.com/libratbag/libratbag.git
synced 2026-11-07 23:23:52 +01:00
f281bd751e
This is superfluous, it's trivial enough to get the Profiles property and then work with that. We're not talking about a huge amount of data anyway. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
294 lines
7.6 KiB
Markdown
294 lines
7.6 KiB
Markdown
The ratbagd DBus-Interface
|
|
--------------------------
|
|
|
|
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
|
|
|
|
For a list of dbus types as used below, see https://dbus.freedesktop.org/doc/dbus-specification.html
|
|
|
|
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.
|
|
|
|
org.freedesktop.ratbag1.Manager
|
|
===============================
|
|
|
|
The **org.freedesktop.ratbag1.Manager** interface is the entry point to
|
|
interact with ratbagd.
|
|
|
|
### Properties
|
|
|
|
#### `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.
|
|
|
|
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.
|
|
|
|
#### `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**.
|
|
|
|
#### `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**
|
|
|
|
### `IsActive`
|
|
- type: `b`, read-only, mutable
|
|
|
|
True if this is the currently active profile, false otherwise.
|
|
|
|
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
|
|
`SetActive()` method to activate a profile.
|
|
|
|
### Methods
|
|
|
|
#### `SetActive() → ()`
|
|
Set this profile to be the 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
|
|
button 10 on profile 0 on event5. The naming is subject to change. Do not
|
|
rely on a constructed object path in your application.
|
|
|
|
|