Handling the virtual mode groups of buttons, strips and rings on tablet pad devices. More...

Data Structures
struct	libinput_tablet_pad_mode_group
	A mode on a tablet pad is a virtual grouping of functionality, usually based on some visual feedback like LEDs on the pad. More...

Functions
int	libinput_device_tablet_pad_get_num_mode_groups (struct libinput_device *device)
	Most devices only provide a single mode group, however devices such as the Wacom Cintiq 22HD provide two mode groups.

struct libinput_tablet_pad_mode_group *	libinput_device_tablet_pad_get_mode_group (struct libinput_device *device, unsigned int index)
	The returned mode group is not refcounted and may become invalid after the next call to libinput.

unsigned int	libinput_tablet_pad_mode_group_get_index (struct libinput_tablet_pad_mode_group *group)
	The returned number is the same index as passed to libinput_device_tablet_pad_get_mode_group().

unsigned int	libinput_tablet_pad_mode_group_get_num_modes (struct libinput_tablet_pad_mode_group *group)
	Query the mode group for the number of available modes.

unsigned int	libinput_tablet_pad_mode_group_get_mode (struct libinput_tablet_pad_mode_group *group)
	Return the current mode this mode group is in.

int	libinput_tablet_pad_mode_group_has_button (struct libinput_tablet_pad_mode_group *group, unsigned int button)
	Devices without mode switching capabilities return true for every button.

int	libinput_tablet_pad_mode_group_has_ring (struct libinput_tablet_pad_mode_group *group, unsigned int ring)
	Devices without mode switching capabilities return true for every ring.

int	libinput_tablet_pad_mode_group_has_strip (struct libinput_tablet_pad_mode_group *group, unsigned int strip)
	Devices without mode switching capabilities return true for every strip.

int	libinput_tablet_pad_mode_group_button_is_toggle (struct libinput_tablet_pad_mode_group *group, unsigned int button)
	The toggle button in a mode group is the button assigned to cycle to or directly assign a new mode when pressed.

struct libinput_tablet_pad_mode_group *	libinput_tablet_pad_mode_group_ref (struct libinput_tablet_pad_mode_group *group)
	Increase the refcount of the mode group.

struct libinput_tablet_pad_mode_group *	libinput_tablet_pad_mode_group_unref (struct libinput_tablet_pad_mode_group *group)
	Decrease the refcount of the mode group.

void	libinput_tablet_pad_mode_group_set_user_data (struct libinput_tablet_pad_mode_group group, void user_data)
	Set caller-specific data associated with this mode group.

void *	libinput_tablet_pad_mode_group_get_user_data (struct libinput_tablet_pad_mode_group *group)
	Get the caller-specific data associated with this mode group, if any.

Detailed Description

Handling the virtual mode groups of buttons, strips and rings on tablet pad devices.

See the libinput documentation for more details.

Function Documentation

◆ libinput_device_tablet_pad_get_mode_group()

struct libinput_tablet_pad_mode_group * libinput_device_tablet_pad_get_mode_group	(	struct libinput_device *	device,
		unsigned int	index
	)

The returned mode group is not refcounted and may become invalid after the next call to libinput.

Use libinput_tablet_pad_mode_group_ref() and libinput_tablet_pad_mode_group_unref() to continue using the handle outside of the immediate scope.

While at least one reference is kept by the caller, the returned mode group will be identical for each subsequent call of this function with the same index and that same struct is returned from libinput_event_tablet_pad_get_mode_group(), provided the event was generated by this mode group.

Parameters

device	A device with the LIBINPUT_DEVICE_CAP_TABLET_PAD capability
index	A mode group index

Returns: the mode group with the given index or NULL if an invalid index is given.

Since: 1.4

◆ libinput_device_tablet_pad_get_num_mode_groups()

int libinput_device_tablet_pad_get_num_mode_groups ( struct libinput_device * device )

Most devices only provide a single mode group, however devices such as the Wacom Cintiq 22HD provide two mode groups.

If multiple mode groups are available, a caller should use libinput_tablet_pad_mode_group_has_button(), libinput_tablet_pad_mode_group_has_ring() and libinput_tablet_pad_mode_group_has_strip() to associate each button, ring and strip with the correct mode group.

Returns: the number of mode groups available on this device

Since: 1.4

◆ libinput_tablet_pad_mode_group_button_is_toggle()

int libinput_tablet_pad_mode_group_button_is_toggle	(	struct libinput_tablet_pad_mode_group *	group,
		unsigned int	button
	)

The toggle button in a mode group is the button assigned to cycle to or directly assign a new mode when pressed.

Not all devices have a toggle button and some devices may have more than one toggle button. For example, the Wacom Cintiq 24HD has six toggle buttons in two groups, each directly selecting one of the three modes per group.

Devices without mode switching capabilities return false for every button.

Parameters

group	A previously obtained mode group
button	A button index, starting at 0

Return values

non-zero if the button is a mode toggle button for this group, or zero otherwise

Since: 1.4

◆ libinput_tablet_pad_mode_group_get_index()

unsigned int libinput_tablet_pad_mode_group_get_index ( struct libinput_tablet_pad_mode_group * group )

The returned number is the same index as passed to libinput_device_tablet_pad_get_mode_group().

For tablets with only one mode this number is always 0.

