Data Structures | |
struct | ratbag_button |
Represents a button on the device. More... | |
struct | ratbag_macro |
Represents a macro that can be assigned to a button. More... | |
Functions | |
void | ratbag_button_set_user_data (struct ratbag_button *button, void *userdata) |
Set caller-specific data associated with this button. More... | |
void * | ratbag_button_get_user_data (const struct ratbag_button *button) |
Get the caller-specific data associated with this button, if any. More... | |
enum ratbag_button_type | ratbag_button_get_type (struct ratbag_button *button) |
Return the type of the physical button. More... | |
enum ratbag_button_action_type | ratbag_button_get_action_type (struct ratbag_button *button) |
int | ratbag_button_has_action_type (struct ratbag_button *button, enum ratbag_button_action_type action_type) |
Check if a button supports a specific action type. More... | |
unsigned int | ratbag_button_get_button (struct ratbag_button *button) |
If a button's action is RATBAG_BUTTON_ACTION_TYPE_BUTTON, this function returns the logical button number this button is mapped to, starting at 1. More... | |
enum ratbag_error_code | ratbag_button_set_button (struct ratbag_button *button, unsigned int btn) |
See ratbag_button_get_button() for a description of the button number. More... | |
enum ratbag_button_action_special | ratbag_button_get_special (struct ratbag_button *button) |
If a button's action is RATBAG_BUTTON_ACTION_TYPE_SPECIAL, this function returns the special function assigned to this button. More... | |
enum ratbag_error_code | ratbag_button_set_special (struct ratbag_button *button, enum ratbag_button_action_special action) |
This function sets the special function assigned to this button. More... | |
unsigned int | ratbag_button_get_key (struct ratbag_button *button, unsigned int *modifiers, size_t *sz) |
If a button's action is RATBAG_BUTTON_ACTION_TYPE_KEY, this function returns the key or button configured for this button. More... | |
enum ratbag_error_code | ratbag_button_set_key (struct ratbag_button *button, unsigned int key, unsigned int *modifiers, size_t sz) |
enum ratbag_error_code | ratbag_button_disable (struct ratbag_button *button) |
const char * | ratbag_button_macro_get_name (struct ratbag_button_macro *macro) |
unsigned int | ratbag_button_macro_get_num_events (struct ratbag_button_macro *macro) |
enum ratbag_macro_event_type | ratbag_button_macro_get_event_type (struct ratbag_button_macro *macro, unsigned int index) |
Returns the macro event type configured for the event at the given index. More... | |
int | ratbag_button_macro_get_event_key (struct ratbag_button_macro *macro, unsigned int index) |
If the event stored at the given index is RATBAG_MACRO_EVENT_KEY_PRESSED or RATBAG_MACRO_EVENT_KEY_RELEASED, this function returns the key code configured for the event at the given index. More... | |
int | ratbag_button_macro_get_event_timeout (struct ratbag_button_macro *macro, unsigned int index) |
If the event stored at the given index is RATBAG_MACRO_EVENT_WAIT, this function returns the timeout configured for the event at the given index. More... | |
enum ratbag_error_code | ratbag_button_set_macro (struct ratbag_button *button, const struct ratbag_button_macro *macro) |
Sets the button's action to RATBAG_BUTTON_ACTION_TYPE_MACRO and assigns the given macro to this button. More... | |
struct ratbag_button_macro * | ratbag_button_macro_new (const char *name) |
Initialize a new button macro. More... | |
struct ratbag_button_macro * | ratbag_button_get_macro (struct ratbag_button *button) |
If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns the current button macro. More... | |
enum ratbag_error_code | ratbag_button_macro_set_event (struct ratbag_button_macro *macro, unsigned int index, enum ratbag_macro_event_type type, unsigned int data) |
Sets the macro's event at the given index to the given type with the key code or timeout given. More... | |
struct ratbag_button_macro * | ratbag_button_macro_ref (struct ratbag_button_macro *macro) |
Add a reference to the macro. More... | |
struct ratbag_button_macro * | ratbag_button_macro_unref (struct ratbag_button_macro *macro) |
Dereference the ratbag button macro. More... | |
struct ratbag_button * | ratbag_button_ref (struct ratbag_button *button) |
Add a reference to the button. More... | |
struct ratbag_button * | ratbag_button_unref (struct ratbag_button *button) |
Dereference the ratbag button. More... | |
Detailed Description
Enumeration Type Documentation
◆ ratbag_button_action_special
◆ ratbag_button_action_type
The type assigned to a button.
◆ ratbag_button_type
enum ratbag_button_type |
Button types describing the physical button.
◆ ratbag_macro_event_type
Function Documentation
◆ ratbag_button_disable()
enum ratbag_error_code ratbag_button_disable | ( | struct ratbag_button * | button | ) |
- Parameters
-
button A previously initialized ratbag button
- Returns
- 0 on success or an error code otherwise. On success, the button's action is set to RATBAG_BUTTON_ACTION_TYPE_NONE.
◆ ratbag_button_get_action_type()
enum ratbag_button_action_type ratbag_button_get_action_type | ( | struct ratbag_button * | button | ) |
- Returns
- The type of the action currently configured for this button
◆ ratbag_button_get_button()
unsigned int ratbag_button_get_button | ( | struct ratbag_button * | button | ) |
If a button's action is RATBAG_BUTTON_ACTION_TYPE_BUTTON, this function returns the logical button number this button is mapped to, starting at 1.
The button numbers are in sequence and do not correspond to any meaning other than its numeric value. It is up to the input stack how to map that logical button number, but usually buttons 1, 2 and 3 are mapped into left, middle, right.
If the button's action type is not RATBAG_BUTTON_ACTION_TYPE_BUTTON, this function returns 0.
- Returns
- The logical button number this button sends.
- Return values
-
0 This button is disabled or its action type is not RATBAG_BUTTON_ACTION_TYPE_BUTTON.
- See also
- ratbag_button_set_button
◆ ratbag_button_get_key()
unsigned int ratbag_button_get_key | ( | struct ratbag_button * | button, |
unsigned int * | modifiers, | ||
size_t * | sz | ||
) |
If a button's action is RATBAG_BUTTON_ACTION_TYPE_KEY, this function returns the key or button configured for this button.
If the button's action type is not RATBAG_BUTTON_ACTION_TYPE_KEY, this function returns 0 and leaves modifiers and sz untouched.
- Parameters
-
button A previously initialized ratbag button [out] modifiers Will be filled with the modifiers required for this action. The modifiers are as defined in linux/input.h. [in,out] sz Takes the size of the modifiers array and returns the number of modifiers filled in. sz may be 0 if no modifiers are required.
- Note
- The caller must ensure that modifiers is large enough to accomodate for the key combination.
- Returns
- The button number
◆ ratbag_button_get_macro()
struct ratbag_button_macro* ratbag_button_get_macro | ( | struct ratbag_button * | button | ) |
If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns the current button macro.
The macro is a copy of the one used on the device, changes to the macro are not reflected on the device until a subsequent call to ratbag_button_set_macro().
If a button's action is not RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns NULL.
- Parameters
-
button A previously initialized ratbag button
◆ ratbag_button_get_special()
enum ratbag_button_action_special ratbag_button_get_special | ( | struct ratbag_button * | button | ) |
If a button's action is RATBAG_BUTTON_ACTION_TYPE_SPECIAL, this function returns the special function assigned to this button.
If the button's action type is not RATBAG_BUTTON_ACTION_TYPE_SPECIAL, this function returns RATBAG_BUTTON_ACTION_SPECIAL_INVALID.
- Returns
- The special function assigned to this button
- See also
- ratbag_button_set_button
◆ ratbag_button_get_type()
enum ratbag_button_type ratbag_button_get_type | ( | struct ratbag_button * | button | ) |
Return the type of the physical button.
This function is intended to be used by configuration tools to provide a generic list of button names or handles to configure devices. The type describes the physical location of the button and remains constant for the lifetime of the device. For example, a button of type RATBAG_BUTTON_TYPE_WHEEL_CLICK may be mapped to a logical middle button, but the physical description is that of a wheel click.
For the button currently mapped to this physical button, see ratbag_button_get_button()
- Returns
- The type of the button
◆ ratbag_button_get_user_data()
void* ratbag_button_get_user_data | ( | const struct ratbag_button * | button | ) |
Get the caller-specific data associated with this button, if any.
- Parameters
-
button A previously initialized ratbag button
- Returns
- The caller-specific data previously assigned in ratbag_button_set_user_data().
◆ ratbag_button_has_action_type()
int ratbag_button_has_action_type | ( | struct ratbag_button * | button, |
enum ratbag_button_action_type | action_type | ||
) |
Check if a button supports a specific action type.
Not all devices allow all buttons to be assigned any action. Ability to change a button to a given action type does not guarantee that any specific action can be configured.
- Note
- It is a client bug to pass in RATBAG_BUTTON_ACTION_TYPE_UNKNOWN or RATBAG_BUTTON_ACTION_TYPE_NONE.
- Parameters
-
button A previously initialized button action_type An action type
- Returns
- non-zero if the action type is supported, zero otherwise.
◆ ratbag_button_macro_get_event_key()
int ratbag_button_macro_get_event_key | ( | struct ratbag_button_macro * | macro, |
unsigned int | index | ||
) |
If the event stored at the given index is RATBAG_MACRO_EVENT_KEY_PRESSED or RATBAG_MACRO_EVENT_KEY_RELEASED, this function returns the key code configured for the event at the given index.
The behavior of this function for an index equal to or greater than the return value of ratbag_button_macro_get_num_events() is undefined.
- Parameters
-
macro A previously initialized ratbag button macro index An index of the event within the macro we are interested in.
- Returns
- The key of the event at the given index
◆ ratbag_button_macro_get_event_timeout()
int ratbag_button_macro_get_event_timeout | ( | struct ratbag_button_macro * | macro, |
unsigned int | index | ||
) |
If the event stored at the given index is RATBAG_MACRO_EVENT_WAIT, this function returns the timeout configured for the event at the given index.
The behavior of this function for an index equal to or greater than the return value of ratbag_button_macro_get_num_events() is undefined.
- Parameters
-
macro A previously initialized ratbag button macro index An index of the event within the macro we are interested in.
- Returns
- The timeout of the event at the given index
◆ ratbag_button_macro_get_event_type()
enum ratbag_macro_event_type ratbag_button_macro_get_event_type | ( | struct ratbag_button_macro * | macro, |
unsigned int | index | ||
) |
Returns the macro event type configured for the event at the given index.
The behavior of this function for an index equal to or greater than the return value of ratbag_button_macro_get_num_events() is undefined.
- Parameters
-
macro A previously initialized ratbag button macro index An index of the event within the macro we are interested in.
- Returns
- The type of the event at the given index
◆ ratbag_button_macro_get_name()
const char* ratbag_button_macro_get_name | ( | struct ratbag_button_macro * | macro | ) |
- Parameters
-
macro A previously initialized ratbag button macro
- Returns
- The name of the macro
◆ ratbag_button_macro_get_num_events()
unsigned int ratbag_button_macro_get_num_events | ( | struct ratbag_button_macro * | macro | ) |
- Parameters
-
macro A previously initialized ratbag button macro
- Returns
- The maximum number of events that can be assigned to this macro
◆ ratbag_button_macro_new()
struct ratbag_button_macro* ratbag_button_macro_new | ( | const char * | name | ) |
Initialize a new button macro.
The macro is refcounted with an initial value of at least 1. Use ratbag_button_macro_unref() to release the macro.
Note that some devices have limited storage for the macro names. libratbag silently shortens macro names to the longest string the device is capable of storing.
- Parameters
-
name The name to assign to this macro.
- Returns
- An "empty" button macro
◆ ratbag_button_macro_ref()
struct ratbag_button_macro* ratbag_button_macro_ref | ( | struct ratbag_button_macro * | macro | ) |
Add a reference to the macro.
A macro is destroyed whenever the reference count reaches 0. See ratbag_button_macro_unref.
- Parameters
-
macro A previously initialized valid ratbag button macro
- Returns
- The passed ratbag macro
◆ ratbag_button_macro_set_event()
enum ratbag_error_code ratbag_button_macro_set_event | ( | struct ratbag_button_macro * | macro, |
unsigned int | index, | ||
enum ratbag_macro_event_type | type, | ||
unsigned int | data | ||
) |
Sets the macro's event at the given index to the given type with the key code or timeout given.
The behavior of this function for an index equal to or greater than the return value of ratbag_button_macro_get_num_events() is undefined.
◆ ratbag_button_macro_unref()
struct ratbag_button_macro* ratbag_button_macro_unref | ( | struct ratbag_button_macro * | macro | ) |
Dereference the ratbag button macro.
When the internal refcount reaches zero, all resources associated with this object are released. The object must be considered invalid once unref is called.
- Parameters
-
macro A previously initialized ratbag button macro
- Returns
- Always NULL
◆ ratbag_button_ref()
struct ratbag_button* ratbag_button_ref | ( | struct ratbag_button * | button | ) |
Add a reference to the button.
A button is destroyed whenever the reference count reaches 0. See ratbag_button_unref.
- Parameters
-
button A previously initialized valid ratbag button
- Returns
- The passed ratbag button
◆ ratbag_button_set_button()
enum ratbag_error_code ratbag_button_set_button | ( | struct ratbag_button * | button, |
unsigned int | btn | ||
) |
See ratbag_button_get_button() for a description of the button number.
- Parameters
-
button A previously initialized ratbag button btn The logical button number to assign to this button.
- Returns
- 0 on success or an error code otherwise. On success, the button's action is set to RATBAG_BUTTON_ACTION_TYPE_BUTTON.
- See also
- ratbag_button_get_button
◆ ratbag_button_set_key()
enum ratbag_error_code ratbag_button_set_key | ( | struct ratbag_button * | button, |
unsigned int | key, | ||
unsigned int * | modifiers, | ||
size_t | sz | ||
) |
- Parameters
-
button A previously initialized ratbag button key The button number to assign to this button, one of BTN_* as defined in linux/input.h modifiers The modifiers required for this action. The modifiers are as defined in linux/input.h, in the order they should be pressed. sz The size of the modifiers array. sz may be 0 if no modifiers are required.
- Returns
- 0 on success or an error code otherwise. On success, the button's action is set to RATBAG_BUTTON_ACTION_TYPE_KEY.
◆ ratbag_button_set_macro()
enum ratbag_error_code ratbag_button_set_macro | ( | struct ratbag_button * | button, |
const struct ratbag_button_macro * | macro | ||
) |
Sets the button's action to RATBAG_BUTTON_ACTION_TYPE_MACRO and assigns the given macro to this button.
libratbag does not use the macro struct passed in, it extracts the required information from the struct. Changes to the macro after a call to ratbag_button_set_macro() are not reflected in the device until a subsequent call to ratbag_button_set_macro().
- Parameters
-
button A previously intialized ratbag button macro A fully initialized macro
- Returns
- 0 on success or nonzero otherwise
◆ ratbag_button_set_special()
enum ratbag_error_code ratbag_button_set_special | ( | struct ratbag_button * | button, |
enum ratbag_button_action_special | action | ||
) |
This function sets the special function assigned to this button.
- Parameters
-
button A previously initialized ratbag button action The special action to assign to this button.
- Returns
- 0 on success or an error code otherwise. On success, the button's action is set to RATBAG_BUTTON_ACTION_TYPE_SPECIAL.
- See also
- ratbag_button_get_button
◆ ratbag_button_set_user_data()
void ratbag_button_set_user_data | ( | struct ratbag_button * | button, |
void * | userdata | ||
) |
Set caller-specific data associated with this button.
libratbag does not manage, look at, or modify this data. The caller must ensure the data is valid.
- Parameters
-
button A previously initialized button userdata Caller-specific data passed to the various callback interfaces.
◆ ratbag_button_unref()
struct ratbag_button* ratbag_button_unref | ( | struct ratbag_button * | button | ) |
Dereference the ratbag button.
When the internal refcount reaches zero, all resources associated with this object are released. The object must be considered invalid once unref is called.
- Parameters
-
button A previously initialized ratbag button
- Returns
- Always NULL