| // 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; |
| |
| const uint32 MAX_EVENT = 128; |
| |
| /// A method for a client to receive 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 as a gesture; a swipe 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. |
| protocol EventProvider { |
| /// A method for a client to receive 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. An unresponsive client may be categorized as |
| /// "App Not Responding" and targeted for channel closure. |
| /// |
| /// Responses. The gesture disambiguation scheme relies on a response per |
| /// dispatched event. Responses for *previous* events are fed to the server |
| /// on the *next* call of |Watch| [1]. Each element in the |responses| |
| /// vector is interprted as the pairwise response to the event in the |
| /// previous |events| vector; the vector lengths must match. |
| /// |
| /// Initial response. The first call to |Watch| must be an empty vector. |
| /// |
| /// Event times. The timestamps on each event in the event vector are *not* |
| /// guaranteed monotonic; pointer 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 an |Event| carries |ViewParameters|, these |
| /// parameters apply to successive |PointerSample|s until the next |
| /// |ViewParameters|. |
| /// |
| /// [1] The hanging get pattern enables straightforward API evolution, but |
| /// unfortunately does not admit an idiomatic matching of response to event. |
| Watch(vector<Response>:MAX_EVENT responses) -> (vector<Event>:MAX_EVENT events); |
| }; |