fuchsia.ui.views

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

SetAutoFocus

Sets the auto focus target to the View specified by view_ref. To unset the target, pass in an empty table.

If a target has been set, then whenever the caller's View would receive focus, an attempt is made to transfer focus immediately to the target instead. If the target is unfocusable, the new target is the first focusable ancestor of the target instead. Setting an auto focus target places no limitations on simultaneous use of RequestFocus().

An auto focus target is "valid" only while it is a descendant of the caller's View in the ViewTree. Specifying an invalid auto focus target is allowed, since it may become valid later. It is the client's responsibility to ensure the target is a valid receiver of auto focus.

If the target is invalid when the auto focus behavior would trigger, then the attempt to move focus will silently fail and focus will remain with the caller's View. A target may become invalid and then become valid again any number of times; auto focus will continue to function whenever the target is in a valid state, and will continue to ignore the target while it's in an invalid state.

If the focus would by some further automatic mechanism return to the caller's View (e.g. if the target is unfocusable), then focus will remain with the caller's View.

AutoFocusError is currently never returned, and is reserved for possible future use.

Request

Name	Type
payload	FocuserSetAutoFocusRequest

Response

Name	Type
result	Focuser_SetAutoFocus_Result

View

Defined in fuchsia.ui.views/view.fidl

Deprecated API for view creation. DO NOT USE.

DEPRECATED

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 Views 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

<EMPTY>

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

<EMPTY>

Focuser_SetAutoFocus_Response

Defined in fuchsia.ui.views/focuser.fidl

<EMPTY>

ViewCreationToken resource

Defined in fuchsia.ui.views/flatland_tokens.fidl

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.

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.

Field	Type	Description	Default
value	handle<channel>		No default

ViewHolderToken resource

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.

Field	Type	Description	Default
value	handle<eventpair>		No default

ViewIdentityOnCreation resource

Defined in fuchsia.ui.views/view_ref.fidl

Convenience data type to self-identify the view, during view creation.

A ViewRef is used to identify the view, and can be freely cloned and distributed to other components.

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 ZX_EVENTPAIR_PEER_CLOSED signal to all ViewRef holders, thus notifying view death.

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.

Field	Type	Description	Default
view_ref	ViewRef	Stable identifier for the view to be created.	No default
view_ref_control	ViewRefControl	A mechanism for lifecycle notification.	No default

ViewRef resource

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.

Field	Type	Description	Default
reference	handle<eventpair>		No default

ViewRefControl resource

Defined in fuchsia.ui.views/view_ref.fidl

A ViewRefControl is the peer to a ViewRef. Their references 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.

Field	Type	Description	Default
reference	handle<eventpair>		No default

ViewRefInstalled_Watch_Response

Defined in fuchsia.ui.views/view_ref_installed.fidl

<EMPTY>

ViewToken resource

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.

Field	Type	Description	Default
value	handle<eventpair>		No default

ViewportCreationToken resource

Defined in fuchsia.ui.views/flatland_tokens.fidl

Two Flatland instances may be connected in a parent-child relationship. The parent endpoint is held in a Viewport.

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.

Field	Type	Description	Default
value	handle<channel>		No default

ENUMS

AutoFocusError flexible

Type: uint32

Defined in fuchsia.ui.views/focuser.fidl

Name	Value	Description

Error strict

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 strict

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	Field	Type	Description
1	focused	bool	Describes if a ViewRef has gained focus (true), or lost focus (false). Required field.

FocuserSetAutoFocusRequest resource

Defined in fuchsia.ui.views/focuser.fidl

Ordinal	Field	Type	Description
1	view_ref	ViewRef

UNIONS

Command strict

Defined in fuchsia.ui.views/commands.fidl

DO NOT USE - Retained for ABI stability in fuchsia.ui.scenic.Command

Ordinal	Variant	Type	Description
1	empty	int32

Focuser_RequestFocus_Result strict

Defined in fuchsia.ui.views/focuser.fidl

Ordinal	Variant	Type	Description
1	response	Focuser_RequestFocus_Response
2	err	Error

Focuser_SetAutoFocus_Result strict

Defined in fuchsia.ui.views/focuser.fidl

Ordinal	Variant	Type	Description
1	response	Focuser_SetAutoFocus_Response
2	err	AutoFocusError

ViewRefInstalled_Watch_Result strict

Defined in fuchsia.ui.views/view_ref_installed.fidl

Ordinal	Variant	Type	Description
1	response	ViewRefInstalled_Watch_Response
2	err	ViewRefInstalledError