blob: 1e3dd8e7e7eb3c6eaea3af8edd436bf72b2d4108 [file] [log] [blame]
// 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.pointer;
using fuchsia.input.report as device;
using zx;
const MOUSE_MAX_EVENT uint32 = 128;
/// A method for a client to receive mouse pointer events.
///
/// The position of a pointer event is defined in the context of a viewport,
/// situated in the view. The dimensions of the view and viewport, and their
/// spatial relationship (defined with a transform matrix), are supplied
/// synchronously in a |ViewParameter| table. A view may retrieve a pointer's
/// position in its local coordinate system by applying the viewport-to-view
/// transform matrix.
///
/// The viewport is embedded in an independent and stable coordinate system,
/// suitable for interpreting pointer events in a scale-independent manner;
/// mouse movement will be observed at a constant scale, even under effects such
/// as magnification or panning. However, other effects, such as enlargening the
/// view's clip bounds, may trigger a change in the viewport extents.
closed protocol MouseSource {
/// A method for a client to receive mouse pointer events.
///
/// This call is formulated as a "hanging get" pattern: the client asks for
/// a set of recent events, and receives them via the callback. This
/// pull-based approach ensures that clients consume events at their own
/// pace; events don't clog up the channel in an unbounded manner.
///
/// Flow control. The caller is allowed at most one in-flight |Watch| call
/// at a time; it is a logical error to have concurrent calls to |Watch|.
/// Non-compliance results in channel closure.
///
/// Client pacing. The server will dispatch events to the caller on a FIFO,
/// lossless, best-effort basis, but the caller must allocate enough time to
/// keep up with new events.
///
/// Event times. The timestamps on each event in the event vector are *not*
/// guaranteed monotonic; events from different devices may be injected into
/// Scenic at different times. Generally, events from a single device are
/// expected to have monotonically increasing timestamps.
///
/// View parameters. Occasionally, changes in view or viewport require
/// notifying the client. If a |MouseEvent| carries |ViewParameters|, these
/// parameters apply to successive |MousePointerSample|s until the next
/// |ViewParameters|.
strict Watch() -> (struct {
events vector<MouseEvent>:MOUSE_MAX_EVENT;
});
};
/// The self-sufficient, self-consistent collection of pointer-related data,
/// sent from server to client.
type MouseEvent = table {
/// The time this event was observed.
/// Required.
1: timestamp zx.Time;
/// The parameters of the associated view and viewport, sufficient to
/// correctly interpret the position, orientation, magnitude, and
/// inter-event distance of pointer events dispatched to a view.
/// - It is issued on connection and on change.
2: view_parameters ViewParameters;
/// A description of the mouse device, sufficient to correctly interpret
/// the capabilities and usage intent of the device.
/// - It is issued once per device.
3: device_info MouseDeviceInfo;
/// A description of each sampled data point in a mouse event stream.
///
/// Issuance policy. There are two dispatch modes, "hover" and "latched".
/// Hover mode is default, and the stream is dispatched in fragments to the
/// visible client that each mouse event hovers above. Latched mode directs
/// the stream to a single client (regardless of view boundary) until
/// unlatched. Latched mode is typically toggled when the user presses the
/// primary mouse button, but is ultimately a product-specific policy.
4: pointer_sample MousePointerSample;
/// The signal for view entry/exit in hover mode.
/// - It is issued on hover entry into a view, and hover exit from a view.
5: stream_info MouseEventStreamInfo;
/// An identifier to correlate this event's send/receive occurrence across
/// component boundaries or abstraction layers.
6: trace_flow_id uint64;
};
/// The valid values of relative motion for a mouse device.
/// - The ranges are placed in (x, y) order.
alias RelativeMotionRange = array<device.Axis, 2>;
/// Information about a device that issues a mouse event stream.
type MouseDeviceInfo = table {
/// An identifier for the mouse device that issues a mouse event stream.
/// Required.
1: id uint32;
/// Range of relative movement values issued by the device.
5: relative_motion_range RelativeMotionRange;
/// Range of vertical scroll values issued by the device.
2: scroll_v_range device.Axis;
/// Range of horizontal scroll values issued by the device.
3: scroll_h_range device.Axis;
/// Button identifiers issued by the device, in priority order.
4: buttons vector<uint8>:device.MOUSE_MAX_NUM_BUTTONS;
};
/// The relative motion performed by a mouse device.
/// - The valid range is defined in [`MouseDeviceInfo.RelativeMotionRange`].
/// - The values are placed in (x, y) order.
alias RelativeMotion = array<float32, 2>;
/// A description of each sampled data point in a mouse event stream.
///
/// `MousePointerSample` may bundle multiple state changes into one event.
/// For example, if user scrolls mouse wheel and presses the left buttton
/// down at the same time, client may receive scroll and button state changes
/// together in 1 event, or receive button change and scroll change in
/// separate events.
type MousePointerSample = table {
/// An identifier for the mouse device that issues a mouse event stream.
/// Required.
1: device_id uint32;
/// The position of this event, in the viewport's coordinate system.
/// Required.
2: position_in_viewport Point2;
/// The relative movement performed, independent of the viewport's
/// coordinate system.
6: relative_motion RelativeMotion;
/// Relative vertical scrolling displacement by detent.
3: scroll_v int64;
/// Relative horizontal scrolling displacement by detent.
4: scroll_h int64;
/// Recommended vertical scrolling displacement by physical pixel, it is
/// computed with accelerator, detent / mm to pixel ratio, etc.
7: scroll_v_physical_pixel float64;
/// Recommended horizontal scrolling displacement by physical pixel, it
/// is computed with accelerator, detent / mm to pixel ratio, etc.
8: 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.
9: is_precision_scroll bool;
/// Identifiers of currently pressed buttons.
5: pressed_buttons vector<uint8>:device.MOUSE_MAX_NUM_BUTTONS;
};
/// The status of a mouse event stream, sent from server to client.
///
/// Invariant: a client's mouse events are bracketed by
/// [`MouseViewStatus.ENTERED`] and [`MouseViewStatus.EXITED`].
///
type MouseEventStreamInfo = struct {
/// An identifier for the mouse device that issues a mouse event stream.
device_id uint32;
/// The mouse event stream's enter/exit status, sent from server to client.
status MouseViewStatus;
};
/// A description of mouse event stream's relationship to this view.
type MouseViewStatus = strict enum {
/// The stream is directed towards this view.
ENTERED = 1;
/// The stream is directed away from this view.
EXITED = 2;
};