fuchsia.ui.input3

Physical keyboard events

Fuchsia's Keyboard service provides a mechanism for delivering physical keyboard events to all interested clients.

Rendered Docs

Overview

Key events are delivered only to the components subscribed via Keyboard FIDL protocol. Components interested in the service, should list FIDL service in the components manifest, and it will be injected when the component is started.

Typical use-cases:

  • TAB navigation between form fields.
  • Arrow keys navigation in menus, lists.
  • Pressing “f” to open a File from a menu.
  • Closing popups on ESC.
  • WASD navigation in games.

Media buttons, shortcuts, and text entry (IME) related events are delivered separately via specialized interfaces.

Key events are only delivered to components in the Scenic focus chain. Only focused components receive key events.

Key events are delivered in root to leaf order - i.e. parent components first.

Parent components have the ability to block further event propagation via KeyboardListener.OnKeyEvent by returning KeyEventStatus.Handled to prevent event’s propagation.

Clients are notified of keys being pressed or released via Pressed and Released event types.

Clients are notified of keys pressed or released while client wasn't available (e.g. not focused, or not started) via Sync and Cancel event types. Those events will delivered for relevant events only, e.g. keys pressed and held while client was not available.

Example

use fidl_fuchsia_ui_input3 as ui_input;

let keyboard = connect_to_protocol::<ui_input::KeyboardMarker>()
    .context("Failed to connect to Keyboard service")?;

let (listener_client_end, mut listener_stream) =
    create_request_stream::<ui_input::KeyboardListenerMarker>()?;

keyboard.add_listener(view_ref, listener_client_end).await.expect("add_listener");

match listener_stream.next().await {
    Some(Ok(ui_input::KeyboardListenerRequest::OnKeyEvent { event, responder, .. })) => {
        assert_eq!(event.key, Some(fuchsia_input::Key::A));
        responder.send(ui_input::Status::Handled).expect("response from key listener")
    },
}
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 may be offered to other clients of other related APIs.

Clients that do not acknowledge their events will eventually be disconnected.

Notification is only dispatched to a view that has focus. No other views, including parents or children, will get notified specifically via OnKeyEvent.

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.

We do not expect new values to be added to this enum.

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.

We do not expect new values to be added into this enum.

NameValueDescription
1

Key is actuated.

Receiving this event type means that a key has been actuated at the timestamp when the event is received, and while the event recipient is focused.

For example, if the key is a keyboard key, then it was just pressed.

2

Key is no longer actuated.

Receiving this event type means that a key has been de-actuated at the timestamp when the event is received, and while the event recipient is focused.

For example, if the key is a keyboard key, then it was just released.

3

Key was actuated while the client wasn't able to receive it, and is still actuated now that the client is able to receive key events.

This may happen in a few ways:

- A new device was connected while its key was actuated.
- The key was actuated while the event recipient did not
  have focus.

Therefore, this is not a "regular" key actuation. It reports now that the key has been actuated in the unknown past. Some event recipients may therefore decide that this is not an actionable key event, while some others may decide that it is.

For example, recipients that trigger some user action may decide to ignore SYNC events, to avoid spurious actions. In contrast, recipients that keep track of the keyboard state may want to consider a SYNC event as a signal to update the key's state to actuated.

4

Key may have been actuated, but its actuation has become invalid due to an event other than a key de-actuation.

This may happen in a few ways:

- A device was disconnected while its key was actuated.
- The event recipient just lost focus.

Therefore, this is not a "regular" key de-actuation. It reports the key is no longer validly actuated due to an event other than a key release. Some event recipients may therefore decide that this is not an actionable key event, while some others may decide that it is.

For example, recipients which trigger some user action may decide to ignore CANCEL events, to avoid spurious actions. In contrast, recipients that keep track of the keyboard state may want to consider a CANCEL event as a signal to update the key's state to being de-actuated.

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.

API version 9 and onwards

Starting from API version 9, the enum value space is subdivided based on the subsection numbers of the section Named Key Attribute Values, multiplied by 0x1000.

For example, the keys from section 3.10 Multimedia keys will be located at 0xa000-0xafff. The values and reservations that were present in this enum prior to the introduction of the convention have not been moved, and values that go logically into pre-existing sections have been inserted into their logical place using the prior convention (see below). This allows us to extract the section ranges if this is for some reason useful to the application.

Prior to API version 9

The space of the nonprintable keys is subdivided roughly to correspond to the subsections of Section 3 of the document Named Key Attribute Values. 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.

Reserved ranges

