Events from button devices

Events that come from button devices. More...

Data Structures

struct  libinput_event_buttonset
 Event representing a button press/release or axis update on device with the LIBINPUT_DEVICE_CAP_BUTTONSET capability. More...
 

Functions

struct libinput_eventlibinput_event_buttonset_get_base_event (struct libinput_event_buttonset *event)
 
uint32_t libinput_event_buttonset_get_time (struct libinput_event_buttonset *event)
 
uint64_t libinput_event_buttonset_get_time_usec (struct libinput_event_buttonset *event)
 
int libinput_event_buttonset_axis_has_changed (struct libinput_event_buttonset *event, unsigned int axis)
 Checks if an axis was updated in this event or return 0 otherwise. More...
 
double libinput_event_buttonset_get_x (struct libinput_event_buttonset *event, unsigned int axis)
 Get the x coordinate in mm for the given axis from the left edge of the device in its current logical rotation. More...
 
double libinput_event_buttonset_get_y (struct libinput_event_buttonset *event, unsigned int axis)
 Get the y coordinate in mm for the given axis from the top edge of the device in its current logical rotation. More...
 
double libinput_event_buttonset_get_z (struct libinput_event_buttonset *event, unsigned int axis)
 Get the z coordinate in mm for the given axis from the top edge of the device in its current logical rotation. More...
 
double libinput_event_buttonset_get_delta_x (struct libinput_event_buttonset *event, unsigned int axis)
 Get the delta coordinates for a relative x axis of type LIBINPUT_BUTTONSET_AXIS_REL_X. More...
 
double libinput_event_buttonset_get_delta_y (struct libinput_event_buttonset *event, unsigned int axis)
 Get the delta coordinates for a relative x axis of type LIBINPUT_BUTTONSET_AXIS_REL_Y. More...
 
double libinput_event_buttonset_get_delta_z (struct libinput_event_buttonset *event, unsigned int axis)
 Get the delta coordinates for a relative x axis of type LIBINPUT_BUTTONSET_AXIS_REL_Z. More...
 
double libinput_event_buttonset_get_rotation_x (struct libinput_event_buttonset *event, unsigned int axis)
 Get the rotational position in degrees off the logical neutral position in the current logical orientation for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_X. More...
 
double libinput_event_buttonset_get_rotation_y (struct libinput_event_buttonset *event, unsigned int axis)
 Get the rotational position in degrees off the logical neutral position in the current logical orientation for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_Y. More...
 
double libinput_event_buttonset_get_rotation_z (struct libinput_event_buttonset *event, unsigned int axis)
 Get the rotational position in degrees off the logical neutral position in the current logical orientation for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_Z. More...
 
double libinput_event_buttonset_get_ring_value (struct libinput_event_buttonset *event, unsigned int axis)
 Get the absolute position for an axis of type LIBINPUT_BUTTONSET_AXIS_RING in degrees clockwise in the device's current logical rotation. More...
 
enum libinput_buttonset_axis_source libinput_event_buttonset_get_ring_source (struct libinput_event_buttonset *event, unsigned int axis)
 Return the source for an axis of type LIBINPUT_BUTTONSET_AXIS_RING. More...
 
double libinput_event_buttonset_get_strip_value (struct libinput_event_buttonset *event, unsigned int axis)
 Get the absolute position for an axis of type LIBINPUT_BUTTONSET_AXIS_STRIP normalized to the axis range [0, 1], where 0 is the strip's top or left-most point in the device's current logical rotation. More...
 
enum libinput_buttonset_axis_source libinput_event_buttonset_get_strip_source (struct libinput_event_buttonset *event, unsigned int axis)
 Return the source for an axis of type LIBINPUT_BUTTONSET_AXIS_STRIP. More...
 
double libinput_event_buttonset_get_axis_value (struct libinput_event_buttonset *event, unsigned int axis)
 Return the axis value of a given axis for a buttonset. More...
 
double libinput_event_buttonset_get_axis_value_transformed (struct libinput_event_buttonset *event, unsigned int axis, uint32_t max)
 Return the axis value of the given axis, linearly transformed into the range [0, max]. More...
 
double libinput_event_buttonset_get_axis_delta (struct libinput_event_buttonset *event, unsigned int axis)
 Return the axis delta of a given axis for a buttonset, relative to the previous event. More...
 
double libinput_event_buttonset_get_axis_delta_discrete (struct libinput_event_buttonset *event, unsigned int axis)
 Return the axis delta of a given axis for a buttonset in discrete steps, relative to the previous event. More...
 
enum libinput_buttonset_axis_source libinput_event_buttonset_get_axis_source (struct libinput_event_buttonset *event, unsigned int axis)
 Return the source for a given buttonset axis. More...
 
uint32_t libinput_event_buttonset_get_button (struct libinput_event_buttonset *event)
 Return the button that triggered this event. More...
 
