The device API

Functions
struct eis *	eis_device_get_context (struct eis_device *device)
struct eis_client *	eis_device_get_client (struct eis_device *device)
struct eis_seat *	eis_device_get_seat (struct eis_device *device)
struct eis_device *	eis_device_ref (struct eis_device *device)
struct eis_device *	eis_device_unref (struct eis_device *device)
void *	eis_device_get_user_data (struct eis_device *eis_device)
void	eis_device_set_user_data (struct eis_device *eis_device, void *user_data)
const char *	eis_device_get_name (struct eis_device *device)
	Return the name of the device.
bool	eis_device_has_capability (struct eis_device *device, enum eis_device_capability cap)
uint32_t	eis_device_get_width (struct eis_device *device)
	Return the width in mm of a device of type EIS_DEVICE_TYPE_PHYSICAL, or zero otherwise.
uint32_t	eis_device_get_height (struct eis_device *device)
	Return the height in mm of a device of type EIS_DEVICE_TYPE_PHYSICAL, or zero otherwise.
void	eis_device_configure_type (struct eis_device *device, enum eis_device_type type)
	Set the device type for this device.
enum eis_device_type	eis_device_get_type (struct eis_device *device)
void	eis_device_configure_name (struct eis_device *device, const char *name)
void	eis_device_configure_capability (struct eis_device *device, enum eis_device_capability cap)
void	eis_device_configure_size (struct eis_device *device, uint32_t width, uint32_t height)
	Configure the size in mm of a device of type EIS_DEVICE_TYPE_PHYSICAL.
struct eis_region *	eis_device_new_region (struct eis_device *device)
	Create a new region on the device of type EIS_DEVICE_TYPE_VIRTUAL with an initial refcount of 1.
struct eis_region *	eis_device_get_region (struct eis_device *device, size_t index)
	Obtain a region from the device.
struct eis_region *	eis_device_get_region_at (struct eis_device *device, double x, double y)
	Return the region that contains the given point x/y (in desktop-wide coordinates) or NULL if the coordinates are outside all regions.
void	eis_device_add (struct eis_device *device)
	Add this device to its seat and notify the client of the device's availability.
void	eis_device_remove (struct eis_device *device)
	Remove the device.
void	eis_device_pause (struct eis_device *device)
	Notify the client that the device is paused and that no events from the client will be processed.
void	eis_device_resume (struct eis_device *device)
	Notify the client that the capabilities are resumed and that events from the device will be processed.
struct eis_keymap *	eis_device_new_keymap (struct eis_device *device, enum eis_keymap_type type, int fd, size_t size)
	Create a new keymap of the given type.
struct eis_keymap *	eis_device_keyboard_get_keymap (struct eis_device *device)
	Return the keymap assigned to this device.
void	eis_device_keyboard_send_xkb_modifiers (struct eis_device *device, uint32_t depressed, uint32_t latched, uint32_t locked, uint32_t group)
	Notify the client of the current XKB modifier state.

Detailed Description

The API to query and interact with a struct eis_device

Function Documentation

eis_device_add()

void eis_device_add

(

struct eis_device *

device

)

Add this device to its seat and notify the client of the device's availability.

The device is paused, use eis_device_resume() to enable events from the client.

eis_device_configure_capability()

void eis_device_configure_capability	(	struct eis_device *	device,
		enum eis_device_capability	cap )

eis_device_configure_name()

void eis_device_configure_name	(	struct eis_device *	device,
		const char *	name )

eis_device_configure_size()

void eis_device_configure_size	(	struct eis_device *	device,
		uint32_t	width,
		uint32_t	height )

Configure the size in mm of a device of type EIS_DEVICE_TYPE_PHYSICAL.

Device with relative-only capabilities does not require a size. A device with capability EIS_DEVICE_CAP_POINTER_ABSOLUTE or EIS_DEVICE_CAP_TOUCH must have a size.

This function has no effect if called on a device of type other than EIS_DEVICE_TYPE_PHYSICAL.

This function has no effect if called after ei_device_add()

eis_device_configure_type()

void eis_device_configure_type	(	struct eis_device *	device,
		enum eis_device_type	type )

Set the device type for this device.

It is recommended that that the device type is the first call to configure the device as the device type influences which other properties on the device can be set and/or will trigger warnings if invoked with wrong arguments.

eis_device_get_client()

struct eis_client * eis_device_get_client

(

struct eis_device *

device

)

eis_device_get_context()

struct eis * eis_device_get_context

(

struct eis_device *

device

)

eis_device_get_height()

uint32_t eis_device_get_height

(

struct eis_device *

device

)

Return the height in mm of a device of type EIS_DEVICE_TYPE_PHYSICAL, or zero otherwise.

