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...
 
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.

If the source is LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS, no terminating event is guaranteed (though it may happen). 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_TILT, no terminating event is guaranteed (though it may happen). Scrolling is in discrete steps and there is no physical equivalent for the value returned here. For backwards compatibility, the value returned by this function is identical to a single mouse wheel rotation by this device (see the documentation for LIBINPUT_POINTER_AXIS_SOURCE_WHEEL above). Callers should not use this value but instead exclusively refer to the value returned by libinput_event_pointer_get_axis_value_discrete().

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 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.

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_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 Normalization of relative motion 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 Normalization of relative motion 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 Normalization of relative motion 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 Normalization of relative motion 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_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 Event timestamps for 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 Event timestamps for 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, this function returns 0.

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