public/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.
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;
    float32 radius_minor;
    // 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;
};

union InputEvent {
    PointerEvent pointer;
    KeyboardEvent keyboard;
    FocusEvent focus;
};