Initialization and manipulation of libinput contexts

Data Structures
struct	libinput
	A handle for accessing libinput. More...
struct	libinput_interface
	libinput does not open file descriptors to devices directly, instead open_restricted() and close_restricted() are called for each path that must be opened. More...

Typedefs
typedef void(*	libinput_log_handler) (struct libinput *libinput, enum libinput_log_priority priority, const char *format, va_list args) LIBINPUT_ATTRIBUTE_PRINTF(3
	Log handler type for custom logging.
typedef void(*) voi	libinput_log_set_handler) (struct libinput *libinput, libinput_log_handler log_handler)
	Set the context's log handler.

Enumerations
enum	libinput_log_priority { LIBINPUT_LOG_PRIORITY_DEBUG , LIBINPUT_LOG_PRIORITY_INFO , LIBINPUT_LOG_PRIORITY_ERROR }
	Log priority for internal logging messages. More...
enum	libinput_event_type {   LIBINPUT_EVENT_NONE , LIBINPUT_EVENT_DEVICE_ADDED , LIBINPUT_EVENT_DEVICE_REMOVED , LIBINPUT_EVENT_KEYBOARD_KEY ,   LIBINPUT_EVENT_POINTER_MOTION , LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE , LIBINPUT_EVENT_POINTER_BUTTON , LIBINPUT_EVENT_POINTER_AXIS ,   LIBINPUT_EVENT_POINTER_SCROLL_WHEEL , LIBINPUT_EVENT_POINTER_SCROLL_FINGER , LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS , LIBINPUT_EVENT_TOUCH_DOWN ,   LIBINPUT_EVENT_TOUCH_UP , LIBINPUT_EVENT_TOUCH_MOTION , LIBINPUT_EVENT_TOUCH_CANCEL , LIBINPUT_EVENT_TOUCH_FRAME ,   LIBINPUT_EVENT_TABLET_TOOL_AXIS , LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY , LIBINPUT_EVENT_TABLET_TOOL_TIP , LIBINPUT_EVENT_TABLET_TOOL_BUTTON ,   LIBINPUT_EVENT_TABLET_PAD_BUTTON , LIBINPUT_EVENT_TABLET_PAD_RING , LIBINPUT_EVENT_TABLET_PAD_STRIP , LIBINPUT_EVENT_TABLET_PAD_KEY ,   LIBINPUT_EVENT_GESTURE_SWIPE_BEGIN , LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE , LIBINPUT_EVENT_GESTURE_SWIPE_END , LIBINPUT_EVENT_GESTURE_PINCH_BEGIN ,   LIBINPUT_EVENT_GESTURE_PINCH_UPDATE , LIBINPUT_EVENT_GESTURE_PINCH_END , LIBINPUT_EVENT_GESTURE_HOLD_BEGIN , LIBINPUT_EVENT_GESTURE_HOLD_END ,   LIBINPUT_EVENT_SWITCH_TOGGLE }
	Event type for events returned by libinput_get_event(). More...

Functions
struct libinput *	libinput_udev_create_context (const struct libinput_interface *interface, void *user_data, struct udev *udev)
	Create a new libinput context from udev.
int	libinput_udev_assign_seat (struct libinput *libinput, const char *seat_id)
	Assign a seat to this libinput context.
struct libinput *	libinput_path_create_context (const struct libinput_interface *interface, void *user_data)
	Create a new libinput context that requires the caller to manually add or remove devices with libinput_path_add_device() and libinput_path_remove_device().
struct libinput_device *	libinput_path_add_device (struct libinput *libinput, const char *path)
	Add a device to a libinput context initialized with libinput_path_create_context().
void	libinput_path_remove_device (struct libinput_device *device)
	Remove a device from a libinput context initialized with libinput_path_create_context() or added to such a context with libinput_path_add_device().
int	libinput_get_fd (struct libinput *libinput)
	libinput keeps a single file descriptor for all events.
int	libinput_dispatch (struct libinput *libinput)
	Main event dispatchment function.
struct libinput_event *	libinput_get_event (struct libinput *libinput)
	Retrieve the next event from libinput's internal event queue.
enum libinput_event_type	libinput_next_event_type (struct libinput *libinput)
	Return the type of the next event in the internal queue.
void	libinput_set_user_data (struct libinput *libinput, void *user_data)
	Set caller-specific data associated with this context.
void *	libinput_get_user_data (struct libinput *libinput)
	Get the caller-specific data associated with this context, if any.
