ei_keyboard

Keyboard Object

Interface for keyboard requests and events.

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.

Enums

ei_keyboard.key_state

The logical state of a key.

ei_keyboard.keymap_type

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

Requests

ei_keyboard.release

Since Version1 Request Opcode0

ei_keyboard.release()

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.

ei_keyboard.key

Since Version1 Request Opcode1

ei_keyboard.key(key, state)

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 and the EIS implementation may ignore either or all key state changes and/or disconnect the client.

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

Events

ei_keyboard.destroyed

Since Version1 Event Opcode0

ei_keyboard.destroyed(serial)

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.

ei_keyboard.keymap

Since Version1 Event Opcode1

ei_keyboard.keymap(keymap_type, size, 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 optional and only 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.

ei_keyboard.key

Since Version1 Event Opcode2

ei_keyboard.key(key, state)

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.

ei_keyboard.modifiers

Since Version1 Event Opcode3

ei_keyboard.modifiers(serial, depressed, locked, latched, group)

Notification that the EIS implementation has changed group or modifier states on this device, but not necessarily in response to an ei_keyboard.key event or request. Future ei_keyboard.key requests must take the new group and modifier state into account.

This event should be sent any time the modifier state or effective group has changed, whether caused by an ei_keyboard.key event in accordance with the keymap, indirectly due to further handling of an ei_keyboard.key event (e.g., because it triggered a keyboard shortcut that then changed the state), or caused by an unrelated an event (e.g., input from a different keyboard, or a group change triggered by a layout selection widget).

For receiver clients, modifiers events will always be properly ordered with received key events, so each key event should be interpreted using the most recently-received modifier state. The server should send this event immediately following the ei_device.frame event for the key press that caused the change. If the state change impacts multiple keyboards, this event should be sent for all of them.

For sender clients, the modifiers event is not inherently synchronized with key requests, but the client may send an ei_connection.sync request when synchronization is required. When the corresponding ei_callback.done event is received, all key requests sent prior to the sync request are guaranteed to have been processed, and any directly-resulting modifiers events are guaranteed to have been received. Note, however, that it is still possible for indirectly-triggered state changes, such as via a keyboard shortcut not encoded in the keymap, to be reported after the done event.

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.

Note: A previous version of the documentation instead specified that this event should not be sent in response to ei_keyboard.key events that change the group or modifier state according to the keymap. However, this complicated client implementation and resulted in situations where the client state could get out of sync with the server.