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;

type KeyboardEventPhase = flexible enum {
    /// 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`.
type KeyboardEvent = struct {
    /// Time the event was delivered. The time is in nanoseconds and corresponds
    /// to the monotonic time as determined by the zx_clock_get_monotonic syscall.
    event_time uint64;

    device_id uint32;

    phase KeyboardEventPhase;

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

    /// 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.
    code_point uint32;

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

type PointerEventType = strict enum {
    /// 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;
};

type PointerEventPhase = strict enum {
    /// 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.
type PointerEvent = struct {
    /// Time the event was delivered. The time is in nanoseconds and corresponds
    /// to the monotonic time as determined by the zx_clock_get_monotonic syscall.
    event_time uint64;

    device_id uint32;

    pointer_id uint32;

    type PointerEventType;

    phase PointerEventPhase;

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

    // TODO(jpoichet) float32 vx;
    // TODO(jpoichet) float32 vy;
    @allow_deprecated_struct_defaults
    radius_major float32 = 0.0; // DO NOT USE
    @allow_deprecated_struct_defaults
    radius_minor float32 = 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`
    buttons uint32;
};

type FocusEvent = struct {
    /// Time the event was delivered. The time is in nanoseconds and corresponds
    /// to the monotonic time as determined by the zx_clock_get_monotonic syscall.
    event_time uint64;

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

type MediaButtonsEvent = table {
    1: volume int8;
    2: mic_mute bool;
    3: pause bool;
    4: camera_disable bool;
};

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