libei 1.3.0
A library for Emulated Input
API for sender clients

Functions

void ei_device_start_emulating (struct ei_device *device, uint32_t sequence)
 Notify the EIS implementation that the given device is about to start sending events.
 
void ei_device_stop_emulating (struct ei_device *device)
 Notify the EIS implementation that the given device is no longer sending events.
 
void ei_device_frame (struct ei_device *device, uint64_t time)
 Generate a frame event to group the current set of events into a logical hardware event.
 
void ei_device_pointer_motion (struct ei_device *device, double x, double y)
 Generate a relative motion event on a device with the EI_DEVICE_CAP_POINTER capability.
 
void ei_device_pointer_motion_absolute (struct ei_device *device, double x, double y)
 Generate an absolute motion event on a device with the EI_DEVICE_CAP_POINTER_ABSOLUTE capability.
 
void ei_device_button_button (struct ei_device *device, uint32_t button, bool is_press)
 Generate a button event on a device with the EI_DEVICE_CAP_BUTTON capability.
 
void ei_device_scroll_delta (struct ei_device *device, double x, double y)
 Generate a smooth (pixel-precise) scroll event on a device with the EI_DEVICE_CAP_SCROLL capability.
 
void ei_device_scroll_discrete (struct ei_device *device, int32_t x, int32_t y)
 Generate a discrete scroll event on a device with the EI_DEVICE_CAP_SCROLL capability.
 
void ei_device_scroll_stop (struct ei_device *device, bool stop_x, bool stop_y)
 Generate a scroll stop event on a device with the EI_DEVICE_CAP_SCROLL capability.
 
void ei_device_scroll_cancel (struct ei_device *device, bool cancel_x, bool cancel_y)
 Generate a scroll cancel event on a device with the EI_DEVICE_CAP_SCROLL capability.
 
void ei_device_keyboard_key (struct ei_device *device, uint32_t keycode, bool is_press)
 Generate a key event on a device with the EI_DEVICE_CAP_KEYBOARD capability.
 
struct ei_touchei_device_touch_new (struct ei_device *device)
 Initiate a new touch on a device with the EI_DEVICE_CAP_TOUCH capability.
 
void ei_touch_down (struct ei_touch *touch, double x, double y)
 This function can only be called once on an ei_touch object.
 
void ei_touch_motion (struct ei_touch *touch, double x, double y)
 Move this touch to the new coordinates.
 
void ei_touch_up (struct ei_touch *touch)
 Release this touch.
 
struct ei_touchei_touch_ref (struct ei_touch *touch)
 Increase the refcount of this struct by one.
 
struct ei_touchei_touch_unref (struct ei_touch *touch)
 Decrease the refcount of this struct by one.
 
void ei_touch_set_user_data (struct ei_touch *touch, void *user_data)
 Set a custom data pointer for this context.
 
void * ei_touch_get_user_data (struct ei_touch *touch)
 Return the custom data pointer for this context.
 
struct ei_deviceei_touch_get_device (struct ei_touch *touch)
 

Detailed Description

The sender client API is available only to clients created with ei_new_sender(). For those clients the EIS implemententation creates devices and but it is the libei client that sends events to EIS implementation. The primary use-case is input emulation from a client, akin to xdotool.

It is a client bug to call any of these functions for a client created with ei_new_receiver().

Function Documentation

◆ ei_device_button_button()

void ei_device_button_button ( struct ei_device * device,
uint32_t button,
bool is_press )

Generate a button event on a device with the EI_DEVICE_CAP_BUTTON capability.

Button codes must match the defines in linux/input-event-codes.h

This method is only available on an ei sender context.

Parameters
deviceThe EI device
buttonThe button code
is_presstrue for button press, false for button release

◆ ei_device_frame()

void ei_device_frame ( struct ei_device * device,
uint64_t time )

Generate a frame event to group the current set of events into a logical hardware event.

This function must be called after any other event has been generated.

