fuchsia.element

PROTOCOLS

AnnotationController

Defined in fuchsia.element/annotations.fidl

An interface to create, read, update, and delete annotations, typically on an element or its view.

GetAnnotations

Returns the current Annotations for the element.

error GetAnnotationsError if the annotations could not be returned.

Request

<EMPTY>

Response

Name	Type
`result`	`AnnotationController_GetAnnotations_Result`

UpdateAnnotations

Adds, updates, and removes annotations.

The server is expected to adhere to the following conventions:

If a key in annotations_to_set is new, a new annotation is added
If a key in annotations_to_set already exists, the annotation value is updated
If a key in annotations_to_delete does not exist, it is ignored

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.

If the operation results in an error, the annotations remain unchanged, and will not be partially updated.

error UpdateAnnotationsError.INVALID_ARGS if the same key exists in both annotations_to_set and annotations_to_delete.
error UpdateAnnotationsError.INVALID_ARGS if a key in annotations_to_set or annotations_to_delete has an empty namespace.
error UpdateAnnotationsError.INVALID_ARGS if an AnnotationValue.buffer in annotations_to_set could not be read.
error UpdateAnnotationsError.TOO_MANY_ANNOTATIONS if the operation results in more than MAX_ANNOTATIONS_PER_ELEMENT annotations existing.

Request

Name	Type
`annotations_to_set`	`Annotations`
`annotations_to_delete`	`AnnotationKeys`

Response

Name	Type
`result`	`AnnotationController_UpdateAnnotations_Result`

Controller

Defined in fuchsia.element/element_manager.fidl

An interface that gives clients of Manager (element proposers) control over the proposed element's lifecycle and annotations.

Lifecycle

The client must keep Controller connected to ensure the element remains in the session and is not destroyed. Once Controller is closed, the element and its component will be terminated. The element may also terminate itself, which will cause Controller to close.

GetAnnotations

Returns the current Annotations for the element.

error GetAnnotationsError if the annotations could not be returned.

Request

<EMPTY>

Response

Name	Type
`result`	`AnnotationController_GetAnnotations_Result`

UpdateAnnotations

Adds, updates, and removes annotations.

The server is expected to adhere to the following conventions:

If a key in annotations_to_set is new, a new annotation is added
If a key in annotations_to_set already exists, the annotation value is updated
If a key in annotations_to_delete does not exist, it is ignored

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.

If the operation results in an error, the annotations remain unchanged, and will not be partially updated.

error UpdateAnnotationsError.INVALID_ARGS if the same key exists in both annotations_to_set and annotations_to_delete.
error UpdateAnnotationsError.INVALID_ARGS if a key in annotations_to_set or annotations_to_delete has an empty namespace.
error UpdateAnnotationsError.INVALID_ARGS if an AnnotationValue.buffer in annotations_to_set could not be read.
error UpdateAnnotationsError.TOO_MANY_ANNOTATIONS if the operation results in more than MAX_ANNOTATIONS_PER_ELEMENT annotations existing.

Request

Name	Type
`annotations_to_set`	`Annotations`
`annotations_to_delete`	`AnnotationKeys`

Response

Name	Type
`result`	`AnnotationController_UpdateAnnotations_Result`

GraphicalPresenter

Defined in fuchsia.element/graphical_presenter.fidl

An interface used to present graphical views.

The GraphicalPresenter protocol is typically implemented by a session component or its child that presents element views.

The presented views can be annotated with fuchsia.element.Annotations to communicate presentation properties to the GraphicalPresenter.

PresentView

Presents the view described by view_spec.

ViewController

view_controller allows clients to receive a ViewController for the presented view. The client can use the ViewController to control the view's presentation and receive events.

If view_controller is closed, the client can assume that the view is no longer being presented, and will not be presented in the future.

If the client closes the view_controller, or does not provide a request to PresentView, the view may be dismissed at any time with no signal to the client.

Errors

PresentView errors are signaled by closing view_controller with an epitaph, ViewControllerEpitaph. See ViewController.

view_spec describes the view to present
annotation_controller a handle to make changes to the respective element's annotations
view_controller_request an optional request for a controller for the view

error PresentViewError.INVALID_ARGS if spec.view_holder_token or spec.view_ref are missing or invalid
error PresentViewError if the view could not be presented

Request

Name	Type
`view_spec`	`ViewSpec`
`annotation_controller`	`AnnotationController?`
`view_controller_request`	`request<ViewController>?`

Response

Name	Type
`result`	`GraphicalPresenter_PresentView_Result`

Manager

