f11/sdk/fidl/fuchsia.input.virtualkeyboard/README.md

<link rel="stylesheet" href="../style.css" />

[TOC]
# fuchsia.input.virtualkeyboard

<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>


## **PROTOCOLS**

## Controller {#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=114)*
<p>Provides the ability to control a virtual keyboard.</p>
<h1>Abstract model</h1>
<p>The virtual keyboard is &quot;owned&quot; by at most one Controller at a time.
The owner is the Controller whose associated <code>View</code> is focused. If no such
Controller exists, the virtual keyboard is unowned (and hidden).</p>
<p>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.</p>
<h1>Roles</h1>
<p>This protocol will typically be:</p>
<ul>
<li>Implemented by platform components which control keyboard visibility.</li>
<li>Consumed by application runtimes. For example, Flutter, Chromium.</li>
</ul>
<h1>Related protocols</h1>
<ul>
<li>This protocol does not provide access to the output of the virtual
keyboard. For that, see one of the following protocols:
<ul>
<li><code>fuchsia.ui.input3.Keyboard</code> (for keystrokes)</li>
<li><code>fuchsia.ui.input.InputMethodEditor</code> (for text editing)</li>
</ul>
</li>
<li>This protocol is tended for the consumer/user of a virtual keyboard.
The implementer/owner of the keyboard should use <code>Manager</code> below.</li>
</ul>
<h1>Note for implementers</h1>
<p>Calls to this protocol's methods would, ideally, only be allowed when the
associated <code>View</code> has focus. However, the implementer and consumer of this
protocol receive focus change notifications independently, with no guarantee
that the <code>Controller</code> implementer will learn of the focus change
before the <code>Controller</code> consumer.</p>
<p>Hence, disallowing calls when the <code>View</code> is not focused would run the risk
of spuriously rejecting valid calls, due to the race condition above.
Instead, implementations <em>should</em> buffer requests as described in the
per-method comments.</p>


### RequestHide {#Controller.RequestHide}

<p>Requests that the keyboard be hidden.</p>
<ul>
<li>If the callee determines that the <code>View</code> for this Controller is
focused, the callee applies the change immediately.</li>
<li>If the callee determines that the <code>View</code> for this Controller is
<em>not</em> focused:
<ul>
<li>If there is a pending <code>RequestShow()</code>, the callee cancels
that request.</li>
<li>Otherwise, the call has no effect.</li>
</ul>
</li>
<li>Calls to this method are idempotent.</li>
</ul>



#### Request {#Controller.RequestHide_Request}

&lt;EMPTY&gt;


### RequestShow {#Controller.RequestShow}

<p>Requests that the keyboard be made visible.</p>
<ul>
<li>If the callee determines that the <code>View</code> for this Controller is
focused, the callee applies the change immediately.</li>
<li>If the callee determines that the <code>View</code> for this Controller is
<em>not</em> focused, the callee applies the change when the <code>View</code>
regains focus. However, a call to <code>RequestHide()</code> will nullify
such a pending request.</li>
<li>Calls to this method are idempotent.</li>
</ul>



#### Request {#Controller.RequestShow_Request}

&lt;EMPTY&gt;


### SetTextType {#Controller.SetTextType}

<p>Requests a change in text type for the virtual keyboard.</p>
<ul>
<li>If the callee determines that the <code>View</code> for this Controller is
focused, the callee applies the change immediately.</li>
<li>If the callee determines that the <code>View</code> for this Controller is
<em>not</em> focused, the callee applies the change when the <code>View</code> regains
focus.</li>
<li>If the callee receives multiple calls before the <code>View</code> regains
focus, the  callee will apply the value from the most recent call.</li>
</ul>



#### Request {#Controller.SetTextType_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>text_type</code></td>
            <td>
                <code><a class='link' href='#TextType'>TextType</a></code>
            </td>
        </tr>
</table>


### WatchVisibility {#Controller.WatchVisibility}

<p>Waits for the visibility to change, then reports the new value.</p>
<ul>
<li>
<p>Returns <code>true</code> after the callee receives a RequestShow()
call from this Controller, when this Controller was not
already requesting the keyboard be shown.</p>
<ul>
<li>This <em>may</em> occur before the keyboard is visible on screen.</li>
<li>This <em>may</em> occur before the <code>View</code> for this Controller is
focused.</li>
</ul>
</li>
<li>
<p>Returns <code>false</code> when the callee decides to hide the keyboard
that was requested by this Controller.</p>
<ul>
<li>This may happen due to a call to <code>RequestHide()</code>, or
implicitly when the <code>View</code> loses focus.</li>
<li>The function <em>may</em> return while the keyboard is still
visible on screen.</li>
</ul>
</li>
<li>
<p>The first call immediately returns...</p>
<ul>
<li><code>true</code> 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)</li>
<li><code>false</code> otherwise</li>
</ul>
</li>
</ul>



#### Request {#Controller.WatchVisibility_Request}

&lt;EMPTY&gt;


#### Response {#Controller.WatchVisibility_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>is_visible</code></td>
            <td>
                <code>bool</code>
            </td>
        </tr>
</table>

## ControllerCreator {#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=55)*
<p>Provides the ability to acquire a <code>Controller</code>.</p>
<p>This protocol exists to bind <code>Controller</code>s to <code>View</code>s (via <code>ViewRef</code>s).
The binding allows the keyboard subsystem to use its knowledge of <code>View</code>
focus to limit when a <code>Controller</code> can influence virtual keyboard
configuration.</p>
<p>Note that the <code>Controller</code> itself allows configuration of the virtual
keyboard's presentation (visibility and layout), but does not pertain
to text events. See the <code>Controller</code> documentation for details.</p>
<h1>Roles</h1>
<p>This protocol will typically be:</p>
<ul>
<li>Implemented by platform components which control UI policy.
For example, Root Presenter, or the Workstation Session.</li>
<li>Consumed by application runtimes. For example, Flutter, Chromium.</li>
</ul>


