Pointer events

Pointer events reflect motion, button and scroll events, as well as events from other axes. More...

Data Structures

struct  libinput_event_pointer
 A pointer event representing relative or absolute pointer movement, a button press/release or scroll axis events. More...
 

Functions

uint32_t libinput_event_pointer_get_time (struct libinput_event_pointer *event)
 
uint64_t libinput_event_pointer_get_time_usec (struct libinput_event_pointer *event)
 
double libinput_event_pointer_get_dx (struct libinput_event_pointer *event)
 Return the delta between the last event and the current event. More...
 
double libinput_event_pointer_get_dy (struct libinput_event_pointer *event)
 Return the delta between the last event and the current event. More...
 
double libinput_event_pointer_get_dx_unaccelerated (struct libinput_event_pointer *event)
 Return the relative delta of the unaccelerated motion vector of the current event. More...
 
double libinput_event_pointer_get_dy_unaccelerated (struct libinput_event_pointer *event)
 Return the relative delta of the unaccelerated motion vector of the current event. More...
 
double libinput_event_pointer_get_absolute_x (struct libinput_event_pointer *event)
 Return the current absolute x coordinate of the pointer event, in mm from the top left corner of the device. More...
 
double libinput_event_pointer_get_absolute_y (struct libinput_event_pointer *event)
 Return the current absolute y coordinate of the pointer event, in mm from the top left corner of the device. More...
 
double libinput_event_pointer_get_absolute_x_transformed (struct libinput_event_pointer *event, uint32_t width)
 Return the current absolute x coordinate of the pointer event, transformed to screen coordinates. More...
 
double libinput_event_pointer_get_absolute_y_transformed (struct libinput_event_pointer *event, uint32_t height)
 Return the current absolute y coordinate of the pointer event, transformed to screen coordinates. More...
 
uint32_t libinput_event_pointer_get_button (struct libinput_event_pointer *event)
 Return the button that triggered this event. More...
 
enum libinput_button_state libinput_event_pointer_get_button_state (struct libinput_event_pointer *event)
 Return the button state that triggered this event. More...
 
uint32_t libinput_event_pointer_get_seat_button_count (struct libinput_event_pointer *event)
 For the button of a LIBINPUT_EVENT_POINTER_BUTTON event, return the total number of buttons pressed on all devices on the associated seat after the event was triggered. More...
 
int libinput_event_pointer_has_axis (struct libinput_event_pointer *event, enum libinput_pointer_axis axis)
 Check if the event has a valid value for the given axis. More...
 
double libinput_event_pointer_get_axis_value (struct libinput_event_pointer *event, enum libinput_pointer_axis axis)
 Return the axis value of the given axis. More...
 
enum libinput_pointer_axis_source libinput_event_pointer_get_axis_source (struct libinput_event_pointer *event)
 Return the source for a given axis event. More...
 
double libinput_event_pointer_get_axis_value_discrete (struct libinput_event_pointer *event, enum libinput_pointer_axis axis)
 Return the axis value in discrete steps for a given axis event. More...
 
double libinput_event_pointer_get_scroll_value (struct libinput_event_pointer *event, enum libinput_pointer_axis axis)
 Return the axis value of the given axis. More...
 
double libinput_event_pointer_get_scroll_value_v120 (struct libinput_event_pointer *event, enum libinput_pointer_axis axis)
 For events of type LIBINPUT_EVENT_POINTER_SCROLL_WHEEL the v120-normalized value represents the movement in logical mouse wheel clicks, normalized to the -120..+120 range. More...
 
struct libinput_eventlibinput_event_pointer_get_base_event (struct libinput_event_pointer *event)
 

Detailed Description

Pointer events reflect motion, button and scroll events, as well as events from other axes.

Function Documentation

◆ libinput_event_pointer_get_absolute_x()

double libinput_event_pointer_get_absolute_x ( struct libinput_event_pointer event)

Return the current absolute x coordinate of the pointer event, in mm from the top left corner of the device.

