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.
- If there is a pending
- 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 theView
regains focus. However, a call toRequestHide()
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 theView
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 theView
loses focus. - The function may return while the keyboard is still visible on screen.
- This may happen due to a call to
-
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 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.
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 |
USER_INTERACTION |
2 |
Visibility changed due to the user's interaction with the GUI compoment. E.g., the user tapped the dismiss button. |