libinput: Tablet pad modes

Data Structures | Functions
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_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

See also
  libinput_event_tablet_pad_get_mode

## § 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

See also
  libinput_tablet_pad_mode_group_set_user_data

## § 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

See also
  libinput_tablet_pad_mode_group_get_user_data

## § 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