<br />

Added: 7

## **PROTOCOLS**

## Controller

*Defined in [fuchsia.input.virtualkeyboard/virtual_keyboard.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.input.virtualkeyboard/virtual_keyboard.fidl;l=113)*

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.

<br />

### RequestHide

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.

#### Request

\<EMPTY\>

### RequestShow

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.

#### Request

\<EMPTY\>

### SetTextType

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.

#### Request

| Name | Type |
|---|---|
| `text_type` | `https://fuchsia.dev/reference/fidl/fuchsia.input.virtualkeyboard#TextType` |

### WatchVisibility

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

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `is_visible` | `bool` |

## ControllerCreator

*Defined in [fuchsia.input.virtualkeyboard/virtual_keyboard.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.input.virtualkeyboard/virtual_keyboard.fidl;l=54)*

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.
- Consumed by application runtimes. For example, Flutter, Chromium.

<br />

### Create

Requests that the `Controller` at the other end of the
`server_end: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).

#### Request

| Name | Type |
|---|---|
| `view_ref` | `https://fuchsia.dev/reference/fuchsia.ui.views//https://fuchsia.dev/reference/fuchsia.ui.views#ViewRef` |
| `text_type` | `https://fuchsia.dev/reference/fidl/fuchsia.input.virtualkeyboard#TextType` |
| `controller_request` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.input.virtualkeyboard#Controller` |

## Manager

*Defined in [fuchsia.input.virtualkeyboard/virtual_keyboard.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.input.virtualkeyboard/virtual_keyboard.fidl;l=183)*

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.
- Consumed by components which provide a GUI affordance for text input.

<br />

### Notify

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.

#### Request

| Name | Type |
|---|---|
| `is_visible` | `bool` |
| `reason` | `https://fuchsia.dev/reference/fidl/fuchsia.input.virtualkeyboard#VisibilityChangeReason` |

#### Response

\<EMPTY\>

### WatchTypeAndVisibility

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.

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `text_type` | `https://fuchsia.dev/reference/fidl/fuchsia.input.virtualkeyboard#TextType` |
| `is_visible` | `bool` |

## **ENUMS**

### TextType [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

Type: `uint32`

*Defined in [fuchsia.input.virtualkeyboard/virtual_keyboard.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.input.virtualkeyboard/virtual_keyboard.fidl;l=10)*

Describes the type of text expected to be input by a virtual keyboard.

<br />

| Name | Value | Description |
|---|---|---|
| ### ALPHANUMERIC | `0` | 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. |
| ### NUMERIC | `1` | The text is likely to contain only numeric characters. |
| ### PHONE | `2` | The text is likely to include both numeric characters, and punctuation used with phone numbers (e.g. '\*', '#'}). |

### VisibilityChangeReason [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

Type: `uint32`

*Defined in [fuchsia.input.virtualkeyboard/virtual_keyboard.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.input.virtualkeyboard/virtual_keyboard.fidl;l=27)*

Describes reasons that the virtual keyboard might be added to, or
removed from, the interface rendered to the user.

<br />

| Name | Value | Description |
|---|---|---|
| ### PROGRAMMATIC | `1` | Visibility changed due to a programmatic request. E.g., the GUI component's call to `WatchTypeAndVisibility()` returned a new value for `is_visible`. |
| ### USER_INTERACTION | `2` | Visibility changed due to the user's interaction with the GUI compoment. E.g., the user tapped the dismiss button. |