mirror of
https://gitlab.freedesktop.org/libinput/libei.git
synced 2025-12-20 04:30:07 +01:00
5e649f682a
This is the outline of the API intended with a minimal compiler just to verify there are no immediate parsing issues.
413 lines
12 KiB
C
413 lines
12 KiB
C
/*
|
|
* Copyright © 2020 Red Hat, Inc.
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a
|
|
* copy of this software and associated documentation files (the "Software"),
|
|
* to deal in the Software without restriction, including without limitation
|
|
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
|
* and/or sell copies of the Software, and to permit persons to whom the
|
|
* Software is furnished to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice (including the next
|
|
* paragraph) shall be included in all copies or substantial portions of the
|
|
* Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
|
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
|
* DEALINGS IN THE SOFTWARE.
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <stdbool.h>
|
|
#include <stdint.h>
|
|
|
|
struct ei_ctx;
|
|
struct ei_device;
|
|
struct ei_event;
|
|
struct ei_event_client;
|
|
struct ei_event_pointer;
|
|
struct ei_event_keyboard;
|
|
struct ei_event_touch;
|
|
|
|
enum ei_device_capability {
|
|
EI_DEVICE_CAP_POINTER,
|
|
EI_DEVICE_CAP_POINTER_ABSOLUTE,
|
|
EI_DEVICE_CAP_KEYBOARD,
|
|
EI_DEVICE_CAP_TOUCH,
|
|
};
|
|
|
|
enum ei_keymap_type {
|
|
EI_KEYMAP_TYPE_XKB = 1,
|
|
};
|
|
|
|
enum ei_event_type {
|
|
/**
|
|
* No event ever has this type, this type exists only as potential
|
|
* return value for ei_next_event_type().
|
|
*/
|
|
EI_EVENT_NONE = 0,
|
|
/**
|
|
* The server has approved the connection to this client.
|
|
*/
|
|
EI_EVENT_CONNECT,
|
|
/**
|
|
* The server has disconnected this client - all resources left to
|
|
* reference this server are now obsolete. Once this event has been
|
|
* received, the @ref struct ei_ctx and all its associated resources
|
|
* should be released.
|
|
*/
|
|
EI_EVENT_DISCONNECT,
|
|
|
|
/**
|
|
* The server has added a device for this client. The capabilities
|
|
* of the device may not match the requested capabilities - it is up
|
|
* to the client to verify the minimum required capabilities are
|
|
* indeed set.
|
|
*/
|
|
EI_EVENT_DEVICE_ADDED,
|
|
/**
|
|
* The server has removed a device belonging to this client.
|
|
*/
|
|
EI_EVENT_DEVICE_REMOVED,
|
|
|
|
|
|
/**
|
|
* The client may send events.
|
|
*/
|
|
EI_EVENT_POINTER_RESUME = 300,
|
|
/**
|
|
* Any events sent will be discarded until the next resume.
|
|
*/
|
|
EI_EVENT_POINTER_SUSPEND,
|
|
/**
|
|
* Update pointer ranges. This provides the client with the allowed
|
|
* axis ranges for absolute pointer motion. The axis ranges may not
|
|
* match the available screen ranges and the axis range may only map
|
|
* to a portion of the available screen size.
|
|
*/
|
|
EI_EVENT_POINTER_RANGES_CHANGED,
|
|
|
|
/**
|
|
* The client may send events.
|
|
*/
|
|
EI_EVENT_KEYBOARD_RESUME = 400,
|
|
/**
|
|
* Any events sent will be discarded until the next resume.
|
|
*/
|
|
EI_EVENT_KEYBOARD_SUSPEND,
|
|
/**
|
|
* Notification of the keymap to be used by the client.
|
|
*/
|
|
EI_EVENT_KEYBOARD_KEYMAP,
|
|
|
|
/**
|
|
* The client may send events.
|
|
*/
|
|
EI_EVENT_TOUCH_RESUME = 500,
|
|
/**
|
|
* Any events sent will be discarded until the next resume.
|
|
*/
|
|
EI_EVENT_TOUCH_SUSPEND,
|
|
/**
|
|
* Update touch ranges. This provides the client with the allowed
|
|
* axis ranges for absolute pointer motion. The axis ranges may not
|
|
* match the available screen ranges and the axis range may only map
|
|
* to a portion of the available screen size.
|
|
*/
|
|
EI_EVENT_TOUCH_RANGES_CHANGED,
|
|
};
|
|
|
|
struct ei_ctx *
|
|
ei_new(void);
|
|
|
|
struct ei_ctx *
|
|
ei_ref(struct ei_ctx *ctx);
|
|
|
|
struct ei_ctx *
|
|
ei_unref(struct ei_ctx *ei);
|
|
|
|
/**
|
|
* Connect to the libeis server via the org.freedesktop.portal
|
|
*
|
|
* @return 0 on success or a negative errno on failure
|
|
*/
|
|
int
|
|
ei_portal_connect(struct ei_ctx *ei);
|
|
|
|
/**
|
|
* Connect to the libeis server on the org.freedesktop.Ei bus name.
|
|
*
|
|
* @return 0 on success or a negative errno on failure
|
|
*/
|
|
int
|
|
ei_dbus_connect(struct ei_ctx *ei);
|
|
|
|
int
|
|
ei_get_fd(struct ei_ctx *ei);
|
|
|
|
void
|
|
ei_dispatch(struct ei_ctx *ei);
|
|
|
|
struct ei_event *
|
|
ei_get_event(struct ei_ctx *ei);
|
|
|
|
enum ei_event_type
|
|
ei_next_event_type(struct ei_ctx *ei);
|
|
|
|
struct ei_event *
|
|
ei_event_unref(struct ei_event *event);
|
|
|
|
struct ei_device *
|
|
ei_device_ref(struct ei_device *device);
|
|
|
|
struct ei_device *
|
|
ei_device_unref(struct ei_device *device);
|
|
|
|
/**
|
|
* Request the creation of a device with suggested capabilities and a
|
|
* suggested name. Note that the server may ignore the name and may ignore
|
|
* all capabilities.
|
|
*
|
|
* The device returned is a stub device maintained by the library and should
|
|
* only used for initial device configuration. It does not represent the
|
|
* server-created device until the @ref EI_EVENT_DEVICE_ADDED for this
|
|
* device has been received.
|
|
*
|
|
* This does not increase the refcount of the device. Use ei_device_ref() to
|
|
* keep a reference beyond the immediate scope.
|
|
*
|
|
* @param ei The context
|
|
* @param capabilities A bitmask of @ref ei_device_capability
|
|
* @param name A name suggestion for the device
|
|
*/
|
|
struct ei_device *
|
|
ei_create_device(struct ei_ctx *ei, uint32_t capabilities, const char *name);
|
|
|
|
/**
|
|
* Request that the device be added to the server.
|
|
* The server will respond with an @ref EI_EVENT_DEVICE_ADDED or @ref
|
|
* EI_EVENT_DEVICE_REMOVED event.
|
|
*/
|
|
void
|
|
ei_device_add(struct ei_device *device);
|
|
|
|
/**
|
|
* Notify the server that the device is no longer required. The server will
|
|
* reply with a @ref EI_EVENT_DEVICE_REMOVED event once the device has been
|
|
* removed.
|
|
*
|
|
* This does not release any resources associated with this device, use
|
|
* ei_device_unref() for any references held by the client.
|
|
*/
|
|
void
|
|
ei_device_remove(struct ei_device *device);
|
|
|
|
|
|
/**
|
|
* @return the name of the device (if any) or NULL
|
|
*/
|
|
const char *
|
|
ei_device_get_name(struct ei_device *device);
|
|
|
|
bool
|
|
ei_device_has_capability(struct ei_device *device,
|
|
enum ei_device_capability cap);
|
|
|
|
struct ei_ctx *
|
|
ei_device_get_context(struct ei_device *device);
|
|
|
|
/**
|
|
* Generate a relative motion event on a device with
|
|
* the @ref EI_DEVICE_CAP_POINTER capability.
|
|
*
|
|
* @param x The x movement in 1/1000th of a logical pixel
|
|
* @param y The y movement in 1/1000th of a logical pixel
|
|
*/
|
|
void
|
|
ei_device_pointer_motion(struct ei_device *device, int32_t x, int32_t y);
|
|
|
|
/**
|
|
* Generate an absolute motion event on a device with
|
|
* the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE capability.
|
|
*
|
|
* The required conditions are:
|
|
* - 0 <= x < width
|
|
* - 0 <= y < height
|
|
*
|
|
* @param x The x position in 1/1000th of a logical pixel
|
|
* @param y The y position in 1/1000th of a logical pixel
|
|
*/
|
|
void
|
|
ei_device_pointer_motion_absolute(struct ei_device *device,
|
|
uint32_t x, uint32_t y);
|
|
|
|
/**
|
|
* Generate a button event on a device with
|
|
* the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE or
|
|
* @ref EI_DEVICE_CAP_POINTER capability.
|
|
*
|
|
* Buttons are merely sequentially numbered. It is up to the server to map
|
|
* button numbers into semantic button codes (if any). A server may silently
|
|
* ignore button events outside meaningful ranges.
|
|
*
|
|
* @param button A sequentially numbered button, starting at index 1
|
|
* @param is_press true for button press, false for button release
|
|
*/
|
|
void
|
|
ei_device_pointer_button(struct ei_device *device,
|
|
uint32_t button, bool is_press);
|
|
|
|
/**
|
|
* Generate a scroll event on a device with
|
|
* the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE or
|
|
* @ref EI_DEVICE_CAP_POINTER capability.
|
|
*
|
|
* The server emulates discrete scrolling based on the pixel value,
|
|
* do not call ei_device_pointer_scroll_discrete() for the
|
|
* same input event.
|
|
*
|
|
* @param x The x scroll distance in 1/1000th of a logical pixel
|
|
* @param y The y scroll distance in 1/1000th of a logical pixel
|
|
*
|
|
* @see ei_device_pointer_scroll_discrete
|
|
*/
|
|
void
|
|
ei_device_pointer_scroll(struct ei_device *device, int32_t x, int32_t y);
|
|
|
|
/**
|
|
* Generate a discrete scroll event on a device with
|
|
* the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE or
|
|
* @ref EI_DEVICE_CAP_POINTER capability.
|
|
*
|
|
* A discrete scroll event is based logical scroll units (equivalent to one
|
|
* mouse wheel click). The value for one scroll unit is 120, a fraction or
|
|
* multiple thereof represents a fraction or multiple of a wheel click.
|
|
*
|
|
* The server emulates pixel-based scrolling based on the discrete value,
|
|
* do not call ei_device_pointer_scroll() for the
|
|
* same input event.
|
|
*
|
|
* @param x The x scroll distance in fractions or multiples of 120
|
|
* @param y The y scroll distance in fractions or multiples of 120
|
|
*
|
|
* @see ei_device_pointer_scroll
|
|
*/
|
|
void
|
|
ei_device_pointer_scroll_discrete(struct ei_device *device, int32_t x, int32_t y);
|
|
|
|
/**
|
|
* Generate a key event on a device with
|
|
* the @ref EI_DEVICE_CAP_KEYBOARD capability.
|
|
*
|
|
* Keys use the evdev scan codes as defined in
|
|
* linux/input-event-codes.h
|
|
*
|
|
* @param keycode The key code
|
|
* @param is_press true for key down, false for key up
|
|
*/
|
|
void
|
|
ei_device_keyboard_key(struct ei_device *device, uint32_t keycode, bool is_press);
|
|
|
|
|
|
/**
|
|
* Set the keymap on the device. This function has no effect if called
|
|
* after ei_device_add(). The keymap for this device is a suggestion to
|
|
* the server, the actual keymap used by this device is provided with
|
|
* the @ref EI_EVENT_KEYBOARD_KEYMAP event.
|
|
*
|
|
* @param type the type of the keymap
|
|
* @param fd a memmap-able file descriptor to the keymap
|
|
*/
|
|
void
|
|
ei_device_keyboard_set_keymap(struct ei_device *device,
|
|
enum ei_keymap_type type,
|
|
int fd);
|
|
|
|
/**
|
|
* Return the device from this event.
|
|
*
|
|
* This does not increase the refcount of the device. Use eis_device_ref()
|
|
* to keep a reference beyond the immediate scope.
|
|
*/
|
|
struct ei_device *
|
|
ei_event_get_device(struct ei_event *event);
|
|
|
|
|
|
/**
|
|
* @return the event time in microseconds
|
|
*/
|
|
uint64_t
|
|
ei_event_pointer_get_time(struct ei_event_pointer *event);
|
|
|
|
/**
|
|
* For an event of type @ref EI_EVENT_POINTER_RANGES_CHANGED, this function
|
|
* defines the allowable range for x - 0 (inclusive) to width (exclusive).
|
|
*
|
|
* The value is in 1/1000th of logical pixels, i.e. the value 1000 000
|
|
* refers to 1000 pixels.
|
|
*
|
|
* It is a client bug to send pointer values outside this range.
|
|
*
|
|
* If the touch range changes at runtime, an event of @ref
|
|
* EI_EVENT_POINTER_RANGES_CHANGED is generated.
|
|
*/
|
|
uint32_t
|
|
ei_event_pointer_get_width(struct ei_event_pointer *event);
|
|
|
|
/**
|
|
* @see ei_event_pointer_get_width
|
|
*/
|
|
uint32_t
|
|
ei_event_pointer_get_height(struct ei_event_pointer *event);
|
|
|
|
/**
|
|
* @return the event time in microseconds
|
|
*/
|
|
uint64_t
|
|
ei_event_keyboard_get_time(struct ei_event_keyboard *event);
|
|
|
|
/**
|
|
* For an event of type @ref EI_EVENT_TOUCH_RANGES_CHANGED, this function
|
|
* defines the allowable range for x - 0 (inclusive) to width (exclusive).
|
|
*
|
|
* The value is in 1/1000th of logical pixels, i.e. the value 1000 000
|
|
* refers to 1000 pixels.
|
|
*
|
|
* It is a client bug to send touch values outside this range.
|
|
*
|
|
* If the touch range changes at runtime, an event of @ref
|
|
* EI_EVENT_TOUCH_RANGES_CHANGED is generated.
|
|
*/
|
|
uint32_t
|
|
ei_event_touch_get_width(struct ei_event_touch *event);
|
|
|
|
/**
|
|
* @see ei_event_touch_get_width
|
|
*/
|
|
uint32_t
|
|
ei_event_touch_get_height(struct ei_event_touch *event);
|
|
|
|
/**
|
|
* @return the event time in microseconds
|
|
*/
|
|
uint64_t
|
|
ei_event_touch_get_time(struct ei_event_touch *event);
|
|
|
|
/**
|
|
* For an event of type @ref EI_EVENT_KEYBOARD_KEYMAP return the
|
|
* type of the keyamp.
|
|
*/
|
|
enum ei_keymap_type
|
|
ei_event_keyboard_get_keymap_type(struct ei_event_keyboard *kbdev);
|
|
|
|
/**
|
|
* For an event of type @ref EI_EVENT_KEYBOARD_KEYMAP return the
|
|
* memmap-able file descriptor to the keymap.
|
|
*/
|
|
int
|
|
ei_event_keyboard_get_keymap(struct ei_event_keyboard *kbdev);
|