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_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. 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_group * | libinput_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_group * | libinput_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
◆ 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.
◆ 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
◆ 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
◆ 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
◆ 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
◆ 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
◆ 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
◆ 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
◆ 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
◆ 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
◆ 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
◆ 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
◆ 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
