// Copyright 2021 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.input.virtualkeyboard;

using fuchsia.ui.views;

/// Describes the type of text expected to be input by a virtual keyboard.
type TextType = flexible enum {
    /// The text is likely to contain both alphabetic and numeric
    /// characters. This is the enum's default (zero-value), so that
    /// uninitialized enum instances provide the keyboard user the most
    /// flexibility in what can be input.
    ALPHANUMERIC = 0;

    /// The text is likely to contain only numeric characters.
    NUMERIC = 1;

    /// The text is likely to include both numeric characters,
    /// and punctuation used with phone numbers (e.g. '*', '#'}).
    PHONE = 2;
};

/// Describes reasons that the virtual keyboard might be added to, or
/// removed from, the interface rendered to the user.
type VisibilityChangeReason = flexible enum {
    /// Visibility changed due to a programmatic request. E.g., the GUI
    /// component's call to `WatchTypeAndVisibility()` returned a new
    /// value for `is_visible`.
    PROGRAMMATIC = 1;

    /// Visibility changed due to the user's interaction with the GUI
    /// compoment. E.g., the user tapped the dismiss button.
    USER_INTERACTION = 2;
};

/// Provides the ability to acquire a `Controller`.
///
/// This protocol exists to bind `Controller`s to `View`s (via `ViewRef`s).
/// The binding allows the keyboard subsystem to use its knowledge of `View`
/// focus to limit when a `Controller` can influence virtual keyboard
/// configuration.
///
/// Note that the `Controller` itself allows configuration of the virtual
/// keyboard's presentation (visibility and layout), but does not pertain
/// to text events. See the `Controller` documentation for details.
///
/// # Roles
/// This protocol will typically be:
/// * Implemented by platform components which control UI policy.
///   For example, Root Presenter, or the Workstation Session.
/// * Consumed by application runtimes. For example, Flutter, Chromium.
@discoverable
protocol ControllerCreator {
    /// Requests that the `Controller` at the other end of the
    /// `request<Controller>` channel be associated with the `View`
    /// referenced by `view_ref`.
    ///
    /// When `Controller.RequestShow()` is called, the `Controller`
    /// implementer will will attempt to provide a keyboard optimized
    /// for the entry of `text_type` (unless the type is overridden by a
    /// call to `Controller.SetType()`).
    ///
    /// Implementers of `ControllerCreator` _should_ use knowledge of
    /// the associated `View`'s focus state to apply access controls to
    /// calls made on `Controller`. See documentation of the `Controller`
    /// methods for further details.
    ///
    /// Consumers of `ControllerCreator` may freely drop their Creator
    /// connection, without affecting their Controller(s).
    Create(resource struct {
        view_ref fuchsia.ui.views.ViewRef;
        text_type TextType;
        controller_request server_end:Controller;
    });
};

/// Provides the ability to control a virtual keyboard.
///
/// # Abstract model
/// The virtual keyboard is "owned" by at most one Controller at a time.
/// The owner is the Controller whose associated `View` is focused. If no such
/// Controller exists, the virtual keyboard is unowned (and hidden).
///
/// Only the owning Controller may modify the virtual keyboard's configuration.
/// When the owning Controller loses focus, the implementer of this protocol
/// will automatically dismiss the virtual keyboard.
///
/// # Roles
/// This protocol will typically be:
/// * Implemented by platform components which control keyboard visibility.
/// * Consumed by application runtimes. For example, Flutter, Chromium.
///
/// # Related protocols
/// * This protocol does not provide access to the output of the virtual
///   keyboard. For that, see one of the following protocols:
///   * `fuchsia.ui.input3.Keyboard` (for keystrokes)
///   * `fuchsia.ui.input.InputMethodEditor` (for text editing)
/// * This protocol is tended for the consumer/user of a virtual keyboard.
///   The implementer/owner of the keyboard should use `Manager` below.
///
/// # Note for implementers
/// Calls to this protocol's methods would, ideally, only be allowed when the
/// associated `View` has focus. However, the implementer and consumer of this
/// protocol receive focus change notifications independently, with no guarantee
/// that the `Controller` implementer will learn of the focus change
/// before the `Controller` consumer.
///
/// Hence, disallowing calls when the `View` is not focused would run the risk
/// of spuriously rejecting valid calls, due to the race condition above.
/// Instead, implementations _should_ buffer requests as described in the
/// per-method comments.
protocol Controller {
    /// Requests a change in text type for the virtual keyboard.
    ///
    /// * If the callee determines that the `View` for this Controller is
    ///   focused, the callee applies the change immediately.
    /// * If the callee determines that the `View` for this Controller is
    ///   _not_ focused, the callee applies the change when the `View` regains
    ///   focus.
    /// * If the callee receives multiple calls before the `View` regains
    ///   focus, the  callee will apply the value from the most recent call.
    SetTextType(struct {
        text_type TextType;
    });

