libinput: Pointer events

Data Structures | Functions
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_event * | libinput_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

  event | The libinput pointer event
  width | The 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

  event | The libinput pointer event
  height | The 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.

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

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

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