// 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.
enum KeyEventType {
    /// Key is pressed down.
    PRESSED = 1;

    /// Key is released.
    RELEASED = 2;

    /// 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.
    SYNC = 3;

    /// 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.
    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:
/// https://www.w3.org/TR/uievents-key/#named-key-attribute-values
flexible enum NonPrintableKey : uint32 {
    // Whitespace keys
    // 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 = 0x00000031;

    /// The Horizontal Tabulation Tab key.
    TAB = 0x00000032;

    // Editing keys
    // Reserved range: 0x00000041 - 0x00000060

    /// Delete the character immediately preceding the cursor (i.e. the
    /// character to the left for LTR languages).
    BACKSPACE = 0x00000041;
};

/// 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.
strict union KeyMeaning {
    /// The Unicode codepoint representing character typed, if any.
    1: uint32 codepoint;

    /// The meaning of the key for key events with no corresponding symbol.
    2: NonPrintableKey non_printable_key;
};

/// 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. 
table KeyEvent {
    /// Time in nanoseconds when the event was recorded, in the `CLOCK_MONOTONIC` time base.
    1: zx.time timestamp;

    /// Type of event.
    2: KeyEventType type;

    /// 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: fuchsia.input.Key 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: KeyMeaning key_meaning;
};