Google is committed to advancing racial equity for Black communities. See how.

fuchsia.ui.input3

PROTOCOLS

KeyEventInjector

Defined in fuchsia.ui.input3/keyboard.fidl

Provides the ability to inject KeyEvents into the keyboard subsystem.

Roles

This protocol will typically be:

  • Implemented by platform components which process and deliver keyboard events.
  • Consumed by components which originiate keyboard events. E.g. an on-screen keyboard, or the Session Framework Input Pipeline.

Related protocols

This protocol should be using in preference to legacy protocols which provide similar functionality. Specifically, this means this protocol should be preferred over

  • fuchsia.ui.input.ImeService which provides InjectInput(), DispatchKey(), and DispatchKey3()
  • fuchsia.ui.input.InputMethodEditor, which provides InjectInput() and DispatchKey3()

Notes

Products should take care to limit access to this protocol, as events injected with this protocol are indistinguishable from those coming from physical devices.

Inject

Inject an event into the keyboard subsystem.

Returns

  • HANDLED if the keyboard subsystem delivered the event to a consumer, and the consumer reported that it HANDLED the event
  • NOT_HANDLED if the keyboard subsystem did not deliever the event to any consumers, or no consumer reported that it HANDLED the event.

Request

NameType
key_event KeyEvent

Response

NameType
status KeyEventStatus

Keyboard

Defined in fuchsia.ui.input3/keyboard.fidl

Components may request this service from their namespace to be notified of physical key events.

AddListener

Add a key event listener for the specified View. If multiple listeners are added, each will receive key events independently and should respond with a Status.

The client calling AddListener should keep the connection to Keyboard alive for as long as the events from KeyboardListener need to be received. Dropping the connection to the Keyboard protocol will terminate KeyboardListener as well.

Request

NameType
view_ref fuchsia.ui.views/ViewRef
listener KeyboardListener

Response

NameType

KeyboardListener

Defined in fuchsia.ui.input3/keyboard.fidl

Client should implement this protocol to get notified of key events.

OnKeyEvent

Called when a key event takes place, such as key press or release. Protocol implementers must respond to acknowledge the event by returning Status in a timely manner, i.e. not introducing significant delays to the input pipeline (typically 10s of milliseconds). Returning NOT_HANDLED means the event will propagate to another client or listener. Clients that do not acknowledge their events will eventually be disconnected. Notification is only dispatched when the View is focused (ViewRef is on FocusChain). Parent Views receive the notification first, child Views last. Returning HANDLED will stop event propagation to other clients and listeners.

Request

NameType
event KeyEvent

Response

NameType
status KeyEventStatus

STRUCTS

ENUMS

KeyEventStatus

Type: uint32

Defined in fuchsia.ui.input3/keyboard.fidl

Return type for clients key events listener.

NameValueDescription
HANDLED 1

The key event was handled and its further propagation should be stopped.

NOT_HANDLED 2

The key event wasn't handled and should be delivered to other clients or listeners.

KeyEventType

Type: uint32

Defined in fuchsia.ui.input3/events.fidl

Type of the keyboard key input event.

NameValueDescription
PRESSED 1

Key is pressed down.

RELEASED 2

Key is released.

SYNC 3

Key was pressed while the client wasn't able to receive it, e.g new device connected with a key held down or before system was started. Client should not handle this as a key press.

CANCEL 4

Key was released while the client wasn't able to receive it, e.g device was disconnected or focus lost. Client should not handle this as a key release.

NonPrintableKey

Type: uint32

Defined in fuchsia.ui.input3/events.fidl

NonPrintableKey represents the meaning of a non-symbolic key on a keyboard.

The definition of each key is derived from W3C named values of a key attribute: https://www.w3.org/TR/uievents-key/#named-key-attribute-values

NameValueDescription
ENTER 49

The Enter or ↵ key, to activate current selection or accept current input. This key value is also used for the Return (Macintosh numpad) key.

TAB 50

The Horizontal Tabulation Tab key.

BACKSPACE 65

Delete the character immediately preceding the cursor (i.e. the character to the left for LTR languages).

TABLES

KeyEvent

Defined in fuchsia.ui.input3/events.fidl

A Keyboard event generated to reflect key input. timestamp and type are required. At least one of key and key_meaning must be set for a valid event.

OrdinalNameTypeDescription
1 timestamp zx/time

Time in nanoseconds when the event was recorded, in the CLOCK_MONOTONIC time base.

2 type KeyEventType

Type of event.

3 key fuchsia.input/Key

Identifies the key ignoring modifiers, layout, prior key events, etc. This is called the "physical key" on some platforms. In cases where the key event did not originate from a physical keyboard (e.g. onscreen keyboard) this field may be empty.

4 modifiers Modifiers

Modifiers in effect at the time of the event. Example: CapsLock is off, user presses CapsLock, then A, then releases both. Event sequence is as follows:

  1. type: Pressed, key: CapsLock, modifiers: None
  2. type: Pressed, key: A, modifiers: CapsLock
  3. type: Released, key: CapsLock, modifiers: CapsLock
  4. type: Released, key: A, modifiers: CapsLock

CapsLock is on, user presses CapsLock, then A, then releases both.

  1. type: Pressed, key: CapsLock, modifiers: CapsLock
  2. type: Pressed, key: A, modifiers: None
  3. type: Released, key: CapsLock, modifiers: None
  4. type: Released, key: A, modifiers: None
5 key_meaning KeyMeaning

Meaning of the key.

UNIONS

KeyMeaning

Defined in fuchsia.ui.input3/events.fidl

The meaning of the key press. This is typically the Unicode codepoint inserted by this event, or an enum representing a key that corresponds to whitespace or is otherwise unprintable.

NameTypeDescription
codepoint uint32

The Unicode codepoint representing character typed, if any.

  • In Dart and Go, this corresponds to a rune.
  • In Rust, this corresponds to a char.
  • In C and C++, this corresponds to ICU's UChar32.
non_printable_key NonPrintableKey

The meaning of the key for key events with no corresponding symbol.

BITS

Modifiers

Type: uint64

Defined in fuchsia.ui.input3/modifiers.fidl

Modifiers are special keys that modify the purpose or the function of other keys when used in combination with them.

NameValueDescription
CAPS_LOCK 1

Applies when the CAPS_LOCK modifier is locked.

NUM_LOCK 2

Applies when the NUM_LOCK modifier is locked.

SCROLL_LOCK 4

Applies when the SCROLL_LOCK modifier is locked.