int	libinput_resume (struct libinput *libinput)
	Resume a suspended libinput context.
void	libinput_suspend (struct libinput *libinput)
	Suspend monitoring for new devices and close existing devices.
struct libinput *	libinput_ref (struct libinput *libinput)
	Add a reference to the context.
struct libinput *	libinput_unref (struct libinput *libinput)
	Dereference the libinput context.
void	libinput_log_set_priority (struct libinput *libinput, enum libinput_log_priority priority)
	Set the log priority for the libinput context.
enum libinput_log_priority	libinput_log_get_priority (const struct libinput *libinput)
	Get the context's log priority.

Detailed Description

Typedef Documentation

libinput_log_handler

typedef void(* libinput_log_handler) (struct libinput *libinput, enum libinput_log_priority priority, const char *format, va_list args) LIBINPUT_ATTRIBUTE_PRINTF(3

Log handler type for custom logging.

Parameters

libinput	The libinput context
priority	The priority of the current message
format	Message format in printf-style
args	Message arguments

See also

libinput_log_set_priority

libinput_log_get_priority

libinput_log_set_handler

libinput_log_set_handler

typedef void(*) voi libinput_log_set_handler) (struct libinput *libinput, libinput_log_handler log_handler)

Set the context's log handler.

Messages with priorities equal to or higher than the context's log priority will be passed to the given log handler.

The default log handler prints to stderr.

Parameters

libinput	A previously initialized libinput context
log_handler	The log handler for library messages.

See also

libinput_log_set_priority

libinput_log_get_priority

Enumeration Type Documentation

libinput_event_type

enum libinput_event_type

Event type for events returned by libinput_get_event().

