blob: 114397ca92a32a3352190108473e6e22089109ed [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;
/// The possible states of a pointer event. These phases of events in a stream
/// follow a state machine that starts with the `ADD` phase, followed by zero or
/// more `CHANGE` phases, and finally terminates with `REMOVE` or `CANCEL`
/// phase.
/// ```
/// ADD ---> CHANGE* -+-> REMOVE
/// |
/// +-> CANCEL
/// ```
///
/// A finite sequence of pointer events that follows this state machine,
/// starting from the initial state, is called an **interaction**. A closed (or
/// past) interaction is one where it has reached the terminal state; an open
/// (or current) interaction is one where it has not.
///
/// For a given device pointer, a stream of events is observed as a succession
/// of zero or more closed interactions (the past history of user engagement),
/// followed by at most one open interaction (the current user engagement).
///
/// When we need to group pointer events by their interaction, an event carries
/// an **interaction id** that is unique in that pointer stream. This common
/// reference makes it possible to operate on a closed interaction, as well as
/// an open interaction.
///
/// For example, touch events are typically observed as a succession of
/// interactions, as fingers engage and disengage with the display.
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 pointer is no longer available.
CANCEL = 4;
};