sdk/fidl/fuchsia.ui.pointerinjector/event.fidl

// 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.pointerinjector;

using fuchsia.input.report;
using zx;

/// The possible states of a pointer event stream's state machine.
///
/// A typical pointer will move through this state machine:
/// ADD - CHANGE* - REMOVE
type EventPhase = strict enum {
    /// The device has started tracking the pointer.
    ADD = 1;

    /// The device has reported an update to the pointer state.
    CHANGE = 2;

    /// The device has stopped tracking the pointer.
    REMOVE = 3;

    /// The event stream is no longer available.
    CANCEL = 4;
};

/// The relative motion performed by a mouse device.
/// - The valid range is defined in [`Config.RelativeMotionRange`].
/// - The values are placed in (x, y) order.
alias RelativeMotion = array<float32, 2>;

/// A description of each sampled data point for a pointer device.
type PointerSample = table {
    /// An identifier of the pointer that issued this event.
    /// It is unique only to a specific pointer device.
    1: pointer_id uint32;

    /// The state of this event in the pointer event stream's state machine.
    2: phase EventPhase;

    /// The position of this event, in the viewport's coordinate system.
    3: position_in_viewport Point2;

    /// The movement of a mouse, independent of the viewport's coordinate
    /// system.
    7: relative_motion RelativeMotion;

    /// Relative vertical scrolling displacement by detent.
    4: scroll_v int64;

    /// Relative horizontal scrolling displacement by detent.
    5: scroll_h int64;

    /// Recommended vertical scrolling displacement by physical pixel, it is
    /// computed with accelerator, detent / mm to pixel ratio, etc.
    8: scroll_v_physical_pixel float64;

    /// Recommended horizontal scrolling displacement by physical pixel, it
    /// is computed with accelerator, detent / mm to pixel ratio, etc.
    9: scroll_h_physical_pixel float64;

    /// Indicated if the scroll event is from a precision scroll device (HI_RES
    /// mouse or touchpad). Clients may want to play interpolation animations
    /// on non precision scroll device for smooth scrolling.
    10: is_precision_scroll bool;

    /// Identifiers of currently pressed buttons.
    6: pressed_buttons vector<uint8>:fuchsia.input.report.MOUSE_MAX_NUM_BUTTONS;
};

/// A selection of FIFO data sent over the channel.
/// Each data may have a different issuance policy.
type Data = flexible union {
    /// The parameters of the viewport, sufficient for a client to correctly
    /// interpret the position and scale of pointer events dispatched to it.
    /// - It is issued on every change to the viewport.
    1: viewport Viewport;

    /// A description of each sampled data point in a pointer event stream.
    /// - It is issued on every sample in the pointer event stream.
    2: pointer_sample PointerSample;
};

// A per-device collection of pointer-related data, sent from server to client.
type Event = table {
    /// The time when this event was observed.
    ///
    /// Required.
    1: timestamp zx.Time;

    /// The event's data.
    ///
    /// Required.
    2: data Data;

    /// An identifier to correlate this event's send/receive occurrence across
    /// component boundaries or abstraction layers.
    3: trace_flow_id uint64;
};