Enumerator
LIBINPUT_EVENT_NONE	This is not a real event type, and is only used to tell the user that no new event is available in the queue. See libinput_next_event_type().
LIBINPUT_EVENT_DEVICE_ADDED	Signals that a device has been added to the context. The device will not be read until the next time the user calls libinput_dispatch() and data is available. This allows setting up initial device configuration before any events are created.
LIBINPUT_EVENT_DEVICE_REMOVED	Signals that a device has been removed. No more events from the associated device will be in the queue or be queued after this event.
LIBINPUT_EVENT_KEYBOARD_KEY
LIBINPUT_EVENT_POINTER_MOTION
LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE
LIBINPUT_EVENT_POINTER_BUTTON
LIBINPUT_EVENT_POINTER_AXIS	A scroll event from various sources. This event is deprecated as of libinput 1.19. Use LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS instead. Use libinput_event_pointer_get_axis_source() to determine the source of a scroll event. For libinput versions 1.19 and later, the source is encoded in the event type. This event is sent in addition to events of type LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS. Do not mix and match, either use the old event or the new events. libinput makes no guarantee about the relation between LIBINPUT_EVENT_POINTER_AXIS and the new event types LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS. You may receive multiple zero, one or more new events per legacy event. Warning Ignore this event if you are processing LIBINPUT_EVENT_POINTER_SCROLL_WHEEL, LIBINPUT_EVENT_POINTER_SCROLL_FINGER, and LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS.
LIBINPUT_EVENT_POINTER_SCROLL_WHEEL	A scroll event from a wheel. This event is sent is sent in addition to the LIBINPUT_EVENT_POINTER_AXIS event for all events with a libinput_event_pointer_get_axis_source() of LIBINPUT_POINTER_AXIS_SOURCE_WHEEL. Ignore LIBINPUT_EVENT_POINTER_AXIS if you are processing this event. See the libinput documentation for details. Since 1.19
LIBINPUT_EVENT_POINTER_SCROLL_FINGER	A scroll event caused by the movement of one or more fingers on a device. This event is sent is sent in addition to the LIBINPUT_EVENT_POINTER_AXIS event for all events with a libinput_event_pointer_get_axis_source() of LIBINPUT_POINTER_AXIS_SOURCE_FINGER. Ignore LIBINPUT_EVENT_POINTER_AXIS if you are processing this event. See the libinput documentation for details. Since 1.19
LIBINPUT_EVENT_POINTER_SCROLL_CONTINUOUS	A scroll event from a continuous scroll source, e.g. button scrolling. This event is sent is sent in addition to the LIBINPUT_EVENT_POINTER_AXIS event for all events with a libinput_event_pointer_get_axis_source() of LIBINPUT_POINTER_AXIS_SOURCE_CONTINUOUS. Ignore LIBINPUT_EVENT_POINTER_AXIS if you are processing this event. See the libinput documentation for details. Since 1.19
LIBINPUT_EVENT_TOUCH_DOWN
LIBINPUT_EVENT_TOUCH_UP
LIBINPUT_EVENT_TOUCH_MOTION
LIBINPUT_EVENT_TOUCH_CANCEL
LIBINPUT_EVENT_TOUCH_FRAME	Signals the end of a set of touchpoints at one device sample time. This event has no coordinate information attached.
LIBINPUT_EVENT_TABLET_TOOL_AXIS	One or more axes have changed state on a device with the LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. This event is only sent when the tool is in proximity, see LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY for details. The proximity event contains the initial state of the axis as the tool comes into proximity. An event of type LIBINPUT_EVENT_TABLET_TOOL_AXIS is only sent when an axis value changes from this initial state. It is possible for a tool to enter and leave proximity without sending an event of type LIBINPUT_EVENT_TABLET_TOOL_AXIS. An event of type LIBINPUT_EVENT_TABLET_TOOL_AXIS is sent when the tip state does not change. See the documentation for LIBINPUT_EVENT_TABLET_TOOL_TIP for more details. Since 1.2
LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY	Signals that a tool has come in or out of proximity of a device with the LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. Proximity events contain each of the current values for each axis, and these values may be extracted from them in the same way they are with LIBINPUT_EVENT_TABLET_TOOL_AXIS events. Some tools may always be in proximity. For these tools, events of type LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_IN are sent only once after LIBINPUT_EVENT_DEVICE_ADDED, and events of type LIBINPUT_TABLET_TOOL_PROXIMITY_STATE_OUT are sent only once before LIBINPUT_EVENT_DEVICE_REMOVED. If the tool that comes into proximity supports x/y coordinates, libinput guarantees that both x and y are set in the proximity event. When a tool goes out of proximity, the value of every axis should be assumed to have an undefined state and any buttons that are currently held down on the stylus are marked as released. Button release events for each button that was held down on the stylus are sent before the proximity out event. Since 1.2
LIBINPUT_EVENT_TABLET_TOOL_TIP	Signals that a tool has come in contact with the surface of a device with the LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. On devices without distance proximity detection, the LIBINPUT_EVENT_TABLET_TOOL_TIP is sent immediately after LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY for the tip down event, and immediately before for the tip up event. The decision when a tip touches the surface is device-dependent and may be derived from pressure data or other means. If the tip state is changed by axes changing state, the LIBINPUT_EVENT_TABLET_TOOL_TIP event includes the changed axes and no additional axis event is sent for this state change. In other words, a caller must look at both LIBINPUT_EVENT_TABLET_TOOL_AXIS and LIBINPUT_EVENT_TABLET_TOOL_TIP events to know the current state of the axes. If a button state change occurs at the same time as a tip state change, the order of events is device-dependent. Since 1.2
LIBINPUT_EVENT_TABLET_TOOL_BUTTON	Signals that a tool has changed a logical button state on a device with the LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. Button state changes occur on their own and do not include axis state changes. If button and axis state changes occur within the same logical hardware event, the order of the LIBINPUT_EVENT_TABLET_TOOL_BUTTON and LIBINPUT_EVENT_TABLET_TOOL_AXIS event is device-specific. This event is not to be confused with the button events emitted by the tablet pad. See LIBINPUT_EVENT_TABLET_PAD_BUTTON. See also LIBINPUT_EVENT_TABLET_PAD_BUTTON Since 1.2
LIBINPUT_EVENT_TABLET_PAD_BUTTON	A button pressed on a device with the LIBINPUT_DEVICE_CAP_TABLET_PAD capability. A button differs from LIBINPUT_EVENT_TABLET_PAD_KEY in that buttons are sequentially indexed from 0 and do not carry any other information. Keys have a specific functionality assigned to them. The key code thus carries a semantic meaning, a button number does not. This event is not to be confused with the button events emitted by tools on a tablet (LIBINPUT_EVENT_TABLET_TOOL_BUTTON). Since 1.3
LIBINPUT_EVENT_TABLET_PAD_RING	A status change on a tablet ring with the LIBINPUT_DEVICE_CAP_TABLET_PAD capability. Since 1.3
LIBINPUT_EVENT_TABLET_PAD_STRIP	A status change on a strip on a device with the LIBINPUT_DEVICE_CAP_TABLET_PAD capability. Since 1.3
LIBINPUT_EVENT_TABLET_PAD_KEY	A key pressed on a device with the LIBINPUT_DEVICE_CAP_TABLET_PAD capability. A key differs from LIBINPUT_EVENT_TABLET_PAD_BUTTON in that keys have a specific functionality assigned to them (buttons are sequentially ordered). The key code thus carries a semantic meaning, a button number does not. Since 1.15
LIBINPUT_EVENT_GESTURE_SWIPE_BEGIN
LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE
LIBINPUT_EVENT_GESTURE_SWIPE_END
LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
LIBINPUT_EVENT_GESTURE_PINCH_UPDATE
LIBINPUT_EVENT_GESTURE_PINCH_END
LIBINPUT_EVENT_GESTURE_HOLD_BEGIN	Since 1.19
LIBINPUT_EVENT_GESTURE_HOLD_END
LIBINPUT_EVENT_SWITCH_TOGGLE	Since 1.7

