// 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;
};