eis_device_get_name()

const char * eis_device_get_name

(

struct eis_device *

device

)

Return the name of the device.

The return value of this function may change after eis_device_configure_name(), a caller should keep a copy of it where required rather than the pointer value.

eis_device_get_region()

struct eis_region * eis_device_get_region	(	struct eis_device *	device,
		size_t	index )

Obtain a region from the device.

This function only returns regions that have been added to the device with eis_region_add(). The number of regions is constant for a device once eis_device_add() has been called and the indices of any region remains the same for the lifetime of 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.

This function returns the given region or NULL if the index is larger than the number of regions available.

This does not increase the refcount of the region. Use eis_region_ref() to keep a reference beyond the immediate scope.

eis_device_get_region_at()

struct eis_region * eis_device_get_region_at	(	struct eis_device *	device,
		double	x,
		double	y )

Return the region that contains the given point x/y (in desktop-wide coordinates) or NULL if the coordinates are outside all regions.

Since

1.1

eis_device_get_seat()

struct eis_seat * eis_device_get_seat

(

struct eis_device *

device

)

eis_device_get_type()

enum eis_device_type eis_device_get_type

(

struct eis_device *

device

)

eis_device_get_user_data()

void * eis_device_get_user_data

(

struct eis_device *

eis_device

)

eis_device_get_width()

uint32_t eis_device_get_width

(

struct eis_device *

device

)

Return the width in mm of a device of type EIS_DEVICE_TYPE_PHYSICAL, or zero otherwise.

eis_device_has_capability()

bool eis_device_has_capability	(	struct eis_device *	device,
		enum eis_device_capability	cap )

eis_device_keyboard_get_keymap()

struct eis_keymap * eis_device_keyboard_get_keymap

(

struct eis_device *

device

)

Return the keymap assigned to this device.

The return value of this function is the keymap (if any) after the call to eis_keymap_add().

eis_device_keyboard_send_xkb_modifiers()

void eis_device_keyboard_send_xkb_modifiers	(	struct eis_device *	device,
		uint32_t	depressed,
		uint32_t	latched,
		uint32_t	locked,
		uint32_t	group )

Notify the client of the current XKB modifier state.

eis_device_new_keymap()

struct eis_keymap * eis_device_new_keymap	(	struct eis_device *	device,
		enum eis_keymap_type	type,
		int	fd,
		size_t	size )

Create a new keymap of the given type.

This keymap does not immediately apply to the device, use eis_keymap_add() to apply this keymap. A keymap may only be applied once and to a single device.

The returned keymap has a refcount of at least 1, use eis_keymap_unref() to release resources associated with this keymap.

Parameters

device	The device with a EIS_DEVICE_CAP_KEYBOARD capability
type	The type of the keymap.
fd	A memmap-able file descriptor of size size pointing to the keymap used by this device. fd can be closed by the caller after this function completes. The file descriptor needs to be mmap:ed with MAP_PRIVATE.
size	The size of the data at fd in bytes

Returns

A keymap object or NULL on failure.

eis_device_new_region()

struct eis_region * eis_device_new_region

(

struct eis_device *

device

)

Create a new region on the device of type EIS_DEVICE_TYPE_VIRTUAL with an initial refcount of 1.

Use eis_region_add() to properly add the region to the device.

A region must have a size to be valid, see eis_region_set_size().

For a device of type EIS_DEVICE_TYPE_PHYSICAL this function returns NULL.

eis_device_pause()

void eis_device_pause

(

struct eis_device *

device

)

Notify the client that the device is paused and that no events from the client will be processed.

The library filters events sent by the client after the pause notification has been processed by the client but this does not affect events already in transit. In other words, the server may still receive a number of events from a device after it has been paused and must update its internal state accordingly.

Pause/resume should only be used for short-term event delaying, a client will expect that the device's state has not changed between pause and resume. Where a device's state changes on the EIS implementation side (e.g. buttons or keys are forcibly released), the device should be removed and re-added as new device.

Parameters

device

A connected device

eis_device_ref()

struct eis_device * eis_device_ref

(

struct eis_device *

device

)

eis_device_remove()

void eis_device_remove

(

struct eis_device *

device

)

Remove the device.

This does not release any resources associated with this device, use eis_device_unref() for any references held by the caller.

eis_device_resume()

void eis_device_resume

(

struct eis_device *

device

)

Notify the client that the capabilities are resumed and that events from the device will be processed.

Parameters

device

A connected device

eis_device_set_user_data()

void eis_device_set_user_data	(	struct eis_device *	eis_device,
		void *	user_data )

eis_device_unref()

struct eis_device * eis_device_unref

(

struct eis_device *

device

)