Parameters

group A previously obtained mode group

Returns: the numeric index this mode group represents, starting at 0

Since: 1.4

◆ libinput_tablet_pad_mode_group_get_mode()

unsigned int libinput_tablet_pad_mode_group_get_mode ( struct libinput_tablet_pad_mode_group * group )

Return the current mode this mode group is in.

Note that the returned mode is the mode valid as of completing the last libinput_dispatch(). The returned mode may thus be different than the mode returned by libinput_event_tablet_pad_get_mode().

For example, if the mode was toggled three times between the call to libinput_dispatch(), this function returns the third mode but the events in the event queue will return the modes 1, 2 and 3, respectively.

Parameters

group A previously obtained mode group

Returns: the numeric index of the current mode in this group, starting at 0

See also: libinput_event_tablet_pad_get_mode

Since: 1.4

◆ libinput_tablet_pad_mode_group_get_num_modes()

unsigned int libinput_tablet_pad_mode_group_get_num_modes ( struct libinput_tablet_pad_mode_group * group )

Query the mode group for the number of available modes.

The number of modes is usually decided by the number of physical LEDs available on the device. Different mode groups may have a different number of modes. Use libinput_tablet_pad_mode_group_get_mode() to get the currently active mode.

libinput guarantees that at least one mode is available. A device without mode switching capability has a single mode group and a single mode.

Parameters

group A previously obtained mode group

Returns: the number of modes available in this mode group

Since: 1.4

◆ libinput_tablet_pad_mode_group_get_user_data()

void * libinput_tablet_pad_mode_group_get_user_data ( struct libinput_tablet_pad_mode_group * group )

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

Parameters

group A previously obtained mode group

Returns: Caller-specific data pointer or NULL if none was set

See also: libinput_tablet_pad_mode_group_set_user_data

Since: 1.4

◆ libinput_tablet_pad_mode_group_has_button()

int libinput_tablet_pad_mode_group_has_button	(	struct libinput_tablet_pad_mode_group *	group,
		unsigned int	button
	)

Devices without mode switching capabilities return true for every button.

Parameters

group	A previously obtained mode group
button	A button index, starting at 0

Returns: true if the given button index is part of this mode group or false otherwise

Since: 1.4

◆ libinput_tablet_pad_mode_group_has_ring()

int libinput_tablet_pad_mode_group_has_ring	(	struct libinput_tablet_pad_mode_group *	group,
		unsigned int	ring
	)

Devices without mode switching capabilities return true for every ring.

Parameters

group	A previously obtained mode group
ring	A ring index, starting at 0

Returns: true if the given ring index is part of this mode group or false otherwise

Since: 1.4

◆ libinput_tablet_pad_mode_group_has_strip()

int libinput_tablet_pad_mode_group_has_strip	(	struct libinput_tablet_pad_mode_group *	group,
		unsigned int	strip
	)

Devices without mode switching capabilities return true for every strip.

Parameters

group	A previously obtained mode group
strip	A strip index, starting at 0

Returns: true if the given strip index is part of this mode group or false otherwise

Since: 1.4

◆ libinput_tablet_pad_mode_group_ref()

struct libinput_tablet_pad_mode_group * libinput_tablet_pad_mode_group_ref ( struct libinput_tablet_pad_mode_group * group )

Increase the refcount of the mode group.

A mode group will be freed whenever the refcount reaches 0.

Parameters

group A previously obtained mode group

Returns: The passed mode group

Since: 1.4

◆ libinput_tablet_pad_mode_group_set_user_data()

void libinput_tablet_pad_mode_group_set_user_data	(	struct libinput_tablet_pad_mode_group *	group,
		void *	user_data
	)

Set caller-specific data associated with this mode group.

libinput does not manage, look at, or modify this data. The caller must ensure the data is valid.

Parameters

group	A previously obtained mode group
user_data	Caller-specific data pointer

See also: libinput_tablet_pad_mode_group_get_user_data

Since: 1.4

◆ libinput_tablet_pad_mode_group_unref()

struct libinput_tablet_pad_mode_group * libinput_tablet_pad_mode_group_unref ( struct libinput_tablet_pad_mode_group * group )

Decrease the refcount of the mode group.

A mode group will be freed whenever the refcount reaches 0.

Parameters

group A previously obtained mode group

Returns: NULL if the group was destroyed, otherwise the passed mode group

Since: 1.4

Data Structures

Functions

Detailed Description

Function Documentation

◆ libinput_device_tablet_pad_get_mode_group()

◆ libinput_device_tablet_pad_get_num_mode_groups()

◆ libinput_tablet_pad_mode_group_button_is_toggle()

◆ libinput_tablet_pad_mode_group_get_index()

◆ libinput_tablet_pad_mode_group_get_mode()

◆ libinput_tablet_pad_mode_group_get_num_modes()

◆ libinput_tablet_pad_mode_group_get_user_data()

◆ libinput_tablet_pad_mode_group_has_button()

◆ libinput_tablet_pad_mode_group_has_ring()

◆ libinput_tablet_pad_mode_group_has_strip()

◆ libinput_tablet_pad_mode_group_ref()

◆ libinput_tablet_pad_mode_group_set_user_data()

◆ libinput_tablet_pad_mode_group_unref()