### Create {#ControllerCreator.Create}

<p>Requests that the <code>Controller</code> at the other end of the
<code>request&lt;Controller&gt;</code> channel be associated with the <code>View</code>
referenced by <code>view_ref</code>.</p>
<p>When <code>Controller.RequestShow()</code> is called, the <code>Controller</code>
implementer will will attempt to provide a keyboard optimized
for the entry of <code>text_type</code> (unless the type is overridden by a
call to <code>Controller.SetType()</code>).</p>
<p>Implementers of <code>ControllerCreator</code> <em>should</em> use knowledge of
the associated <code>View</code>'s focus state to apply access controls to
calls made on <code>Controller</code>. See documentation of the <code>Controller</code>
methods for further details.</p>
<p>Consumers of <code>ControllerCreator</code> may freely drop their Creator
connection, without affecting their Controller(s).</p>



#### Request {#ControllerCreator.Create_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>view_ref</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewRef'>ViewRef</a></code>
            </td>
        </tr>
        <tr>
            <td><code>text_type</code></td>
            <td>
                <code><a class='link' href='#TextType'>TextType</a></code>
            </td>
        </tr>
        <tr>
            <td><code>controller_request</code></td>
            <td>
                <code>server_end&lt;<a class='link' href='#Controller'>Controller</a>&gt;</code>
            </td>
        </tr>
</table>


## Manager {#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=185)*
<p>Enables the virtual keyboard UI to synchronize state with the platform.</p>
<h1>Roles</h1>
<p>This protocol will typically be:</p>
<ul>
<li>Implemented by platform components which control UI policy.
For example, Root Presenter, or the Workstation Session.</li>
<li>Consumed by components which provide a GUI affordance for text input.</li>
</ul>


### Notify {#Manager.Notify}

<p>Informs the callee that the visibility of the virtual keyboard has
changed, and what triggered the change.</p>
<p>The caller <em>should</em> wait for a result before invoking invoking this
method again, to avoid overloading the callee.</p>



#### Request {#Manager.Notify_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>is_visible</code></td>
            <td>
                <code>bool</code>
            </td>
        </tr>
        <tr>
            <td><code>reason</code></td>
            <td>
                <code><a class='link' href='#VisibilityChangeReason'>VisibilityChangeReason</a></code>
            </td>
        </tr>
</table>


#### Response {#Manager.Notify_Response}

&lt;EMPTY&gt;

### WatchTypeAndVisibility {#Manager.WatchTypeAndVisibility}

<p>Waits for a change in intended <code>text_type</code> or visibility, then
reports the new value. In response to a status change, the caller
should set the requested type and visibility, then call <code>Notify</code>
to inform the platform of the change.</p>
<p>The first call immediately returns the currently intended
<code>text_type</code> and visibility.</p>
<p>In the event that <code>text_type</code> is not supported, the caller should
implement a fallback that provides as many of the necessary keys
as possible.</p>



#### Request {#Manager.WatchTypeAndVisibility_Request}

&lt;EMPTY&gt;


#### Response {#Manager.WatchTypeAndVisibility_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>text_type</code></td>
            <td>
                <code><a class='link' href='#TextType'>TextType</a></code>
            </td>
        </tr>
        <tr>
            <td><code>is_visible</code></td>
            <td>
                <code>bool</code>
            </td>
        </tr>
</table>



## **ENUMS**

### TextType [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#TextType data-text="TextType"}
Type: <code>uint32</code>

*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)*
<p>Describes the type of text expected to be input by a virtual keyboard.</p>

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="TextType.ALPHANUMERIC">
<td><h3 id="TextType.ALPHANUMERIC" class="add-link hide-from-toc">ALPHANUMERIC</h3></td>
            <td><code>0</code></td>
            <td><p>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.</p>
</td>
        </tr>
        <tr id="TextType.NUMERIC">
<td><h3 id="TextType.NUMERIC" class="add-link hide-from-toc">NUMERIC</h3></td>
            <td><code>1</code></td>
            <td><p>The text is likely to contain only numeric characters.</p>
</td>
        </tr>
        <tr id="TextType.PHONE">
<td><h3 id="TextType.PHONE" class="add-link hide-from-toc">PHONE</h3></td>
            <td><code>2</code></td>
            <td><p>The text is likely to include both numeric characters,
and punctuation used with phone numbers (e.g. '*', '#'}).</p>
</td>
        </tr>
</table>

### VisibilityChangeReason [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#VisibilityChangeReason data-text="VisibilityChangeReason"}
Type: <code>uint32</code>

*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)*
<p>Describes reasons that the virtual keyboard might be added to, or
removed from, the interface rendered to the user.</p>

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="VisibilityChangeReason.PROGRAMMATIC">
<td><h3 id="VisibilityChangeReason.PROGRAMMATIC" class="add-link hide-from-toc">PROGRAMMATIC</h3></td>
            <td><code>1</code></td>
            <td><p>Visibility changed due to a programmatic request. E.g., the GUI
component's call to <code>WatchTypeAndVisibility()</code> returned a new
value for <code>is_visible</code>.</p>
</td>
        </tr>
        <tr id="VisibilityChangeReason.USER_INTERACTION">
<td><h3 id="VisibilityChangeReason.USER_INTERACTION" class="add-link hide-from-toc">USER_INTERACTION</h3></td>
            <td><code>2</code></td>
            <td><p>Visibility changed due to the user's interaction with the GUI
compoment. E.g., the user tapped the dismiss button.</p>
</td>
        </tr>
</table>