// Copyright 2019 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.
@available(added=HEAD)
library fuchsia.ui.input.accessibility;

using fuchsia.math;
using fuchsia.ui.input;
using zx;

/// Possible ways an accessibility listener can process pointer events.
type EventHandling = strict enum {
    /// The listener consumes all the pointer events for (device_id, pointer_id)
    /// until the next UP event.
    CONSUMED = 1;
    /// The listener rejects the remaining pointer events for (device_id,
    /// pointer_id), and observed (past) and expected (future) pointer events
    /// until the next UP event are to be sent for regular input dispatch.
    REJECTED = 2;
};

/// A PointerEvent is a privileged pointer event that has local view and global
/// screen coordinates as well as some metadata about the event type.
type PointerEvent = table {
    /// Time the event was delivered. The time is in nanoseconds and corresponds
    /// to the monotonic time as determined by the zx_clock_get_monotonic syscall.
    1: event_time uint64;
    /// ID of the device that captured this event.
    2: device_id uint32;
    /// ID of the pointer that identifies this event.
    3: pointer_id uint32;
    /// Type of this event, e.g. touch, mouse, etc.
    @deprecated("Use fuchsia.ui.pointer.augment.LocalHit")
    4: type fuchsia.ui.input.PointerEventType;
    /// Phase of this event, e.g. add, down, etc.
    @deprecated("Use fuchsia.ui.pointer.augment.LocalHit")
    5: phase fuchsia.ui.input.PointerEventPhase;
    /// The coordinate of this pointer event in normalized device coordinates.
    /// Normalized device coordinates have dimensions in the range [-1, 1],
    /// with (0, 0) being the center of the device and axes aligned with the
    /// native display.
    6: ndc_point fuchsia.math.PointF;
    /// The viewref koid of the top most view hit for this pointer event.
    /// This field is set to `ZX_KOID_INVALID` when there is no view hit and
    /// `local_point` is undefined.
    7: viewref_koid zx.Koid;
    /// The point of this pointer event in local view coordinates.
    8: local_point fuchsia.math.PointF;
};

/// PointerEventRegistration allows an accessibility service to register a
/// pointer event listener, so that it can intercept pointer events before they
/// reach clients.
@discoverable
closed protocol PointerEventRegistry {
    /// Registers a listener to start receiving incoming pointer events. For
    /// now, only one listener is allowed and the first to register is honored.
    strict Register(resource struct {
        pointer_event_listener client_end:PointerEventListener;
    }) -> (struct {
        success bool;
    });
};

/// A PointerEventListener receives pointer events and decides to consume them
/// or not.
/// TODO(https://fxbug.dev/42111956): Investigate flow control mechanisms for a11y input events.
closed protocol PointerEventListener {
    /// Sends a PointerEvent to an accessibility service. An event is returned
    /// at any time to indicate whether the pointer event stream was consumed /
    /// rejected for a particular stream of pointer events related to a
    /// `device_id` and a `pointer_id`. A stream is a sequence of pointer events
    /// starting with an event with phase DOWN, followed by any number of MOVE,
    /// ending in an UP phase event. The event can arrive while the stream is in
    /// progress or when it has already finished. The resulting
    /// behavior depends on how it was handled, please see EventHandling above.
    strict OnEvent(struct {
        pointer_event PointerEvent;
    });

    strict -> OnStreamHandled(struct {
        device_id uint32;
        pointer_id uint32;
        handled EventHandling;
    });
};