| // 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. |
| @available(added=7) |
| 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; |
| }) -> (); |
| }; |