The given timestamp applies to all events in the current frame. The timestamp must be in microseconds of CLOCK_MONOTONIC, use the return value of ei_now() to get a compatible timestamp.

Note
libei does not prevent a caller from passing in a future time but it is strongly recommended that this is avoided by the caller.

This method is only available on an ei sender context.

◆ ei_device_keyboard_key()

void ei_device_keyboard_key ( struct ei_device * device,
uint32_t keycode,
bool is_press )

Generate a key event on a device with the EI_DEVICE_CAP_KEYBOARD capability.

Keys use the evdev scan codes as defined in 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 client must look at the keymap returned by ei_device_keyboard_get_keymap() and generate the appropriate keycodes.

This method is only available on an ei sender context.

Parameters
deviceThe EI device
keycodeThe key code
is_presstrue for key down, false for key up

◆ ei_device_pointer_motion()

void ei_device_pointer_motion ( struct ei_device * device,
double x,
double y )

Generate a relative motion event on a device with the EI_DEVICE_CAP_POINTER capability.

This method is only available on an ei sender context.

Parameters
deviceThe EI device
xThe x movement in logical pixels or mm, depending on the device type
yThe y movement in logical pixels or mm, depending on the device type

◆ ei_device_pointer_motion_absolute()

void ei_device_pointer_motion_absolute ( struct ei_device * device,
double x,
double y )

Generate an absolute motion event on a device with the EI_DEVICE_CAP_POINTER_ABSOLUTE capability.

The x/y coordinate must be within the device's regions or the event is silently discarded.

This method is only available on an ei sender context.

Parameters
deviceThe EI device
xThe x position in logical pixels or mm, depending on the device type
yThe y position in logical pixels or mm, depending on the device type

◆ ei_device_scroll_cancel()

void ei_device_scroll_cancel ( struct ei_device * device,
bool cancel_x,
bool cancel_y )

Generate a scroll cancel event on a device with the EI_DEVICE_CAP_SCROLL capability.

A scroll cancel event notifies the server that a scroll motion previously triggered with ei_device_scroll_delta() or ei_device_scroll_discrete() has ceased and no further events should be sent.

This event indicates that the interaction has stopped to the point where further (server-emulated) scroll events from this device are wrong.

Use ei_device_scroll_stop() to signal that the interaction has stopped but a server may emulate further scroll events.

Calling ei_device_scroll_cancel() after ei_device_scroll_stop() without any of ei_device_scroll_delta() or ei_device_scroll_discrete() in between iis permitted.

libei keeps track of the scroll axis and filters duplicate calls to ei_device_scroll_cancel() for the same axis. A nonzero scroll or scroll-discrete value is required for the given axis to re-start scrolling for that axis.

This method is only available on an ei sender context.

◆ ei_device_scroll_delta()

void ei_device_scroll_delta ( struct ei_device * device,
double x,
double y )

Generate a smooth (pixel-precise) scroll event on a device with the EI_DEVICE_CAP_SCROLL capability.

Note
The server is responsible for emulating discrete scrolling based on the pixel value, do not call ei_device_scroll_discrete() for the same input event.

This method is only available on an ei sender context.

Parameters
deviceThe EI device
xThe x scroll distance in logical pixels or mm, depending on the device type
yThe y scroll distance in logical pixels or mm, depending on the device type
See also
ei_device_scroll_discrete

◆ ei_device_scroll_discrete()

void ei_device_scroll_discrete ( struct ei_device * device,
int32_t x,
int32_t y )

Generate a discrete scroll event on a device with the EI_DEVICE_CAP_SCROLL 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.

Note
The server is responsible for emulating pixel-based scrolling based on the discrete value, do not call ei_device_scroll_delta() for the same input event.

This method is only available on an ei sender context.

Parameters
deviceThe EI device
xThe x scroll distance in fractions or multiples of 120
yThe y scroll distance in fractions or multiples of 120
See also
ei_device_scroll_delta

◆ ei_device_scroll_stop()