The space of possible values for [NonPrintableKey] is subdivided into a number of ranges, with the intention that the enum values are placed in the appropriate range when added.

  • Special keys: 0x00-0x10
  • Modifier keys: 0x11-0x30
  • Whitespace keys: 0x31-0x40
  • Navigation keys: 0x61-0x80
  • General-purpose function keys: 0x9000-0x9FFF

NameValueDescription
0

This key value is used when an implementation is unable to identify another key value, due to either hardware, platform, or software constraints.

Added: 9
17

The Alt (Alternative) key.

This key enables the alternate modifier function for interpreting concurrent or subsequent keyboard input. This key value is also used for the Apple Option key.

Added: 9
18

The Alternate Graphics (AltGr or AltGraph).

This key is used enable the ISO Level 3 shift modifier (the standard Shift key is the level 2 modifier). See ISO9995-1.

Added: 9
19

The Caps Lock (Capital) key.

Toggle capital character lock function for interpreting subsequent keyboard input event.

Added: 9
20

The Control or Ctrl key, to enable control modifier function for interpreting concurrent or subsequent keyboard input.

Added: 9
21

The Function switch Fn key.

Activating this key simultaneously with another key changes that key’s value to an alternate character or function. This key is often handled directly in the keyboard hardware and does not usually generate key events.

Added: 9
22

The Function-Lock (FnLock or F-Lock) key.

Activating this key switches the mode of the keyboard to changes some keys' values to an alternate character or function. This key is often handled directly in the keyboard hardware and does not usually generate key events.

Added: 9
23

The Meta key, to enable meta modifier function for interpreting concurrent or subsequent keyboard input.

This key value is used for the Windows Logo key and the Apple Command or ⌘ key.

Added: 9
24

The NumLock or Number Lock key, to toggle numpad mode function for interpreting subsequent keyboard input.

Added: 9
25

The Scroll Lock key, to toggle between scrolling and cursor movement modes.

Added: 9
26

The Shift key, to enable shift modifier function for interpreting concurrent or subsequent keyboard input.

Added: 9
27

The Symbol modifier key (used on some virtual keyboards).

Added: 9
28

The Symbol Lock key.

Added: 9
29

The Hyper key. A legacy modifier.

Added: 9
30

The Super key. A legacy modifier.

Added: 9
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.

24581

The Escape or Esc key.

Added: 10
24588

The Select key. Used to select the window of a task to focus on.

Added: 10
28672

The Brightness Down key. Typically controls the display brightness.

Added: 10
28673

The Brightness Up key. Typically controls the display brightness.

Added: 10
36865

The F1 key, a general purpose function key, as index 1.

Added: 9
36866

The F2 key, a general purpose function key, as index 2.

Added: 9
36867

The F3 key, a general purpose function key, as index 3.

Added: 9
36868

The F4 key, a general purpose function key, as index 4.

Added: 9
36869

The F5 key, a general purpose function key, as index 5.

Added: 9
36870

The F6 key, a general purpose function key, as index 6.

Added: 9
36871

The F7 key, a general purpose function key, as index 7.

Added: 9
36872

The F8 key, a general purpose function key, as index 8.

Added: 9
36873

The F9 key, a general purpose function key, as index 9.

Added: 9
36874

The F10 key, a general purpose function key, as index 10.

Added: 9
36875

The F11 key, a general purpose function key, as index 11.

Added: 9
36876

The F1 key, a general purpose function key, as index 12.

Added: 9
36881

General purpose virtual function key, as index 1.

Added: 9
36882

General purpose virtual function key, as index 2.

Added: 9
36883

General purpose virtual function key, as index 3.

Added: 9
36884

General purpose virtual function key, as index 4.

Added: 9
40968

Pause the currently playing media.

NOTE: Media controller devices should use this value rather than PAUSE for their pause keys.

Added: 10
49162

Decrease audio volume.

Added: 10
49163

Increase audio volume.

Added: 10
49164

Toggle between muted state and prior volume level.

Added: 10
61440

Navigate to previous content or page in current history.

Added: 10
61441

Open the list of browser favorites.

Added: 10
61442

Navigate to next content or page in current history.

Added: 10
61443

Go to the user’s preferred home page.

Added: 10
61444

Refresh the current page or content.

Added: 10
61446
Added: 10
73799

Toggle between full-screen and scaled content, or alter magnification level.

Added: 10

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.

NOTE: If you want to examine the lock state (such as whether Caps Lock needs to turn all letters into uppercase),you want [LockState] instead.

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.