mirror of
https://gitlab.freedesktop.org/libinput/libei.git
synced 2026-05-05 01:58:01 +02:00
libei: some more documentation and reshuffling
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer
parent
799d64d284
commit
9b6257bb9d
1 changed files with 83 additions and 49 deletions
132
src/libei.h
132
src/libei.h
|
|
@ -254,6 +254,10 @@ ei_log_get_priority(const struct ei *ei);
|
|||
* Set the name for this client. This is a suggestion to the
|
||||
* server only and may not be honored.
|
||||
*
|
||||
* The client name may be used for display to the user, for example in
|
||||
* an authorization dialog that requires the user to approve a connection to
|
||||
* the EIS implementation.
|
||||
*
|
||||
* This function must be called immediately after ei_new() and before
|
||||
* setting up a backend with ei_setup_backend_socket() or
|
||||
* ei_setup_backend_fd().
|
||||
|
|
@ -266,6 +270,11 @@ ei_configure_name(struct ei * ei, const char *name);
|
|||
* connect to the socket at the given path and initiate the conversation
|
||||
* with the EIS server listening on that socket.
|
||||
*
|
||||
* If @p socketpath is `NULL`, the value of the environment variable
|
||||
* `LIBEI_SOCKET` is used. If @p socketpath does not start with '/', it is
|
||||
* relative to `$XDG_RUNTIME_DIR`. If `XDG_RUNTIME_DIR` is not set, this
|
||||
* function fails.
|
||||
*
|
||||
* If the connection was successful, an event of type @ref EI_EVENT_CONNECT
|
||||
* or @ref EI_EVENT_DISCONNECT will become available after a future call to
|
||||
* ei_dispatch().
|
||||
|
|
@ -295,6 +304,26 @@ ei_setup_backend_socket(struct ei *ei, const char *socketpath);
|
|||
int
|
||||
ei_setup_backend_fd(struct ei *ei, int fd);
|
||||
|
||||
/**
|
||||
* Connect to the `org.freedesktop.portal.Desktop` portal.
|
||||
*
|
||||
* @return 0 on success or a negative errno on failure
|
||||
*/
|
||||
int
|
||||
ei_setup_backend_portal(struct ei *ei);
|
||||
|
||||
/**
|
||||
* Connect to an `org.freedesktop.portal.Desktop` implementation on the
|
||||
* given busname.
|
||||
*
|
||||
* Outside of testing environments, there is usually no reason to use
|
||||
* this function, use ei_setup_backend_portal() instead.
|
||||
*
|
||||
* @return 0 on success or a negative errno on failure
|
||||
*/
|
||||
int
|
||||
ei_setup_backend_portal_busname(struct ei *ei, const char *busname);
|
||||
|
||||
/**
|
||||
* Increase the refcount of this struct by one. Use ei_unref() to decrease
|
||||
* the refcount.
|
||||
|
|
@ -329,26 +358,6 @@ ei_set_user_data(struct ei *ei, void *user_data);
|
|||
void *
|
||||
ei_get_user_data(struct ei *ei);
|
||||
|
||||
/**
|
||||
* Connect to the `org.freedesktop.portal.Desktop` portal.
|
||||
*
|
||||
* @return 0 on success or a negative errno on failure
|
||||
*/
|
||||
int
|
||||
ei_setup_backend_portal(struct ei *ei);
|
||||
|
||||
/**
|
||||
* Connect to an `org.freedesktop.portal.Desktop` implementation on the
|
||||
* given busname.
|
||||
*
|
||||
* Outside of testing environments, there is usually no reason to use
|
||||
* this function, use ei_setup_backend_portal() instead.
|
||||
*
|
||||
* @return 0 on success or a negative errno on failure
|
||||
*/
|
||||
int
|
||||
ei_setup_backend_portal_busname(struct ei *ei, const char *busname);
|
||||
|
||||
/**
|
||||
* libei keeps a single file descriptor for all events. This fd should be
|
||||
* monitored for events by the caller's mainloop, e.g. using select(). When
|
||||
|
|
@ -409,6 +418,30 @@ ei_peek_event(struct ei *ei);
|
|||
struct ei_event *
|
||||
ei_event_unref(struct ei_event *event);
|
||||
|
||||
/**
|
||||
* @return the type of this event
|
||||
*/
|
||||
enum ei_event_type
|
||||
ei_event_get_type(struct ei_event *event);
|
||||
|
||||
/**
|
||||
* Return the device from this event.
|
||||
*
|
||||
* For events of type @ref EI_EVENT_CONNECT and @ref EI_EVENT_DISCONNECT,
|
||||
* this function returns NULL.
|
||||
*
|
||||
* 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_get_time(struct ei_event *event);
|
||||
|
||||
/**
|
||||
* Increase the refcount of this struct by one. Use ei_device_unref() to
|
||||
* decrease the refcount.
|
||||
|
|
@ -829,9 +862,9 @@ ei_device_pointer_button(struct ei_device *device,
|
|||
* 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.
|
||||
* @note The server is responsible for emulateing discrete scrolling based
|
||||
* on the pixel value, do not call ei_device_pointer_scroll_discrete() for
|
||||
* the same input event.
|
||||
*
|
||||
* @param device The EI device
|
||||
* @param x The x scroll distance in logical pixels
|
||||
|
|
@ -851,8 +884,8 @@ ei_device_pointer_scroll(struct ei_device *device, double x, double y);
|
|||
* 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
|
||||
* @note The server is responsible for emulating pixel-based scrolling based
|
||||
* on the discrete value, do not call ei_device_pointer_scroll() for the
|
||||
* same input event.
|
||||
*
|
||||
* @param device The EI device
|
||||
|
|
@ -918,45 +951,46 @@ ei_touch_motion(struct ei_touch *touch, double x, double y);
|
|||
void
|
||||
ei_touch_up(struct ei_touch *touch);
|
||||
|
||||
/**
|
||||
* Increase the refcount of this struct by one. Use ei_touch_unref() to
|
||||
* decrease the refcount.
|
||||
*
|
||||
* @return the argument passed into the function
|
||||
*/
|
||||
struct ei_touch *
|
||||
ei_touch_ref(struct ei_touch *touch);
|
||||
|
||||
/**
|
||||
* Decrease the refcount of this struct by one. When the refcount reaches
|
||||
* zero, the context disconnects from the server and all allocated resources
|
||||
* are released.
|
||||
*
|
||||
* @return always NULL
|
||||
*/
|
||||
struct ei_touch *
|
||||
ei_touch_unref(struct ei_touch *touch);
|
||||
|
||||
void *
|
||||
ei_touch_get_user_data(struct ei_touch *touch);
|
||||
|
||||
/**
|
||||
* Return the custom data pointer for this context. libei will not look at or
|
||||
* modify the pointer. Use ei_touch_set_user_data() to change the user data.
|
||||
*/
|
||||
void
|
||||
ei_touch_set_user_data(struct ei_touch *touch, void *user_data);
|
||||
|
||||
/**
|
||||
* Set a custom data pointer for this context. libei will not look at or
|
||||
* modify the pointer. Use ei_touch_get_user_data() to retrieve a previously
|
||||
* set user data.
|
||||
*/
|
||||
void *
|
||||
ei_touch_get_user_data(struct ei_touch *touch);
|
||||
|
||||
/**
|
||||
* @return the device this touch originates on
|
||||
*/
|
||||
struct ei_device *
|
||||
ei_touch_get_device(struct ei_touch *touch);
|
||||
|
||||
enum ei_event_type
|
||||
ei_event_get_type(struct ei_event *event);
|
||||
|
||||
/**
|
||||
* Return the device from this event.
|
||||
*
|
||||
* For events of type @ref EI_EVENT_CONNECT and @ref EI_EVENT_DISCONNECT,
|
||||
* this function returns NULL.
|
||||
*
|
||||
* 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_get_time(struct ei_event *event);
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue