Tablet pad events

Events that come from the pad of tablet devices. More...

Data Structures

struct  libinput_event_tablet_pad
 Tablet pad event representing a button press, or ring/strip update on the tablet pad itself. More...
 

Enumerations

enum  libinput_tablet_pad_ring_axis_source { LIBINPUT_TABLET_PAD_RING_SOURCE_UNKNOWN , LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER }
 The source for a LIBINPUT_EVENT_TABLET_PAD_RING event. More...
 
enum  libinput_tablet_pad_strip_axis_source { LIBINPUT_TABLET_PAD_STRIP_SOURCE_UNKNOWN , LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER }
 The source for a LIBINPUT_EVENT_TABLET_PAD_STRIP event. More...
 

Functions

struct libinput_eventlibinput_event_tablet_pad_get_base_event (struct libinput_event_tablet_pad *event)
 
double libinput_event_tablet_pad_get_ring_position (struct libinput_event_tablet_pad *event)
 Returns the current position of the ring, in degrees counterclockwise from the northern-most point of the ring in the tablet's current logical orientation. More...
 
unsigned int libinput_event_tablet_pad_get_ring_number (struct libinput_event_tablet_pad *event)
 Returns the number of the ring that has changed state, with 0 being the first ring. More...
 
enum libinput_tablet_pad_ring_axis_source libinput_event_tablet_pad_get_ring_source (struct libinput_event_tablet_pad *event)
 Returns the source of the interaction with the ring. More...
 
double libinput_event_tablet_pad_get_strip_position (struct libinput_event_tablet_pad *event)
 Returns the current position of the strip, normalized to the range [0, 1], with 0 being the top/left-most point in the tablet's current logical orientation. More...
 
unsigned int libinput_event_tablet_pad_get_strip_number (struct libinput_event_tablet_pad *event)
 Returns the number of the strip that has changed state, with 0 being the first strip. More...
 
enum libinput_tablet_pad_strip_axis_source libinput_event_tablet_pad_get_strip_source (struct libinput_event_tablet_pad *event)
 Returns the source of the interaction with the strip. More...
 
uint32_t libinput_event_tablet_pad_get_button_number (struct libinput_event_tablet_pad *event)
 Return the button number that triggered this event, starting at 0. More...
 
enum libinput_button_state libinput_event_tablet_pad_get_button_state (struct libinput_event_tablet_pad *event)
 Return the button state of the event. More...
 
uint32_t libinput_event_tablet_pad_get_key (struct libinput_event_tablet_pad *event)
 Return the key code that triggered this event, e.g. More...
 
enum libinput_key_state libinput_event_tablet_pad_get_key_state (struct libinput_event_tablet_pad *event)
 Return the key state of the event. More...
 
unsigned int libinput_event_tablet_pad_get_mode (struct libinput_event_tablet_pad *event)
 Returns the mode the button, ring, or strip that triggered this event is in, at the time of the event. More...
 
struct libinput_tablet_pad_mode_grouplibinput_event_tablet_pad_get_mode_group (struct libinput_event_tablet_pad *event)
 Returns the mode group that the button, ring, or strip that triggered this event is considered in. More...
 
uint32_t libinput_event_tablet_pad_get_time (struct libinput_event_tablet_pad *event)
 
uint64_t libinput_event_tablet_pad_get_time_usec (struct libinput_event_tablet_pad *event)
 

Detailed Description

Events that come from the pad of tablet devices.

For events from the tablet tools, see Tablet events.

Since
1.3

Enumeration Type Documentation

◆ libinput_tablet_pad_ring_axis_source

The source for a LIBINPUT_EVENT_TABLET_PAD_RING event.

See libinput_event_tablet_pad_get_ring_source() for details.

Since
1.3
Enumerator
LIBINPUT_TABLET_PAD_RING_SOURCE_UNKNOWN 
LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER 

The event is caused by the movement of one or more fingers on the ring.

◆ libinput_tablet_pad_strip_axis_source

The source for a LIBINPUT_EVENT_TABLET_PAD_STRIP event.

See libinput_event_tablet_pad_get_strip_source() for details.

Since
1.3
Enumerator
LIBINPUT_TABLET_PAD_STRIP_SOURCE_UNKNOWN 
LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER 

The event is caused by the movement of one or more fingers on the strip.

Function Documentation

◆ libinput_event_tablet_pad_get_base_event()

struct libinput_event* libinput_event_tablet_pad_get_base_event ( struct libinput_event_tablet_pad event)
Returns
The generic libinput_event of this event
Since
1.3

◆ libinput_event_tablet_pad_get_button_number()

uint32_t libinput_event_tablet_pad_get_button_number ( struct libinput_event_tablet_pad event)

Return the button number that triggered this event, starting at 0.

For events that are not of type LIBINPUT_EVENT_TABLET_PAD_BUTTON, this function returns 0.

Note that the number returned is a generic sequential button number and not a semantic button code as defined in linux/input.h. See the libinput documentation for more details.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_BUTTON. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
the button triggering this event
Since
1.3

◆ libinput_event_tablet_pad_get_button_state()

enum libinput_button_state libinput_event_tablet_pad_get_button_state ( struct libinput_event_tablet_pad event)

Return the button state of the event.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_BUTTON. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
the button state triggering this event
Since
1.3

◆ libinput_event_tablet_pad_get_key()

uint32_t libinput_event_tablet_pad_get_key ( struct libinput_event_tablet_pad event)

Return the key code that triggered this event, e.g.

KEY_CONTROLPANEL. The list of key codes is defined in linux/input-event-codes.h.

For events that are not of type LIBINPUT_EVENT_TABLET_PAD_KEY, this function returns 0.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_KEY. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
the key code triggering this event
Since
1.15

◆ libinput_event_tablet_pad_get_key_state()

enum libinput_key_state libinput_event_tablet_pad_get_key_state ( struct libinput_event_tablet_pad event)

Return the key state of the event.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_KEY. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
the key state triggering this event
Since
1.15

◆ libinput_event_tablet_pad_get_mode()

unsigned int libinput_event_tablet_pad_get_mode ( struct libinput_event_tablet_pad event)

Returns the mode the button, ring, or strip that triggered this event is in, at the time of the event.

The mode is a virtual grouping of functionality, usually based on some visual feedback like LEDs on the pad. Mode indices start at 0, a device that does not support modes always returns 0.

Note
Pad keys are not part of a mode group. It is an application bug to call this function for LIBINPUT_EVENT_TABLET_PAD_KEY.

Mode switching is controlled by libinput and more than one mode may exist on the tablet. This function returns the mode that this event's button, ring or strip is logically in. If the button is a mode toggle button and the button event caused a new mode to be toggled, the mode returned is the new mode the button is in.

Note that the returned mode is the mode valid as of the time of the event. The returned mode may thus be different to the mode returned by libinput_tablet_pad_mode_group_get_mode(). See libinput_tablet_pad_mode_group_get_mode() for details.

Parameters
eventThe libinput tablet pad event
Returns
the 0-indexed mode of this button, ring or strip at the time of the event
See also
libinput_tablet_pad_mode_group_get_mode
Since
1.4

◆ libinput_event_tablet_pad_get_mode_group()

struct libinput_tablet_pad_mode_group* libinput_event_tablet_pad_get_mode_group ( struct libinput_event_tablet_pad event)

Returns the mode group that the button, ring, or strip that triggered this event is considered in.

The mode is a virtual grouping of functionality, usually based on some visual feedback like LEDs on the pad.

Note
Pad keys are not part of a mode group. It is an application bug to call this function for LIBINPUT_EVENT_TABLET_PAD_KEY.

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.

Parameters
eventThe libinput tablet pad event
Returns
the mode group of the button, ring or strip that caused this event
See also
libinput_device_tablet_pad_get_mode_group
Since
1.4

◆ libinput_event_tablet_pad_get_ring_number()

unsigned int libinput_event_tablet_pad_get_ring_number ( struct libinput_event_tablet_pad event)

Returns the number of the ring that has changed state, with 0 being the first ring.

On tablets with only one ring, this function always returns 0.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
The index of the ring that changed state
Since
1.3

◆ libinput_event_tablet_pad_get_ring_position()

double libinput_event_tablet_pad_get_ring_position ( struct libinput_event_tablet_pad event)

Returns the current position of the ring, in degrees counterclockwise from the northern-most point of the ring in the tablet's current logical orientation.

If the source is LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER, libinput sends a terminating event with a ring value of -1 when the finger is lifted from the ring. A caller may use this information to e.g. determine if kinetic scrolling should be triggered.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
The current value of the the axis
Return values
-1The finger was lifted
Since
1.3

◆ libinput_event_tablet_pad_get_ring_source()

enum libinput_tablet_pad_ring_axis_source libinput_event_tablet_pad_get_ring_source ( struct libinput_event_tablet_pad event)

Returns the source of the interaction with the ring.

If the source is LIBINPUT_TABLET_PAD_RING_SOURCE_FINGER, libinput sends a ring position value of -1 to terminate the current interaction.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_RING. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
The source of the ring interaction
Since
1.3

◆ libinput_event_tablet_pad_get_strip_number()

unsigned int libinput_event_tablet_pad_get_strip_number ( struct libinput_event_tablet_pad event)

Returns the number of the strip that has changed state, with 0 being the first strip.

On tablets with only one strip, this function always returns 0.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
The index of the strip that changed state
Since
1.3

◆ libinput_event_tablet_pad_get_strip_position()

double libinput_event_tablet_pad_get_strip_position ( struct libinput_event_tablet_pad event)

Returns the current position of the strip, normalized to the range [0, 1], with 0 being the top/left-most point in the tablet's current logical orientation.

If the source is LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER, libinput sends a terminating event with a ring value of -1 when the finger is lifted from the ring. A caller may use this information to e.g. determine if kinetic scrolling should be triggered.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
The current value of the the axis
Return values
-1The finger was lifted
Since
1.3

◆ libinput_event_tablet_pad_get_strip_source()

enum libinput_tablet_pad_strip_axis_source libinput_event_tablet_pad_get_strip_source ( struct libinput_event_tablet_pad event)

Returns the source of the interaction with the strip.

If the source is LIBINPUT_TABLET_PAD_STRIP_SOURCE_FINGER, libinput sends a strip position value of -1 to terminate the current interaction.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_TABLET_PAD_STRIP. For other events, this function returns 0.
Parameters
eventThe libinput tablet pad event
Returns
The source of the strip interaction
Since
1.3

◆ libinput_event_tablet_pad_get_time()

uint32_t libinput_event_tablet_pad_get_time ( struct libinput_event_tablet_pad event)
Note
Timestamps may not always increase. See the libinput documentation for more details.
Parameters
eventThe libinput tablet pad event
Returns
The event time for this event
Since
1.3

◆ libinput_event_tablet_pad_get_time_usec()

uint64_t libinput_event_tablet_pad_get_time_usec ( struct libinput_event_tablet_pad event)
Note
Timestamps may not always increase. See the libinput documentation for more details.
Parameters
eventThe libinput tablet pad event
Returns
The event time for this event in microseconds
Since
1.3