sdk/fidl/fuchsia.ui.test.input/touch.fidl

// Copyright 2022 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.test.input;

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

@available(added=12)
const MAX_FINGERS uint8 = 10;

/// A tool to inject touch events into Input Pipeline.
///
/// Please extend as necessary.
closed protocol TouchScreen {
    /// Simulates a tap at the requested location.
    strict SimulateTap(table {
        /// Location of the tap event, in the coordinate units specified during
        /// registration.
        1: tap_location fuchsia.math.Vec;
    }) -> ();

    /// Simulates multi finger tap at the requested locations.
    @available(added=12)
    strict SimulateMultiTap(table {
        /// Locations of the tap event, in the coordinate units specified during
        /// registration.
        1: tap_locations vector<fuchsia.math.Vec>:MAX_FINGERS;
    }) -> ();

    /// Simulates a swipe that starts at `start_location` and ends at `end_location`,
    /// with a total number of move events equal to `move_event_count`.
    ///
    /// The generated pointer event stream will be:
    ///
    /// DOWN + CHANGE_1 + ... + CHANGE_n + UP, where n == `move_event_count`
    ///
    /// Events are injected with no explicit delay in between; in other words, the
    /// observed delay between successive events will be approximately equal to the
    /// time required to inject a single event.
    strict SimulateSwipe(table {
        /// Starting location of the swipe, in the coordinate units specified during
        /// registration.
        1: start_location fuchsia.math.Vec;

        /// End location of the swipe, in the coordinate units specified during
        /// registration.
        2: end_location fuchsia.math.Vec;

        /// Number of move events in the swipe.
        3: move_event_count uint32;
    }) -> ();


    /// Simulates a multi fingers linear gesture that starts at `start_locations`
    /// and ends at `end_locations`, with a total number of move events equal to
    /// `move_event_count`. if the arguments are invalid, the server should close
    /// the connection.
    ///
    /// The generated pointer event stream will be:
    ///
    /// DOWN + CHANGE_1 + ... + CHANGE_n + UP, where n == `move_event_count`
    ///
    /// Events are injected with a small explicit delay in between.
    @available(added=12)
    strict SimulateMultiFingerGesture(table {
        /// Starting locations of the gesture, in the coordinate units specified during
        /// registration.
        1: start_locations array<fuchsia.math.Vec, MAX_FINGERS>;

        /// End locations of the gesture, in the coordinate units specified during
        /// registration.
        2: end_locations array<fuchsia.math.Vec, MAX_FINGERS>;

        /// Number of move events in the pinch.
        3: move_event_count uint32;

        /// Number of fingers, because `array<fuchsia.math.Vec, MAX_FINGERS>` is
        /// fixed length, we use this field to know how many fingers in gesture.
        @available(added=18)
        4: finger_count uint32;
    }) -> ();

    /// Simulate a touch event by a touch input report.
    ///
    /// TouchInputReport includes a list of contacts that are currently contacting the
    /// touch surface. The report can represent multiply touch events by comparing with
    /// previous reports received.
    @available(added=17)
    strict SimulateTouchEvent(struct {
        report fuchsia.input.report.TouchInputReport;
    }) -> ();
};

/// A tool for applications to report touch input to interested parties (e.g. a test
/// fixture).
@discoverable
closed protocol TouchInputListener {
    /// Report that component under test has received expected input.
    strict ReportTouchInput(table {
        /// The horizontal coordinate, in the reporter's coordinate system.
        1: local_x float64;

        /// The vertical coordinate, in the reporter's coordinate system.
        2: local_y float64;

        /// The monotonic time (ns) the pointer data was received by the reporter.
        /// Note that this value should be used with caution. Some reporters may not be
        /// capable of ns-level precision, but still report in ns-level units.
        3: time_received zx.Time;

        /// The number of physical pixels, per logical pixel, as reported by the reporter.
        4: device_pixel_ratio float64;

        /// Name of the component to help distinguish responses from multiple components.
        ///
        /// NOTE: This name is *independent* of component framework, so the reporter and
        /// listener are free to agree on an arbitrary value.
        5: component_name string:1024;

        /// The phase of the touch event.
        @available(added=12)
        6: phase fuchsia.ui.pointer.EventPhase;

        /// pointer_id is used to identify finger in multi touch. each finger
        /// is sent in a separate call to `ReportTouchInput()`, and the callee
        /// is responsible for assembling the fingers as needed
        @available(added=12)
        7: pointer_id uint32;
    });
};