libinput_log_priority

enum libinput_log_priority

Log priority for internal logging messages.

Enumerator
LIBINPUT_LOG_PRIORITY_DEBUG
LIBINPUT_LOG_PRIORITY_INFO
LIBINPUT_LOG_PRIORITY_ERROR

Function Documentation

libinput_dispatch()

int libinput_dispatch

(

struct libinput *

libinput

)

Main event dispatchment function.

Reads events of the file descriptors and processes them internally. Use libinput_get_event() to retrieve the events.

Dispatching does not necessarily queue libinput events. This function should be called immediately once data is available on the file descriptor returned by libinput_get_fd(). libinput has a number of timing-sensitive features (e.g. tap-to-click), any delay in calling libinput_dispatch() may prevent these features from working correctly.

Parameters

libinput

A previously initialized libinput context

Returns

0 on success, or a negative errno on failure

libinput_get_event()

struct libinput_event * libinput_get_event

(

struct libinput *

libinput

)

Retrieve the next event from libinput's internal event queue.

After handling the retrieved event, the caller must destroy it using libinput_event_destroy().

Parameters

libinput

A previously initialized libinput context

Returns

The next available event, or NULL if no event is available.

libinput_get_fd()

int libinput_get_fd

(

struct libinput *

libinput

)

libinput keeps a single file descriptor for all events.

Call into libinput_dispatch() if any events become available on this fd.

Returns

The file descriptor used to notify of pending events.

libinput_get_user_data()

void * libinput_get_user_data

(

struct libinput *

libinput

)

Get the caller-specific data associated with this context, if any.

Parameters

libinput

A previously initialized libinput context

Returns

The caller-specific data previously assigned in libinput_set_user_data(), libinput_path_create_context() or libinput_udev_create_context().

libinput_log_get_priority()

enum libinput_log_priority libinput_log_get_priority

(

const struct libinput *

libinput

)

Get the context's log priority.

Messages with priorities equal to or higher than the argument will be printed to the current log handler.

The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.

Parameters

libinput

A previously initialized libinput context

Returns

The minimum priority of log messages to print.

See also

libinput_log_set_handler

libinput_log_set_priority

libinput_log_set_priority()

void libinput_log_set_priority	(	struct libinput *	libinput,
		enum libinput_log_priority	priority
	)

Set the log priority for the libinput context.

Messages with priorities equal to or higher than the argument will be printed to the context's log handler.

The default log priority is LIBINPUT_LOG_PRIORITY_ERROR.

Parameters

libinput	A previously initialized libinput context
priority	The minimum priority of log messages to print.

See also

libinput_log_set_handler

libinput_log_get_priority

libinput_next_event_type()

enum libinput_event_type libinput_next_event_type

(

struct libinput *

libinput

)

Return the type of the next event in the internal queue.

This function does not pop the event off the queue and the next call to libinput_get_event() returns that event.

Parameters

libinput

A previously initialized libinput context

Returns

The event type of the next available event or LIBINPUT_EVENT_NONE if no event is available.

libinput_path_add_device()

struct libinput_device * libinput_path_add_device	(	struct libinput *	libinput,
		const char *	path
	)

Add a device to a libinput context initialized with libinput_path_create_context().

If successful, the device will be added to the internal list and re-opened on libinput_resume(). The device can be removed with libinput_path_remove_device().

If the device was successfully initialized, it is returned in the device argument. The lifetime of the returned device pointer is limited until the next libinput_dispatch(), use libinput_device_ref() to keep a permanent reference.

Parameters

libinput	A previously initialized libinput context
path	Path to an input device

Returns

