PROTOCOLS
Focuser
Defined in fuchsia.ui.views/focuser.fidl
A method of programmatically transferring view focus.
The protocol client has implicit access to a requestor ViewRef, which is used as the basis for request authority.
RequestFocus
Asks the server to transfer focus to the view specified by view_ref
,
with the authority of the requestor ViewRef. Such a request may be
honored or denied.
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.
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.
The request may be denied for many reasons, for example:
- if
view_ref
is invalid - if there is no view backed by
view_ref
- if there is no requestor ViewRef accessible to Focuser
- if the requestor ViewRef lacks authority over
view_ref
's view - if
view_ref
's view is not hittable or may not receive focus etc. A denied request is indicated with a Error.
Request
Name | Type |
---|---|
view_ref |
ViewRef
|
Response
Name | Type |
---|---|
result |
Focuser_RequestFocus_Result
|
View
Defined in fuchsia.ui.views/view.fidl
A View is an interface that a component implements to offer Scenic view(s) to its clients.
A Scenic view contains a tree of Scenic graph nodes which is used to render a graphical user interface, such as a module, shell, or on-screen keyboard. Other Scenic views can be embedded within this tree of nodes. This creates a scene graph describing the UI of the entire system, rooted at the top-most view. Different processes can contribute branches to the scene graph, and their content will be rendered together in a shared space.
Offering a View
A component that wishes to offer a View
can do so in one of two ways:
-
Expose a
View
interface as a service. This is usually done by components that provide a single view, or have a clearly defined "main" view. In this case, the component may obtain relevant properties for configuring the view using services that may be available in its namespace, such as:fuchsia.intl.PropertyProvider
fuchsia.accessibility.PropertyProvider
-
Offer a domain-specific interface that provides
View
s using arequest<View>
parameter. In this case, the component may obtain relevant properties for configuring the view using services that may be provided by its client as part of the request.For example, an encyclopedia component might offer a method to expose article views:
GetArticleView(string article_id, fuchsia.intl.PropertyProvider intl_properties, fuchsia.accessibility.PropertyProvider accessibility_properties, request
view_request); This latter case is probably less common, as controlling domain-specific views tends to be the job of the component that creates them.
Presenting a View
A client of the View
interface will:
- Launch (or bind to) the component that provides the interface.
- Connect to the component's
View
interface. - Call
Present()
to give theView
an attachment point into the scene graph via theview_token
. Subsequent calls toPresent()
will generate an error and cause the connection to be closed.
When the client no longer needs the View, it should disconnect from the interface.
NOTE: The client owns the View
instance and must retain it for the
lifetime of the UI that it displays. If the View
instance is destroyed,
the connection will be dropped and all UI content will be destroyed.
Implementing a View
On the implementation side, a component that exposes the View
interface
has the following responsibilities:
- When
Present()
is called, create a root for theView
's content in the Scenic scene graph by passing the providedview_token
. - Provide graphical content for the view and attach it to the root.
- Adjust the appearance and/or contents of the view's content based on relevant internationalization and/or accessibility properties as described above.
- Handle user interface events such as touches, key presses, and
fuchsia.ui.gfx.ViewProperty
changes using other Scenic interfaces such asfuchsia.ui.Scenic
andfuchsia.ui.SessionListener
.
See also: fuchsia.intl.PropertyProvider
, fuchsia.accessibility.PropertyProvider
.
TODO(fxbug.dev/24402): Migrate all implementations of ViewProvider
to use View
.
Present
Provides the View with an attachment point to Scenic's scene graph.
When Present()
is called the View's implementation should create a
View resource within Scenic by providing it with the view_token
(using
a fuchsia.ui.gfx.CreateResourceCmd
and fuchsia.ui.gfx.ViewArgs
).
Then the implementation should attach its graphical content to the
newly-created View resource using a fuchsia.ui.gfx.AddChildCmd
.
If the implementation already owns a View resource (because Present()
had already been called before), then it should terminate the connection
with an error.
TODO(fxbug.dev/24470): Allow re-parenting View
s with a new Present()
call.
Request
Name | Type |
---|---|
view_token |
ViewToken
|
ViewRefFocused
Defined in fuchsia.ui.views/view_ref_focused.fidl
A method of enabling a ViewRef creator to determine if its ViewRef has gained or lost focus in the view tree.
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.
Watch
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 "compress" focus change history into just the latest known focus state.
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:
- true -> true: The ViewRef has lost focus at least once, and has gained focus by the time of callback issuance.
- true -> false: The ViewRef has lost focus at least once, and has lost focus by the time of callback issuance.
- false -> true: The ViewRef has gained focus at least once, and has gained focus by the time of callback issuance.
- false -> false: The ViewRef has gained focus at least once, and has lost focus by the time of callback issuance.
The client avoids "focus flapping" and always sees the latest state. Every callback issuance is meaningful, and the client should renegotiate focus-related services appropriately, such as IME.
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.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
state |
FocusState
|
ViewRefInstalled
Defined in fuchsia.ui.views/view_ref_installed.fidl
A method of enabling ViewRef holders to determine if a ViewRef has been "installed" 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.
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 "no" to "yes". The latter may change continuously, depending on view tree topology. As such, "installed" cannot imply "currently connected to view tree"; even a hypothetical "ViewRefConnected" protocol is fundamentally racy.
Watch
Sets up a callback to fire when the requested |view_ref| is installed.
- If |view_ref| has not already been installed, the |Watch| response will fire when it is.
- If |view_ref| has already been installed, the |Watch| response will fire immediately.
- 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.
Flow control: The caller is allowed multiple |Watch| calls on multiple ViewRefs. There is at most one response per call back to the client.
Note: Prior to installation, this |Watch| call is kept alive as long as the ViewRef is valid.
Request
Name | Type |
---|---|
view_ref |
ViewRef
|
Response
Name | Type |
---|---|
result |
ViewRefInstalled_Watch_Result
|
STRUCTS
Focuser_RequestFocus_Response
Defined in fuchsia.ui.views/focuser.fidl
Name | Type | Description | Default |
---|
ViewHolderToken
Defined in fuchsia.ui.views/view_token.fidl
Token that uniquely identifies an attachment point for a View
in the
global scene graph. Each ViewHolderToken
has exactly one corresponding
ViewToken
.
A Scenic client can reference contents from another client by creating a
ViewHolder
resource using this token. The other client must also create
a View
resource using the corresponding ViewToken
.
Name | Type | Description | Default |
---|---|---|---|
value |
handle<eventpair>
|
No default |
ViewRef
Defined in fuchsia.ui.views/view_ref.fidl
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.
Clients use a ViewRef to identify a View, to validate a View, and to receive a View invalidation signal.
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.
The client may freely clone its ViewRef and share it, even before sending it to Scenic.
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.
Example 2. We use ViewRefs to create a FocusChain, which identifies Views considered as "in-focus" down the View hierarchy. When a View is destroyed, Scenic signals to all FocusChain holders that the ViewRef is now invalid.
Name | Type | Description | Default |
---|---|---|---|
reference |
handle<eventpair>
|
No default |
ViewRefControl
Defined in fuchsia.ui.views/view_ref.fidl
A ViewRefControl is the peer to a ViewRef. Their reference
s are linked.
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 ZX_EVENTPAIR_PEER_CLOSED
signal sent to all ViewRef
holders; hence ViewRef holders may track View lifetime.
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.
Name | Type | Description | Default |
---|---|---|---|
reference |
handle<eventpair>
|
No default |
ViewRefInstalled_Watch_Response
Defined in fuchsia.ui.views/view_ref_installed.fidl
Name | Type | Description | Default |
---|
ViewToken
Defined in fuchsia.ui.views/view_token.fidl
Token that uniquely identifies a View
, which is the root point for a
subgraph in the global scene graph. Each ViewToken
has exactly one
corresponding ViewHolderToken
.
A Scenic client can have its contents referenced from another client by
creating a View
resource using this token. The other client must also
create a ViewHolder
resource using the corresponding ViewHolderToken
.
Name | Type | Description | Default |
---|---|---|---|
value |
handle<eventpair>
|
No default |
ENUMS
Error
Type: uint32
Defined in fuchsia.ui.views/focuser.fidl
Problematic situations that occur on Focuser.RequestFocus.
Name | Value | Description |
---|---|---|
DENIED |
1 |
Value returned when RequestFocus is denied. |
ViewRefInstalledError
Type: uint32
Defined in fuchsia.ui.views/view_ref_installed.fidl
A collection of error codes related to |ViewRefInstalled|.
Name | Value | Description |
---|---|---|
INVALID_VIEW_REF |
1 |
The ViewRef being watched is invalid, or has become invalid. |
TABLES
FocusState
Defined in fuchsia.ui.views/view_ref_focused.fidl
A ViewRef's state of focus.
Ordinal | Name | Type | Description |
---|---|---|---|
1 | focused |
bool
|
Describes if a ViewRef has gained focus (true), or lost focus (false). Required field. |
UNIONS
Command
Defined in fuchsia.ui.views/commands.fidl
DO NOT USE - Retained for ABI stability in fuchsia.ui.scenic.Command
DO NOT USE
Name | Type | Description |
---|---|---|
empty |
int32
|
Focuser_RequestFocus_Result
Defined in fuchsia.ui.views/focuser.fidl
Name | Type | Description |
---|---|---|
response |
Focuser_RequestFocus_Response
|
|
err |
Error
|
ViewRefInstalled_Watch_Result
Defined in fuchsia.ui.views/view_ref_installed.fidl
Name | Type | Description |
---|---|---|
response |
ViewRefInstalled_Watch_Response
|
|
err |
ViewRefInstalledError
|