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