Defined in fuchsia.element/element_manager.fidl

An interface used to add elements to a session.

An element 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 element proposer is a component that calls ProposeElement to add an element to the session.

The session will typically implement Manager and provide it to its child element proposers.

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 Manager protocol. Similarly, the element proposer may be part of an interactive user interface that proposes elements based on user input.

ProposeElement

Proposes to add an element to the session.

If ProposeElement 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.

Spec

spec.component_url is required

If spec.additional_services is specified,

spec.component_url must point to a CFv1 component (additional_services is not supported for CFv2 components)
The fuchsia.sys/ServiceList.host_directory field in spec.additional_services must be set to a channel to a directory hosting the services (fuchsia.sys/ServiceList.provider is not supported and must be null)

spec describes the element to add
controller can be used to observe and affect the lifecycle of the element, and to set and get annotations on the element

error ProposeElementError.NOT_FOUND if spec.component_url is missing or could not be resolved
error ProposeElementError.INVALID_ARGS if spec.additional_services:
- is specified for a CFv2 spec.component_url, or
- does not have a valid fuchsia.sys/ServiceList.host_directory, or
- contains a non-null fuchsia.sys/ServiceList.provider

Request

Name	Type
`spec`	`Spec`
`controller`	`request<Controller>?`

Response

Name	Type
`result`	`Manager_ProposeElement_Result`

ViewController

Defined in fuchsia.element/graphical_presenter.fidl

An interface that gives clients of GraphicalPresenter control over a view that was presented.

Lifecycle

The client must keep ViewController connected to ensure the view is presented. Once ViewController is closed, the view will be permanently dismissed.

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 ViewController is closed.

Epitaph

This protocol is closed with an epitaph:

ZX_OK when the view is dismissed

Dismiss

Instructs the presenter to dismiss the associated view.

This call results in the ViewController being closed with a ZX_OK 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.

Request

<EMPTY>

OnPresented

Informs the view controller that the view was presented successfully.

Response

<EMPTY>

STRUCTS

Annotation resource

Defined in fuchsia.element/annotations.fidl

An annotation defined dynamically by key/value pair.

The Session Framework does not constrain the contents of key and value in any way. Cooperating components that exchange annotations must define and validate annotation entries based on their own conventions.

Field	Type	Description	Default
`key`	`AnnotationKey`	An identfier for this annotation.	No default
`value`	`AnnotationValue`	The content of this annotation.	No default

AnnotationController_GetAnnotations_Response resource

Defined in fuchsia.element/annotations.fidl

Field	Type	Description	Default
`annotations`	`Annotations`		No default

AnnotationController_UpdateAnnotations_Response

Defined in fuchsia.element/annotations.fidl

<EMPTY>

AnnotationKey

Defined in fuchsia.element/annotations.fidl

The key of an fuchsia.element/Annotation.

Field Type Description Default

Field	Type	Description	Default
`namespace`	`string[128]`	A namespace that disambiguates groups of keys across clients. 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. The namespace is required and must be non-empty. The namespace "global" is represents the global namespace, reserved for annotations common across many products and session components. To ensure compatibility, clients should use a unique namespace, like a UUID or the client's component URL, when introducing new keys.	No default
`value`	`string[128]`	An identifier for this annotation, uniquely identifying the annotation within `namespace`.	No default

namespace

string[128]

A namespace that disambiguates groups of keys across clients.

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.

The namespace is required and must be non-empty.

The namespace "global" is represents the global namespace, reserved for annotations common across many products and session components.

To ensure compatibility, clients should use a unique namespace, like a UUID or the client's component URL, when introducing new keys.

No default

value

string[128]

An identifier for this annotation, uniquely identifying the annotation within namespace.

No default

GraphicalPresenter_PresentView_Response

Defined in fuchsia.element/graphical_presenter.fidl

<EMPTY>

Manager_ProposeElement_Response

Defined in fuchsia.element/element_manager.fidl

<EMPTY>

ENUMS

GetAnnotationsError strict

Type: uint32

Defined in fuchsia.element/annotations.fidl

An error returned from ElementController/GetAnnotations.

Name	Value	Description
`BUFFER_READ_FAILED`	`1`	The `AnnotationValue.buffer` of an annotation could not be read.

PresentViewError strict

Type: uint32

Defined in fuchsia.element/graphical_presenter.fidl

An error returned when GraphicalPresenter fails to present a view.

Name	Value	Description
`INVALID_ARGS`	`1`	The provided `ViewSpec` is malformed.

ProposeElementError strict

Type: uint32

Defined in fuchsia.element/element_manager.fidl

Errors that can be returned when attempting to add elements to a session.

Name	Value	Description
`INVALID_ARGS`	`1`	The element spec was malformed.
`NOT_FOUND`	`2`	The element's component URL could not be resolved.

UpdateAnnotationsError strict

Type: uint32

Defined in fuchsia.element/annotations.fidl

An error returned from AnnotationController/UpdateAnnotations

Name	Value	Description
`INVALID_ARGS`	`1`	The arguments passed to `UpdateAnnotations` are malformed.
`TOO_MANY_ANNOTATIONS`	`2`	The total number of annotations will exceed MAX_ANNOTATIONS_PER_ELEMENT as a result of updating the annotations.

TABLES

Spec resource

Defined in fuchsia.element/element_manager.fidl

Description of an element to be added to a session.

Ordinal	Field	Type	Description
1	`component_url`	`fuchsia.url/Url`	The component URL of the element. Required.
2	`annotations`	`Annotations`	Initial annotations on the element. Required, but can be an empty vector.
3	`additional_services`	`fuchsia.sys/ServiceList`	A list of services passed to the Element. Optional.

ViewSpec resource

Defined in fuchsia.element/graphical_presenter.fidl

A description of a view that can be presented by a GraphicalPresenter.

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`view_holder_token`	`fuchsia.ui.views/ViewHolderToken`	The view holder token for the presented view. Required.
2	`view_ref`	`fuchsia.ui.views/ViewRef`	The `ViewRef` of the presented view. Required.
3	`annotations`	`Annotations`	The annotations associated with the presented view. The presenter must observe incoming annotations and update the presentation accordingly. For views that come from elements, the annotations are expected to be the same as the annotations for the element. For example, if the `GraphicalPresenter` component uses `ElementManager` to add an element to the session, and gives it an annotation, the presenter can expect that annotation to be passed back in `ViewSpec.annotations` for the associated view. Optional.

view_holder_token

fuchsia.ui.views/ViewHolderToken

The view holder token for the presented view. Required.

view_ref

fuchsia.ui.views/ViewRef

The ViewRef of the presented view. Required.

annotations

Annotations

The annotations associated with the presented view.

The presenter must observe incoming annotations and update the presentation accordingly.

For views that come from elements, the annotations are expected to be the same as the annotations for the element. For example, if the GraphicalPresenter component uses ElementManager to add an element to the session, and gives it an annotation, the presenter can expect that annotation to be passed back in ViewSpec.annotations for the associated view.

Optional.

UNIONS

AnnotationController_GetAnnotations_Result strict resource

Defined in fuchsia.element/annotations.fidl

Ordinal
Variant	Type	Description
1	`response`	`AnnotationController_GetAnnotations_Response`
2	`err`	`GetAnnotationsError`

AnnotationController_UpdateAnnotations_Result strict

Defined in fuchsia.element/annotations.fidl

Ordinal
Variant	Type	Description
1	`response`	`AnnotationController_UpdateAnnotations_Response`
2	`err`	`UpdateAnnotationsError`

AnnotationValue strict resource

Defined in fuchsia.element/annotations.fidl

The value of an fuchsia.element/Annotation.

The actual field used depends on the type of annotation.

Ordinal
Variant	Type	Description
1	`text`	`string`
2	`buffer`	`fuchsia.mem/Buffer`

GraphicalPresenter_PresentView_Result strict

Defined in fuchsia.element/graphical_presenter.fidl

Ordinal
Variant	Type	Description
1	`response`	`GraphicalPresenter_PresentView_Response`
2	`err`	`PresentViewError`

Manager_ProposeElement_Result strict

Defined in fuchsia.element/element_manager.fidl

Ordinal
Variant	Type	Description
1	`response`	`Manager_ProposeElement_Response`
2	`err`	`ProposeElementError`

CONSTANTS

Name	Value	Type	Description
MAX_ANNOTATIONS_PER_ELEMENT	`1024`	`uint32`	Maximum number of annotations for a single element or view.
MAX_ANNOTATION_KEY_NAMESPACE_SIZE	`128`	`uint32`	Maximum length of `AnnotationKey.namespace`.
MAX_ANNOTATION_KEY_VALUE_SIZE	`128`	`uint32`	Maximum length of `AnnotationKey.value`.

TYPE ALIASES

Name	Value	Description
AnnotationKeys	`vector`[`MAX_ANNOTATIONS_PER_ELEMENT`]	A list of annotation keys.
Annotations	`vector`[`MAX_ANNOTATIONS_PER_ELEMENT`]	A list of annotations on an element.