Keyboard Object

Interface for keyboard requests and events. This interface is available on devices with the ei_device.capability keyboard.

This interface is only provided once per device and where a client requests ei_keyboard.release the interface does not get re-initialized. An EIS implementation may adjust the behavior of the device (including removing the device) if the interface is releasd.

Note that for a client to receive objects of this type, it must announce support for this interface in ei_handshake.interface_version.



Enum names are shown here in uppercase. The exact name depends on the language bindings.


The logical state of a key.

Name Value Summary
RELEASED 0 the key is logically up
PRESS 1 the key is logically down


The keymap type describes how the keymap in the ei_keyboard.keymap event should be parsed.

Name Value Summary
XKB 1 a libxkbcommon-compatible XKB keymap



Since Version1 Request Opcode0


Notification that the client is no longer interested in this keyboard. The EIS implementation will release any resources related to this keyboard and send the ei_keyboard.destroyed event once complete.


Since Version1 Request Opcode1

ei_keyboard.key(key, state)
Argument Type Summary
key uint32 the key code
state uint32 logical state of the key

This request is only available for clients of ei_handshake.context_type.sender.

Generate a key event on this keyboard. If the device has an ei_keyboard.keymap, the key code corresponds to that keymap.

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

It is a client bug to send more than one key request for the same key within the same ei_device.frame.

It is a protocol violation to send this request for a client of an ei_handshake.context_type other than sender.



Since Version1 Event Opcode0

Argument Type Summary
serial uint32 this event’s serial number

Immediately after sending this request, the object is considered destroyed by the EIS implementation. It must no longer be used by the client.

This keyboard has been removed and a client should release all associated resources.

This ei_keyboard object will be destroyed by the EIS implementation immmediately after after this event is sent and as such the client must not attempt to use it after that point.


Since Version1 Event Opcode1

ei_keyboard.keymap(keymap_type, size, keymap)
Argument Type Summary
keymap_type uint32 the keymap type
size uint32 the keymap size in bytes
keymap fd file descriptor to the keymap

Notification that this device has a keymap. Future key events must be interpreted by the client according to this keymap. For clients of ei_handshake.context_type sender it is the client’s responsibility to send the correct ei_keyboard.key keycodes to generate the expected keysym in the EIS implementation.

The keymap is constant for the lifetime of the device.

This event provides a file descriptor to the client which can be memory-mapped in read-only mode to provide a keyboard mapping description. The fd must be mapped with MAP_PRIVATE by the recipient, as MAP_SHARED may fail.

This event is sent immediately after the ei_keyboard object is created and before the ei_device.done event. It is a protocol violation to send this event after the ei_device.done event.


Since Version1 Event Opcode2

ei_keyboard.key(key, state)
Argument Type Summary
key uint32
state uint32

This event is only available for clients of ei_handshake.context_type.receiver.

See the ei_keyboard.key request for details.

It is a protocol violation to send this request for a client of an ei_handshake.context_type other than receiver.

It is a protocol violation to send a key down event in the same frame as a key up event for the same key in the same frame.


Since Version1 Event Opcode3

ei_keyboard.modifiers(serial, depressed, locked, latched, group)
Argument Type Summary
serial uint32 this event’s serial number
depressed uint32 depressed modifiers
locked uint32 locked modifiers
latched uint32 latched modifiers
group uint32 the keyboard group (layout)

Notification that the EIS implementation has changed modifier states on this device. Future ei_keyboard.key requests must take the new modifier state into account.

A client must assume that all modifiers are lifted when it receives an ei_device.paused event. The EIS implementation must send this event after ei_device.resumed to notify the client of any nonzero modifier state.

This event does not reqire an ei_device.frame and should be processed immediately by the client.

This event is only sent for devices with an ei_keyboard.keymap.