Events¶

Event¶

class libinput.event.Event(hevent, libinput)¶

Base class for device events.

type¶

An enum describing event type.

Returns:	Event type.
Return type:	EventType

device¶

The device associated with this event.

For device added/removed events this is the device added or removed. For all other device events, this is the device that generated the event.

Returns:	Device object.
Return type:	Device

PointerEvent¶

class libinput.event.PointerEvent(*args)¶

A pointer event.

An event representing relative or absolute pointer movement, a button press/release or scroll axis events.

time¶

Note

Timestamps may not always increase. See Event timestamps for details.

Returns:	The event time for this event in microseconds.
Return type:	int

delta¶

The delta between the last event and the current event.

For pointer events that are not of type POINTER_MOTION, this property raises AttributeError.

If a device employs pointer acceleration, the delta returned by this method 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.

Returns:	The relative (x, y) movement since the last event.
Return type:	(float, float)
Raises:	`AttributeError`

delta_unaccelerated¶

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

For pointer events that are not of type POINTER_MOTION, this property raises AttributeError.

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, Y) resolution of the touchpad. See Normalization of relative motion for more details.

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

Returns:	The unaccelerated relative (x, y) movement since the last event.
Return type:	(float, float)
Raises:	`AttributeError`

absolute_coords¶

The current absolute coordinates of the pointer event, in mm from the top left corner of the device.

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

For pointer events that are not of type POINTER_MOTION_ABSOLUTE, this property raises AttributeError.

Returns:	The current absolute coordinates.
Return type:	(float, float)
Raises:	`AttributeError`

transform_absolute_coords(width, height)¶

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

For pointer events that are not of type POINTER_MOTION_ABSOLUTE, this method raises AttributeError.

Parameters:	width (int) – The current output screen width. height (int) – The current output screen height.
Returns:	The current absolute (x, y) coordinates transformed to a screen coordinates.
Return type:	(float, float)
Raises:	`AttributeError`

button¶

The button that triggered this event.

For pointer events that are not of type POINTER_BUTTON, this property raises AttributeError.

Returns:	The button triggering this event.
Return type:	int
Raises:	`AttributeError`

button_state¶

The button state that triggered this event.

For pointer events that are not of type POINTER_BUTTON, this property raises AttributeError.

Returns:	The button state triggering this event.
Return type:	ButtonState
Raises:	`AttributeError`

seat_button_count¶

The total number of buttons pressed on all devices on the associated seat after the event was triggered.

For pointer events that are not of type POINTER_BUTTON, this property raises AssertionError.

Returns:	The seat wide pressed button count for the key of this event.
Return type:	int
Raises:	`AssertionError`

has_axis(axis)¶

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

If this method returns True for an axis and get_axis_value() returns a value of 0, the event is a scroll stop event.

For pointer events that are not of type POINTER_AXIS, this method raises AttributeError.

Parameters:	axis (PointerAxis) – The axis to check.
Returns:	True if this event contains a value for this axis.
Return type:	bool
Raises:	`AttributeError`

get_axis_value(axis)¶

Return the axis value of the given axis.

The interpretation of the value depends on the axis. For the two scrolling axes SCROLL_VERTICAL and 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 axis_source.

If has_axis() returns False for an axis, this method returns 0 for that axis.

For pointer events that are not of type POINTER_AXIS, this method raises AttributeError.

Parameters:	axis (PointerAxis) – The axis who’s value to get.
Returns:	The axis value of this event.
Return type:	float
Raises:	`AttributeError`

axis_source¶

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 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 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 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 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 of this property is identical to a single mouse wheel rotation by this device (see the documentation for WHEEL above). Callers should not use this value but instead exclusively refer to the value returned by get_axis_value_discrete().

For pointer events that are not of type POINTER_AXIS, this property raises AttributeError.

Returns:	The source for this axis event.
Return type:	PointerAxisSource
Raises:	`AttributeError`

