// 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.

/// A test library that allows tests to pretend to be devices and inject input
/// into the input pipeline.
///
/// The library exposes the functionality from the Rust library
/// `//src/lib/ui/input-synthesis` through a FIDL adapter.
///
/// This FIDL adapter makes it possible to call the test methods from all languages
/// that FIDL supports.
library test.inputsynthesis;

using fuchsia.input.report;

/// A protocol that allows the test to pretend to be a keyboard and inject
/// key presses into the input pipeline.
///
/// Only minimally required text synthesis is exposed through the protocol. If
/// you need to expose more functionality, feel free to add methods to this
/// protocol.
@discoverable
closed protocol Text {
    /// Sends `text` through the input pipeline, pretending to be a keyboard,
    /// effectively converting the text into key presses as if on a US QWERTY
    /// keyboard, and typing characters up one at a time with a brief pause
    /// between successive key events.
    ///
    /// US ASCII text get mapped to the corresponding key presses.
    /// For example `a` gets mapped into a press and
    /// a followup release of the key `a` on the US QWERTY keyboard.  Also,
    /// `A` gets mapped into a press of the `Shift` key, followed by a press
    /// and release of `a`.
    ///
    /// For convenience, the `\n` and `\t` get converted into `Enter` and `Tab`
    /// keys respectively.
    ///
    /// On error-free return, the caller can assume that all keys corresponding
    /// to `text` has been typed up on the fake keyboard.  On error, the caller
    /// should fail the test.
    ///
    /// This API does not support sending multiple key events at the same time.
    /// Feel free to expose the appropriate functionality from the
    /// `input-synthesis` library if you need that.
    strict Send(struct {
        text string:1024;
    }) -> ();
};

/// A hardcoded number of max mouse buttons. This should be increased in the future
/// if we ever see mice with more buttons. Copied from fuchsia.input.report.mouse.
const MOUSE_MAX_NUM_BUTTONS uint32 = 32;

/// Error when calling inputsynthesis protocols.
type Error = flexible enum : uint32 {
    /// SendInputReport receive an invalid device id.
    INVALID_DEVICE_ID = 1;
};

/// A protocol that allows the test to pretend to be a mouse and inject
/// mouse cursor movement and button presses into the input pipeline.
///
/// Only minimally required mouse synthesis is exposed through the protocol. If
/// you need to expose more functionality, feel free to add methods to this
/// protocol.
@discoverable
closed protocol Mouse {
    /// Add a new device for testing.
    strict AddDevice() -> (struct {
        device_id uint32;
    });

    /// Send input report to specified device. Returning empty tuple will block
    /// the caller until the input report is dispatched. `event_time` used as
    /// the timestamp in the `InputReport`, it doesn't change the timing of
    /// when the report is dispatched to the input pipeline.
    strict SendInputReport(struct {
        device_id uint32;
        report fuchsia.input.report.MouseInputReport;
        event_time uint64;
    }) -> () error Error;
};