Button configuration

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...
 

Enumerations

enum  ratbag_button_type {
  RATBAG_BUTTON_TYPE_UNKNOWN, RATBAG_BUTTON_TYPE_LEFT, RATBAG_BUTTON_TYPE_MIDDLE, RATBAG_BUTTON_TYPE_RIGHT,
  RATBAG_BUTTON_TYPE_THUMB, RATBAG_BUTTON_TYPE_THUMB2, RATBAG_BUTTON_TYPE_THUMB3, RATBAG_BUTTON_TYPE_THUMB4,
  RATBAG_BUTTON_TYPE_WHEEL_LEFT, RATBAG_BUTTON_TYPE_WHEEL_RIGHT, RATBAG_BUTTON_TYPE_WHEEL_CLICK, RATBAG_BUTTON_TYPE_WHEEL_UP,
  RATBAG_BUTTON_TYPE_WHEEL_DOWN, RATBAG_BUTTON_TYPE_WHEEL_RATCHET_MODE_SHIFT, RATBAG_BUTTON_TYPE_EXTRA, RATBAG_BUTTON_TYPE_SIDE,
  RATBAG_BUTTON_TYPE_PINKIE, RATBAG_BUTTON_TYPE_PINKIE2, RATBAG_BUTTON_TYPE_RESOLUTION_CYCLE_UP, RATBAG_BUTTON_TYPE_RESOLUTION_UP,
  RATBAG_BUTTON_TYPE_RESOLUTION_DOWN, RATBAG_BUTTON_TYPE_PROFILE_CYCLE_UP, RATBAG_BUTTON_TYPE_PROFILE_UP, RATBAG_BUTTON_TYPE_PROFILE_DOWN
}
 Button types describing the physical button. More...
 
enum  ratbag_button_action_type {
  RATBAG_BUTTON_ACTION_TYPE_UNKNOWN, RATBAG_BUTTON_ACTION_TYPE_NONE, RATBAG_BUTTON_ACTION_TYPE_BUTTON, RATBAG_BUTTON_ACTION_TYPE_SPECIAL,
  RATBAG_BUTTON_ACTION_TYPE_KEY, RATBAG_BUTTON_ACTION_TYPE_MACRO
}
 The type assigned to a button. More...
 
enum  ratbag_button_action_special {
  RATBAG_BUTTON_ACTION_SPECIAL_INVALID, RATBAG_BUTTON_ACTION_SPECIAL_UNKNOWN, RATBAG_BUTTON_ACTION_SPECIAL_DOUBLECLICK, RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_LEFT,
  RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_RIGHT, RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_UP, RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_DOWN, RATBAG_BUTTON_ACTION_SPECIAL_RATCHET_MODE_SWITCH,
  RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_CYCLE_UP, RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_UP, RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_DOWN, RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_ALTERNATE,
  RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_DEFAULT, RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_CYCLE_UP, RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_UP, RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_DOWN,
  RATBAG_BUTTON_ACTION_SPECIAL_SECOND_MODE, RATBAG_BUTTON_ACTION_SPECIAL_BATTERY_LEVEL
}
 
enum  ratbag_macro_event_type {
  RATBAG_MACRO_EVENT_INVALID, RATBAG_MACRO_EVENT_NONE, RATBAG_MACRO_EVENT_KEY_PRESSED, RATBAG_MACRO_EVENT_KEY_RELEASED,
  RATBAG_MACRO_EVENT_WAIT
}
 Macro event types describing the event. 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_buttonratbag_button_ref (struct ratbag_button *button)
 Add a reference to the button. More...
 
struct ratbag_buttonratbag_button_unref (struct ratbag_button *button)
 Dereference the ratbag button. More...
 

Detailed Description

Enumeration Type Documentation

Enumerator
RATBAG_BUTTON_ACTION_SPECIAL_INVALID 

This button is not set up for a special action.

RATBAG_BUTTON_ACTION_SPECIAL_UNKNOWN 
RATBAG_BUTTON_ACTION_SPECIAL_DOUBLECLICK 
RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_LEFT 
RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_RIGHT 
RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_UP 
RATBAG_BUTTON_ACTION_SPECIAL_WHEEL_DOWN 
RATBAG_BUTTON_ACTION_SPECIAL_RATCHET_MODE_SWITCH 
RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_CYCLE_UP 
RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_UP 
RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_DOWN 
RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_ALTERNATE 
RATBAG_BUTTON_ACTION_SPECIAL_RESOLUTION_DEFAULT 
RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_CYCLE_UP 
RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_UP 
RATBAG_BUTTON_ACTION_SPECIAL_PROFILE_DOWN 
RATBAG_BUTTON_ACTION_SPECIAL_SECOND_MODE 
RATBAG_BUTTON_ACTION_SPECIAL_BATTERY_LEVEL 

The type assigned to a button.

Enumerator
RATBAG_BUTTON_ACTION_TYPE_UNKNOWN 

Button action is unknown.

RATBAG_BUTTON_ACTION_TYPE_NONE 

Button is disabled.

RATBAG_BUTTON_ACTION_TYPE_BUTTON 

Button sends numeric button events.

RATBAG_BUTTON_ACTION_TYPE_SPECIAL 