get_axis_value_discrete(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 WHEEL, the discrete value correspond to the number of physical mouse wheel clicks.

If the source is CONTINUOUS or FINGER, the discrete value is always 0.

Parameters:	axis (PointerAxis) – The axis who’s value to get.
Returns:	The discrete value for the given event.
Return type:	float
Raises:	`AttributeError`

KeyboardEvent¶

class libinput.event.KeyboardEvent(*args)¶

A keyboard event representing a key press/release.

time¶

Note

Timestamps may not always increase. See Event timestamps for details.

Returns:	The event time for this event in microseconds.
Return type:	int

key¶

The keycode that triggered this event.

Returns:	The keycode that triggered this key event.
Return type:	int

key_state¶

The logical state of the key.

Returns:	The state change of the key.
Return type:	KeyState

seat_key_count¶

The total number of keys pressed on all devices on the associated seat after the event was triggered.

Returns:	The seat wide pressed key count for the key of this event.
Return type:	int

TouchEvent¶

class libinput.event.TouchEvent(*args)¶

Touch event representing a touch down, move or up, as well as a touch cancel and touch frame events.

time¶

Note

Timestamps may not always increase. See Event timestamps for details.

Returns:	The event time for this event in microseconds.
Return type:	int

slot¶

The slot of this touch event.

See the kernel’s multitouch protocol B documentation for more information.

If the touch event has no assigned slot, for example if it is from a single touch device, this property returns -1.

For events not of type TOUCH_DOWN, TOUCH_UP, TOUCH_MOTION or TOUCH_CANCEL, this property raises AttributeError.

Returns:	The slot of this touch event.
Return type:	int
Raises:	`AttributeError`

seat_slot¶

The seat slot of the touch event.

A seat slot is a non-negative seat wide unique identifier of an active touch point.

Events from single touch devices will be represented as one individual touch point per device.

For events not of type TOUCH_DOWN, TOUCH_UP, TOUCH_MOTION or TOUCH_CANCEL, this property raises AssertionError.

Returns:	The seat slot of the touch event.
Return type:	int
Raises:	`AssertionError`

coords¶

The current absolute coordinates of the touch event, in mm from the top left corner of the device.

To get the corresponding output screen coordinates, use transform_coords().

For events not of type TOUCH_DOWN, TOUCH_MOTION, this property raises AttributeError.

Returns:	The current absolute (x, y) coordinates.
Return type:	(float, float)
Raises:	`AttributeError`

transform_coords(width, height)¶

Return the current absolute coordinates of the touch event, transformed to screen coordinates.

For events not of type TOUCH_DOWN, TOUCH_MOTION, this method raises AttributeError.

Parameters:	width (int) – The current output screen width. height (int) – The current output screen height.
Returns:	The current absolute (x, y) coordinates transformed to screen coordinates.
Return type:	(float, float)

GestureEvent¶

class libinput.event.GestureEvent(*args)¶

A gesture event representing gesture on a touchpad.

Gesture sequences always start with a GESTURE_FOO_START event. All following gesture events will be of the GESTURE_FOO_UPDATE type until a GESTURE_FOO_END is generated which signals the end of the gesture.

See Gestures for more information on gesture handling.

time¶

Note

Timestamps may not always increase. See Event timestamps for details.

Returns:	The event time for this event in microseconds.
Return type:	int

finger_count¶

The number of fingers used for a gesture.

This can be used e.g. to differentiate between 3 or 4 finger swipes. This property is valid for all gesture events and the returned finger count value will not change during a sequence.

Returns:	The number of fingers used for a gesture.
Return type:	int

cancelled¶

Return if the gesture ended normally, or if it was cancelled.

For gesture events that are not of type GESTURE_SWIPE_END or GESTURE_PINCH_END, this property raises AttributeError.

Returns:	`True` indicating that the gesture was cancelled.
Return type:	bool
Raises:	`AttributeError`

delta¶

The delta between the last event and the current event.

For gesture events that are not of type GESTURE_SWIPE_UPDATE or GESTURE_PINCH_UPDATE, this property raises AttributeError.

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

Relative motion deltas are normalized to represent those of a device with 1000dpi resolution. See Normalization of relative motion for more details.

Returns:	The relative (x, y) movement since the last event.
Return type:	(float, float)

delta_unaccelerated¶

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

For gesture events that are not of type GESTURE_SWIPE_UPDATE or GESTURE_PINCH_UPDATE, this property raises AttributeError.

Relative unaccelerated motion deltas are normalized to represent those of a device with 1000dpi resolution. See Normalization of relative motion for more details. Note that unaccelerated events are not equivalent to ‘raw’ events as read from the device.

Any rotation applied to the device also applies to gesture motion (see set_angle()).

Returns:	The unaccelerated relative (x, y) movement since the last event.
Return type:	(float, float)

scale¶

The absolute scale of a pinch gesture, the scale is the division of the current distance between the fingers and the distance at the start of the gesture.

The scale begins at 1.0, and if e.g. the fingers moved together by 50% then the scale will become 0.5, if they move twice as far apart as initially the scale becomes 2.0, etc.

For gesture events that are of type GESTURE_PINCH_BEGIN, this property returns 1.0.

For gesture events that are of type GESTURE_PINCH_END, this property returns the scale value of the most recent GESTURE_PINCH_UPDATE event (if any) or 1.0 otherwise.

For all other events this property raises AttributeError.

Returns:	The absolute scale of a pinch gesture.
Return type:	float
Raises:	`AttributeError`

angle_delta¶

The angle delta in degrees between the last and the current GESTURE_PINCH_UPDATE event.

For gesture events that are not of type GESTURE_PINCH_UPDATE, this property raises AttributeError.

The angle delta is defined as the change in angle of the line formed by the 2 fingers of a pinch gesture. Clockwise rotation is represented by a positive delta, counter-clockwise by a negative delta. If e.g. the fingers are on the 12 and 6 location of a clock face plate and they move to the 1 resp. 7 location in a single event then the angle delta is 30 degrees.

If more than two fingers are present, the angle represents the rotation around the center of gravity. The calculation of the center of gravity is implementation-dependent.

Returns:	The angle delta since the last event.
Return type:	float
Raises:	`AttributeError`

TabletToolEvent¶

class libinput.event.TabletToolEvent(*args)¶

Tablet tool event representing an axis update, button press, or tool update.

Valid event types for this event are TABLET_TOOL_AXIS, TABLET_TOOL_PROXIMITY, TABLET_TOOL_TIP and TABLET_TOOL_BUTTON.

coords¶

The (X, Y) coordinates of the tablet tool, in mm from the top left corner of the tablet in its current logical orientation and whether they have changed in this event.

Use transform_coords() for transforming the axes values into a different coordinate space.

Note

On some devices, returned value may be negative or larger than the width of the device. See Out-of-bounds motion events for more details.

Returns:	The current values of the the axes and whether they have changed.
Return type:	((float, float), bool)

delta¶

The delta between the last event and the current event.

If the tool employs pointer acceleration, the delta contained in this property is the accelerated delta.

This value is in screen coordinate space, the delta is to be interpreted like the value of PointerEvent.delta. See Relative motion for tablet tools for more details.

Returns:	The relative (x, y) movement since the last event.
Return type:	(float, float)

pressure¶

The current pressure being applied on the tool in use, normalized to the range [0, 1] and whether it has changed in this event.

If this axis does not exist on the current tool, this property is (0, False).

Returns:	The current value of the the axis and whether it has changed.
Return type:	(float, bool)

distance¶

The current distance from the tablet’s sensor, normalized to the range [0, 1] and whether it has changed in this event.

If this axis does not exist on the current tool, this property is (0, False).

Returns:	The current value of the the axis.
Return type:	(float, bool)

tilt_axes¶

The current tilt along the (X, Y) axes of the tablet’s current logical orientation, in degrees off the tablet’s Z axis and whether they have changed in this event.

That is, if the tool is perfectly orthogonal to the tablet, the tilt angle is 0. When the top tilts towards the logical top/left of the tablet, the x/y tilt angles are negative, if the top tilts towards the logical bottom/right of the tablet, the x/y tilt angles are positive.

If these axes do not exist on the current tool, this property returns ((0, 0), False).

Returns:	The current value of the axes in degrees and whether it has changed.
Return type:	((float, float), bool)

rotation¶

The current Z rotation of the tool in degrees, clockwise from the tool’s logical neutral position and whether it has changed in this event.

For tools of type MOUSE and LENS the logical neutral position is pointing to the current logical north of the tablet. For tools of type BRUSH, the logical neutral position is with the buttons pointing up.

If this axis does not exist on the current tool, this property is (0, False).

Returns:	The current value of the the axis and whether it has changed.
Return type:	(float, bool)

slider_position¶

The current position of the slider on the tool, normalized to the range [-1, 1] and whether it has changed in this event.

The logical zero is the neutral position of the slider, or the logical center of the axis. This axis is available on e.g. the Wacom Airbrush.

If this axis does not exist on the current tool, this property is (0, False).

Returns:	The current value of the the axis.
Return type:	(float, bool)

wheel_delta¶

The delta for the wheel in degrees and whether it has changed in this event.

Returns:	The delta of the wheel, in degrees, compared to the last event and whether it has changed.
Return type:	(float, bool)

wheel_delta_discrete¶

The delta for the wheel in discrete steps (e.g. wheel clicks) and whether it has changed in this event.

Returns:	The delta of the wheel, in discrete steps, compared to the last event and whether it has changed.
Return type:	(int, bool)

transform_coords(width, height)¶

Return the current absolute (x, y) coordinates of the tablet tool event, transformed to screen coordinates and whether they have changed in this event.

Note

On some devices, returned value may be negative or larger than the width of the device. See Out-of-bounds motion events for more details.

Parameters:	width (int) – The current output screen width. height (int) – The current output screen height.
Returns:	The current absolute (x, y) coordinates transformed to screen coordinates and whether they have changed.
Return type:	((float, float), bool)

tool¶

The tool that was in use during this event.

If the caller keeps a reference to a tool, the tool object will compare equal to the previously obtained tool object.

Note

Physical tool tracking requires hardware support. If unavailable, libinput creates one tool per type per tablet. See Tracking unique tools for more details.

Returns:	The new tool triggering this event.
Return type:	TabletTool

proximity_state¶

The new proximity state of a tool from a proximity event.

Used to check whether or not a tool came in or out of proximity during an event of type TABLET_TOOL_PROXIMITY.

See Handling of proximity events for recommendations on proximity handling.

Returns:	The new proximity state of the tool from the event.
Return type:	TabletToolProximityState

tip_state¶

The new tip state of a tool from a tip event.

Used to check whether or not a tool came in contact with the tablet surface or left contact with the tablet surface during an event of type TABLET_TOOL_TIP.

Returns:	The new tip state of the tool from the event.
Return type:	TabletToolTipState

button¶

The button that triggered this event.

For events that are not of type TABLET_TOOL_BUTTON, this property raises AttributeError.

Returns:	The button triggering this event.
Return type:	int

button_state¶

The button state of the event.

For events that are not of type TABLET_TOOL_BUTTON, this property raises AttributeError.

Returns:	The button state triggering this event.
Return type:	ButtonState

seat_button_count¶

The total number of buttons pressed on all devices on the associated seat after the the event was triggered.

For events that are not of type TABLET_TOOL_BUTTON, this property raises AttributeError.

Returns:	The seat wide pressed button count for the key of this event.
Return type:	int

time¶

Note

Timestamps may not always increase. See Event timestamps for details.

Returns:	The event time for this event in microseconds.
Return type:	int

TabletPadEvent¶

class libinput.event.TabletPadEvent(*args)¶

Tablet pad event representing a button press or ring/strip update on the tablet pad itself.

Valid event types for this event are TABLET_PAD_BUTTON, TABLET_PAD_RING and TABLET_PAD_STRIP.

ring_position¶

The current position of the ring, in degrees counterclockwise from the northern-most point of the ring in the tablet’s current logical orientation.

If the source is FINGER, libinput sends a terminating event with a ring value of -1 when the finger is lifted from the ring. A caller may use this information to e.g. determine if kinetic scrolling should be triggered.

For events not of type TABLET_PAD_RING, this property raises AttributeError.

Returns:	The current value of the the axis. -1 if the finger was lifted.
Return type:	float
Raises:	`AttributeError`

ring_number¶

The number of the ring that has changed state, with 0 being the first ring.

On tablets with only one ring, this method always returns 0.

For events not of type TABLET_PAD_RING, this property raises AssertionError.

Returns:	The index of the ring that changed state.
Return type:	int
Raises:	`AssertionError`

ring_source¶

The source of the interaction with the ring.

If the source is FINGER, libinput sends a ring position value of -1 to terminate the current interaction.

For events not of type TABLET_PAD_RING, this property raises AttributeError.

Returns:	The source of the ring interaction.
Return type:	TabletPadRingAxisSource
Raises:	`AttributeError`

strip_position¶

The current position of the strip, normalized to the range [0, 1], with 0 being the top/left-most point in the tablet’s current logical orientation.

If the source is FINGER, libinput sends a terminating event with a value of -1 when the finger is lifted from the strip. A caller may use this information to e.g. determine if kinetic scrolling should be triggered.

For events not of type TABLET_PAD_STRIP, this property raises AttributeError.

Returns:	The current value of the the axis. -1 if the finger was lifted.
Return type:	float
Raises:	`AttributeError`

strip_number¶

The number of the strip that has changed state, with 0 being the first strip.

On tablets with only one strip, this method always returns 0.

For events not of type TABLET_PAD_STRIP, this property raises AttributeError.

Returns:	The index of the strip that changed state.
Return type:	int
Raises:	`AttributeError`

strip_source¶

The source of the interaction with the strip.

If the source is FINGER, libinput sends a strip position value of -1 to terminate the current interaction.

For events not of type TABLET_PAD_STRIP, this property raises AttributeError.

Returns:	The source of the strip interaction.
Return type:	TabletPadStripAxisSource
Raises:	`AttributeError`

button_number¶

The button number that triggered this event, starting at 0.

For events that are not of type TABLET_PAD_BUTTON, this property raises AttributeError.

Note that the number returned is a generic sequential button number and not a semantic button code as defined in linux/input.h. See Tablet pad button numbers for more details.

Returns:	The button triggering this event.
Return type:	int
Raises:	`AttributeError`

button_state¶

The button state of the event.

For events not of type TABLET_PAD_BUTTON, this property raises AttributeError.

Returns:	The button state triggering this event.
Return type:	ButtonState
Raises:	`AttributeError`

mode¶

The mode the button, ring, or strip that triggered this event is in, at the time of the event.

The mode is a virtual grouping of functionality, usually based on some visual feedback like LEDs on the pad. See Tablet pad modes for details. Mode indices start at 0, a device that does not support modes always returns 0.

Mode switching is controlled by libinput and more than one mode may exist on the tablet. This method returns the mode that this event’s button, ring or strip is logically in. If the button is a mode toggle button and the button event caused a new mode to be toggled, the mode returned is the new mode the button is in.

Note that the returned mode is the mode valid as of the time of the event. The returned mode may thus be different to the mode returned by mode. See mode for details.

Returns:	The 0-indexed mode of this button, ring or strip at the time of the event.
Return type:	int

mode_group¶

The mode group that the button, ring, or strip that triggered this event is considered in.

The mode is a virtual grouping of functionality, usually based on some visual feedback like LEDs on the pad. See Tablet pad modes for details.

Returns:	The mode group of the button, ring or strip that caused this event.
Return type:	TabletPadModeGroup

time¶

Note

Timestamps may not always increase. See Event timestamps for details.

Returns:	The event time for this event in microseconds.
Return type:	int

SwitchEvent¶

class libinput.event.SwitchEvent(*args)¶

A switch event representing a changed state in a switch.

switch¶

The switch that triggered this event.

Returns:	The switch triggering this event.
Return type:	Switch

switch_state¶

The switch state that triggered this event.

Returns:	The switch state triggering this event.
Return type:	SwitchState

time¶

Note

Timestamps may not always increase. See Event timestamps for details.

Returns:	The event time for this event in microseconds.
Return type:	int

DeviceNotifyEvent¶

class libinput.event.DeviceNotifyEvent(*args)¶: An event notifying the caller of a device being added or removed.