Data Structures
struct	ratbag_button
	Represents a button on the device. 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...

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

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

int	ratbag_button_set_key (struct ratbag_button button, unsigned int key, unsigned int modifiers, size_t sz)

int	ratbag_button_disable (struct ratbag_button *button)

const char *	ratbag_button_get_macro_name (struct ratbag_button *button)
	If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns the macro name. More...

enum ratbag_macro_event_type	ratbag_button_get_macro_event_type (struct ratbag_button *button, unsigned int index)
	If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns the macro event type configured for the event at the given index. More...

int	ratbag_button_get_macro_event_key (struct ratbag_button *button, unsigned int index)
	If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, and 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_get_macro_event_timeout (struct ratbag_button *button, unsigned int index)
	If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, and 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...

int	ratbag_button_set_macro (struct ratbag_button button, const char name)
	Sets the button's action to RATBAG_BUTTON_ACTION_TYPE_MACRO and allocates the required memory to store the macro. More...

int	ratbag_button_set_macro_event (struct ratbag_button *button, 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 *	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

enum ratbag_button_action_special

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

enum ratbag_button_action_type

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.

enum ratbag_button_type

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

enum ratbag_macro_event_type

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

int ratbag_button_disable ( struct ratbag_button * button )

Parameters

button A previously initialized ratbag button

Returns: 0 on success or nonzero 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

0	This 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

	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

int ratbag_button_get_macro_event_key	(	struct ratbag_button *	button,
		unsigned int	index
	)

If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, and 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.

If the button's action type is not RATBAG_BUTTON_ACTION_TYPE_MACRO, or if the event stored at the given index is not RATBAG_MACRO_EVENT_KEY_PRESSED or RATBAG_MACRO_EVENT_KEY_RELEASED, this function returns -EINVAL.

Parameters

button	A previously initialized ratbag button
index	An index of the event within the macro we are interested in.

Returns: The key of the event at the given index

int ratbag_button_get_macro_event_timeout	(	struct ratbag_button *	button,
		unsigned int	index
	)

If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, and 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.

If the button's action type is not RATBAG_BUTTON_ACTION_TYPE_MACRO, or if the event stored at the given index is not RATBAG_MACRO_EVENT_WAIT, this function returns -EINVAL.

Parameters

button	A previously initialized ratbag button
index	An index of the event within the macro we are interested in.

Returns: The tiemout of the event at the given index

enum ratbag_macro_event_type ratbag_button_get_macro_event_type	(	struct ratbag_button *	button,
		unsigned int	index
	)

If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns the macro event type configured for the event at the given index.

If the button's action type is not RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns RATBAG_MACRO_EVENT_INVALID.

Parameters

button	A previously initialized ratbag button
index	An 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_get_macro_name ( struct ratbag_button * button )

If a button's action is RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns the macro name.

If the button's action type is not RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns NULL.

Parameters

button A previously initialized ratbag button

Returns: The name of the macro associated to the 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

button A 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

button	A previously initialized button
action_type	An action type

Returns: non-zero if the action type is supported, zero otherwise.

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

int 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 nonzero otherwise. On success, the button's action is set to RATBAG_BUTTON_ACTION_TYPE_BUTTON.

See also: ratbag_button_get_button

int 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 nonzero otherwise. On success, the button's action is set to RATBAG_BUTTON_ACTION_TYPE_KEY.

int ratbag_button_set_macro	(	struct ratbag_button *	button,
		const char *	name
	)

Sets the button's action to RATBAG_BUTTON_ACTION_TYPE_MACRO and allocates the required memory to store the macro.

int ratbag_button_set_macro_event	(	struct ratbag_button *	button,
		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.

int 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 nonzero 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

button	A previously initialized button
userdata	Caller-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

button A previously initialized ratbag button

Returns: Always NULL

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation