PROTOCOLS

Controller

Defined in fuchsia.input.virtualkeyboard/virtual_keyboard.fidl

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.

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

Provides the ability to acquire a Controller.

This protocol exists to bind Controllers to Views (via ViewRefs). 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.

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	fuchsia.ui.views/ViewRef
text_type	TextType
controller_request	server_end:Controller

Manager

Defined in fuchsia.input.virtualkeyboard/virtual_keyboard.fidl

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.

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	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	TextType
is_visible	bool

ENUMS

TextType flexible

Type: uint32

Defined in fuchsia.input.virtualkeyboard/virtual_keyboard.fidl

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

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

Type: uint32

Defined in fuchsia.input.virtualkeyboard/virtual_keyboard.fidl

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

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.