Tablet pad modes

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. More...
 
struct libinput_tablet_pad_mode_grouplibinput_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. More...
 
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(). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
struct libinput_tablet_pad_mode_grouplibinput_tablet_pad_mode_group_ref (struct libinput_tablet_pad_mode_group *group)
 Increase the refcount of the mode group. More...
 
struct libinput_tablet_pad_mode_grouplibinput_tablet_pad_mode_group_unref (struct libinput_tablet_pad_mode_group *group)
 Decrease the refcount of the mode group. More...
 
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. More...
 
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. More...
 

Detailed Description

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

See Tablet pad modes for details.

Function Documentation

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
deviceA device with the LIBINPUT_DEVICE_CAP_TABLET_PAD capability
indexA mode group index
Returns
the mode group with the given index or NULL if an invalid index is given.
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
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
groupA previously obtained mode group
buttonA button index, starting at 0
Return values
non-zeroif the button is a mode toggle button for this group, or zero otherwise
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
groupA previously obtained mode group
Returns
the numeric index this mode group represents, starting at 0
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
groupA 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
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
groupA previously obtained mode group
Returns
the number of modes available in 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.

Parameters
groupA 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
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
groupA previously obtained mode group
buttonA button index, starting at 0
Returns
true if the given button index is part of this mode group or false otherwise
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
groupA previously obtained mode group
ringA ring index, starting at 0
Returns
true if the given ring index is part of this mode group or false otherwise
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
groupA previously obtained mode group
stripA strip index, starting at 0
Returns
true if the given strip index is part of this mode group or false otherwise
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
groupA previously obtained mode group
Returns
The passed 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.

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

Parameters
groupA previously obtained mode group
user_dataCaller-specific data pointer
See also
libinput_tablet_pad_mode_group_get_user_data
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
groupA previously obtained mode group
Returns
NULL if the group was destroyed, otherwise the passed mode group