// 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.ui.input3;

/// A tool to inject keyboard events into Input Pipeline.
///
/// Please extend as necessary.
closed protocol Keyboard {
    /// Simulates input of the set of keystrokes required to type `text`,
    /// as if on a US QWERTY keyboard.
    ///
    /// 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.
    strict SimulateUsAsciiTextEntry(table {
        1: text string:1024;
    }) -> ();

    /// Simulate a key event by a keyboard input report.
    ///
    /// KeyboardInputReport includes a list of keys that are currently pressing
    /// down. The report can represent key down / up by comparing with previous
    /// reports received.
    @available(added=16)
    strict SimulateKeyEvent(table {
        1: report fuchsia.input.report.KeyboardInputReport;
    }) -> ();
};

/// A tool for client applications to report text input to interested parties
/// (e.g. a test fixture).
///
/// NOTE: The reporter is the *client* of this service.
///
/// Canonical usage is for a test to inject text via fuchsia.ui.test.input.Keyboad,
/// and wait for the client under test to report back that it received the injected
/// text via fuchsia.ui.test.input.KeyboardInputListener.
///
/// NOTE: This protocol is implemented by OOT code. Use versioning to make changes
/// to this protocol.
@discoverable
closed protocol KeyboardInputListener {
    /// Notify that the client is ready to receive text input. Clients that need
    /// to complete their setup to be able to continue with testing should call
    /// this method, so that the listener can wait until they are ready to
    /// proceed with testing.
    @available(added=9, replaced=10)
    strict ReportReady() -> ();

    /// Notify that the client is ready to receive text input. Clients that need
    /// to complete their setup to be able to continue with testing should call
    /// this method, so that the listener can wait until they are ready to
    /// proceed with testing.
    @available(added=10)
    strict ReportReady() -> ();

    /// Notify the listener of the text string generated by the set of key events
    /// received by the application.
    strict ReportTextInput(table {
        /// The content of the text input received by the reporter.
        1: text string:1024;
        /// The non printable key received by the reporter.
        @available(added=18)
        2: non_printable fuchsia.ui.input3.NonPrintableKey;
    });
};