| // Copyright 2020 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.ui.input3; |
| |
| using fuchsia.input; |
| using zx; |
| |
| /// Type of the keyboard key input event. |
| /// |
| /// We do not expect new values to be added into this enum. |
| type KeyEventType = strict enum { |
| /// 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. |
| PRESSED = 1; |
| |
| /// 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. |
| RELEASED = 2; |
| |
| /// 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. |
| SYNC = 3; |
| |
| /// 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. |
| CANCEL = 4; |
| }; |
| |
| /// 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][1]. |
| /// |
| /// ## 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][1], multiplied |
| /// by 0x1000. |
| /// |
| /// For example, the keys from section [3.10 Multimedia keys][2] 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 |
| /// |
| /// [1]: https://www.w3.org/TR/uievents-key/#named-key-attribute-values |
| /// [2]: https://www.w3.org/TR/uievents-key/#keys-multimedia |
| type NonPrintableKey = flexible enum : uint32 { |
| // Special keys |
| // https://www.w3.org/TR/uievents-key/#keys-special |
| // |
| // Reserved range: 0x00-0x10 |
| |
| /// This key value is used when an implementation is unable to identify |
| /// another key value, due to either hardware, platform, or software |
| /// constraints. |
| @available(added=9) |
| @unknown |
| UNIDENTIFIED = 0x00; |
| |
| // Modifier keys |
| // https://www.w3.org/TR/uievents-key/#keys-modifier |
| // |
| // Reserved range: 0x11 - 0x30 |
| |
| /// 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. |
| @available(added=9) |
| ALT = 0x11; |
| |
| /// 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]. |
| /// |
| /// [ISO9995-1]: http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=51645 |
| @available(added=9) |
| ALT_GRAPH = 0x12; |
| |
| /// The Caps Lock (Capital) key. |
| /// |
| /// Toggle capital character lock function for interpreting subsequent keyboard input event. |
| @available(added=9) |
| CAPS_LOCK = 0x13; |
| |
| /// The Control or Ctrl key, to enable control modifier function for interpreting concurrent or |
| /// subsequent keyboard input. |
| @available(added=9) |
| CONTROL = 0x14; |
| |
| /// 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. |
| @available(added=9) |
| FN = 0x15; |
| |
| /// 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. |
| @available(added=9) |
| FN_LOCK = 0x16; |
| |
| /// 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. |
| @available(added=9) |
| META = 0x17; |
| |
| /// The NumLock or Number Lock key, to toggle numpad mode function for interpreting subsequent |
| /// keyboard input. |
| @available(added=9) |
| NUM_LOCK = 0x18; |
| |
| /// The Scroll Lock key, to toggle between scrolling and cursor movement modes. |
| @available(added=9) |
| SCROLL_LOCK = 0x19; |
| |
| /// The Shift key, to enable shift modifier function for interpreting concurrent or subsequent |
| /// keyboard input. |
| @available(added=9) |
| SHIFT = 0x1a; |
| |
| /// The Symbol modifier key (used on some virtual keyboards). |
| @available(added=9) |
| SYMBOL = 0x1b; |
| |
| /// The Symbol Lock key. |
| @available(added=9) |
| SYMBOL_LOCK = 0x1c; |
| |
| /// The Hyper key. A legacy modifier. |
| @available(added=9) |
| HYPER = 0x1d; |
| |
| /// The Super key. A legacy modifier. |
| @available(added=9) |
| SUPER = 0x1e; |
| |
| // Whitespace keys |
| // https://www.w3.org/TR/uievents-key/#keys-whitespace |
| // |
| // Reserved range: 0x00000031 - 0x00000040 |
| |
| /// The Enter or ↵ key, to activate current selection or accept current input. |
| /// This key value is also used for the Return (Macintosh numpad) key. |
| ENTER = 0x31; |
| |
| /// The Horizontal Tabulation Tab key. |
| TAB = 0x32; |
| |
| // Editing keys |
| // Reserved range: 0x00000041 - 0x00000060 |
| |
| /// Delete the character immediately preceding the cursor (i.e. the |
| /// character to the left for LTR languages). |
| BACKSPACE = 0x41; |
| |
| // Navigation keys |
| // https://www.w3.org/TR/uievents-key/#keys-navigation |
| // |
| // Range reserved for navigation keys: 0x61-0x80. |
| // Arrow keys are named for consistency with keys in `fuchsia.ui.input`, |
| // althought W3C name them ArrowUp for example, and not Up. |
| |
| /// The down arrow navigation key. |
| DOWN = 0x61; |
| |
| /// The left arrow navigation key. |
| LEFT = 0x62; |
| |
| /// The right arrow navigation key. |
| RIGHT = 0x63; |
| |
| /// The up arrow navigation key. |
| UP = 0x64; |
| |
| /// The "End" key. |
| END = 0x65; |
| |
| /// The "Home" key. |
| HOME = 0x66; |
| |
| /// The "Page Down" key. |
| PAGE_DOWN = 0x67; |
| |
| /// The "Page Up" key. |
| PAGE_UP = 0x68; |
| |
| // UI keys |
| // https://www.w3.org/TR/uievents-key/#keys-ui |
| // Reserved range: 0x6000-0x6FFF |
| |
| /// The `Escape` or `Esc` key. |
| @available(added=10) |
| ESCAPE = 0x6005; |
| |
| /// The Select key. Used to select the window of a task to focus on. |
| @available(added=10) |
| SELECT = 0x600C; |
| |
| // Device keys |
| // https://www.w3.org/TR/uievents-key/#keys-device |
| // Reserved range: 0x7000-0x7FFF |
| |
| /// The Brightness Down key. Typically controls the display brightness. |
| @available(added=10) |
| BRIGHTNESS_DOWN = 0x7000; |
| |
| /// The Brightness Up key. Typically controls the display brightness. |
| @available(added=10) |
| BRIGHTNESS_UP = 0x7001; |
| |
| // General-purpose function keys. |
| // https://www.w3.org/TR/uievents-key/#keys-function |
| // Reserved range: 0x9000-0x9FFF |
| |
| /// The F1 key, a general purpose function key, as index 1. |
| @available(added=9) |
| F1 = 0x9001; |
| |
| /// The F2 key, a general purpose function key, as index 2. |
| @available(added=9) |
| F2 = 0x9002; |
| |
| /// The F3 key, a general purpose function key, as index 3. |
| @available(added=9) |
| F3 = 0x9003; |
| |
| /// The F4 key, a general purpose function key, as index 4. |
| @available(added=9) |
| F4 = 0x9004; |
| |
| /// The F5 key, a general purpose function key, as index 5. |
| @available(added=9) |
| F5 = 0x9005; |
| |
| /// The F6 key, a general purpose function key, as index 6. |
| @available(added=9) |
| F6 = 0x9006; |
| |
| /// The F7 key, a general purpose function key, as index 7. |
| @available(added=9) |
| F7 = 0x9007; |
| |
| /// The F8 key, a general purpose function key, as index 8. |
| @available(added=9) |
| F8 = 0x9008; |
| |
| /// The F9 key, a general purpose function key, as index 9. |
| @available(added=9) |
| F9 = 0x9009; |
| |
| /// The F10 key, a general purpose function key, as index 10. |
| @available(added=9) |
| F10 = 0x900a; |
| |
| /// The F11 key, a general purpose function key, as index 11. |
| @available(added=9) |
| F11 = 0x900b; |
| |
| /// The F1 key, a general purpose function key, as index 12. |
| @available(added=9) |
| F12 = 0x900c; |
| |
| /// General purpose virtual function key, as index 1. |
| @available(added=9) |
| SOFT_1 = 0x9011; |
| |
| /// General purpose virtual function key, as index 2. |
| @available(added=9) |
| SOFT_2 = 0x9012; |
| |
| /// General purpose virtual function key, as index 3. |
| @available(added=9) |
| SOFT_3 = 0x9013; |
| |
| /// General purpose virtual function key, as index 4. |
| @available(added=9) |
| SOFT_4 = 0x9014; |
| |
| // Multimedia keys |
| // https://www.w3.org/TR/uievents-key/#keys-multimedia |
| // Reserved range: 0xA000-0xAFFF |
| |
| /// Pause the currently playing media. |
| /// |
| /// NOTE: Media controller devices should use this value rather than |
| /// `PAUSE` for their pause keys. |
| @available(added=10) |
| MEDIA_PLAY_PAUSE = 0xA008; |
| |
| // Audio keys |
| // https://www.w3.org/TR/uievents-key/#keys-audio |
| // Reserved range: 0xC000-0xCFFF |
| |
| /// Decrease audio volume. |
| @available(added=10) |
| AUDIO_VOLUME_DOWN = 0xC00A; |
| |
| /// Increase audio volume. |
| @available(added=10) |
| AUDIO_VOLUME_UP = 0xC00B; |
| |
| /// Toggle between muted state and prior volume level. |
| @available(added=10) |
| AUDIO_VOLUME_MUTE = 0xC00C; |
| |
| // Browser keys |
| // https://www.w3.org/TR/uievents-key/#keys-browser |
| // Reserved range: 0xF000-0xFFFF |
| |
| /// Navigate to previous content or page in current history. |
| @available(added=10) |
| BROWSER_BACK = 0xF000; |
| |
| /// Open the list of browser favorites. |
| @available(added=10) |
| BROWSER_FAVORITES = 0xF001; |
| |
| /// Navigate to next content or page in current history. |
| @available(added=10) |
| BROWSER_FORWARD = 0xF002; |
| |
| /// Go to the user’s preferred home page. |
| @available(added=10) |
| BROWSER_HOME = 0xF003; |
| |
| /// Refresh the current page or content. |
| @available(added=10) |
| BROWSER_REFRESH = 0xF004; |
| |
| /// Call up the user’s preferred search page. |
| @available(added=10) |
| BROWSER_SEARCH = 0xF005; |
| |
| @available(added=10) |
| BROWSER_STOP = 0xF006; |
| |
| // Media controller keys |
| // https://www.w3.org/TR/uievents-key/#keys-media-controller |
| // Reserved range: 0x12000-0x12FFF |
| |
| /// Toggle between full-screen and scaled content, or alter magnification level. |
| @available(added=10) |
| ZOOM_TOGGLE = 0x12047; |
| }; |
| |
| /// 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. |
| type KeyMeaning = strict union { |
| /// 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. |
| 1: codepoint uint32; |
| |
| /// The meaning of the key for key events with no corresponding symbol. |
| 2: non_printable_key NonPrintableKey; |
| }; |
| |
| /// 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. |
| type KeyEvent = table { |
| /// 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. |
| 1: timestamp zx.Time; |
| |
| /// Type of event. |
| 2: type KeyEventType; |
| |
| /// 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. |
| 3: key fuchsia.input.Key; |
| |
| /// 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 |
| 4: modifiers Modifiers; |
| |
| /// Meaning of the key. |
| 5: key_meaning KeyMeaning; |
| |
| /// 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. |
| 6: repeat_sequence uint32; |
| |
| /// 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. |
| 7: lock_state LockState; |
| }; |