Button triggers a mouse-specific special function.

This includes resolution changes and profile changes.

RATBAG_BUTTON_ACTION_TYPE_KEY 

Button sends a key or key + modifier combination.

RATBAG_BUTTON_ACTION_TYPE_MACRO 

Button sends a user-defined key or button sequence.

Button types describing the physical button.

Enumerator
RATBAG_BUTTON_TYPE_UNKNOWN 
RATBAG_BUTTON_TYPE_LEFT 
RATBAG_BUTTON_TYPE_MIDDLE 
RATBAG_BUTTON_TYPE_RIGHT 
RATBAG_BUTTON_TYPE_THUMB 
RATBAG_BUTTON_TYPE_THUMB2 
RATBAG_BUTTON_TYPE_THUMB3 
RATBAG_BUTTON_TYPE_THUMB4 
RATBAG_BUTTON_TYPE_WHEEL_LEFT 
RATBAG_BUTTON_TYPE_WHEEL_RIGHT 
RATBAG_BUTTON_TYPE_WHEEL_CLICK 
RATBAG_BUTTON_TYPE_WHEEL_UP 
RATBAG_BUTTON_TYPE_WHEEL_DOWN 
RATBAG_BUTTON_TYPE_WHEEL_RATCHET_MODE_SHIFT 

A button to toggle the wheel from free-spinning to click-based.

RATBAG_BUTTON_TYPE_EXTRA 
RATBAG_BUTTON_TYPE_SIDE 
RATBAG_BUTTON_TYPE_PINKIE 
RATBAG_BUTTON_TYPE_PINKIE2 
RATBAG_BUTTON_TYPE_RESOLUTION_CYCLE_UP 
RATBAG_BUTTON_TYPE_RESOLUTION_UP 
RATBAG_BUTTON_TYPE_RESOLUTION_DOWN 
RATBAG_BUTTON_TYPE_PROFILE_CYCLE_UP 
RATBAG_BUTTON_TYPE_PROFILE_UP 
RATBAG_BUTTON_TYPE_PROFILE_DOWN 

Macro event types describing the event.

Enumerator
RATBAG_MACRO_EVENT_INVALID 
RATBAG_MACRO_EVENT_NONE 
RATBAG_MACRO_EVENT_KEY_PRESSED 
RATBAG_MACRO_EVENT_KEY_RELEASED 
RATBAG_MACRO_EVENT_WAIT 

Function Documentation

enum ratbag_error_code ratbag_button_disable ( struct ratbag_button button)
Parameters
buttonA 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.
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
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
0This button is disabled or its action type is not RATBAG_BUTTON_ACTION_TYPE_BUTTON.
See also
ratbag_button_set_button
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
buttonA previously initialized ratbag button
[out]modifiersWill be filled with the modifiers required for this action. The modifiers are as defined in linux/input.h.
[in,out]szTakes 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
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
buttonA previously initialized ratbag button
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
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
void* ratbag_button_get_user_data ( const struct ratbag_button button)

Get the caller-specific data associated with this button, if any.

Parameters
buttonA previously initialized ratbag button
Returns
The caller-specific data previously assigned in ratbag_button_set_user_data().
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
buttonA previously initialized button
action_typeAn action type
Returns
non-zero if the action type is supported, zero otherwise.
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
macroA previously initialized ratbag button macro
indexAn index of the event within the macro we are interested in.
Returns
The key of the event at the given index
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
macroA previously initialized ratbag button macro
indexAn index of the event within the macro we are interested in.
Returns
The timeout of the event at the given index
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
macroA previously initialized ratbag button macro
indexAn index of the event within the macro we are interested in.
Returns
The type of the event at the given index
const char* ratbag_button_macro_get_name ( struct ratbag_button_macro *  macro)
Parameters
macroA previously initialized ratbag button macro
Returns
The name of the macro
unsigned int ratbag_button_macro_get_num_events ( struct ratbag_button_macro *  macro)
Parameters
macroA previously initialized ratbag button macro
Returns
The maximum number of events that can be assigned to this macro
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
nameThe name to assign to this macro.
Returns
An "empty" button macro
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
macroA previously initialized valid ratbag button macro
Returns
The passed ratbag macro
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.

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
macroA previously initialized ratbag button macro
Returns
Always NULL
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
buttonA previously initialized valid ratbag button
Returns
The passed ratbag 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
buttonA previously initialized ratbag button
btnThe 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
enum ratbag_error_code ratbag_button_set_key ( struct ratbag_button button,
unsigned int  key,
unsigned int *  modifiers,
size_t  sz 
)
Parameters
buttonA previously initialized ratbag button
keyThe button number to assign to this button, one of BTN_* as defined in linux/input.h
modifiersThe modifiers required for this action. The modifiers are as defined in linux/input.h, in the order they should be pressed.
szThe 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.
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
buttonA previously intialized ratbag button
macroA fully initialized macro
Returns
0 on success or nonzero otherwise
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
buttonA previously initialized ratbag button
actionThe 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
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
buttonA previously initialized button
userdataCaller-specific data passed to the various callback interfaces.
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
buttonA previously initialized ratbag button
Returns
Always NULL