mirror of
https://gitlab.freedesktop.org/libinput/libei.git
synced 2026-04-28 05:30:40 +02:00
doc: updates all over the place
This commit is contained in:
Peter Hutterer
parent
d695cf1ab7
commit
9f1db1e10b
2 changed files with 25 additions and 39 deletions
52
src/libei.h
52
src/libei.h
|
|
@ -134,7 +134,7 @@ struct ei_region;
|
|||
* Keyboard events sent through such a device will be treated as client bug
|
||||
* and discarded.
|
||||
*
|
||||
* See eis_device_has_capability().
|
||||
* See ei_device_has_capability().
|
||||
*
|
||||
*/
|
||||
enum ei_device_capability {
|
||||
|
|
@ -202,9 +202,6 @@ enum ei_event_type {
|
|||
*
|
||||
* This event is not generated for properties without the @ref
|
||||
* EI_PROPERTY_PERM_READ set.
|
||||
*
|
||||
* libei guarantees that a @ref EI_EVENT_DISCONNECT is provided to
|
||||
* the caller even where the server does not send one.
|
||||
*/
|
||||
EI_EVENT_PROPERTY,
|
||||
|
||||
|
|
@ -249,7 +246,7 @@ enum ei_event_type {
|
|||
* are discarded.
|
||||
*
|
||||
* When this event is received, the device is already removed. A
|
||||
* caller does not need to call ei_device_remove() event on this
|
||||
* caller does not need to call ei_device_close() event on this
|
||||
* device.
|
||||
*/
|
||||
EI_EVENT_DEVICE_REMOVED,
|
||||
|
|
@ -789,8 +786,8 @@ void *
|
|||
ei_keymap_get_user_data(struct ei_keymap *keymap);
|
||||
|
||||
/**
|
||||
* Notify the server that the client is no longer listening to events
|
||||
* from this device.
|
||||
* Notify the server that the client is no longer interested in
|
||||
* this device.
|
||||
*
|
||||
* Due to the asynchronous nature of the client-server interaction,
|
||||
* events for this device may still be in transit. The server will send an
|
||||
|
|
@ -799,7 +796,7 @@ ei_keymap_get_user_data(struct ei_keymap *keymap);
|
|||
*
|
||||
* A client can assume that an @ref EI_EVENT_DEVICE_REMOVED event is sent
|
||||
* for any device for which ei_device_close() was called before the @ref
|
||||
* EI_EVENT_DISCONNECT. Where a client gets
|
||||
* EI_EVENT_DISCONNECT event. Where a client gets
|
||||
* disconnected libei will emulate that event.
|
||||
*
|
||||
* This does not release any resources associated with this device, use
|
||||
|
|
@ -809,13 +806,6 @@ void
|
|||
ei_device_close(struct ei_device *device);
|
||||
|
||||
/**
|
||||
* Return the name of this device.
|
||||
*
|
||||
* The return value of this function is constant after receiving the @ref
|
||||
* EI_EVENT_DEVICE_ADDED event. Before then, the returned string may be
|
||||
* freed at any time, callers must strdup() the returned value if they need
|
||||
* to keep the name around.
|
||||
*
|
||||
* @return the name of the device (if any) or NULL
|
||||
*/
|
||||
const char *
|
||||
|
|
@ -823,10 +813,7 @@ ei_device_get_name(struct ei_device *device);
|
|||
|
||||
/**
|
||||
* Return true if the device has the requested capability. Device
|
||||
* capabilities are constant after the @ref EI_EVENT_DEVICE_ADDED event.
|
||||
*
|
||||
* To change a device's capability, the device must be removed and a new
|
||||
* device with the different capabilities must be added.
|
||||
* capabilities are constant.
|
||||
*/
|
||||
bool
|
||||
ei_device_has_capability(struct ei_device *device,
|
||||
|
|
@ -839,8 +826,10 @@ ei_device_has_capability(struct ei_device *device,
|
|||
* the device.
|
||||
*
|
||||
* Regions are shared between all capabilities. Where two capabilities need
|
||||
* different region, the EIS implementation must create multiple devices with
|
||||
* individual capabilities and regions.
|
||||
* different regions, the EIS implementation must create multiple devices with
|
||||
* individual capabilities and regions. For example, two touchscreens that are
|
||||
* mapped to two screens would typically show up as two separate devices with
|
||||
* one region each.
|
||||
*
|
||||
* This function returns the given region or NULL if the index is larger than
|
||||
* the number of regions available.
|
||||
|
|
@ -886,7 +875,7 @@ ei_region_contains(struct ei_region *region, double x, double y);
|
|||
* Convert the point x/y in a desktop-wide coordinate system into the
|
||||
* corresponding point relative to the offset of the given region.
|
||||
* If the point is inside the region, this function returns true and @a x and @a
|
||||
* y are set to the points with region offset subtracted.
|
||||
* y are set to the points with the region offset subtracted.
|
||||
* If the point is outside the region, this function returns false and @a x
|
||||
* and @a y are left unmodified.
|
||||
*/
|
||||
|
|
@ -957,16 +946,15 @@ ei_region_convert_point(struct ei_region *region, double *x, double *y);
|
|||
* A second possible use-case for the physical scale is to match pixels from
|
||||
* one region to their respective counterpart on a different region.
|
||||
* For example, if the bottom-right corner of the 2k screen in the
|
||||
* illustration above has a coordinate of x/y, the neighbouring pixel on the
|
||||
* **physical** 4k screen is (0/y * scale).
|
||||
* illustration above has a coordinate of ``(x, y)``, the neighbouring pixel on
|
||||
* the **physical** 4k screen is ``(0, y * scale)``.
|
||||
*/
|
||||
double
|
||||
ei_region_get_physical_scale(struct ei_region *region);
|
||||
|
||||
/**
|
||||
* Return the keymap for this device or `NULL`. The keymap is constant for
|
||||
* the lifetime of the device after the @ref EI_EVENT_DEVICE_ADDED was
|
||||
* received and applies to this device individually.
|
||||
* the lifetime of the device and applies to this device individually.
|
||||
*
|
||||
* If this function returns `NULL`, this device does not have
|
||||
* an individual keymap assigned. What keymap applies to the device in this
|
||||
|
|
@ -975,7 +963,8 @@ ei_region_get_physical_scale(struct ei_region *region);
|
|||
* This does not increase the refcount of the keymap. Use ei_keymap_ref() to
|
||||
* keep a reference beyond the immediate scope.
|
||||
*
|
||||
* FIXME: the current API makes it impossible to know when the keymap has
|
||||
*/
|
||||
/* FIXME: the current API makes it impossible to know when the keymap has
|
||||
* been consumed so the file stays open forever.
|
||||
*/
|
||||
struct ei_keymap *
|
||||
|
|
@ -1060,7 +1049,7 @@ ei_device_pointer_motion_absolute(struct ei_device *device,
|
|||
* the @ref EI_DEVICE_CAP_POINTER_ABSOLUTE or
|
||||
* @ref EI_DEVICE_CAP_POINTER capability.
|
||||
*
|
||||
* Button codes must match the defines in linux/input-event-codes.h
|
||||
* Button codes must match the defines in ``linux/input-event-codes.h``
|
||||
*
|
||||
* @param device The EI device
|
||||
* @param button The button code
|
||||
|
|
@ -1170,7 +1159,7 @@ ei_device_pointer_scroll_cancel(struct ei_device *device, bool cancel_x, bool ca
|
|||
* the @ref EI_DEVICE_CAP_KEYBOARD capability.
|
||||
*
|
||||
* Keys use the evdev scan codes as defined in
|
||||
* linux/input-event-codes.h
|
||||
* ``linux/input-event-codes.h``.
|
||||
*
|
||||
* Note that this is a keymap-independent key code, equivalent to the scancode
|
||||
* a physical keyboard would produce. To generate a specific key symbol, a
|
||||
|
|
@ -1199,9 +1188,8 @@ ei_device_touch_new(struct ei_device *device);
|
|||
* This function can only be called once on an ei_touch object. Further
|
||||
* calls to ei_touch_down() on the same object are silently ignored.
|
||||
*
|
||||
* The required conditions are:
|
||||
* - 0 <= x < width
|
||||
* - 0 <= y < height
|
||||
* The x/y coordinate must be within the device's regions or the event is
|
||||
* silently discarded.
|
||||
*
|
||||
* @param touch A newly created touch
|
||||
* @param x The x position in logical pixels
|
||||
|
|
|
|||
12
src/libeis.h
12
src/libeis.h
|
|
@ -358,7 +358,7 @@ eis_backend_fd_add_fd(struct eis *ctx, int fd);
|
|||
/**
|
||||
* libeis 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
|
||||
* events are available on this fd, call libeis_dispatch() immediately to
|
||||
* events are available on this fd, call eis_dispatch() immediately to
|
||||
* process.
|
||||
*/
|
||||
int
|
||||
|
|
@ -366,12 +366,12 @@ eis_get_fd(struct eis *eis);
|
|||
|
||||
/**
|
||||
* Main event dispatching function. Reads events of the file descriptors
|
||||
* and processes them internally. Use libeis_get_event() to retrieve the
|
||||
* and processes them internally. Use eis_get_event() to retrieve the
|
||||
* events.
|
||||
*
|
||||
* Dispatching does not necessarily queue events. This function
|
||||
* should be called immediately once data is available on the file
|
||||
* descriptor returned by libeis_get_fd().
|
||||
* descriptor returned by eis_get_fd().
|
||||
*/
|
||||
void
|
||||
eis_dispatch(struct eis *eis);
|
||||
|
|
@ -762,9 +762,7 @@ eis_device_new_keymap(struct eis_device *device,
|
|||
enum eis_keymap_type type, int fd, size_t size);
|
||||
|
||||
/**
|
||||
* Set the keymap on the device. Note that **not** calling this function when
|
||||
* eis_device_keyboard_get_keymap() returns non-`NULL` meas the keymap is not
|
||||
* applied to the device.
|
||||
* Set the keymap on the device.
|
||||
*
|
||||
* The keymap is constant for the lifetime of the device and assigned to
|
||||
* this device individually. Where the keymap has to change, remove the
|
||||
|
|
@ -861,7 +859,7 @@ eis_event_pointer_get_dx(struct eis_event *event);
|
|||
|
||||
/**
|
||||
* For an event of type @ref EIS_EVENT_POINTER_MOTION return the relative y
|
||||
uint32_* movement in logical pixels.
|
||||
* movement in logical pixels.
|
||||
*/
|
||||
double
|
||||
eis_event_pointer_get_dy(struct eis_event *event);
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue