Google Git
Sign in
fuchsia / reference-docs / main / . / f7 / sdk / fidl / fuchsia.element / README.md
blob: fdccc32382ff76e2ba48c773a3e79ce4e84a8e96 [file] [log] [blame] [view]
<link rel="stylesheet" href="../style.css" />
[TOC]
# fuchsia.element
<p><b>Added:7</b></p>
## **PROTOCOLS**
## AnnotationController {#AnnotationController}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=67)*
<p>An interface to create, read, update, and delete annotations,
typically on an element or its view.</p>
### GetAnnotations {#AnnotationController.GetAnnotations}
<p>Returns the current <code>Annotations</code> for the element.</p>
<ul>
<li>error <code>GetAnnotationsError</code> if the annotations could not be returned.</li>
</ul>
#### Request {#AnnotationController.GetAnnotations_Request}
&lt;EMPTY&gt;
#### Response {#AnnotationController.GetAnnotations_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#AnnotationController_GetAnnotations_Result'>AnnotationController_GetAnnotations_Result</a></code>
</td>
</tr>
</table>
### UpdateAnnotations {#AnnotationController.UpdateAnnotations}
<p>Adds, updates, and removes annotations.</p>
<p>The server is expected to adhere to the following conventions:</p>
<ul>
<li>If a key in <code>annotations_to_set</code> is new, a new annotation is added</li>
<li>If a key in <code>annotations_to_set</code> already exists, the annotation value is updated</li>
<li>If a key in <code>annotations_to_delete</code> does not exist, it is ignored</li>
</ul>
<p>The same key cannot appear twice in a call to UpdateAnnotations(). In other words,
to set two Annotations with matching keys is illegal, as is an attempt to set an
Annotation and also delete it.</p>
<p>If the operation results in an error, the annotations remain unchanged,
and will not be partially updated.</p>
<ul>
<li>error <code>UpdateAnnotationsError.INVALID_ARGS</code> if the same key exists in
both <code>annotations_to_set</code> and <code>annotations_to_delete</code>.</li>
<li>error <code>UpdateAnnotationsError.INVALID_ARGS</code> if a key in <code>annotations_to_set</code> or
<code>annotations_to_delete</code> has an empty namespace.</li>
<li>error <code>UpdateAnnotationsError.INVALID_ARGS</code> if an <code>AnnotationValue.buffer</code> in
<code>annotations_to_set</code> could not be read.</li>
<li>error <code>UpdateAnnotationsError.TOO_MANY_ANNOTATIONS</code> if the operation results
in more than <code>MAX_ANNOTATIONS_PER_ELEMENT</code> annotations existing.</li>
</ul>
#### Request {#AnnotationController.UpdateAnnotations_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>annotations_to_set</code></td>
<td>
<code><a class='link' href='#Annotations'>Annotations</a></code>
</td>
</tr>
<tr>
<td><code>annotations_to_delete</code></td>
<td>
<code><a class='link' href='#AnnotationKeys'>AnnotationKeys</a></code>
</td>
</tr>
</table>
#### Response {#AnnotationController.UpdateAnnotations_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#AnnotationController_UpdateAnnotations_Result'>AnnotationController_UpdateAnnotations_Result</a></code>
</td>
</tr>
</table>
### WatchAnnotations {#AnnotationController.WatchAnnotations}
<p>Returns annotations when they have changed, or when this method is
called by the client for the first time.</p>
<p>This operation does not block other requests from the client, but only one
<code>WatchAnnotations</code> request at a time can be made on a connection. If the
client makes a second <code>WatchAnnotations</code> request before waiting for the
previous request to complete, the connection will be closed.</p>
<ul>
<li>error <code>WatchAnnotationsError</code> if the annotations could not be returned.</li>
</ul>
#### Request {#AnnotationController.WatchAnnotations_Request}
&lt;EMPTY&gt;
#### Response {#AnnotationController.WatchAnnotations_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#AnnotationController_WatchAnnotations_Result'>AnnotationController_WatchAnnotations_Result</a></code>
</td>
</tr>
</table>
## Controller {#Controller}
*Defined in [fuchsia.element/element_manager.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/element_manager.fidl;l=105)*
<p>An interface that gives clients of <code>Manager</code> (element proposers) control
over the proposed element's lifecycle and annotations.</p>
<h2>Lifecycle</h2>
<p>The client must keep <code>Controller</code> connected to ensure the element
remains in the session and is not destroyed. Once <code>Controller</code> is closed,
the element and its component will be terminated. The element may also terminate
itself, which will cause <code>Controller</code> to close.</p>
### GetAnnotations {#Controller.GetAnnotations}
<p>Returns the current <code>Annotations</code> for the element.</p>
<ul>
<li>error <code>GetAnnotationsError</code> if the annotations could not be returned.</li>
</ul>
#### Request {#Controller.GetAnnotations_Request}
&lt;EMPTY&gt;
#### Response {#Controller.GetAnnotations_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#AnnotationController_GetAnnotations_Result'>AnnotationController_GetAnnotations_Result</a></code>
</td>
</tr>
</table>
### UpdateAnnotations {#Controller.UpdateAnnotations}
<p>Adds, updates, and removes annotations.</p>
<p>The server is expected to adhere to the following conventions:</p>
<ul>
<li>If a key in <code>annotations_to_set</code> is new, a new annotation is added</li>
<li>If a key in <code>annotations_to_set</code> already exists, the annotation value is updated</li>
<li>If a key in <code>annotations_to_delete</code> does not exist, it is ignored</li>
</ul>
<p>The same key cannot appear twice in a call to UpdateAnnotations(). In other words,
to set two Annotations with matching keys is illegal, as is an attempt to set an
Annotation and also delete it.</p>
<p>If the operation results in an error, the annotations remain unchanged,
and will not be partially updated.</p>
<ul>
<li>error <code>UpdateAnnotationsError.INVALID_ARGS</code> if the same key exists in
both <code>annotations_to_set</code> and <code>annotations_to_delete</code>.</li>
<li>error <code>UpdateAnnotationsError.INVALID_ARGS</code> if a key in <code>annotations_to_set</code> or
<code>annotations_to_delete</code> has an empty namespace.</li>
<li>error <code>UpdateAnnotationsError.INVALID_ARGS</code> if an <code>AnnotationValue.buffer</code> in
<code>annotations_to_set</code> could not be read.</li>
<li>error <code>UpdateAnnotationsError.TOO_MANY_ANNOTATIONS</code> if the operation results
in more than <code>MAX_ANNOTATIONS_PER_ELEMENT</code> annotations existing.</li>
</ul>
#### Request {#Controller.UpdateAnnotations_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>annotations_to_set</code></td>
<td>
<code><a class='link' href='#Annotations'>Annotations</a></code>
</td>
</tr>
<tr>
<td><code>annotations_to_delete</code></td>
<td>
<code><a class='link' href='#AnnotationKeys'>AnnotationKeys</a></code>
</td>
</tr>
</table>
#### Response {#Controller.UpdateAnnotations_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#AnnotationController_UpdateAnnotations_Result'>AnnotationController_UpdateAnnotations_Result</a></code>
</td>
</tr>
</table>
### WatchAnnotations {#Controller.WatchAnnotations}
<p>Returns annotations when they have changed, or when this method is
called by the client for the first time.</p>
<p>This operation does not block other requests from the client, but only one
<code>WatchAnnotations</code> request at a time can be made on a connection. If the
client makes a second <code>WatchAnnotations</code> request before waiting for the
previous request to complete, the connection will be closed.</p>
<ul>
<li>error <code>WatchAnnotationsError</code> if the annotations could not be returned.</li>
</ul>
#### Request {#Controller.WatchAnnotations_Request}
&lt;EMPTY&gt;
#### Response {#Controller.WatchAnnotations_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#AnnotationController_WatchAnnotations_Result'>AnnotationController_WatchAnnotations_Result</a></code>
</td>
</tr>
</table>
## GraphicalPresenter {#GraphicalPresenter}
*Defined in [fuchsia.element/graphical_presenter.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/graphical_presenter.fidl;l=16)*
<p>An interface used to present graphical views.</p>
<p>The <code>GraphicalPresenter</code> protocol is typically implemented by a session component or
its child that presents element views.</p>
<p>The presented views can be annotated with <code>fuchsia.element.Annotations</code> to communicate
presentation properties to the <code>GraphicalPresenter</code>.</p>
### PresentView {#GraphicalPresenter.PresentView}
<p>Presents the view described by <code>view_spec</code>.</p>
<h2>ViewController</h2>
<p><code>view_controller</code> allows clients to receive a <code>ViewController</code> for the
presented view. The client can use the <code>ViewController</code> to control the view's
presentation and receive events.</p>
<p>If <code>view_controller</code> is closed, the client can assume that the view is
no longer being presented, and will not be presented in the future.</p>
<p>If the client closes the <code>view_controller</code>, or does not provide a request
to <code>PresentView</code>, the view may be dismissed at any time with no signal to the client.</p>
<h2>Errors</h2>
<p><code>PresentView</code> errors are signaled by closing <code>view_controller</code>
with an epitaph, <code>ViewControllerEpitaph</code>. See <a class='link' href='#ViewController'>ViewController</a>.</p>
<ul>
<li><code>view_spec</code> describes the view to present</li>
<li><code>annotation_controller</code> a handle to make changes to the respective element's
annotations</li>
<li><code>view_controller_request</code> an optional request for a controller for the view</li>
</ul>
<ul>
<li>error <code>view_spec</code> must contain <code>view_holder_token</code> and <code>view_ref</code> for Gfx views,
OR <code>viewport_creation_token</code> for Flatland views, but never both. If both are
set, error <code>PresentViewError.INVALID_ARGS</code> is thrown.</li>
<li>error <code>PresentViewError.INVALID_ARGS</code> if <code>spec.view_holder_token</code> or
<code>spec.view_ref</code> are missing or invalid</li>
<li>error <code>PresentViewError</code> if the view could not be presented</li>
</ul>
#### Request {#GraphicalPresenter.PresentView_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>view_spec</code></td>
<td>
<code><a class='link' href='#ViewSpec'>ViewSpec</a></code>
</td>
</tr>
<tr>
<td><code>annotation_controller</code></td>
<td>
<code><a class='link' href='#AnnotationController'>AnnotationController</a>?</code>
</td>
</tr>
<tr>
<td><code>view_controller_request</code></td>
<td>
<code>request&lt;<a class='link' href='#ViewController'>ViewController</a>&gt;?</code>
</td>
</tr>
</table>
#### Response {#GraphicalPresenter.PresentView_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#GraphicalPresenter_PresentView_Result'>GraphicalPresenter_PresentView_Result</a></code>
</td>
</tr>
</table>
## Manager {#Manager}
*Defined in [fuchsia.element/element_manager.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/element_manager.fidl;l=25)*
<p>An interface used to add elements to a session.</p>
<p>An <em>element</em> is a component that is expected to be instantiated as a child
of the session and to interact with the user in some way. An <em>element proposer</em>
is a component that calls <code>ProposeElement</code> to add an element to the session.</p>
<p>The session will typically implement <code>Manager</code> and provide it
to its child element proposers.</p>
<p>For example, an element proposer may be a non-interactive application that
listens to the network for a command to display an element to the user.
When it receives the command, the element proposer proposes to add an
element to the session via the <code>Manager</code> protocol. Similarly,
the element proposer may be part of an interactive user interface that
proposes elements based on user input.</p>
### ProposeElement {#Manager.ProposeElement}
<p>Proposes to add an element to the session.</p>
<p>If <code>ProposeElement</code> returns without error, the caller can assume
the element is now part of the session. However, whether or not the
element component is actively running, or not, depends on the session
implementation. For example, a session may decide to conserve resources by
suspending an element which is not visible, or delay the running of an
element until a more appropriate time.</p>
<h2>Spec</h2>
<ul>
<li><code>spec.component_url</code> is required</li>
</ul>
<p>If <code>spec.additional_services</code> is specified,</p>
<ul>
<li>
<p><code>spec.component_url</code> must point to a CFv1 component
(<code>additional_services</code> is not supported for CFv2 components)</p>
</li>
<li>
<p>The <a class='link' href='../fuchsia.sys/'>fuchsia.sys</a>/<a class='link' href='../fuchsia.sys/#ServiceList.host_directory'>ServiceList.host_directory</a> field in
<code>spec.additional_services</code> must be set to a channel to a directory hosting
the services (<a class='link' href='../fuchsia.sys/'>fuchsia.sys</a>/<a class='link' href='../fuchsia.sys/#ServiceList.provider'>ServiceList.provider</a> is not supported
and must be null)</p>
</li>
</ul>
<p>If <code>spec.arguments</code> is specified,</p>
<ul>
<li><code>spec.component_url</code> must point to a CFv1 component
(<code>arguments</code> is not supported for CFv2 components)</li>
</ul>
<ul>
<li><code>spec</code> describes the element to add</li>
<li><code>controller</code> can be used to observe and affect the lifecycle of the
element, and to set and get annotations on the element</li>
</ul>
<ul>
<li>error <code>ProposeElementError.NOT_FOUND</code> if <code>spec.component_url</code> is missing or
could not be resolved</li>
<li>error <code>ProposeElementError.INVALID_ARGS</code>
if <code>spec.additional_services</code>:
<ul>
<li>is specified for a CFv2 <code>spec.component_url</code>, or</li>
<li>does not have a valid <a class='link' href='../fuchsia.sys/'>fuchsia.sys</a>/<a class='link' href='../fuchsia.sys/#ServiceList.host_directory'>ServiceList.host_directory</a>, or</li>
<li>contains a non-null <a class='link' href='../fuchsia.sys/'>fuchsia.sys</a>/<a class='link' href='../fuchsia.sys/#ServiceList.provider'>ServiceList.provider</a>
if <code>spec.arguments</code>:</li>
<li>is specified for a CFv2 <code>spec.component_url</code></li>
</ul>
</li>
</ul>
#### Request {#Manager.ProposeElement_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>spec</code></td>
<td>
<code><a class='link' href='#Spec'>Spec</a></code>
</td>
</tr>
<tr>
<td><code>controller</code></td>
<td>
<code>request&lt;<a class='link' href='#Controller'>Controller</a>&gt;?</code>
</td>
</tr>
</table>
#### Response {#Manager.ProposeElement_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#Manager_ProposeElement_Result'>Manager_ProposeElement_Result</a></code>
</td>
</tr>
</table>
## ViewController {#ViewController}
*Defined in [fuchsia.element/graphical_presenter.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/graphical_presenter.fidl;l=106)*
<p>An interface that gives clients of <code>GraphicalPresenter</code> control over a view
that was presented.</p>
<h2>Lifecycle</h2>
<p>The client must keep <code>ViewController</code> connected to ensure the view is
presented. Once <code>ViewController</code> is closed, the view will be
permanently dismissed.</p>
<p>For example, if the view originates from an element, the component
that manages the element's lifecycle may choose to stop the element's
component once the <code>ViewController</code> is closed.</p>
<h2>Epitaph</h2>
<p>This protocol is closed with an epitaph:</p>
<ul>
<li><code>ZX_OK</code> when the view is dismissed</li>
</ul>
### Dismiss {#ViewController.Dismiss}
<p>Instructs the presenter to dismiss the associated view.</p>
<p>This call results in the <code>ViewController</code> being closed with a
<code>ZX_OK</code> epitaph once any exit animation has been performed, the
view/view holder connection has been severed, and the component
instance serving the view can be terminated.</p>
#### Request {#ViewController.Dismiss_Request}
&lt;EMPTY&gt;
### OnPresented {#ViewController.OnPresented}
<p>Informs the view controller that the view was presented successfully.</p>
#### Response {#ViewController.OnPresented_Response}
&lt;EMPTY&gt;
## **STRUCTS**
### Annotation [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#Annotation data-text="Annotation"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=51)*
<p>An annotation defined dynamically by key/value pair.</p>
<p>The Session Framework does not constrain the contents of <code>key</code> and <code>value</code>
in any way. Cooperating components that exchange annotations must define
and validate annotation entries based on their own conventions.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="Annotation.key">
<td><code>key</code></td>
<td>
<code><a class='link' href='#AnnotationKey'>AnnotationKey</a></code>
</td>
<td><p>An identfier for this annotation.</p>
</td>
<td>No default</td>
</tr>
<tr id="Annotation.value">
<td><code>value</code></td>
<td>
<code><a class='link' href='#AnnotationValue'>AnnotationValue</a></code>
</td>
<td><p>The content of this annotation.</p>
</td>
<td>No default</td>
</tr>
</table>
### AnnotationController_GetAnnotations_Response [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#AnnotationController_GetAnnotations_Response data-text="AnnotationController_GetAnnotations_Response"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=99)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="AnnotationController_GetAnnotations_Response.annotations">
<td><code>annotations</code></td>
<td>
<code><a class='link' href='#Annotations'>Annotations</a></code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### AnnotationController_UpdateAnnotations_Response {#AnnotationController_UpdateAnnotations_Response data-text="AnnotationController_UpdateAnnotations_Response"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=94)*
&lt;EMPTY&gt;
### AnnotationController_WatchAnnotations_Response [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#AnnotationController_WatchAnnotations_Response data-text="AnnotationController_WatchAnnotations_Response"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=113)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="AnnotationController_WatchAnnotations_Response.annotations">
<td><code>annotations</code></td>
<td>
<code><a class='link' href='#Annotations'>Annotations</a></code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### AnnotationKey {#AnnotationKey data-text="AnnotationKey"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=16)*
<p>The key of an <a class='link' href='../fuchsia.element/'>fuchsia.element</a>/<a class='link' href='../fuchsia.element/#Annotation'>Annotation</a>.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="AnnotationKey.namespace">
<td><code>namespace</code></td>
<td>
<code>string[128]</code>
</td>
<td><p>A namespace that disambiguates groups of keys across clients.</p>
<p>This is intended to group related keys together under the same
identifier, and avoid naming collisions. For example, a session may
use a custom namespace to define annotations that are specific
to its implementation.</p>
<p>The namespace is required and must be non-empty.</p>
<p>The namespace &quot;global&quot; is represents the global namespace, reserved for
annotations common across many products and session components.</p>
<p>To ensure compatibility, clients should use a unique namespace,
like a UUID or the client's component URL, when introducing new keys.</p>
</td>
<td>No default</td>
</tr>
<tr id="AnnotationKey.value">
<td><code>value</code></td>
<td>
<code>string[128]</code>
</td>
<td><p>An identifier for this annotation, uniquely identifying the annotation
within <code>namespace</code>.</p>
</td>
<td>No default</td>
</tr>
</table>
### GraphicalPresenter_PresentView_Response {#GraphicalPresenter_PresentView_Response data-text="GraphicalPresenter_PresentView_Response"}
*Defined in [fuchsia.element/graphical_presenter.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/graphical_presenter.fidl;l=50)*
&lt;EMPTY&gt;
### Manager_ProposeElement_Response {#Manager_ProposeElement_Response data-text="Manager_ProposeElement_Response"}
*Defined in [fuchsia.element/element_manager.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/element_manager.fidl;l=69)*
&lt;EMPTY&gt;
## **ENUMS**
### GetAnnotationsError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#GetAnnotationsError data-text="GetAnnotationsError"}
Type: <code>uint32</code>
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=129)*
<p>An error returned from <code>ElementController/GetAnnotations</code>.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="GetAnnotationsError.BUFFER_READ_FAILED">
<td><h3 id="GetAnnotationsError.BUFFER_READ_FAILED" class="add-link hide-from-toc">BUFFER_READ_FAILED</h3></td>
<td><code>1</code></td>
<td><p>The <code>AnnotationValue.buffer</code> of an annotation could not be read.</p>
</td>
</tr>
</table>
### PresentViewError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#PresentViewError data-text="PresentViewError"}
Type: <code>uint32</code>
*Defined in [fuchsia.element/graphical_presenter.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/graphical_presenter.fidl;l=54)*
<p>An error returned when <code>GraphicalPresenter</code> fails to present a view.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="PresentViewError.INVALID_ARGS">
<td><h3 id="PresentViewError.INVALID_ARGS" class="add-link hide-from-toc">INVALID_ARGS</h3></td>
<td><code>1</code></td>
<td><p>The provided <code>ViewSpec</code> is malformed.</p>
</td>
</tr>
</table>
### ProposeElementError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ProposeElementError data-text="ProposeElementError"}
Type: <code>uint32</code>
*Defined in [fuchsia.element/element_manager.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/element_manager.fidl;l=88)*
<p>Errors that can be returned when attempting to add elements to a session.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="ProposeElementError.INVALID_ARGS">
<td><h3 id="ProposeElementError.INVALID_ARGS" class="add-link hide-from-toc">INVALID_ARGS</h3></td>
<td><code>1</code></td>
<td><p>The element spec was malformed.</p>
</td>
</tr>
<tr id="ProposeElementError.NOT_FOUND">
<td><h3 id="ProposeElementError.NOT_FOUND" class="add-link hide-from-toc">NOT_FOUND</h3></td>
<td><code>2</code></td>
<td><p>The element's component URL could not be resolved.</p>
</td>
</tr>
</table>
### UpdateAnnotationsError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#UpdateAnnotationsError data-text="UpdateAnnotationsError"}
Type: <code>uint32</code>
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=119)*
<p>An error returned from <code>AnnotationController/UpdateAnnotations</code></p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="UpdateAnnotationsError.INVALID_ARGS">
<td><h3 id="UpdateAnnotationsError.INVALID_ARGS" class="add-link hide-from-toc">INVALID_ARGS</h3></td>
<td><code>1</code></td>
<td><p>The arguments passed to <code>UpdateAnnotations</code> are malformed.</p>
</td>
</tr>
<tr id="UpdateAnnotationsError.TOO_MANY_ANNOTATIONS">
<td><h3 id="UpdateAnnotationsError.TOO_MANY_ANNOTATIONS" class="add-link hide-from-toc">TOO_MANY_ANNOTATIONS</h3></td>
<td><code>2</code></td>
<td><p>The total number of annotations will exceed <a class='link' href='#MAX_ANNOTATIONS_PER_ELEMENT'>MAX_ANNOTATIONS_PER_ELEMENT</a>
as a result of updating the annotations.</p>
</td>
</tr>
</table>
### WatchAnnotationsError [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#WatchAnnotationsError data-text="WatchAnnotationsError"}
Type: <code>uint32</code>
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=136)*
<p>An error returned from <code>AnnotationController/WatchAnnotations</code> and
<code>ElementController/WatchAnnotations</code>.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="WatchAnnotationsError.BUFFER_READ_FAILED">
<td><h3 id="WatchAnnotationsError.BUFFER_READ_FAILED" class="add-link hide-from-toc">BUFFER_READ_FAILED</h3></td>
<td><code>1</code></td>
<td><p>The <code>AnnotationValue.buffer</code> of an annotation could not be read.</p>
</td>
</tr>
</table>
## **TABLES**
### Spec [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#Spec data-text="Spec"}
*Defined in [fuchsia.element/element_manager.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/element_manager.fidl;l=73)*
<p>Description of an element to be added to a session.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="Spec.component_url">
<td><h3 id="Spec.component_url" class="add-link hide-from-toc">1</h3></td>
<td><code>component_url</code></td>
<td>
<code><a class='link' href='../fuchsia.url/'>fuchsia.url</a>/<a class='link' href='../fuchsia.url/#Url'>Url</a></code>
</td>
<td><p>The component URL of the element. Required.</p>
</td>
</tr>
<tr id="Spec.annotations">
<td><h3 id="Spec.annotations" class="add-link hide-from-toc">2</h3></td>
<td><code>annotations</code></td>
<td>
<code><a class='link' href='#Annotations'>Annotations</a></code>
</td>
<td><p>Initial annotations on the element. Required, but can be an empty vector.</p>
</td>
</tr>
<tr id="Spec.additional_services">
<td><h3 id="Spec.additional_services" class="add-link hide-from-toc">3</h3></td>
<td><code>additional_services</code></td>
<td>
<code><a class='link' href='../fuchsia.sys/'>fuchsia.sys</a>/<a class='link' href='../fuchsia.sys/#ServiceList'>ServiceList</a></code>
</td>
<td><p>A list of services passed to the Element. Optional.</p>
</td>
</tr>
<tr id="Spec.arguments">
<td><h3 id="Spec.arguments" class="add-link hide-from-toc">4</h3></td>
<td><code>arguments</code></td>
<td>
<code>vector&lt;string&gt;</code>
</td>
<td><p>Arguments provided to the component. Optional.</p>
</td>
</tr>
</table>
### ViewSpec [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ViewSpec data-text="ViewSpec"}
*Defined in [fuchsia.element/graphical_presenter.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/graphical_presenter.fidl;l=60)*
<p>A description of a view that can be presented by a <code>GraphicalPresenter</code>.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="ViewSpec.view_holder_token">
<td><h3 id="ViewSpec.view_holder_token" class="add-link hide-from-toc">1</h3></td>
<td><code>view_holder_token</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewHolderToken'>ViewHolderToken</a></code>
</td>
<td><p>The view holder token for the presented Gfx view. Must be unset for
Flatland views.</p>
</td>
</tr>
<tr id="ViewSpec.view_ref">
<td><h3 id="ViewSpec.view_ref" class="add-link hide-from-toc">2</h3></td>
<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>
<td><p>The <code>ViewRef</code> of the presented Gfx view. Must be unset for Flatland
views.</p>
</td>
</tr>
<tr id="ViewSpec.viewport_creation_token">
<td><h3 id="ViewSpec.viewport_creation_token" class="add-link hide-from-toc">4</h3></td>
<td><code>viewport_creation_token</code></td>
<td>
<code><a class='link' href='../fuchsia.ui.views/'>fuchsia.ui.views</a>/<a class='link' href='../fuchsia.ui.views/#ViewportCreationToken'>ViewportCreationToken</a></code>
</td>
<td><p>The viewport creation token for the presented Flatland view. Must be
unset for Gfx views.</p>
</td>
</tr>
<tr id="ViewSpec.annotations">
<td><h3 id="ViewSpec.annotations" class="add-link hide-from-toc">3</h3></td>
<td><code>annotations</code></td>
<td>
<code><a class='link' href='#Annotations'>Annotations</a></code>
</td>
<td><p>The annotations associated with the presented view.</p>
<p>The presenter must observe incoming annotations and update the presentation
accordingly.</p>
<p>For views that come from elements, the annotations are expected to be the same
as the annotations for the element. For example, if the <code>GraphicalPresenter</code>
component uses <code>ElementManager</code> to add an element to the session, and gives it
an annotation, the presenter can expect that annotation to be passed back in
<code>ViewSpec.annotations</code> for the associated view.</p>
<p>Optional.</p>
</td>
</tr>
</table>
## **UNIONS**
### AnnotationController_GetAnnotations_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#AnnotationController_GetAnnotations_Result data-text="AnnotationController_GetAnnotations_Result"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=99)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="AnnotationController_GetAnnotations_Result.response">
<td><h3 id="AnnotationController_GetAnnotations_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#AnnotationController_GetAnnotations_Response'>AnnotationController_GetAnnotations_Response</a></code>
</td>
<td></td>
</tr>
<tr id="AnnotationController_GetAnnotations_Result.err">
<td><h3 id="AnnotationController_GetAnnotations_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#GetAnnotationsError'>GetAnnotationsError</a></code>
</td>
<td></td>
</tr>
</table>
### AnnotationController_UpdateAnnotations_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#AnnotationController_UpdateAnnotations_Result data-text="AnnotationController_UpdateAnnotations_Result"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=94)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="AnnotationController_UpdateAnnotations_Result.response">
<td><h3 id="AnnotationController_UpdateAnnotations_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#AnnotationController_UpdateAnnotations_Response'>AnnotationController_UpdateAnnotations_Response</a></code>
</td>
<td></td>
</tr>
<tr id="AnnotationController_UpdateAnnotations_Result.err">
<td><h3 id="AnnotationController_UpdateAnnotations_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#UpdateAnnotationsError'>UpdateAnnotationsError</a></code>
</td>
<td></td>
</tr>
</table>
### AnnotationController_WatchAnnotations_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#AnnotationController_WatchAnnotations_Result data-text="AnnotationController_WatchAnnotations_Result"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=113)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="AnnotationController_WatchAnnotations_Result.response">
<td><h3 id="AnnotationController_WatchAnnotations_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#AnnotationController_WatchAnnotations_Response'>AnnotationController_WatchAnnotations_Response</a></code>
</td>
<td></td>
</tr>
<tr id="AnnotationController_WatchAnnotations_Result.err">
<td><h3 id="AnnotationController_WatchAnnotations_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#WatchAnnotationsError'>WatchAnnotationsError</a></code>
</td>
<td></td>
</tr>
</table>
### AnnotationValue [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#AnnotationValue data-text="AnnotationValue"}
*Defined in [fuchsia.element/annotations.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=41)*
<p>The value of an <a class='link' href='../fuchsia.element/'>fuchsia.element</a>/<a class='link' href='../fuchsia.element/#Annotation'>Annotation</a>.</p>
<p>The actual field used depends on the type of annotation.</p>
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="AnnotationValue.text">
<td><h3 id="AnnotationValue.text" class="add-link hide-from-toc">1</h3></td>
<td><code>text</code></td>
<td>
<code>string</code>
</td>
<td></td>
</tr>
<tr id="AnnotationValue.buffer">
<td><h3 id="AnnotationValue.buffer" class="add-link hide-from-toc">2</h3></td>
<td><code>buffer</code></td>
<td>
<code><a class='link' href='../fuchsia.mem/'>fuchsia.mem</a>/<a class='link' href='../fuchsia.mem/#Buffer'>Buffer</a></code>
</td>
<td></td>
</tr>
</table>
### GraphicalPresenter_PresentView_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#GraphicalPresenter_PresentView_Result data-text="GraphicalPresenter_PresentView_Result"}
*Defined in [fuchsia.element/graphical_presenter.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/graphical_presenter.fidl;l=50)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="GraphicalPresenter_PresentView_Result.response">
<td><h3 id="GraphicalPresenter_PresentView_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#GraphicalPresenter_PresentView_Response'>GraphicalPresenter_PresentView_Response</a></code>
</td>
<td></td>
</tr>
<tr id="GraphicalPresenter_PresentView_Result.err">
<td><h3 id="GraphicalPresenter_PresentView_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#PresentViewError'>PresentViewError</a></code>
</td>
<td></td>
</tr>
</table>
### Manager_ProposeElement_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Manager_ProposeElement_Result data-text="Manager_ProposeElement_Result"}
*Defined in [fuchsia.element/element_manager.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/element_manager.fidl;l=69)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="Manager_ProposeElement_Result.response">
<td><h3 id="Manager_ProposeElement_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#Manager_ProposeElement_Response'>Manager_ProposeElement_Response</a></code>
</td>
<td></td>
</tr>
<tr id="Manager_ProposeElement_Result.err">
<td><h3 id="Manager_ProposeElement_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#ProposeElementError'>ProposeElementError</a></code>
</td>
<td></td>
</tr>
</table>
## **CONSTANTS**
<table>
<tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
<tr id="MAX_ANNOTATIONS_PER_ELEMENT">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=13">MAX_ANNOTATIONS_PER_ELEMENT</a></td>
<td>
<code>1024</code>
</td>
<td><code>uint32</code></td>
<td><p>Maximum number of annotations for a single element or view.</p>
</td>
</tr>
<tr id="MAX_ANNOTATION_KEY_NAMESPACE_SIZE">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=9">MAX_ANNOTATION_KEY_NAMESPACE_SIZE</a></td>
<td>
<code>128</code>
</td>
<td><code>uint32</code></td>
<td><p>Maximum length of <code>AnnotationKey.namespace</code>.</p>
</td>
</tr>
<tr id="MAX_ANNOTATION_KEY_VALUE_SIZE">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=11">MAX_ANNOTATION_KEY_VALUE_SIZE</a></td>
<td>
<code>128</code>
</td>
<td><code>uint32</code></td>
<td><p>Maximum length of <code>AnnotationKey.value</code>.</p>
</td>
</tr>
</table>
## **TYPE ALIASES**
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="AnnotationKeys">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=63">AnnotationKeys</a></td>
<td>
<code>vector</code>[<code><a class='link' href='#MAX_ANNOTATIONS_PER_ELEMENT'>MAX_ANNOTATIONS_PER_ELEMENT</a></code>]</td>
<td><p>A list of annotation keys.</p>
</td>
</tr>
<tr id="Annotations">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.element/annotations.fidl;l=60">Annotations</a></td>
<td>
<code>vector</code>[<code><a class='link' href='#MAX_ANNOTATIONS_PER_ELEMENT'>MAX_ANNOTATIONS_PER_ELEMENT</a></code>]</td>
<td><p>A list of annotations on an element.</p>
</td>
</tr>
</table>