To get the corresponding output screen coordinate, use libinput_event_pointer_get_absolute_x_transformed().

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
Returns
The current absolute x coordinate

◆ libinput_event_pointer_get_absolute_x_transformed()

double libinput_event_pointer_get_absolute_x_transformed ( struct libinput_event_pointer event,
uint32_t  width 
)

Return the current absolute x coordinate of the pointer event, transformed to screen coordinates.

For pointer events that are not of type LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is undefined.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
Parameters
eventThe libinput pointer event
widthThe current output screen width
Returns
The current absolute x coordinate transformed to a screen coordinate

◆ libinput_event_pointer_get_absolute_y()

double libinput_event_pointer_get_absolute_y ( struct libinput_event_pointer event)

Return the current absolute y coordinate of the pointer event, in mm from the top left corner of the device.

To get the corresponding output screen coordinate, use libinput_event_pointer_get_absolute_y_transformed().

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
Returns
The current absolute y coordinate

◆ libinput_event_pointer_get_absolute_y_transformed()

double libinput_event_pointer_get_absolute_y_transformed ( struct libinput_event_pointer event,
uint32_t  height 
)

Return the current absolute y coordinate of the pointer event, transformed to screen coordinates.

For pointer events that are not of type LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE, the return value of this function is undefined.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE.
Parameters
eventThe libinput pointer event
heightThe current output screen height
Returns
The current absolute y coordinate transformed to a screen coordinate

◆ libinput_event_pointer_get_axis_source()

enum libinput_pointer_axis_source libinput_event_pointer_get_axis_source ( struct libinput_event_pointer event)

Return the source for a given axis event.

Axis events (scroll events) can be caused by a hardware item such as a scroll wheel or emulated from other input sources, such as two-finger or edge scrolling on a touchpad.

If the source is LIBINPUT_POINTER_AXIS_SOURCE_FINGER, libinput guarantees that a scroll sequence is terminated with a scroll value of 0. A caller may use this information to decide on whether kinetic scrolling should be triggered on this scroll sequence. The coordinate system is identical to the cursor movement, i.e. a scroll value of 1 represents the equivalent relative motion of 1.

If the source is LIBINPUT_POINTER_AXIS_SOURCE_WHEEL, no terminating event is guaranteed (though it may happen). Scrolling is in discrete steps, the value is the angle the wheel moved in degrees. The default is 15 degrees per wheel click, but some mice may have differently grained wheels. It is up to the caller how to interpret such different step sizes. Callers should use libinput_event_pointer_get_scroll_value_v120() for a simpler API of handling scroll wheel events of different step sizes.

If the source is LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS, libinput guarantees that a scroll sequence is terminated with a scroll value of 0. The coordinate system is identical to the cursor movement, i.e. a scroll value of 1 represents the equivalent relative motion of 1.

Deprecated:
The source LIBINPUT_POINTER_AXIS_SOURCE_WHEEL_TILT is deprecated as of libinput 1.16. No device has ever sent this source.

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_AXIS.
This function is superfluous as of libinput 1.19. The event codes for LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER and LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS have the axis source encoded in the event type.
Returns
The source for this axis event

◆ libinput_event_pointer_get_axis_value()

double libinput_event_pointer_get_axis_value ( struct libinput_event_pointer event,
enum libinput_pointer_axis  axis 
)

Return the axis value of the given axis.

The interpretation of the value depends on the axis. For the two scrolling axes LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in relative scroll units, with the positive direction being down or right, respectively. For the interpretation of the value, see libinput_event_pointer_get_axis_source().

If libinput_event_pointer_has_axis() returns 0 for an axis, this function returns 0 for that axis.

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_AXIS.
Returns
The axis value of this event
See also
libinput_event_pointer_get_axis_value_discrete

◆ libinput_event_pointer_get_axis_value_discrete()

double libinput_event_pointer_get_axis_value_discrete ( struct libinput_event_pointer event,
enum libinput_pointer_axis  axis 
)

Return the axis value in discrete steps for a given axis event.

How a value translates into a discrete step depends on the source.

Note
This function does not support high-resolution mouse wheels and should be considered deprecated as of libinput 1.19. Callers should use LIBINPUT_EVENT_POINTER_SCROLL_WHEEL and libinput_event_pointer_get_scroll_value_v120() instead.

If the event is not of type LIBINPUT_EVENT_POINTER_AXIS, this function returns 0.

If the source is LIBINPUT_POINTER_AXIS_SOURCE_WHEEL, the discrete value correspond to the number of physical mouse wheel clicks.

If the source is LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS or LIBINPUT_POINTER_AXIS_SOURCE_FINGER, the discrete value is always 0.

Returns
The discrete value for the given event.
See also
libinput_event_pointer_get_axis_value
libinput_event_pointer_get_scroll_value_v120

◆ libinput_event_pointer_get_base_event()

struct libinput_event * libinput_event_pointer_get_base_event ( struct libinput_event_pointer event)
Returns
The generic libinput_event of this event

◆ libinput_event_pointer_get_button()

uint32_t libinput_event_pointer_get_button ( struct libinput_event_pointer event)

Return the button that triggered this event.

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_BUTTON.
Returns
The button triggering this event

◆ libinput_event_pointer_get_button_state()

enum libinput_button_state libinput_event_pointer_get_button_state ( struct libinput_event_pointer event)

Return the button state that triggered this event.

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_BUTTON.
Returns
The button state triggering this event

◆ libinput_event_pointer_get_dx()

double libinput_event_pointer_get_dx ( struct libinput_event_pointer event)

Return the delta between the last event and the current event.

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

If a device employs pointer acceleration, the delta returned by this function is the accelerated delta.

Relative motion deltas are to be interpreted as pixel movement of a standardized mouse. See the libinput documentation for more details.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_MOTION.
Returns
The relative x movement since the last event

◆ libinput_event_pointer_get_dx_unaccelerated()

double libinput_event_pointer_get_dx_unaccelerated ( struct libinput_event_pointer event)

Return the relative delta of the unaccelerated motion vector of the current event.

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

Relative unaccelerated motion deltas are raw device coordinates. Note that these coordinates are subject to the device's native resolution. Touchpad coordinates represent raw device coordinates in the X resolution of the touchpad. See the libinput documentation for more details.

Any rotation applied to the device also applies to unaccelerated motion (see libinput_device_config_rotation_set_angle()).

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_MOTION.
Returns
The unaccelerated relative x movement since the last event

◆ libinput_event_pointer_get_dy()

double libinput_event_pointer_get_dy ( struct libinput_event_pointer event)

Return the delta between the last event and the current event.

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

If a device employs pointer acceleration, the delta returned by this function is the accelerated delta.

Relative motion deltas are to be interpreted as pixel movement of a standardized mouse. See the libinput documentation for more details.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_MOTION.
Returns
The relative y movement since the last event

◆ libinput_event_pointer_get_dy_unaccelerated()

double libinput_event_pointer_get_dy_unaccelerated ( struct libinput_event_pointer event)

Return the relative delta of the unaccelerated motion vector of the current event.

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

Relative unaccelerated motion deltas are raw device coordinates. Note that these coordinates are subject to the device's native resolution. Touchpad coordinates represent raw device coordinates in the X resolution of the touchpad. See the libinput documentation for more details.

Any rotation applied to the device also applies to unaccelerated motion (see libinput_device_config_rotation_set_angle()).

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_MOTION.
Returns
The unaccelerated relative y movement since the last event

◆ libinput_event_pointer_get_scroll_value()

double libinput_event_pointer_get_scroll_value ( struct libinput_event_pointer event,
enum libinput_pointer_axis  axis 
)

Return the axis value of the given axis.

The interpretation of the value depends on the axis. For the two scrolling axes LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL and LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL, the value of the event is in relative scroll units, with the positive direction being down or right, respectively. If libinput_event_pointer_has_axis() returns 0 for an axis, this function returns 0 for that axis.

If the event is LIBINPUT_EVENT_POINTER_SCROLL_FINGER, libinput guarantees that a scroll sequence is terminated with a scroll value of 0. A caller may use this information to decide on whether kinetic scrolling should be triggered on this scroll sequence. The coordinate system is identical to the cursor movement, i.e. a scroll value of 1 represents the equivalent relative motion of 1.

If the event is LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, no terminating event is guaranteed (though it may happen). Scrolling is in discrete steps, the value is the angle the wheel moved in degrees. The default is 15 degrees per wheel click, but some mice may have differently grained wheels. It is up to the caller how to interpret such different step sizes. Callers should use libinput_event_pointer_get_scroll_value_v120() for a simpler API of handling scroll wheel events of different step sizes.

If the event is LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS, libinput guarantees that a scroll sequence is terminated with a scroll value of 0. The coordinate system is identical to the cursor movement, i.e. a scroll value of 1 represents the equivalent relative motion of 1.

For pointer events that are not of type LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER, or LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS, this function returns zero.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER, or LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS.
Returns
The axis value of this event
See also
libinput_event_pointer_get_scroll_value_v120
Since
1.19

◆ libinput_event_pointer_get_scroll_value_v120()

double libinput_event_pointer_get_scroll_value_v120 ( struct libinput_event_pointer event,
enum libinput_pointer_axis  axis 
)

For events of type LIBINPUT_EVENT_POINTER_SCROLL_WHEEL the v120-normalized value represents the movement in logical mouse wheel clicks, normalized to the -120..+120 range.

A value that is a fraction of ±120 indicates a wheel movement less than one logical click, a caller should either scroll by the respective fraction of the normal scroll distance or accumulate that value until a multiple of 120 is reached.

For most callers, this is the preferred way of handling high-resolution scroll events.

The normalized v120 value does not take device-specific physical angles or distances into account, i.e. a wheel with a click angle of 20 degrees produces only 18 logical clicks per 360 degree rotation, a wheel with a click angle of 15 degrees produces 24 logical clicks per 360 degree rotation. Where the physical angle matters, use libinput_event_pointer_get_axis_value() instead.

The magic number 120 originates from the Windows Vista Mouse Wheel design document.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_SCROLL_WHEEL.
Returns
A value normalized to the 0-±120 range
See also
libinput_event_pointer_get_axis_value
libinput_event_pointer_get_axis_value_discrete
Since
1.19

◆ libinput_event_pointer_get_seat_button_count()

uint32_t libinput_event_pointer_get_seat_button_count ( struct libinput_event_pointer event)

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

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_BUTTON. For other events, this function returns 0.
Returns
The seat wide pressed button count for the key of this event

◆ libinput_event_pointer_get_time()

uint32_t libinput_event_pointer_get_time ( struct libinput_event_pointer event)
Note
Timestamps may not always increase. See the libinput documentation for more details.
Returns
The event time for this event

◆ libinput_event_pointer_get_time_usec()

uint64_t libinput_event_pointer_get_time_usec ( struct libinput_event_pointer event)
Note
Timestamps may not always increase. See the libinput documentation for more details.
Returns
The event time for this event in microseconds

◆ libinput_event_pointer_has_axis()

int libinput_event_pointer_has_axis ( struct libinput_event_pointer event,
enum libinput_pointer_axis  axis 
)

Check if the event has a valid value for the given axis.

If this function returns non-zero for an axis and libinput_event_pointer_get_axis_value() returns a value of 0, the event is a scroll stop event.

For pointer events that are not of type LIBINPUT_EVENT_POINTER_AXIS, LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER, or LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS this function returns 0.

Note
It is an application bug to call this function for events other than LIBINPUT_EVENT_POINTER_AXIS, LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER, or LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS.
Returns
Non-zero if this event contains a value for this axis