void ei_device_scroll_stop ( struct ei_device * device,
bool stop_x,
bool stop_y )

Generate a scroll stop event on a device with the EI_DEVICE_CAP_SCROLL capability.

A scroll stop event notifies the server that the interaction causing a scroll motion previously triggered with ei_device_scroll_delta() or ei_device_scroll_discrete() has stopped. For example, if all fingers are lifted off a touchpad, two-finger scrolling has logically stopped.

The server may use this information to e.g. start kinetic scrolling previously based on the previous finger speed.

Use ei_device_scroll_cancel() to signal that the scroll motion has completely stopped.

Calling ei_device_scroll_stop() after ei_device_scroll_cancel() without any of ei_device_scroll_delta() or ei_device_scroll_discrete() in between indicates a client logic bug.

libei keeps track of the scroll axis and filters duplicate calls to ei_device_scroll_stop() for the same axis. A nonzero scroll or scroll-discrete value is required for the given axis to re-start scrolling for that axis.

This method is only available on an ei sender context.

◆ ei_device_start_emulating()

void ei_device_start_emulating ( struct ei_device * device,
uint32_t sequence )

Notify the EIS implementation that the given device is about to start sending events.

This should be seen more as a transactional boundary than a time-based boundary. The primary use-cases for this are to allow for setup on the EIS implementation side and/or UI updates to indicate that a device is sending events now and for out-of-band information to sync with a given event sequence.

There is no actual requirement that events start immediately once emulation starts and there is no requirement that a client calls ei_device_stop_emulating() after the most recent events.

For example, in a synergy-like use-case the client would call ei_device_start_emulating() once the pointer moves into the the screen and ei_device_stop_emulating() once the pointer moves out of the screen.

Sending events before ei_device_start_emulating() or after ei_device_stop_emulating() is a client bug.

The sequence number identifies this transaction between start/stop emulating. It must go up by at least 1 on each call to ei_device_start_emulating(). Wraparound must be handled by the EIS implementation but Callers must ensure that detection of wraparound is reasonably.

This method is only available on an ei sender context.

◆ ei_device_stop_emulating()

void ei_device_stop_emulating ( struct ei_device * device)

Notify the EIS implementation that the given device is no longer sending events.

See ei_device_start_emulating() for details.

This method is only available on an ei sender context.

◆ ei_device_touch_new()

struct ei_touch * ei_device_touch_new ( struct ei_device * device)

Initiate a new touch on a device with the EI_DEVICE_CAP_TOUCH capability.

This touch does not immediately send events, use ei_touch_down(), ei_touch_motion(), and ei_touch_up().

The returned touch has a refcount of at least 1, use ei_touch_unref() to release resources associated with this touch

This method is only available on an ei sender context.

◆ ei_touch_down()

void ei_touch_down ( struct ei_touch * touch,
double x,
double y )

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 x/y coordinate must be within the device's regions or the event is silently discarded.

Parameters
touchA newly created touch
xThe x position in logical pixels
yThe y position in logical pixels

◆ ei_touch_get_device()

struct ei_device * ei_touch_get_device ( struct ei_touch * touch)
Returns
the device this touch originates on

◆ ei_touch_get_user_data()

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.

◆ ei_touch_motion()

void ei_touch_motion ( struct ei_touch * touch,
double x,
double y )

Move this touch to the new coordinates.

◆ ei_touch_ref()

struct ei_touch * ei_touch_ref ( struct ei_touch * touch)

Increase the refcount of this struct by one.

Use ei_touch_unref() to decrease the refcount.

Returns
the argument passed into the function

◆ ei_touch_set_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.

◆ ei_touch_unref()

struct ei_touch * ei_touch_unref ( 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.

Returns
always NULL

◆ ei_touch_up()

void ei_touch_up ( struct ei_touch * touch)

Release this touch.

After this call, the touch event becomes inert and no longer responds to either ei_touch_down(), ei_touch_motion() or ei_touch_up() and the caller should call ei_touch_unref().