Google Git
Sign in
fuchsia / reference-docs / main / . / f8 / sdk / fidl / fuchsia.ui.views / README.md
blob: fc326fe831e51cb8b5f75b9e4c7cec032d07c029 [file] [log] [blame] [view]
<link rel="stylesheet" href="../style.css" />
[TOC]
# fuchsia.ui.views
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>
## **PROTOCOLS**
## Focuser {#Focuser}
*Defined in [fuchsia.ui.views/focuser.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/focuser.fidl;l=16)*
<p>A method of programmatically transferring view focus.</p>
<p>The protocol client has implicit access to a requestor ViewRef, which is
used as the basis for request authority.</p>
### RequestFocus {#Focuser.RequestFocus}
<p>Asks the server to transfer focus to the view specified by <code>view_ref</code>,
with the authority of the requestor ViewRef. Such a request may be
honored or denied.</p>
<p>If the request was honored, and it triggers a focus change, a FocusEvent
(with focused=true) is issued to the newly-focused view, and a
FocusEvent (with focused=false) is issued to the previous view.</p>
<p>The result callback indicates that the request was received and honored.
It does not guarantee that the requested view actually received a
FocusEvent in time.</p>
<p>The request may be denied for many reasons, for example:</p>
<ul>
<li>if <code>view_ref</code> is invalid</li>
<li>if there is no view backed by <code>view_ref</code></li>
<li>if there is no requestor ViewRef accessible to Focuser</li>
<li>if the requestor ViewRef lacks authority over <code>view_ref</code>'s view</li>
<li>if <code>view_ref</code>'s view is not hittable or may not receive focus
etc. A denied request is indicated with a Error.</li>
</ul>
#### Request {#Focuser.RequestFocus_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>view_ref</code></td>
<td>
<code><a class='link' href='#ViewRef'>ViewRef</a></code>
</td>
</tr>
</table>
#### Response {#Focuser.RequestFocus_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#Focuser_RequestFocus_Result'>Focuser_RequestFocus_Result</a></code>
</td>
</tr>
</table>
## View {#View}
*Defined in [fuchsia.ui.views/view.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view.fidl;l=9)*
<p>Deprecated API for view creation. DO NOT USE.</p>
<p><b>DEPRECATED </b></p>
### Present {#View.Present}
<p>Provides the View with an attachment point to Scenic's scene graph.</p>
<p>When <code>Present()</code> is called the View's implementation should create a
View resource within Scenic by providing it with the <code>view_token</code> (using
a <code>fuchsia.ui.gfx.CreateResourceCmd</code> and <code>fuchsia.ui.gfx.ViewArgs</code>).</p>
<p>Then the implementation should attach its graphical content to the
newly-created View resource using a <code>fuchsia.ui.gfx.AddChildCmd</code>.</p>
<p>If the implementation already owns a View resource (because <code>Present()</code>
had already been called before), then it should terminate the connection
with an error.</p>
<p>TODO(fxbug.dev/24470): Allow re-parenting <code>View</code>s with a new <code>Present()</code> call.</p>
#### Request {#View.Present_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>view_token</code></td>
<td>
<code><a class='link' href='#ViewToken'>ViewToken</a></code>
</td>
</tr>
</table>
## ViewRefFocused {#ViewRefFocused}
*Defined in [fuchsia.ui.views/view_ref_focused.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref_focused.fidl;l=22)*
<p>A method of enabling a ViewRef creator to determine if its ViewRef has
gained or lost focus in the view tree.</p>
<p>The protocol client has implicit access to the ViewRef it created; the
protocol itself does not accept a ViewRef parameter. Clients, both trusted
or otherwise, need access to view-focus state, so the protocol is
deliberately minimal. Possession of a ViewRef (and this protocol) does not
grant the power to learn about a ViewRef's focus state.</p>
### Watch {#ViewRefFocused.Watch}
<p>Sets up a callback to fire when the implicit ViewRef has gained or lost
focus. Typically, focus changes happen at a slow pace, such that every
transition is captured by the callback. However, focus changes can
happen rapidly, so the callback may &quot;compress&quot; focus change history into
just the latest known focus state.</p>
<p>The callback reports the last focus change spanning the duration from
its issuance to the previous callback's issuance. The client may observe
any of the following four transitions:</p>
<ul>
<li>true -&gt; true: The ViewRef has lost focus at least once, and has gained
focus by the time of callback issuance.</li>
<li>true -&gt; false: The ViewRef has lost focus at least once, and has lost
focus by the time of callback issuance.</li>
<li>false -&gt; true: The ViewRef has gained focus at least once, and has
gained focus by the time of callback issuance.</li>
<li>false -&gt; false: The ViewRef has gained focus at least once, and has
lost focus by the time of callback issuance.</li>
</ul>
<p>The client avoids &quot;focus flapping&quot; and always sees the latest state.
Every callback issuance is meaningful, and the client should renegotiate
focus-related services appropriately, such as IME.</p>
<p>Flow control: The caller is allowed at most one in-flight |Watch| call
at at time: subsequent |Watch| calls must wait until the acknowledgment
returns. Non-compliance results in channel closure.</p>
#### Request {#ViewRefFocused.Watch_Request}
&lt;EMPTY&gt;
#### Response {#ViewRefFocused.Watch_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>state</code></td>
<td>
<code><a class='link' href='#FocusState'>FocusState</a></code>
</td>
</tr>
</table>
## ViewRefInstalled {#ViewRefInstalled}
*Defined in [fuchsia.ui.views/view_ref_installed.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref_installed.fidl;l=24)*
<p>A method of enabling ViewRef holders to determine if a ViewRef has been
&quot;installed&quot; in the view tree: the time it is first connected, transitively,
to the root view. Typically, after installation, view focus may be
transferred to that ViewRef.</p>
<p>Note: It's important to distinguish between a ViewRef's installed status and
current connected-to-view-tree status. The former undergoes a state
change once, from &quot;no&quot; to &quot;yes&quot;. The latter may change continuously,
depending on view tree topology. As such, &quot;installed&quot; cannot imply
&quot;currently connected to view tree&quot;; even a hypothetical
&quot;ViewRefConnected&quot; protocol is fundamentally racy.</p>
### Watch {#ViewRefInstalled.Watch}
<p>Sets up a callback to fire when the requested |view_ref| is installed.</p>
<ul>
<li>If |view_ref| has not already been installed, the |Watch| response
will fire when it is.</li>
<li>If |view_ref| has already been installed, the |Watch| response will
fire immediately.</li>
<li>If |view_ref| is invalid, or becomes invalid (perhaps because the view
was destroyed), the |Watch| call returns with an error. The error is
not guaranteed to be immediate, but a ViewRef holder can itself
determine ViewRef validity by listening for ZX_EVENTPAIR_PEER_CLOSED.</li>
</ul>
<p>Flow control: The caller is allowed multiple |Watch| calls on multiple
ViewRefs. There is at most one response per call back to the client.</p>
<p>Note: Prior to installation, this |Watch| call is kept alive as long as
the ViewRef is valid.</p>
#### Request {#ViewRefInstalled.Watch_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>view_ref</code></td>
<td>
<code><a class='link' href='#ViewRef'>ViewRef</a></code>
</td>
</tr>
</table>
#### Response {#ViewRefInstalled.Watch_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#ViewRefInstalled_Watch_Result'>ViewRefInstalled_Watch_Result</a></code>
</td>
</tr>
</table>
## **STRUCTS**
### Focuser_RequestFocus_Response {#Focuser_RequestFocus_Response data-text="Focuser_RequestFocus_Response"}
*Defined in [fuchsia.ui.views/focuser.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/focuser.fidl;l=38)*
&lt;EMPTY&gt;
### ViewCreationToken [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewCreationToken data-text="ViewCreationToken"}
*Defined in [fuchsia.ui.views/flatland_tokens.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/flatland_tokens.fidl;l=14)*
<p>Two Flatland instances may be connected in a parent-child relationship. The child endpoint is
held in a View. This view is strongly associated with a ViewRef and other related protocols.</p>
<p>ViewCreationToken is a typed wrapper for a channel, representing the child endpoint of the
connection between two Flatland instances. No messages will be sent over this channel, because
it is only used as an unclonable object with peer.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ViewCreationToken.value">
<td><code>value</code></td>
<td>
<code>handle&lt;channel&gt;</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### ViewHolderToken [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewHolderToken data-text="ViewHolderToken"}
*Defined in [fuchsia.ui.views/view_token.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_token.fidl;l=15)*
<p>Token that uniquely identifies an attachment point for a <code>View</code> in the
global scene graph. Each <code>ViewHolderToken</code> has exactly one corresponding
<code>ViewToken</code>.</p>
<p>A Scenic client can reference contents from another client by creating a
<code>ViewHolder</code> resource using this token. The other client must also create
a <code>View</code> resource using the corresponding <code>ViewToken</code>.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ViewHolderToken.value">
<td><code>value</code></td>
<td>
<code>handle&lt;eventpair&gt;</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### ViewIdentityOnCreation [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewIdentityOnCreation data-text="ViewIdentityOnCreation"}
*Defined in [fuchsia.ui.views/view_ref.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref.fidl;l=66)*
<p>Convenience data type to self-identify the view, during view creation.</p>
<p>A ViewRef is used to identify the view, and can be freely cloned and
distributed to other components.</p>
<p>A ViewRefControl is used to implement lifecycle notification, and must not
be cloned, and cannot be distributed to other components. Scenic binds the
ViewRefControl object to the view, so when the view is destroyed, the
destruction of the ViewRefControl triggers a <code>ZX_EVENTPAIR_PEER_CLOSED</code>
signal to all ViewRef holders, thus notifying view death.</p>
<p>Usage: When creating a view, place a ViewRef and ViewRefControl together in
this struct, so that they travel as a unit to the destination component.
This convenience struct allows a protocol author to describe this traveling
pair as one argument. It improves readability and reduces mishandling.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ViewIdentityOnCreation.view_ref">
<td><code>view_ref</code></td>
<td>
<code><a class='link' href='#ViewRef'>ViewRef</a></code>
</td>
<td><p>Stable identifier for the view to be created.</p>
</td>
<td>No default</td>
</tr>
<tr id="ViewIdentityOnCreation.view_ref_control">
<td><code>view_ref_control</code></td>
<td>
<code><a class='link' href='#ViewRefControl'>ViewRefControl</a></code>
</td>
<td><p>A mechanism for lifecycle notification.</p>
</td>
<td>No default</td>
</tr>
</table>
### ViewRef [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewRef data-text="ViewRef"}
*Defined in [fuchsia.ui.views/view_ref.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref.fidl;l=29)*
<p>A ViewRef is a handle to a kernel object which identifies a unique View
across the system. Two ViewRefs to the same View have the same KOID.</p>
<p>Clients use a ViewRef to identify a View, to validate a View, and to
receive a View invalidation signal.</p>
<p>As part of View creation, the client creates a linked
ViewRef/ViewRefControl pair and hands the pair to Scenic (ViewRefControl is
described below). The client must remove the ViewRef's signal
capabilities; otherwise the View is not created.</p>
<p>The client may freely clone its ViewRef and share it, even before sending
it to Scenic.</p>
<p>Example 1. Accessibility accepts a ViewRef from a client to group the
semantic nodes, and semantic operations, associated with a client's View.
It must validate a client's ViewRef with Scenic.</p>
<p>Example 2. We use ViewRefs to create a FocusChain, which identifies Views
considered as &quot;in-focus&quot; down the View hierarchy. When a View is destroyed,
Scenic signals to all FocusChain holders that the ViewRef is now invalid.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ViewRef.reference">
<td><code>reference</code></td>
<td>
<code>handle&lt;eventpair&gt;</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### ViewRefControl [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewRefControl data-text="ViewRefControl"}
*Defined in [fuchsia.ui.views/view_ref.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref.fidl;l=47)*
<p>A ViewRefControl is the peer to a ViewRef. Their <code>reference</code>s are linked.</p>
<p>Like ViewRef, a ViewRefControl is a typed handle to an eventpair. Unlike
ViewRef, a ViewRefControl's handle is unique. Scenic uses this property
when it ties a ViewRefControl to a View, arranged to share fate. When a
View is destroyed, the associated destruction of its ViewRefControl
triggers an automatic <code>ZX_EVENTPAIR_PEER_CLOSED</code> signal sent to all ViewRef
holders; hence ViewRef holders may track View lifetime.</p>
<p>As part of View creation, the client creates a linked
ViewRef/ViewRefControl pair and hands the pair to Scenic (ViewRef is
described above). The client must not clone the ViewRefControl. It must
not remove or modify the ViewRefControl's capabilities; otherwise the View
is not created.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ViewRefControl.reference">
<td><code>reference</code></td>
<td>
<code>handle&lt;eventpair&gt;</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### ViewRefInstalled_Watch_Response {#ViewRefInstalled_Watch_Response data-text="ViewRefInstalled_Watch_Response"}
*Defined in [fuchsia.ui.views/view_ref_installed.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref_installed.fidl;l=42)*
&lt;EMPTY&gt;
### ViewToken [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewToken data-text="ViewToken"}
*Defined in [fuchsia.ui.views/view_token.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_token.fidl;l=26)*
<p>Token that uniquely identifies a <code>View</code>, which is the root point for a
subgraph in the global scene graph. Each <code>ViewToken</code> has exactly one
corresponding <code>ViewHolderToken</code>.</p>
<p>A Scenic client can have its contents referenced from another client by
creating a <code>View</code> resource using this token. The other client must also
create a <code>ViewHolder</code> resource using the corresponding <code>ViewHolderToken</code>.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ViewToken.value">
<td><code>value</code></td>
<td>
<code>handle&lt;eventpair&gt;</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### ViewportCreationToken [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewportCreationToken data-text="ViewportCreationToken"}
*Defined in [fuchsia.ui.views/flatland_tokens.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/flatland_tokens.fidl;l=24)*
<p>Two Flatland instances may be connected in a parent-child relationship. The parent endpoint is
held in a Viewport.</p>
<p>ViewportCreationToken is a typed wrapper for a channel, representing the parent endpoint of the
connection between two Flatlands. No messages will be sent over this channel, because it is only
used as an unclonable object with peer.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="ViewportCreationToken.value">
<td><code>value</code></td>
<td>
<code>handle&lt;channel&gt;</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
## **ENUMS**
### Error [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Error data-text="Error"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.views/focuser.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/focuser.fidl;l=7)*
<p>Problematic situations that occur on Focuser.RequestFocus.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="Error.DENIED">
<td><h3 id="Error.DENIED" class="add-link hide-from-toc">DENIED</h3></td>
<td><code>1</code></td>
<td><p>Value returned when RequestFocus is denied.</p>
</td>
</tr>
</table>
### ViewRefInstalledError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ViewRefInstalledError data-text="ViewRefInstalledError"}
Type: <code>uint32</code>
*Defined in [fuchsia.ui.views/view_ref_installed.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref_installed.fidl;l=7)*
<p>A collection of error codes related to |ViewRefInstalled|.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="ViewRefInstalledError.INVALID_VIEW_REF">
<td><h3 id="ViewRefInstalledError.INVALID_VIEW_REF" class="add-link hide-from-toc">INVALID_VIEW_REF</h3></td>
<td><code>1</code></td>
<td><p>The ViewRef being watched is invalid, or has become invalid.</p>
</td>
</tr>
</table>
## **TABLES**
### FocusState {#FocusState data-text="FocusState"}
*Defined in [fuchsia.ui.views/view_ref_focused.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref_focused.fidl;l=7)*
<p>A ViewRef's state of focus.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="FocusState.focused">
<td><h3 id="FocusState.focused" class="add-link hide-from-toc">1</h3></td>
<td><code>focused</code></td>
<td>
<code>bool</code>
</td>
<td><p>Describes if a ViewRef has gained focus (true), or lost focus (false).</p>
<p>Required field.</p>
</td>
</tr>
</table>
## **UNIONS**
### Command [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Command data-text="Command"}
*Defined in [fuchsia.ui.views/commands.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/commands.fidl;l=9)*
<p>DO NOT USE - Retained for ABI stability in fuchsia.ui.scenic.Command</p>
<p>DO NOT USE</p>
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="Command.empty">
<td><h3 id="Command.empty" class="add-link hide-from-toc">1</h3></td>
<td><code>empty</code></td>
<td>
<code>int32</code>
</td>
<td></td>
</tr>
</table>
### Focuser_RequestFocus_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Focuser_RequestFocus_Result data-text="Focuser_RequestFocus_Result"}
*Defined in [fuchsia.ui.views/focuser.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/focuser.fidl;l=38)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="Focuser_RequestFocus_Result.response">
<td><h3 id="Focuser_RequestFocus_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#Focuser_RequestFocus_Response'>Focuser_RequestFocus_Response</a></code>
</td>
<td></td>
</tr>
<tr id="Focuser_RequestFocus_Result.err">
<td><h3 id="Focuser_RequestFocus_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#Error'>Error</a></code>
</td>
<td></td>
</tr>
</table>
### ViewRefInstalled_Watch_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ViewRefInstalled_Watch_Result data-text="ViewRefInstalled_Watch_Result"}
*Defined in [fuchsia.ui.views/view_ref_installed.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.views/view_ref_installed.fidl;l=42)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="ViewRefInstalled_Watch_Result.response">
<td><h3 id="ViewRefInstalled_Watch_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#ViewRefInstalled_Watch_Response'>ViewRefInstalled_Watch_Response</a></code>
</td>
<td></td>
</tr>
<tr id="ViewRefInstalled_Watch_Result.err">
<td><h3 id="ViewRefInstalled_Watch_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#ViewRefInstalledError'>ViewRefInstalledError</a></code>
</td>
<td></td>
</tr>
</table>