    /// Requests that the keyboard be made visible.
    ///
    /// * If the callee determines that the `View` for this Controller is
    ///   focused, the callee applies the change immediately.
    /// * If the callee determines that the `View` for this Controller is
    ///   _not_ focused, the callee applies the change when the `View`
    ///   regains focus. However, a call to `RequestHide()` will nullify
    ///   such a pending request.
    /// * Calls to this method are idempotent.
    RequestShow();

    /// Requests that the keyboard be hidden.
    ///
    /// * If the callee determines that the `View` for this Controller is
    ///   focused, the callee applies the change immediately.
    /// * If the callee determines that the `View` for this Controller is
    ///   _not_ focused:
    ///   * If there is a pending `RequestShow()`, the callee cancels
    ///     that request.
    ///   * Otherwise, the call has no effect.
    /// * Calls to this method are idempotent.
    RequestHide();

    /// Waits for the visibility to change, then reports the new value.
    ///
    /// * Returns `true` after the callee receives a RequestShow()
    ///   call from this Controller, when this Controller was not
    ///   already requesting the keyboard be shown.
    ///   * This _may_ occur before the keyboard is visible on screen.
    ///   * This _may_ occur before the `View` for this Controller is
    ///     focused.
    ///
    /// * Returns `false` when the callee decides to hide the keyboard
    ///   that was requested by this Controller.
    ///   * This may happen due to a call to `RequestHide()`, or
    ///     implicitly when the `View` loses focus.
    ///   * The function _may_ return while the keyboard is still
    ///     visible on screen.
    ///
    /// * The first call immediately returns...
    ///    * `true` if the callee has decided that the keyboard should
    ///      be visible due to a request from this Controller (this
    ///      does not guarantee that the keyboard is visible on screen)
    ///    * `false` otherwise
    WatchVisibility() -> (struct {
        is_visible bool;
    });
};

/// Enables the virtual keyboard UI to synchronize state with the platform.
///
/// # Roles
/// This protocol will typically be:
/// * Implemented by platform components which control UI policy.
///   For example, Root Presenter, or the Workstation Session.
/// * Consumed by components which provide a GUI affordance for text input.
@discoverable
protocol Manager {
    /// Waits for a change in intended `text_type` or visibility, then
    /// reports the new value. In response to a status change, the caller
    /// should set the requested type and visibility, then call `Notify`
    /// to inform the platform of the change.
    ///
    /// The first call immediately returns the currently intended
    /// `text_type` and visibility.
    ///
    /// In the event that `text_type` is not supported, the caller should
    /// implement a fallback that provides as many of the necessary keys
    /// as possible.
    WatchTypeAndVisibility() -> (struct {
        text_type TextType;
        is_visible bool;
    });

    /// Informs the callee that the visibility of the virtual keyboard has
    /// changed, and what triggered the change.
    ///
    /// The caller _should_ wait for a result before invoking invoking this
    /// method again, to avoid overloading the callee.
    Notify(struct {
        is_visible bool;
        reason VisibilityChangeReason;
    }) -> ();
};