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 bothannotations_to_set
andannotations_to_delete
. - error
UpdateAnnotationsError.INVALID_ARGS
if a key inannotations_to_set
orannotations_to_delete
has an empty namespace. - error
UpdateAnnotationsError.INVALID_ARGS
if anAnnotationValue.buffer
inannotations_to_set
could not be read. - error
UpdateAnnotationsError.TOO_MANY_ANNOTATIONS
if the operation results in more thanMAX_ANNOTATIONS_PER_ELEMENT
annotations existing.
Request
Name | Type |
---|---|
annotations_to_set |
Annotations
|
annotations_to_delete |
AnnotationKeys
|
Response
Name | Type |
---|---|
result |
AnnotationController_UpdateAnnotations_Result
|
WatchAnnotations
Returns the full set of Annotations
when one or more of them have changed, or
when this method is called by the client for the first time.
This operation does not block other requests from the client, but only one
WatchAnnotations
request at a time can be made on a connection. If the
client makes a second WatchAnnotations
request before waiting for the
previous request to complete, the connection will be closed.
- error
WatchAnnotationsError
if the annotations could not be returned.
Request
<EMPTY>
Response
Name | Type |
---|---|
result |
AnnotationController_WatchAnnotations_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 bothannotations_to_set
andannotations_to_delete
. - error
UpdateAnnotationsError.INVALID_ARGS
if a key inannotations_to_set
orannotations_to_delete
has an empty namespace. - error
UpdateAnnotationsError.INVALID_ARGS
if anAnnotationValue.buffer
inannotations_to_set
could not be read. - error
UpdateAnnotationsError.TOO_MANY_ANNOTATIONS
if the operation results in more thanMAX_ANNOTATIONS_PER_ELEMENT
annotations existing.
Request
Name | Type |
---|---|
annotations_to_set |
Annotations
|
annotations_to_delete |
AnnotationKeys
|
Response
Name | Type |
---|---|
result |
AnnotationController_UpdateAnnotations_Result
|
WatchAnnotations
Returns the full set of Annotations
when one or more of them have changed, or
when this method is called by the client for the first time.
This operation does not block other requests from the client, but only one
WatchAnnotations
request at a time can be made on a connection. If the
client makes a second WatchAnnotations
request before waiting for the
previous request to complete, the connection will be closed.
- error
WatchAnnotationsError
if the annotations could not be returned.
Request
<EMPTY>
Response
Name | Type |
---|---|
result |
AnnotationController_WatchAnnotations_Result
|
GraphicalPresenter
Defined in fuchsia.element/graphical_presenter.fidl
An interface used to instruct a server to present graphical views, and observe and control the view's lifecycle.
PresentView
Presents the view described by view_spec
.
If view_controller_request
is provided, it will be connected to a ViewController
implemented by the GraphicalPresenter
server. When the view is dismissed,
the ViewController
channel is closed with a ZX_OK
, at which point it is safe
to clean up resources backing the view. To dismiss the view, the client should
call ViewController.Dismiss()
and wait for the ZX_OK
epitaph.
Not providing a view_controller_request
handle will make it impossible for the
client to observe the view's lifecycle.
view_spec
describes the view to presentannotation_controller
a handle to anAnnotationController
, allowing theGraphicalPresenter
server to observe and update the view's annotations.view_controller_request
an optional request for a controller for the view
- error
view_spec
must containview_holder_token
andview_ref
for Gfx views, ORviewport_creation_token
for Flatland views, but never both. If both are set, errorPresentViewError.INVALID_ARGS
is returned. - error
PresentViewError.INVALID_ARGS
ifspec.view_holder_token
orspec.view_ref
are missing or invalid.
Request
Name | Type |
---|---|
view_spec |
ViewSpec
|
annotation_controller |
AnnotationController?
|
view_controller_request |
server_end<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
spec
describes the element to addcontroller
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
ifspec.component_url
could not be resolved - error
ProposeElementError.INVALID_ARGS
if a required field is not present or annotations are invalid
Request
Name | Type |
---|---|
spec |
Spec
|
controller |
server_end<Controller>?
|
Response
Name | Type |
---|---|
result |
Manager_ProposeElement_Result
|
ViewController
Defined in fuchsia.element/graphical_presenter.fidl
Gives clients of GraphicalPresenter
control over an individual view
presented through PresentView()
.
Dismiss
Instructs the presenter to dismiss the associated view. Once dismissed,
the ViewController
channel is closed with a ZX_OK
epitaph. At this
point, it is safe to clean up any resources (such as terminating
a component) backing the view.
Clients should call Dismiss()
prior to closing the ViewController
channel themselves.
Request
<EMPTY>
OnPresented
An event that signals that the view is now being presented.
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>
AnnotationController_WatchAnnotations_Response resource
Defined in fuchsia.element/annotations.fidl
Field | Type | Description | Default |
---|---|---|---|
annotations |
Annotations
|
No default |
AnnotationKey
Defined in fuchsia.element/annotations.fidl
The key of an fuchsia.element/Annotation.
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 |
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 |
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 |
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 |
TOO_MANY_ANNOTATIONS |
2 |
The total number of annotations will exceed MAX_ANNOTATIONS_PER_ELEMENT as a result of updating the annotations. |
WatchAnnotationsError flexible
Type: uint32
Defined in fuchsia.element/annotations.fidl
An error returned from AnnotationController/WatchAnnotations
and
ElementController/WatchAnnotations
.
Name | Value | Description |
---|---|---|
BUFFER_READ_FAILED |
1 |
The |
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 |
RESERVED |
|
Added: 12
|
4 |
RESERVED |
|
Added: 12
|
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 |
---|---|---|---|
1 |
view_holder_token |
fuchsia.ui.views/ViewHolderToken
|
The view holder token for the presented Gfx view. Must be unset for
Flatland views. One of |
2 |
view_ref |
fuchsia.ui.views/ViewRef
|
The |
3 |
annotations |
Annotations
|
The initial annotations associated with the presented view. Updates to
annotations are observed through the Optional. |
4 |
viewport_creation_token |
fuchsia.ui.views/ViewportCreationToken
|
The viewport creation token for the presented Flatland view. Must be
unset for Gfx views. One of |
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
|
AnnotationController_WatchAnnotations_Result strict resource
Defined in fuchsia.element/annotations.fidl
Ordinal | Variant | Type | Description |
---|---|---|---|
1 |
response |
AnnotationController_WatchAnnotations_Response
|
|
2 |
err |
WatchAnnotationsError
|
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 |
MAX_ANNOTATION_KEY_VALUE_SIZE |
128
|
uint32 |
Maximum length of |
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. |