third_party/fuchsia-sdk/fidl/fuchsia.ui.input/input_events.fidl

// Copyright 2014 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.input;

enum KeyboardEventPhase {
    /// When key is pressed down.
    PRESSED = 0;
    /// When key is released.
    RELEASED = 1;
    /// This key `PRESSED` is not directed to this input client anymore.
    CANCELLED = 2;
    /// Whether this is an automatically generated key repeat
    REPEAT = 3;
};

/// `KeyboardEvent` represents event generated by a user's interaction with a
/// keyboard.
///
/// Those events are triggered by distinct pressed state changes of the keys.
///
/// The state transitions should be as follows:
/// PRESSED -> (REPEAT ->) RELEASED
/// or
/// PRESSED -> (REPEAT ->) CANCELLED
///
/// The input system will repeat those events automatically when a code_point is
/// available.
///
/// DEPRECATED: Will be removed in favor of `fuchsia.ui.input.KeyEvent`.
struct KeyboardEvent {
    /// Time the event was delivered. The time is in nanoseconds and corresponds
    /// to the uptime of the machine.
    uint64 event_time;

    uint32 device_id;

    KeyboardEventPhase phase;

    /// Keyboard HID Usage
    /// See https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
    uint32 hid_usage;

    /// The unicode code point represented by this key event, if any.
    /// Dead keys are represented as Unicode combining characters.
    ///
    /// If there is no unicode code point, this value is zero.
    uint32 code_point;

    /// Key modifiers as defined by the different kModifier constants such as
    /// `kModifierCapsLock` currently pressed
    uint32 modifiers;
};

enum PointerEventType {
    /// A touch-based pointer device.
    TOUCH = 0;

    /// A pointer device with a stylus.
    STYLUS = 1;

    /// A pointer device with a stylus that has been inverted.
    INVERTED_STYLUS = 2;

    /// A pointer device without a stylus.
    MOUSE = 3;
};

enum PointerEventPhase {
    /// The device has started tracking the pointer.
    ///
    /// For example, the pointer might be hovering above the device, having not yet
    /// made contact with the surface of the device.
    ADD = 0;

    /// The pointer has moved with respect to the device while not in contact with
    /// the device.
    HOVER = 1;

    /// The pointer has made contact with the device.
    ///
    /// For `MOUSE` devices, this is triggered when the primary button is pressed
    /// down to emulate a touch on the screen.
    DOWN = 2;

    /// The pointer has moved with respect to the device while in contact with the
    /// device.
    MOVE = 3;

    /// The pointer has stopped making contact with the device.
    ///
    /// For `MOUSE` devices, this is triggered when the primary button is
    /// released.
    UP = 4;

    /// The device is no longer tracking the pointer.
    ///
    /// For example, the pointer might have drifted out of the device's hover
    /// detection range or might have been disconnected from the system entirely.
    REMOVE = 5;

    /// The input from the pointer is no longer directed towards this receiver.
    CANCEL = 6;

    // TODO: add phases to indicate button press / release
};

/// Pointers represent raw data about the user's interaction with the screen.
///
/// The state transitions should be as follows:
/// ADD (-> HOVER) -> DOWN -> MOVE -> UP (-> HOVER) -> REMOVE
///
/// At any point after the initial ADD, a transition to CANCEL is also possible.
struct PointerEvent {
    /// Time the event was delivered. The time is in nanoseconds and corresponds
    /// to the uptime of the machine.
    uint64 event_time;

    uint32 device_id;

    uint32 pointer_id;

    PointerEventType type;

    PointerEventPhase phase;

    /// `x` and `y` are in the coordinate system of the View.
    float32 x;
    float32 y;

    // TODO(jpoichet) float32 vx;
    // TODO(jpoichet) float32 vy;

    float32 radius_major = 0.0; // DO NOT USE
    float32 radius_minor = 0.0; // DO NOT USE
    // TODO(jpoichet) float32 orientation;
    // TODO(jpoichet) float32 tilt;
    // TODO(jpoichet) float32 altitude;
    // TODO(jpichet) float32 amplitude;

    /// Currently pressed buttons as defined the kButton constants such as
    /// `kMousePrimaryButton`
    uint32 buttons;
};

struct FocusEvent {
    /// Time the event was delivered. The time is in nanoseconds and corresponds
    /// to the uptime of the machine.
    uint64 event_time;

    /// Whether the view has gained input focused or not.
    bool focused;
};

table MediaButtonsEvent {
    1: int8 volume;
    2: bool mic_mute;
    3: bool pause;
};

/// This union does not include MediaButtonsEvent because it's processed differently.
union InputEvent {
    1: PointerEvent pointer;
    2: KeyboardEvent keyboard;
    3: FocusEvent focus;
};