mirror of
https://gitlab.freedesktop.org/libinput/libinput.git
synced 2025-12-25 16:20:05 +01:00
9a2f2ab46b
For consistency with the other ref/unref funtions, see
13e9a1d744
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
1663 lines
49 KiB
C
1663 lines
49 KiB
C
/*
|
|
* Copyright © 2013 Jonas Ådahl
|
|
*
|
|
* Permission to use, copy, modify, distribute, and sell this software and
|
|
* its documentation for any purpose is hereby granted without fee, provided
|
|
* that the above copyright notice appear in all copies and that both that
|
|
* copyright notice and this permission notice appear in supporting
|
|
* documentation, and that the name of the copyright holders not be used in
|
|
* advertising or publicity pertaining to distribution of the software
|
|
* without specific, written prior permission. The copyright holders make
|
|
* no representations about the suitability of this software for any
|
|
* purpose. It is provided "as is" without express or implied warranty.
|
|
*
|
|
* THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
|
|
* SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
|
* FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
|
* SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
|
|
* RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
|
|
* CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
|
|
* CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
*/
|
|
|
|
#ifndef LIBINPUT_H
|
|
#define LIBINPUT_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#include <stdlib.h>
|
|
#include <stdint.h>
|
|
#include <libudev.h>
|
|
|
|
#define LIBINPUT_ATTRIBUTE_PRINTF(_format, _args) \
|
|
__attribute__ ((format (printf, _format, _args)))
|
|
#define LIBINPUT_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated))
|
|
|
|
/**
|
|
* @mainpage
|
|
* libinput is a generic input device handling library. It abstracts
|
|
* commonly-used concepts such as keyboard, pointer and touchpad handling
|
|
* behind an API.
|
|
*/
|
|
|
|
/**
|
|
* @page tpbuttons Touchpad button behavior
|
|
*
|
|
* For touchpad devices without physical buttons, libinput enables an
|
|
* emulated right button area through either of two methods.
|
|
*
|
|
* Software button areas
|
|
* =====================
|
|
* On most touchpads, the bottom area of the touchpad is split into a left
|
|
* and a right-button area. Pressing the touchpad down with a finger in
|
|
* those areas will generate clicks as shown in the diagram below:
|
|
*
|
|
* @code
|
|
+------------------------+
|
|
| |
|
|
| |
|
|
| LEFT |
|
|
| |
|
|
| |
|
|
+------------------------+
|
|
| LEFT | RIGHT |
|
|
+------------------------+
|
|
* @endcode
|
|
*
|
|
* Generally, the touchpad will emulate a right-button click if the finger
|
|
* was set down in the right button area and did not leave the
|
|
* right button area before clicking, even if another finger was already
|
|
* down on the touchpad in another area.
|
|
* A middle click is generated by clicking the touchpad when one finger is
|
|
* in the bottom left button area, and one finger is in the botton right
|
|
* button area.
|
|
* The exact behavior of the touchpad is implementation-dependent.
|
|
*
|
|
* Top software button area
|
|
* ========================
|
|
* On selected touchpads, the top area of the touchpad is a separate set of
|
|
* software buttons split into a left, middle and right button area.
|
|
* Pressing the touchpad down with a finger in those areas will generate
|
|
* clicks as shown in the diagram below:
|
|
*
|
|
* @code
|
|
+------------------------+
|
|
| LEFT | MIDDLE | RIGHT |
|
|
+------------------------+
|
|
| |
|
|
| LEFT |
|
|
| |
|
|
+------------------------+
|
|
| LEFT | RIGHT |
|
|
+------------------------+
|
|
* @endcode
|
|
* This behavior is enabled on the Lenovo *40 series (T440, T540, T240...)
|
|
* and the Lenovo Helix, Yoga S1 and Carbon X1 2nd.
|
|
*
|
|
* Clickfinger
|
|
* ===========
|
|
* On Apple touchpads, no button areas are provided. Instead, use a
|
|
* two-finger click for a right button click, and a three-finger click for a
|
|
* middle button click.
|
|
*/
|
|
|
|
/**
|
|
* Log priority for internal logging messages.
|
|
*/
|
|
enum libinput_log_priority {
|
|
LIBINPUT_LOG_PRIORITY_DEBUG = 10,
|
|
LIBINPUT_LOG_PRIORITY_INFO = 20,
|
|
LIBINPUT_LOG_PRIORITY_ERROR = 30,
|
|
};
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Capabilities on a device. A device may have one or more capabilities
|
|
* at a time, and capabilities may appear or disappear during the
|
|
* lifetime of the device.
|
|
*/
|
|
enum libinput_device_capability {
|
|
LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
|
|
LIBINPUT_DEVICE_CAP_POINTER = 1,
|
|
LIBINPUT_DEVICE_CAP_TOUCH = 2,
|
|
LIBINPUT_DEVICE_CAP_TABLET = 3
|
|
};
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Logical state of a key. Note that the logical state may not represent
|
|
* the physical state of the key.
|
|
*/
|
|
enum libinput_key_state {
|
|
LIBINPUT_KEY_STATE_RELEASED = 0,
|
|
LIBINPUT_KEY_STATE_PRESSED = 1
|
|
};
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Mask reflecting LEDs on a device.
|
|
*/
|
|
enum libinput_led {
|
|
LIBINPUT_LED_NUM_LOCK = (1 << 0),
|
|
LIBINPUT_LED_CAPS_LOCK = (1 << 1),
|
|
LIBINPUT_LED_SCROLL_LOCK = (1 << 2)
|
|
};
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Logical state of a physical button. Note that the logical state may not
|
|
* represent the physical state of the button.
|
|
*/
|
|
enum libinput_button_state {
|
|
LIBINPUT_BUTTON_STATE_RELEASED = 0,
|
|
LIBINPUT_BUTTON_STATE_PRESSED = 1
|
|
};
|
|
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Axes on a device that are not x or y coordinates.
|
|
*/
|
|
enum libinput_pointer_axis {
|
|
LIBINPUT_POINTER_AXIS_SCROLL_VERTICAL = 0,
|
|
LIBINPUT_POINTER_AXIS_SCROLL_HORIZONTAL = 1,
|
|
};
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Available axis types for a device. It must have the @ref
|
|
* LIBINPUT_DEVICE_CAP_TABLET capability.
|
|
*/
|
|
enum libinput_tablet_axis {
|
|
LIBINPUT_TABLET_AXIS_NONE = -1,
|
|
LIBINPUT_TABLET_AXIS_X = 0,
|
|
LIBINPUT_TABLET_AXIS_Y = 1,
|
|
LIBINPUT_TABLET_AXIS_DISTANCE = 2,
|
|
LIBINPUT_TABLET_AXIS_PRESSURE = 3,
|
|
LIBINPUT_TABLET_AXIS_TILT_VERTICAL = 4,
|
|
LIBINPUT_TABLET_AXIS_TILT_HORIZONTAL = 5,
|
|
LIBINPUT_TABLET_AXIS_CNT = LIBINPUT_TABLET_AXIS_TILT_HORIZONTAL + 1
|
|
};
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* An object representing a tool being used by the device. It must have the @ref
|
|
* LIBINPUT_DEVICE_CAP_TABLET capability.
|
|
*/
|
|
struct libinput_tool;
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Available tool types for a device. It must have the @ref
|
|
* LIBINPUT_DEVICE_CAP_TABLET capability.
|
|
*/
|
|
enum libinput_tool_type {
|
|
LIBINPUT_TOOL_NONE = -1,
|
|
LIBINPUT_TOOL_PEN = 0x140, /* Matches BTN_TOOL_PEN */
|
|
LIBINPUT_TOOL_ERASER,
|
|
LIBINPUT_TOOL_BRUSH,
|
|
LIBINPUT_TOOL_PENCIL,
|
|
LIBINPUT_TOOL_AIRBRUSH,
|
|
LIBINPUT_TOOL_FINGER,
|
|
LIBINPUT_TOOL_MOUSE,
|
|
LIBINPUT_TOOL_LENS
|
|
};
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Event type for events returned by libinput_get_event().
|
|
*/
|
|
enum libinput_event_type {
|
|
/**
|
|
* 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_NONE = 0,
|
|
|
|
/**
|
|
* 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_ADDED,
|
|
|
|
/**
|
|
* 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_DEVICE_REMOVED,
|
|
|
|
LIBINPUT_EVENT_KEYBOARD_KEY = 300,
|
|
|
|
LIBINPUT_EVENT_POINTER_MOTION = 400,
|
|
LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
|
|
LIBINPUT_EVENT_POINTER_BUTTON,
|
|
LIBINPUT_EVENT_POINTER_AXIS,
|
|
|
|
LIBINPUT_EVENT_TOUCH_DOWN = 500,
|
|
LIBINPUT_EVENT_TOUCH_UP,
|
|
LIBINPUT_EVENT_TOUCH_MOTION,
|
|
LIBINPUT_EVENT_TOUCH_CANCEL,
|
|
/**
|
|
* Signals the end of a set of touchpoints at one device sample
|
|
* time. This event has no coordinate information attached.
|
|
*/
|
|
LIBINPUT_EVENT_TOUCH_FRAME,
|
|
|
|
LIBINPUT_EVENT_TABLET_AXIS = 600,
|
|
/**
|
|
* Signals that a device with the @ref LIBINPUT_DEVICE_CAP_TABLET
|
|
* capability has changed its tool.
|
|
*/
|
|
LIBINPUT_EVENT_TABLET_TOOL_UPDATE,
|
|
/**
|
|
* Signals that a device with the @ref LIBINPUT_DEVICE_CAP_TABLET
|
|
* capability has detected that there is no longer a tool in use. When
|
|
* this happens, the value of every axis should be assumed to have a
|
|
* value of 0 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 initial proximity out
|
|
* event.
|
|
*/
|
|
LIBINPUT_EVENT_TABLET_PROXIMITY_OUT,
|
|
LIBINPUT_EVENT_TABLET_BUTTON
|
|
};
|
|
|
|
struct libinput;
|
|
struct libinput_device;
|
|
struct libinput_seat;
|
|
|
|
struct libinput_event;
|
|
struct libinput_event_device_notify;
|
|
struct libinput_event_keyboard;
|
|
struct libinput_event_pointer;
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
* @struct libinput_event_touch
|
|
*
|
|
* Touch event representing a touch down, move or up, as well as a touch
|
|
* cancel and touch frame events. Valid event types for this event are @ref
|
|
* LIBINPUT_EVENT_TOUCH_DOWN, @ref LIBINPUT_EVENT_TOUCH_MOTION, @ref
|
|
* LIBINPUT_EVENT_TOUCH_UP, @ref LIBINPUT_EVENT_TOUCH_CANCEL and @ref
|
|
* LIBINPUT_EVENT_TOUCH_FRAME.
|
|
*/
|
|
struct libinput_event_touch;
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
* @struct libinput_event_tablet
|
|
*
|
|
* Tablet event representing an axis update, button press, or tool update. Valid
|
|
* event types for this event are @ref LIBINPUT_EVENT_TABLET_AXIS, @ref
|
|
* LIBINPUT_EVENT_TABLET_TOOL_UPDATE, @ref LIBINPUT_EVENT_TABLET_TOOL_UPDATE and
|
|
* @ref LIBINPUT_EVENT_TABLET_BUTTON.
|
|
*/
|
|
struct libinput_event_tablet;
|
|
|
|
/**
|
|
* @defgroup event Accessing and destruction of events
|
|
*/
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Destroy the event.
|
|
*
|
|
* @param event An event retrieved by libinput_get_event().
|
|
*/
|
|
void
|
|
libinput_event_destroy(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Get the type of the event.
|
|
*
|
|
* @param event An event retrieved by libinput_get_event().
|
|
*/
|
|
enum libinput_event_type
|
|
libinput_event_get_type(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Get the libinput context from the event.
|
|
*
|
|
* @param event The libinput event
|
|
* @return The libinput context for this event.
|
|
*/
|
|
struct libinput *
|
|
libinput_event_get_context(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Return the device associated with this event, if applicable. 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.
|
|
*
|
|
* This device is not refcounted and its lifetime is that of the event. Use
|
|
* libinput_device_ref() before using the device outside of this scope.
|
|
*
|
|
* @return The device associated with this event
|
|
*/
|
|
|
|
struct libinput_device *
|
|
libinput_event_get_device(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Return the pointer event that is this input event. If the event type does
|
|
* not match the pointer event types, this function returns NULL.
|
|
*
|
|
* The inverse of this function is libinput_event_pointer_get_base_event().
|
|
*
|
|
* @return A pointer event, or NULL for other events
|
|
*/
|
|
struct libinput_event_pointer *
|
|
libinput_event_get_pointer_event(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Return the keyboard event that is this input event. If the event type does
|
|
* not match the keyboard event types, this function returns NULL.
|
|
*
|
|
* The inverse of this function is libinput_event_keyboard_get_base_event().
|
|
*
|
|
* @return A keyboard event, or NULL for other events
|
|
*/
|
|
struct libinput_event_keyboard *
|
|
libinput_event_get_keyboard_event(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Return the touch event that is this input event. If the event type does
|
|
* not match the touch event types, this function returns NULL.
|
|
*
|
|
* The inverse of this function is libinput_event_touch_get_base_event().
|
|
*
|
|
* @return A touch event, or NULL for other events
|
|
*/
|
|
struct libinput_event_touch *
|
|
libinput_event_get_touch_event(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Return the tablet event that is this input event. If the event type does not
|
|
* match the tablet event types, this function returns NULL.
|
|
*
|
|
* The inverse of this function is libinput_event_tablet_get_base_event().
|
|
*
|
|
* @return A touch event, or NULL for other events
|
|
*/
|
|
struct libinput_event_tablet *
|
|
libinput_event_get_tablet_event(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* Return the device event that is this input event. If the event type does
|
|
* not match the device event types, this function returns NULL.
|
|
*
|
|
* The inverse of this function is
|
|
* libinput_event_device_notify_get_base_event().
|
|
*
|
|
* @return A device event, or NULL for other events
|
|
*/
|
|
struct libinput_event_device_notify *
|
|
libinput_event_get_device_notify_event(struct libinput_event *event);
|
|
|
|
/**
|
|
* @ingroup event
|
|
*
|
|
* @return The generic libinput_event of this event
|
|
*/
|
|
struct libinput_event *
|
|
libinput_event_device_notify_get_base_event(struct libinput_event_device_notify *event);
|
|
|
|
/**
|
|
* @defgroup event_keyboard Keyboard events
|
|
*
|
|
* Key events are generated when a key changes its logical state, usually by
|
|
* being pressed or released.
|
|
*/
|
|
|
|
/**
|
|
* @ingroup event_keyboard
|
|
*
|
|
* @return The event time for this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
|
|
|
|
/**
|
|
* @ingroup event_keyboard
|
|
*
|
|
* @return The keycode that triggered this key event
|
|
*/
|
|
uint32_t
|
|
libinput_event_keyboard_get_key(struct libinput_event_keyboard *event);
|
|
|
|
/**
|
|
* @ingroup event_keyboard
|
|
*
|
|
* @return The state change of the key
|
|
*/
|
|
enum libinput_key_state
|
|
libinput_event_keyboard_get_key_state(struct libinput_event_keyboard *event);
|
|
|
|
|
|
/**
|
|
* @ingroup event_keyboard
|
|
*
|
|
* @return The generic libinput_event of this event
|
|
*/
|
|
struct libinput_event *
|
|
libinput_event_keyboard_get_base_event(struct libinput_event_keyboard *event);
|
|
|
|
/**
|
|
* @ingroup event_keyboard
|
|
*
|
|
* For the key of a LIBINPUT_EVENT_KEYBOARD_KEY event, return the total number
|
|
* of keys 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_KEYBOARD_KEY. For other events, this function returns 0.
|
|
*
|
|
* @return the seat wide pressed key count for the key of this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_keyboard_get_seat_key_count(
|
|
struct libinput_event_keyboard *event);
|
|
|
|
/**
|
|
* @defgroup event_pointer Pointer events
|
|
*
|
|
* Pointer events reflect motion, button and scroll events, as well as
|
|
* events from other axes.
|
|
*/
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* @return The event time for this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_pointer_get_time(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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.
|
|
*
|
|
* @note It is an application bug to call this function for events other than
|
|
* LIBINPUT_EVENT_POINTER_MOTION.
|
|
*
|
|
* @return the relative x movement since the last event
|
|
*/
|
|
double
|
|
libinput_event_pointer_get_dx(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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.
|
|
*
|
|
* @note It is an application bug to call this function for events other than
|
|
* LIBINPUT_EVENT_POINTER_MOTION.
|
|
*
|
|
* @return the relative y movement since the last event
|
|
*/
|
|
double
|
|
libinput_event_pointer_get_dy(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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_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.
|
|
*
|
|
* @return the current absolute x coordinate
|
|
*/
|
|
double
|
|
libinput_event_pointer_get_absolute_x(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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_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.
|
|
*
|
|
* @return the current absolute y coordinate
|
|
*/
|
|
double
|
|
libinput_event_pointer_get_absolute_y(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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.
|
|
*
|
|
* @param event The libinput pointer event
|
|
* @param width The current output screen width
|
|
* @return the current absolute x coordinate transformed to a screen coordinate
|
|
*/
|
|
double
|
|
libinput_event_pointer_get_absolute_x_transformed(
|
|
struct libinput_event_pointer *event,
|
|
uint32_t width);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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.
|
|
*
|
|
* @param event The libinput pointer event
|
|
* @param height The current output screen height
|
|
* @return the current absolute y coordinate transformed to a screen coordinate
|
|
*/
|
|
double
|
|
libinput_event_pointer_get_absolute_y_transformed(
|
|
struct libinput_event_pointer *event,
|
|
uint32_t height);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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.
|
|
*
|
|
* @return the button triggering this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_pointer_get_button(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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.
|
|
*
|
|
* @return the button state triggering this event
|
|
*/
|
|
enum libinput_button_state
|
|
libinput_event_pointer_get_button_state(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* 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
|
|
* 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.
|
|
*
|
|
* @return the seat wide pressed button count for the key of this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_pointer_get_seat_button_count(
|
|
struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* Return the axis that triggered this 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.
|
|
*
|
|
* @return the axis triggering this event
|
|
*/
|
|
enum libinput_pointer_axis
|
|
libinput_event_pointer_get_axis(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* Return the axis value of the given axis. The interpretation of the value
|
|
* is dependent 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. The dimension of a scroll unit is equal to one unit of
|
|
* motion in the respective axis, where applicable (e.g. touchpad two-finger
|
|
* scrolling).
|
|
*
|
|
* 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.
|
|
*
|
|
* @return the axis value of this event
|
|
*/
|
|
double
|
|
libinput_event_pointer_get_axis_value(struct libinput_event_pointer *event);
|
|
|
|
/**
|
|
* @ingroup event_pointer
|
|
*
|
|
* @return The generic libinput_event of this event
|
|
*/
|
|
struct libinput_event *
|
|
libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
|
|
|
|
|
|
/**
|
|
* @defgroup event_touch Touch events
|
|
*
|
|
* Events from absolute touch devices.
|
|
*/
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
*
|
|
* @return The event time for this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_touch_get_time(struct libinput_event_touch *event);
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
*
|
|
* Get 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 function returns -1.
|
|
*
|
|
* @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
|
|
* LIBINPUT_EVENT_TOUCH_FRAME.
|
|
*
|
|
* @return The slot of this touch event
|
|
*/
|
|
int32_t
|
|
libinput_event_touch_get_slot(struct libinput_event_touch *event);
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
*
|
|
* Get 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.
|
|
*
|
|
* @note this function should not be called for LIBINPUT_EVENT_TOUCH_CANCEL or
|
|
* LIBINPUT_EVENT_TOUCH_FRAME.
|
|
*
|
|
* @return The seat slot of the touch event
|
|
*/
|
|
int32_t
|
|
libinput_event_touch_get_seat_slot(struct libinput_event_touch *event);
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
*
|
|
* Return the current absolute x coordinate of the touch event, in mm from
|
|
* the top left corner of the device. To get the corresponding output screen
|
|
* coordinate, use libinput_event_touch_get_x_transformed().
|
|
*
|
|
* @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
|
|
* LIBINPUT_EVENT_TOUCH_MOTION.
|
|
*
|
|
* @param event The libinput touch event
|
|
* @return the current absolute x coordinate
|
|
*/
|
|
double
|
|
libinput_event_touch_get_x(struct libinput_event_touch *event);
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
*
|
|
* Return the current absolute y coordinate of the touch event, in mm from
|
|
* the top left corner of the device. To get the corresponding output screen
|
|
* coordinate, use libinput_event_touch_get_y_transformed().
|
|
*
|
|
* For LIBINPUT_EVENT_TOUCH_UP 0 is returned.
|
|
*
|
|
* @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
|
|
* LIBINPUT_EVENT_TOUCH_MOTION.
|
|
*
|
|
* @param event The libinput touch event
|
|
* @return the current absolute y coordinate
|
|
*/
|
|
double
|
|
libinput_event_touch_get_y(struct libinput_event_touch *event);
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
*
|
|
* Return the current absolute x coordinate of the touch event, transformed to
|
|
* screen coordinates.
|
|
*
|
|
* @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
|
|
* LIBINPUT_EVENT_TOUCH_MOTION.
|
|
*
|
|
* @param event The libinput touch event
|
|
* @param width The current output screen width
|
|
* @return the current absolute x coordinate transformed to a screen coordinate
|
|
*/
|
|
double
|
|
libinput_event_touch_get_x_transformed(struct libinput_event_touch *event,
|
|
uint32_t width);
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
*
|
|
* Return the current absolute y coordinate of the touch event, transformed to
|
|
* screen coordinates.
|
|
*
|
|
* @note this function should only be called for LIBINPUT_EVENT_TOUCH_DOWN and
|
|
* LIBINPUT_EVENT_TOUCH_MOTION.
|
|
*
|
|
* @param event The libinput touch event
|
|
* @param height The current output screen height
|
|
* @return the current absolute y coordinate transformed to a screen coordinate
|
|
*/
|
|
double
|
|
libinput_event_touch_get_y_transformed(struct libinput_event_touch *event,
|
|
uint32_t height);
|
|
|
|
/**
|
|
* @ingroup event_touch
|
|
*
|
|
* @return The generic libinput_event of this event
|
|
*/
|
|
struct libinput_event *
|
|
libinput_event_touch_get_base_event(struct libinput_event_touch *event);
|
|
|
|
/**
|
|
* @defgroup event_tablet Tablet events
|
|
*
|
|
* Events that come from tablet devices.
|
|
*/
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Checks if an axis was updated in this event or return 0 otherwise.
|
|
* For tablet events that are not of type @ref LIBINPUT_EVENT_TABLET_AXIS,
|
|
* this function returns 0.
|
|
*
|
|
* @note It is an application bug to call this function for events other than
|
|
* @ref LIBINPUT_EVENT_TABLET_AXIS.
|
|
*
|
|
* @param event The libinput tablet event
|
|
* @param axis The axis to check for updates
|
|
* @return 1 if the axis was updated or 0 otherwise
|
|
*/
|
|
int
|
|
libinput_event_tablet_axis_has_changed(struct libinput_event_tablet *event,
|
|
enum libinput_tablet_axis axis);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Return the axis value of a given axis for a tablet. The interpretation of the
|
|
* value is dependent on the axis:
|
|
* - @ref LIBINPUT_TABLET_AXIS_X and @ref LIBINPUT_TABLET_AXIS_Y - the X and
|
|
* Y coordinates of the tablet tool, in mm from the top left corner of the
|
|
* tablet. Use libinput_event_tablet_get_x_transformed() and
|
|
* libinput_event_tablet_get_y_transformed() for transforming each
|
|
* respective axis value.
|
|
* - @ref LIBINPUT_TABLET_AXIS_DISTANCE - The distance from the tablet's
|
|
* sensor, normalized from 0 to 1
|
|
* - @ref LIBINPUT_TABLET_AXIS_PRESSURE - The current pressure being applied on
|
|
* the tool in use, normalized from 0 to 1
|
|
* - @ref LIBINPUT_TABLET_AXIS_TILT_VERTICAL and @ref
|
|
* LIBINPUT_TABLET_AXIS_TILT_HORIZONTAL - normalized value between -1 and 1
|
|
* that indicates the tilt vertical or horizontal tilt of the tool
|
|
* respectively
|
|
*
|
|
* For tablet events that are not of type @ref LIBINPUT_EVENT_TABLET_AXIS, this
|
|
* function returns 0.
|
|
*
|
|
* @param event The libinput tablet event
|
|
* @param axis The axis to retrieve the value of
|
|
* @return The current value of the the axis
|
|
*/
|
|
double
|
|
libinput_event_tablet_get_axis_value(struct libinput_event_tablet *event,
|
|
enum libinput_tablet_axis axis);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Return the current absolute x coordinate of the tablet event, transformed to
|
|
* screen coordinates.
|
|
*
|
|
* @param event The libinput tablet event
|
|
* @param width The current output screen width
|
|
* @return the current absolute x coordinate transformed to a screen coordinate
|
|
*/
|
|
double
|
|
libinput_event_tablet_get_x_transformed(struct libinput_event_tablet *event,
|
|
uint32_t width);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Return the current absolute y coordinate of the tablet event, transformed to
|
|
* screen coordinates.
|
|
*
|
|
* @param event The libinput tablet event
|
|
* @param height The current output screen height
|
|
* @return the current absolute y coordinate transformed to a screen coordinate
|
|
*/
|
|
double
|
|
libinput_event_tablet_get_y_transformed(struct libinput_event_tablet *event,
|
|
uint32_t height);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Return the new tool in use for this event.
|
|
* For tablet events that are not of type @ref
|
|
* LIBINPUT_EVENT_TABLET_TOOL_UPDATE, this function returns NULL. By default,
|
|
* the lifetime of each tool is bound to the lifetime of the event, so the tool
|
|
* will be destroyed when the event is destroyed. However, the lifetime of the
|
|
* tool may be extended by using libinput_tool_ref() to increment the reference
|
|
* count of the tool. Whenever libinput detects that the tool is in proximity of
|
|
* any tablet that's connected, it will return the same libinput_tool object.
|
|
*
|
|
* @note It is an application bug to call this function for events other than
|
|
* @ref LIBINPUT_EVENT_TABLET_TOOL_UPDATE.
|
|
*
|
|
* @note On tablets where the serial number of tools is not reported, each tool
|
|
* cannot be guaranteed to be unique.
|
|
*
|
|
* @param event The libinput tablet event
|
|
* @return The new tool triggering this event
|
|
*/
|
|
struct libinput_tool *
|
|
libinput_event_tablet_get_tool(struct libinput_event_tablet *event);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Return the button that triggered this event.
|
|
* For tablet events that are not of type @ref LIBINPUT_EVENT_TABLET_BUTTON, this
|
|
* function returns 0.
|
|
*
|
|
* @note It is an application bug to call this function for events other than
|
|
* @ref LIBINPUT_EVENT_TABLET_BUTTON.
|
|
*
|
|
* @param event The libinput tablet event
|
|
* @return the button triggering this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_tablet_get_button(struct libinput_event_tablet *event);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Return the button state of the event.
|
|
*
|
|
* @note It is an application bug to call this function for events other than
|
|
* @ref LIBINPUT_EVENT_TABLET_BUTTON.
|
|
*
|
|
* @param event The libinput tablet event
|
|
* @return the button state triggering this event
|
|
*/
|
|
enum libinput_button_state
|
|
libinput_event_tablet_get_button_state(struct libinput_event_tablet *event);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* For the button of a @ref LIBINPUT_EVENT_TABLET_BUTTON event, return the total
|
|
* number of buttons pressed on all devices on the associated seat after the
|
|
* the event was triggered.
|
|
*
|
|
" @note It is an application bug to call this function for events other than
|
|
* @ref LIBINPUT_EVENT_TABLET_BUTTON. For other events, this function returns 0.
|
|
*
|
|
* @return the seat wide pressed button count for the key of this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_tablet_get_seat_button_count(struct libinput_event_tablet *event);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* @param event The libinput tablet event
|
|
* @return The event time for this event
|
|
*/
|
|
uint32_t
|
|
libinput_event_tablet_get_time(struct libinput_event_tablet *event);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Return the type of tool type for a tool object
|
|
*
|
|
* @param tool The libinput tool
|
|
* @return The tool type for this tool object
|
|
*/
|
|
enum libinput_tool_type
|
|
libinput_tool_get_type(struct libinput_tool *tool);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Increment the ref count of tool by one
|
|
*
|
|
* @param tool The tool to increment the ref count of
|
|
* @return The passed tool
|
|
*/
|
|
struct libinput_tool *
|
|
libinput_tool_ref(struct libinput_tool *tool);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Decrement the ref count of tool by one. When the ref count of tool reaches 0,
|
|
* the memory allocated for tool will be freed.
|
|
*
|
|
* @param tool The tool to decrement the ref count of
|
|
* @return NULL if the tool was destroyed otherwise the passed tool
|
|
*/
|
|
struct libinput_tool *
|
|
libinput_tool_unref(struct libinput_tool *tool);
|
|
|
|
/**
|
|
* @ingroup event_tablet
|
|
*
|
|
* Return the serial number of a tool
|
|
*
|
|
* @note Not all tablets report a serial number along with the type of tool
|
|
* being used. If the hardware does not provide a unique serial number, the
|
|
* serial number is always 0.
|
|
*
|
|
* @param tool The libinput tool
|
|
* @return The new tool serial triggering this event
|
|
*/
|
|
uint32_t
|
|
libinput_tool_get_serial(struct libinput_tool *tool);
|
|
|
|
/**
|
|
* @defgroup base Initialization and manipulation of libinput contexts
|
|
*/
|
|
|
|
struct libinput_interface {
|
|
/**
|
|
* Open the device at the given path with the flags provided and
|
|
* return the fd.
|
|
*
|
|
* @param path The device path to open
|
|
* @param flags Flags as defined by open(2)
|
|
* @param user_data The user_data provided in
|
|
* libinput_udev_create_context()
|
|
*
|
|
* @return the file descriptor, or a negative errno on failure.
|
|
*/
|
|
int (*open_restricted)(const char *path, int flags, void *user_data);
|
|
/**
|
|
* Close the file descriptor.
|
|
*
|
|
* @param fd The file descriptor to close
|
|
* @param user_data The user_data provided in
|
|
* libinput_udev_create_context()
|
|
*/
|
|
void (*close_restricted)(int fd, void *user_data);
|
|
};
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Create a new libinput context from udev. This context is inactive until
|
|
* assigned a seat ID with libinput_udev_assign_seat().
|
|
*
|
|
* @param interface The callback interface
|
|
* @param user_data Caller-specific data passed to the various callback
|
|
* interfaces.
|
|
* @param udev An already initialized udev context
|
|
*
|
|
* @return An initialized, but inactive libinput context or NULL on error
|
|
*/
|
|
struct libinput *
|
|
libinput_udev_create_context(const struct libinput_interface *interface,
|
|
void *user_data,
|
|
struct udev *udev);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* 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
|
|
* @ref 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.
|
|
*
|
|
* @param libinput A libinput context initialized with
|
|
* libinput_udev_create_context()
|
|
* @param seat_id A seat identifier. This string must not be NULL.
|
|
*
|
|
* @return 0 on success or -1 on failure.
|
|
*/
|
|
int
|
|
libinput_udev_assign_seat(struct libinput *libinput,
|
|
const char *seat_id);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* 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 @ref
|
|
* libinput_unref.
|
|
*
|
|
* @param interface The callback interface
|
|
* @param user_data Caller-specific data passed to the various callback
|
|
* interfaces.
|
|
*
|
|
* @return An initialized, empty libinput context.
|
|
*/
|
|
struct libinput *
|
|
libinput_path_create_context(const struct libinput_interface *interface,
|
|
void *user_data);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* 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.
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @param path Path to an input device
|
|
* @return 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().
|
|
*/
|
|
struct libinput_device *
|
|
libinput_path_add_device(struct libinput *libinput,
|
|
const char *path);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* 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.
|
|
*
|
|
* @param device A libinput device
|
|
*
|
|
* @note It is an application bug to call this function on a libinput
|
|
* context initialized with libinput_udev_create_context().
|
|
*/
|
|
void
|
|
libinput_path_remove_device(struct libinput_device *device);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* libinput keeps a single file descriptor for all events. Call into
|
|
* libinput_dispatch() if any events become available on this fd.
|
|
*
|
|
* @return the file descriptor used to notify of pending events.
|
|
*/
|
|
int
|
|
libinput_get_fd(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* 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.
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
*
|
|
* @return 0 on success, or a negative errno on failure
|
|
*/
|
|
int
|
|
libinput_dispatch(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Retrieve the next event from libinput's internal event queue.
|
|
*
|
|
* After handling the retrieved event, the caller must destroy it using
|
|
* libinput_event_destroy().
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @return The next available event, or NULL if no event is available.
|
|
*/
|
|
struct libinput_event *
|
|
libinput_get_event(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* 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.
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @return The event type of the next available event or LIBINPUT_EVENT_NONE
|
|
* if no event is availble.
|
|
*/
|
|
enum libinput_event_type
|
|
libinput_next_event_type(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @return the caller-specific data previously assigned in
|
|
* libinput_create_udev().
|
|
*/
|
|
void *
|
|
libinput_get_user_data(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Resume a suspended libinput context. This re-enables device
|
|
* monitoring and adds existing devices.
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @see libinput_suspend
|
|
*
|
|
* @return 0 on success or -1 on failure
|
|
*/
|
|
int
|
|
libinput_resume(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* 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().
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
*/
|
|
void
|
|
libinput_suspend(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Add a reference to the context. A context is destroyed whenever the
|
|
* reference count reaches 0. See @ref libinput_unref.
|
|
*
|
|
* @param libinput A previously initialized valid libinput context
|
|
* @return The passed libinput context
|
|
*/
|
|
struct libinput *
|
|
libinput_ref(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* 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.
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @return NULL if context was destroyed otherwise the passed context
|
|
*/
|
|
struct libinput *
|
|
libinput_unref(struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Set the global 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.
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @param priority The minimum priority of log messages to print.
|
|
*
|
|
* @see libinput_log_set_handler
|
|
* @see libinput_log_get_priority
|
|
*/
|
|
void
|
|
libinput_log_set_priority(struct libinput *libinput,
|
|
enum libinput_log_priority priority);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Get the global 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.
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @return The minimum priority of log messages to print.
|
|
*
|
|
* @see libinput_log_set_handler
|
|
* @see libinput_log_set_priority
|
|
*/
|
|
enum libinput_log_priority
|
|
libinput_log_get_priority(const struct libinput *libinput);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Log handler type for custom logging.
|
|
*
|
|
* @param libinput The libinput context
|
|
* @param priority The priority of the current message
|
|
* @param format Message format in printf-style
|
|
* @param args Message arguments
|
|
*
|
|
* @see libinput_set_log_priority
|
|
* @see libinput_log_set_handler
|
|
*/
|
|
typedef void (*libinput_log_handler)(struct libinput *libinput,
|
|
enum libinput_log_priority priority,
|
|
const char *format, va_list args)
|
|
LIBINPUT_ATTRIBUTE_PRINTF(3, 0);
|
|
|
|
/**
|
|
* @ingroup base
|
|
*
|
|
* Set the global log handler. Messages with priorities equal to or higher
|
|
* than the current log priority will be passed to the given
|
|
* log handler.
|
|
*
|
|
* The default log handler prints to stderr.
|
|
*
|
|
* @param libinput A previously initialized libinput context
|
|
* @param log_handler The log handler for library messages.
|
|
* @param user_data Caller-specific data pointer, passed into the log
|
|
* handler.
|
|
*
|
|
* @see libinput_log_set_handler
|
|
*/
|
|
void
|
|
libinput_log_set_handler(struct libinput *libinput,
|
|
libinput_log_handler log_handler);
|
|
|
|
/**
|
|
* @defgroup seat Initialization and manipulation of seats
|
|
*
|
|
* A seat has two identifiers, the physical name and the logical name. The
|
|
* physical name is summarized as the list of devices a process on the same
|
|
* physical seat has access to.
|
|
*
|
|
* The logical seat name is the seat name for a logical group of devices. A
|
|
* compositor may use that to create additonal seats as independent device
|
|
* sets. Alternatively, a compositor may limit itself to a single logical
|
|
* seat, leaving a second compositor to manage devices on the other logical
|
|
* seats.
|
|
*
|
|
* @code
|
|
* +---+--------+------------+------------------------+------------+
|
|
* | | event0 | | | log seat A |
|
|
* | K +--------+ | +------------+
|
|
* | e | event1 | phys seat0 | libinput context 1 | |
|
|
* | r +--------+ | | log seat B |
|
|
* | n | event2 | | | |
|
|
* | e +--------+------------+------------------------+------------+
|
|
* | l | event3 | phys seat1 | libinput context 2 | log seat C |
|
|
* +---+--------+------------+------------------------+------------+
|
|
* @endcode
|
|
*/
|
|
|
|
/**
|
|
* @ingroup seat
|
|
*
|
|
* Increase the refcount of the seat. A seat will be freed whenever the
|
|
* refcount reaches 0. This may happen during dispatch if the
|
|
* seat was removed from the system. A caller must ensure to reference
|
|
* the seat correctly to avoid dangling pointers.
|
|
*
|
|
* @param seat A previously obtained seat
|
|
* @return The passed seat
|
|
*/
|
|
struct libinput_seat *
|
|
libinput_seat_ref(struct libinput_seat *seat);
|
|
|
|
/**
|
|
* @ingroup seat
|
|
*
|
|
* Decrease the refcount of the seat. A seat will be freed whenever the
|
|
* refcount reaches 0. This may happen during dispatch if the
|
|
* seat was removed from the system. A caller must ensure to reference
|
|
* the seat correctly to avoid dangling pointers.
|
|
*
|
|
* @param seat A previously obtained seat
|
|
* @return NULL if seat was destroyed, otherwise the passed seat
|
|
*/
|
|
struct libinput_seat *
|
|
libinput_seat_unref(struct libinput_seat *seat);
|
|
|
|
/**
|
|
* @ingroup seat
|
|
*
|
|
* Set caller-specific data associated with this seat. libinput does
|
|
* not manage, look at, or modify this data. The caller must ensure the
|
|
* data is valid.
|
|
*
|
|
* @param seat A previously obtained seat
|
|
* @param user_data Caller-specific data pointer
|
|
* @see libinput_seat_get_user_data
|
|
*/
|
|
void
|
|
libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
|
|
|
|
/**
|
|
* @ingroup seat
|
|
*
|
|
* Get the caller-specific data associated with this seat, if any.
|
|
*
|
|
* @param seat A previously obtained seat
|
|
* @return Caller-specific data pointer or NULL if none was set
|
|
* @see libinput_seat_set_user_data
|
|
*/
|
|
void *
|
|
libinput_seat_get_user_data(struct libinput_seat *seat);
|
|
|
|
/**
|
|
* @ingroup seat
|
|
*
|
|
* Return the physical name of the seat. For libinput contexts created from
|
|
* udev, this is always the same value as passed into
|
|
* libinput_udev_assign_seat() and all seats from that context will have
|
|
* the same physical name.
|
|
*
|
|
* The physical name of the seat is one that is usually set by the system or
|
|
* lower levels of the stack. In most cases, this is the base filter for
|
|
* devices - devices assigned to seats outside the current seat will not
|
|
* be available to the caller.
|
|
*
|
|
* @param seat A previously obtained seat
|
|
* @return the physical name of this seat
|
|
*/
|
|
const char *
|
|
libinput_seat_get_physical_name(struct libinput_seat *seat);
|
|
|
|
/**
|
|
* @ingroup seat
|
|
*
|
|
* Return the logical name of the seat. This is an identifier to group sets
|
|
* of devices within the compositor.
|
|
*
|
|
* @param seat A previously obtained seat
|
|
* @return the logical name of this seat
|
|
*/
|
|
const char *
|
|
libinput_seat_get_logical_name(struct libinput_seat *seat);
|
|
|
|
/**
|
|
* @defgroup device Initialization and manipulation of input devices
|
|
*/
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Increase the refcount of the input device. An input device will be freed
|
|
* whenever the refcount reaches 0. This may happen during dispatch if the
|
|
* device was removed from the system. A caller must ensure to reference
|
|
* the device correctly to avoid dangling pointers.
|
|
*
|
|
* @param device A previously obtained device
|
|
* @return The passed device
|
|
*/
|
|
struct libinput_device *
|
|
libinput_device_ref(struct libinput_device *device);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Decrease the refcount of the input device. An input device will be freed
|
|
* whenever the refcount reaches 0. This may happen during dispatch if the
|
|
* device was removed from the system. A caller must ensure to reference
|
|
* the device correctly to avoid dangling pointers.
|
|
*
|
|
* @param device A previously obtained device
|
|
* @return NULL if device was destroyed, otherwise the passed device
|
|
*/
|
|
struct libinput_device *
|
|
libinput_device_unref(struct libinput_device *device);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Set caller-specific data associated with this input device. libinput does
|
|
* not manage, look at, or modify this data. The caller must ensure the
|
|
* data is valid.
|
|
*
|
|
* @param device A previously obtained device
|
|
* @param user_data Caller-specific data pointer
|
|
* @see libinput_device_get_user_data
|
|
*/
|
|
void
|
|
libinput_device_set_user_data(struct libinput_device *device, void *user_data);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Get the caller-specific data associated with this input device, if any.
|
|
*
|
|
* @param device A previously obtained device
|
|
* @return Caller-specific data pointer or NULL if none was set
|
|
* @see libinput_device_set_user_data
|
|
*/
|
|
void *
|
|
libinput_device_get_user_data(struct libinput_device *device);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Get the system name of the device.
|
|
*
|
|
* @param device A previously obtained device
|
|
* @return System name of the device
|
|
*/
|
|
const char *
|
|
libinput_device_get_sysname(struct libinput_device *device);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* A device may be mapped to a single output, or all available outputs. If a
|
|
* device is mapped to a single output only, a relative device may not move
|
|
* beyond the boundaries of this output. An absolute device has its input
|
|
* coordinates mapped to the extents of this output.
|
|
*
|
|
* @return the name of the output this device is mapped to, or NULL if no
|
|
* output is set
|
|
*/
|
|
const char *
|
|
libinput_device_get_output_name(struct libinput_device *device);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Get the seat associated with this input device.
|
|
*
|
|
* A seat can be uniquely identified by the physical and logical seat name.
|
|
* There will ever be only one seat instance with a given physical and logical
|
|
* seat name pair at any given time, but if no external reference is kept, it
|
|
* may be destroyed if no device belonging to it is left.
|
|
*
|
|
* @param device A previously obtained device
|
|
* @return The seat this input device belongs to
|
|
*/
|
|
struct libinput_seat *
|
|
libinput_device_get_seat(struct libinput_device *device);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Update the LEDs on the device, if any. If the device does not have
|
|
* LEDs, or does not have one or more of the LEDs given in the mask, this
|
|
* function does nothing.
|
|
*
|
|
* @param device A previously obtained device
|
|
* @param leds A mask of the LEDs to set, or unset.
|
|
*/
|
|
void
|
|
libinput_device_led_update(struct libinput_device *device,
|
|
enum libinput_led leds);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Set the bitmask in keys to the bitmask of the keys present on the device
|
|
* (see linux/input.h), up to size characters.
|
|
*
|
|
* @param device A current input device
|
|
* @param keys An array filled with the bitmask for the keys
|
|
* @param size Size of the keys array
|
|
*
|
|
* @return The number of valid bytes in keys, or a negative errno on failure
|
|
*/
|
|
int
|
|
libinput_device_get_keys(struct libinput_device *device,
|
|
char *keys, size_t size);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Apply the 3x3 transformation matrix to absolute device coordinates. This
|
|
* matrix has no effect on relative events.
|
|
*
|
|
* Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
|
|
* @code
|
|
* [ a b c ] [ x ]
|
|
* [ d e f ] * [ y ]
|
|
* [ 0 0 1 ] [ 1 ]
|
|
* @endcode
|
|
*/
|
|
void
|
|
libinput_device_calibrate(struct libinput_device *device,
|
|
float calibration[6]);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Check if the given device has the specified capability
|
|
*
|
|
* @return 1 if the given device has the capability or 0 if not
|
|
*/
|
|
int
|
|
libinput_device_has_capability(struct libinput_device *device,
|
|
enum libinput_device_capability capability);
|
|
|
|
/**
|
|
* @ingroup device
|
|
*
|
|
* Get the physical size of a device in mm, where meaningful. This function
|
|
* only succeeds on devices with the required data, i.e. tablets, touchpads
|
|
* and touchscreens.
|
|
*
|
|
* If this function returns nonzero, width and height are unmodified.
|
|
*
|
|
* @param device The device
|
|
* @param width Set to the width of the device
|
|
* @param height Set to the height of the device
|
|
* @return 0 on success, or nonzero otherwise
|
|
*/
|
|
int
|
|
libinput_device_get_size(struct libinput_device *device,
|
|
double *width,
|
|
double *height);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* LIBINPUT_H */
|