The newly initiated device on success, or NULL on failure.

Note

It is an application bug to call this function on a libinput context initialized with libinput_udev_create_context().

libinput_path_create_context()

struct libinput * libinput_path_create_context	(	const struct libinput_interface *	interface,
		void *	user_data
	)

Create a new libinput context that requires the caller to manually add or remove devices with libinput_path_add_device() and libinput_path_remove_device().

The context is fully initialized but will not generate events until at least one device has been added.

The reference count of the context is initialized to 1. See libinput_unref.

Parameters

interface	The callback interface
user_data	Caller-specific data passed to the various callback interfaces.

Returns

An initialized, empty libinput context.

libinput_path_remove_device()

void libinput_path_remove_device

(

struct libinput_device *

device

)

Remove a device from a libinput context initialized with libinput_path_create_context() or added to such a context with libinput_path_add_device().

Events already processed from this input device are kept in the queue, the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this device.

If no matching device exists, this function does nothing.

Parameters

device

A libinput device

Note

It is an application bug to call this function on a libinput context initialized with libinput_udev_create_context().

libinput_ref()

struct libinput * libinput_ref

(

struct libinput *

libinput

)

Add a reference to the context.

A context is destroyed whenever the reference count reaches 0. See libinput_unref.

Parameters

libinput

A previously initialized valid libinput context

Returns

The passed libinput context

libinput_resume()

int libinput_resume

(

struct libinput *

libinput

)

Resume a suspended libinput context.

This re-enables device monitoring and adds existing devices.

Parameters

libinput

A previously initialized libinput context

See also

libinput_suspend

Returns

0 on success or -1 on failure

libinput_set_user_data()

void libinput_set_user_data	(	struct libinput *	libinput,
		void *	user_data
	)

Set caller-specific data associated with this context.

libinput does not manage, look at, or modify this data. The caller must ensure the data is valid.

Parameters

libinput	A previously initialized libinput context
user_data	Caller-specific data passed to the various callback interfaces.

libinput_suspend()

void libinput_suspend

(

struct libinput *

libinput

)

Suspend monitoring for new devices and close existing devices.

This all but terminates libinput but does keep the context valid to be resumed with libinput_resume().

Parameters

libinput

A previously initialized libinput context

libinput_udev_assign_seat()

int libinput_udev_assign_seat	(	struct libinput *	libinput,
		const char *	seat_id
	)

Assign a seat to this libinput context.

New devices or the removal of existing devices will appear as events during libinput_dispatch().

libinput_udev_assign_seat() succeeds even if no input devices are currently available on this seat, or if devices are available but fail to open in libinput_interface::open_restricted. Devices that do not have the minimum capabilities to be recognized as pointer, keyboard or touch device are ignored. Such devices and those that failed to open ignored until the next call to libinput_resume().

This function may only be called once per context.

Parameters

libinput	A libinput context initialized with libinput_udev_create_context()
seat_id	A seat identifier. This string must not be NULL.

Returns

0 on success or -1 on failure.

libinput_udev_create_context()

struct libinput * libinput_udev_create_context	(	const struct libinput_interface *	interface,
		void *	user_data,
		struct udev *	udev
	)

Create a new libinput context from udev.

This context is inactive until assigned a seat ID with libinput_udev_assign_seat().

Parameters

interface	The callback interface
user_data	Caller-specific data passed to the various callback interfaces.
udev	An already initialized udev context

Returns

An initialized, but inactive libinput context or NULL on error

libinput_unref()

struct libinput * libinput_unref

(

struct libinput *

libinput

)

Dereference the libinput context.

After this, the context may have been destroyed, if the last reference was dereferenced. If so, the context is invalid and may not be interacted with.

Bug:

When the refcount reaches zero, libinput_unref() releases resources even if a caller still holds refcounted references to related resources (e.g. a libinput_device). When libinput_unref() returns NULL, the caller must consider any resources related to that context invalid. See https://bugs.freedesktop.org/show_bug.cgi?id=91872.

Example code:

li = libinput_path_create_context(&interface, NULL);
device = libinput_path_add_device(li, "/dev/input/event0");
// get extra reference to device
libinput_device_ref(device);
 
// refcount reaches 0, so *all* resources are cleaned up,
// including device
libinput_unref(li);
 
// INCORRECT: device has been cleaned up and must not be used
// li = libinput_device_get_context(device);

Parameters

libinput

A previously initialized libinput context

Returns

NULL if context was destroyed otherwise the passed context