Honoring Asian Pacific American Heritage Month. See how.

fuchsia.ui.input3

Added: 7

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

<EMPTY>

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

ENUMS

KeyEventStatus strict

Type: uint32

Defined in fuchsia.ui.input3/keyboard.fidl

Return type for clients key events listener.

NameValueDescription
1

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

2

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

KeyEventType strict

Type: uint32

Defined in fuchsia.ui.input3/events.fidl

Type of the keyboard key input event.

NameValueDescription
1

Key is pressed down.

2

Key is released.

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.

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 flexible

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

The space of the arrow keys is subdivided roughly to correspond to the subsections of section 3 of that document. The choice for the section values is arbitrary, so long as blocks of values are allocated at once, and the keys with similar purpose are kept together.

NameValueDescription
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.

50

The Horizontal Tabulation Tab key.

65

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

97

The down arrow navigation key.

98

The left arrow navigation key.

99

The right arrow navigation key.

100

The up arrow navigation key.

101

The "End" key.

102

The "Home" key.

103

The "Page Down" key.

104

The "Page Up" key.

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.

OrdinalFieldTypeDescription
timestamp zx/time

Time in nanoseconds when the event was recorded, in the CLOCK_MONOTONIC time base. The timestamp is required on every key event, and users can expect that it will always be present.

type KeyEventType

Type of event.

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.

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
key_meaning KeyMeaning

Meaning of the key.

repeat_sequence uint32

The sequence number of this KeyEvent in the sequence of autorepeated keys.

Unset if this event has been generated in the immediate response to an input from the keyboard driver. If the KeyEvent has been generated through the autorepeat mechanism, this property is set and is incremented by one for each successive generated key event.

lock_state LockState

The lock state in effect at the time of the event.

For example, if CapsLock effect is turned on (pressing 'a' results in the effect 'A'), the corresponding bit in the lock state is set.

NOTE: LockState is different from whether the CapsLock modifier key is actuated or not. LockState.CAPS_LOCK can be active even if the Caps Lock key is not currently actuated.

UNIONS

KeyMeaning strict

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.

OrdinalVariantTypeDescription
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

LockState flexible

Type: uint64

Defined in fuchsia.ui.input3/modifiers.fidl

A bit field of lock states which are currently active.

Lock state reports whether the lock is active for the keys which have a lock state (need to be pressed once to activate, and one more time to deactivate). A set bit denotes active lock state.

For example, when Caps Lock is active, i.e. pressing 'a' produces the effect of 'A' appearing on the screen, the CAPS_LOCK bit will be active.

The bit values in LockState are chosen to correspond to the values in Modifiers, to the extent that this is doable in the long run.

NameValueDescription
1

Applies when the CAPS_LOCK modifier is locked.

Users should bear in mind that the effect of CAPS_LOCK is limited to alphabetic keys (not even alphanumerics) mainly.

For example, pressing a on a US QWERTY keyboard while CAPS_LOCK state is locked results in the key meaning A, just as if the Shift modifier was used. However, pressing [ when CAPS_LOCK is locked gives [, even though Shift+[ gives {.

The position of alphabetic keys may vary depending on the keymap in current use too.

2

Applies when the NUM_LOCK modifier is locked.

4

Applies when the SCROLL_LOCK modifier is locked.

8

Applies when the FUNCTION modifier is locked.

16

Applies when the SYMBOL modifier is locked.

Modifiers flexible

Type: uint64

Defined in fuchsia.ui.input3/modifiers.fidl

Declares all the modifiers supported by Fuchsia's input subsystem.

Modifiers are special keys that modify the purpose or the function of other keys when used in combination with them. In the Modifiers type, a bit is set if the specific modifier key is actuated (held down), irrespective of whether the modifier has an associated lock state or not.

Somewhat specially, and as a convenience for the users, the modifiers that have "left" and "right" flavors have special bit values which can be used if the distinction between sides does not matter.

NameValueDescription
1

Applies when the CAPS_LOCK modifier is actuated.

2

Applies when the NUM_LOCK modifier is actuated.

4

Applies when the SCROLL_LOCK modifier is actuated.

8

Applies when the FUNCTION modifier is actuated.

16

Applies when the SYMBOL modifier is actuated.

32

Applies when the left SHIFT modifier is actuated.

64

Applies when the right SHIFT modifier is actuated.

128

Applies when either LEFT_SHIFT or RIGHT_SHIFT modifier is actuated.

This bit mask a convenience to test for either LEFT_SHIFT or RIGHT_SHIFT.

256

Applies when the left ALT modifier is actuated.

512

Applies when the right ALT modifier is actuated.

1024

Applies when either the left ALT or the right ALT modifier is actuated.

2048

Applies when the ALT_GRAPH modifier is actuated.

4096

Applies when the LEFT_META modifier is actuated.

8192

Applies when the RIGHT_META modifier is actuated.

16384

Applies when either LEFT_META or RIGHT_META modifier is actuated.

32768

Applies when the LEFT_CTRL modifier is actuated.

65536

Applies when the RIGHT_CTRL modifier is actuated.

131072

Applies when either LEFT_CTRL or RIGHT_CTRL modifier is actuated.