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_touch *	ei_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.

void	ei_touch_cancel (struct ei_touch *touch)
	Cancel this touch.

struct ei_touch *	ei_touch_ref (struct ei_touch *touch)
	Increase the refcount of this struct by one.

struct ei_touch *	ei_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_device *	ei_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

device	The EI device
button	The button code
is_press	true 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

device	The EI device
keycode	The key code
is_press	true 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

device	The EI device
x	The x movement in logical pixels or mm, depending on the device type
y	The 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

device	The EI device
x	The x position in logical pixels or mm, depending on the device type
y	The 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

device	The EI device
x	The x scroll distance in logical pixels or mm, depending on the device type
y	The 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

device	The EI device
x	The x scroll distance in fractions or multiples of 120
y	The 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.

If the device is not logically in a neutral state, that state is left as-is. It is the caller's responsibility to release any buttons, keys, touch sequences, etc. when stopping emulation to avoid adverse side effects.

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_cancel()

void ei_touch_cancel ( struct ei_touch * touch )

Cancel 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().

This is only available if the EIS implementation supports version 2 or later of the ei_touchscreen protocol interface. Otherwise, this function is equivalent to calling ei_touch_up().

◆ 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

touch	A newly created touch
x	The x position in logical pixels
y	The 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().

Functions

Detailed Description

Function Documentation

◆ ei_device_button_button()

◆ ei_device_frame()

◆ ei_device_keyboard_key()

◆ ei_device_pointer_motion()

◆ ei_device_pointer_motion_absolute()

◆ ei_device_scroll_cancel()

◆ ei_device_scroll_delta()

◆ ei_device_scroll_discrete()

◆ ei_device_scroll_stop()

◆ ei_device_start_emulating()

◆ ei_device_stop_emulating()

◆ ei_device_touch_new()

◆ ei_touch_cancel()

◆ ei_touch_down()

◆ ei_touch_get_device()

◆ ei_touch_get_user_data()

◆ ei_touch_motion()

◆ ei_touch_ref()

◆ ei_touch_set_user_data()

◆ ei_touch_unref()

◆ ei_touch_up()