enum libinput_button_state libinput_event_buttonset_get_button_state (struct libinput_event_buttonset *event)
 Return the button state of the event. More...
 
uint32_t libinput_event_buttonset_get_seat_button_count (struct libinput_event_buttonset *event)
 For the button of a LIBINPUT_EVENT_BUTTONSET_BUTTON event, return the total number of buttons pressed on all devices on the associated seat after the the event was triggered. More...
 

Detailed Description

Events that come from button devices.

Such devices provide one or more custom buttons (other than left, middle, right) and usually do not control the pointer. Axes other than x/y axes may be present on the device.

Note that buttonset devices may have x/y axes. It is up to the caller to decide whether those devices should control the pointer. While libinput provides some information about the device and a unified API to handle axes and events, the caller is expected to gather additional information from external sources. For example, for information on the button layout and other behaviors on Wacom tablet pads, the caller should use libwacom.

Function Documentation

int libinput_event_buttonset_axis_has_changed ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Checks if an axis was updated in this event or return 0 otherwise.

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_BUTTONSET_AXIS.
Parameters
eventThe libinput buttonset event
axisThe axis to check for updates
Returns
1 if the axis was updated or 0 otherwise
double libinput_event_buttonset_get_axis_delta ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Return the axis delta of a given axis for a buttonset, relative to the previous event.

The interpretation of the value is dependent on the axis:

For all other axes, see libinput_event_buttonset_get_axis_value() for details on the various axes.

Parameters
eventThe libinput buttonset event
axisThe axis to retrieve the value of
Returns
The axis delta to the last last event in discrete steps
double libinput_event_buttonset_get_axis_delta_discrete ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Return the axis delta of a given axis for a buttonset in discrete steps, relative to the previous event.

How an axis value translates into a discrete steps depends on the device.

Parameters
eventThe libinput buttonset event
axisThe axis to retrieve the value of
Returns
The axis delta to the last last event in discrete steps
enum libinput_buttonset_axis_source libinput_event_buttonset_get_axis_source ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Return the source for a given buttonset axis.

If the source is LIBINPUT_BUTTONSET_AXIS_SOURCE_FINGER, libinput guarantees that a sequence is terminated with an out-of-range value (see libinput_event_buttonset_get_axis_value() for details). A caller may use this information to decide on whether kinetic motion should be triggered on this event sequence.

If the source is LIBINPUT_BUTTONSET_AXIS_SOURCE_UNKNOWN, libinput does not send a terminating value to indicate release.

For buttonset events that are not of type LIBINPUT_EVENT_BUTTONSET_AXIS, this function returns 0. For axes not present in this event, this function returns 0.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_BUTTONSET_AXIS or for axes not present in this event.
Returns
the source for this buttonset axis event
double libinput_event_buttonset_get_axis_value ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Return the axis value of a given axis for a buttonset.

The interpretation of the value is dependent on the axis type:

Note
This function may be called for axes that have not changed in this event. libinput always includes all device axes in the event.
Parameters
eventThe libinput buttonset event
axisThe axis to retrieve the value of
Returns
The current value of the the axis
Return values
-1The finger was lifted from a ring or strip axis.
double libinput_event_buttonset_get_axis_value_transformed ( struct libinput_event_buttonset event,
unsigned int  axis,
uint32_t  max 
)

Return the axis value of the given axis, linearly transformed into the range [0, max].

For a detailed explanation of the value, see libinput_event_buttonset_get_axis_value().

Parameters
eventThe libinput buttonset event
axisThe axis to retrieve the value of
maxThe upper value of the range to convert to (inclusive)
Returns
The current value of the the axis, transformed into [0, max]
struct libinput_event* libinput_event_buttonset_get_base_event ( struct libinput_event_buttonset event)
Returns
The generic libinput_event of this event
uint32_t libinput_event_buttonset_get_button ( struct libinput_event_buttonset event)

Return the button that triggered this event.

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_BUTTONSET_BUTTON.
Parameters
eventThe libinput buttonset event
Returns
the button triggering this event
enum libinput_button_state libinput_event_buttonset_get_button_state ( struct libinput_event_buttonset event)

Return the button state of the event.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_BUTTONSET_BUTTON.
Parameters
eventThe libinput buttonset event
Returns
the button state triggering this event
double libinput_event_buttonset_get_delta_x ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the delta coordinates for a relative x axis of type LIBINPUT_BUTTONSET_AXIS_REL_X.

The interpretation of a delta is device-specific. Buttonset devices are not usually supposed to control the cursor position, a caller should not assume that delta coordinates are directly applicable to pointer movement.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_REL_X
Returns
The delta x coordinate, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_REL_X.
double libinput_event_buttonset_get_delta_y ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the delta coordinates for a relative x axis of type LIBINPUT_BUTTONSET_AXIS_REL_Y.

The interpretation of a delta is device-specific. Buttonset devices are not usually supposed to control the cursor position, a caller should not assume that delta coordinates are directly applicable to pointer movement.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_REL_Y
Returns
The delta y coordinate, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_REL_Y.
double libinput_event_buttonset_get_delta_z ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the delta coordinates for a relative x axis of type LIBINPUT_BUTTONSET_AXIS_REL_Z.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_REL_Z
Returns
The delta z coordinate, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_REL_Z.
enum libinput_buttonset_axis_source libinput_event_buttonset_get_ring_source ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Return the source for an axis of type LIBINPUT_BUTTONSET_AXIS_RING.

If the source is LIBINPUT_BUTTONSET_AXIS_SOURCE_FINGER, libinput guarantees that a sequence is terminated with an out-of-range value (see libinput_event_buttonset_get_ring_value() for details). A caller may use this information to decide on whether kinetic motion should be triggered on this event sequence.

If the source is LIBINPUT_BUTTONSET_AXIS_SOURCE_UNKNOWN, libinput does not send a terminating value to indicate release.

double libinput_event_buttonset_get_ring_value ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the absolute position for an axis of type LIBINPUT_BUTTONSET_AXIS_RING in degrees clockwise in the device's current logical rotation.

If the libinput_event_buttonset_get_ring_source() returns LIBINPUT_BUTTONSET_AXIS_SOURCE_FINGER for this event and this axis, libinput will send an event with a value of -1 when the finger is lifted.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_RING
Returns
The ring's position in degrees, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_RING.
double libinput_event_buttonset_get_rotation_x ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the rotational position in degrees off the logical neutral position in the current logical orientation for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_X.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_X
Returns
The rotational x value in degrees, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_REL_Z.
double libinput_event_buttonset_get_rotation_y ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the rotational position in degrees off the logical neutral position in the current logical orientation for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_Y.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_Y
Returns
The rotational y value in degrees, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_REL_Y.
double libinput_event_buttonset_get_rotation_z ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the rotational position in degrees off the logical neutral position in the current logical orientation for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_Z.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_ROTATION_Z
Returns
The rotational z value in degrees, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_REL_Z.
uint32_t libinput_event_buttonset_get_seat_button_count ( struct libinput_event_buttonset event)

For the button of a LIBINPUT_EVENT_BUTTONSET_BUTTON event, return the total number of buttons pressed on all devices on the associated seat after the the event was triggered.

"

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_BUTTONSET_BUTTON. For other events, this function returns 0.
Returns
the seat wide pressed button count for the key of this event
enum libinput_buttonset_axis_source libinput_event_buttonset_get_strip_source ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Return the source for an axis of type LIBINPUT_BUTTONSET_AXIS_STRIP.

If the source is LIBINPUT_BUTTONSET_AXIS_SOURCE_FINGER, libinput guarantees that a sequence is terminated with an out-of-range value (see libinput_event_buttonset_get_strip_value() for details). A caller may use this information to decide on whether kinetic motion should be triggered on this event sequence.

If the source is LIBINPUT_BUTTONSET_AXIS_SOURCE_UNKNOWN, libinput does not send a terminating value to indicate release.

double libinput_event_buttonset_get_strip_value ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the absolute position for an axis of type LIBINPUT_BUTTONSET_AXIS_STRIP normalized to the axis range [0, 1], where 0 is the strip's top or left-most point in the device's current logical rotation.

If the libinput_event_buttonset_get_strip_source() returns LIBINPUT_BUTTONSET_AXIS_SOURCE_FINGER for this event and this axis, libinput will send an event with a value of -1 when the finger is lifted.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_STRIP
Returns
The normalized position on the strip, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_STRIP.
uint32_t libinput_event_buttonset_get_time ( struct libinput_event_buttonset event)
Returns
The event time for this event
uint64_t libinput_event_buttonset_get_time_usec ( struct libinput_event_buttonset event)
Returns
The event time for this event
double libinput_event_buttonset_get_x ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the x coordinate in mm for the given axis from the left edge of the device in its current logical rotation.

The axis must be one of type LIBINPUT_BUTTONSET_AXIS_X.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_X
Returns
The x coordinate in mm, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_X.
double libinput_event_buttonset_get_y ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the y coordinate in mm for the given axis from the top edge of the device in its current logical rotation.

The axis must be one of type LIBINPUT_BUTTONSET_AXIS_Y.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_Y
Returns
The y coordinate in mm, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_Y.
double libinput_event_buttonset_get_z ( struct libinput_event_buttonset event,
unsigned int  axis 
)

Get the z coordinate in mm for the given axis from the top edge of the device in its current logical rotation.

The axis must be one of type LIBINPUT_BUTTONSET_AXIS_Z.

Parameters
eventThe event
axisAn index for an axis of type LIBINPUT_BUTTONSET_AXIS_Z
Returns
The z coordinate in mm, or 0 if the axis is not of type LIBINPUT_BUTTONSET_AXIS_Z.