| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.accessibility.semantics; |
| |
| using fuchsia.math; |
| using fuchsia.ui.views; |
| |
| /// Maximum depth of the semantic tree. |
| const MAX_TREE_DEPTH uint64 = 256; |
| |
| /// Maximum number of children for a node in the semantic tree. |
| const MAX_FAN_OUT uint64 = 20000; |
| |
| /// Maximum number of semantic nodes that may be sent in a single update. |
| const MAX_NODES_PER_UPDATE uint64 = 2048; |
| |
| /// Maximum size of a label string, in bytes. |
| const MAX_LABEL_SIZE uint64 = 16384; |
| |
| /// Maximum size of a value string, in bytes. |
| const MAX_VALUE_SIZE uint64 = 16384; |
| |
| /// Maximum size of a message string, in bytes. |
| const MAX_MESSAGE_SIZE uint64 = 16384; |
| |
| /// An interface to manage connections with views for the purposes of gathering semantic information |
| /// about their current UI state. |
| /// |
| /// The manager allows clients to register as a semantic provider for their view(s). In return the |
| /// semantics manager supplies an interface to update, commit and delete information from the |
| /// semantic tree for that view. If the semantic manager encounters an error, it will close the |
| /// channel, delete any associated data and rely on the client to re-register. |
| @discoverable |
| protocol SemanticsManager { |
| RegisterViewForSemantics(resource struct { |
| view_ref fuchsia.ui.views.ViewRef; |
| listener client_end:SemanticListener; |
| semantic_tree_request server_end:SemanticTree; |
| }); |
| }; |
| |
| /// Represents a Semantic Event that is fired on a Semantic Tree. |
| type SemanticEvent = strict union { |
| 1: announce AnnounceEvent; |
| }; |
| |
| /// An announce event is one where a message is sent to a Semantic Tree, |
| /// informing a change of some global state in the application. Because this |
| /// announcement can be disruptive to assistive technology, it should be used |
| /// sparingly. |
| type AnnounceEvent = table { |
| /// A message describing the change in the application. This message is expected to be localized in the language that the application is in. |
| 1: message string:MAX_MESSAGE_SIZE; |
| }; |
| |
| /// Interface to update the semantic tree for a particular view. Nodes can be added, updated or |
| /// deleted. Because the size of an update may exceed FIDL transfer limits, clients are responsible |
| /// for breaking up changes into multiple update and delete calls that conform to these limits. The |
| /// commit function must always be called at the end of a full update push to signal the end of an |
| /// update. |
| /// |
| /// The client may make several calls to UpdateSemanticNodes(...) or DeleteSemanticNodes(...) |
| /// before calling CommitUpdates(), and must wait for the semantics manager to reply to the |
| /// CommitUpdates() method to know whether an update has been processed. This allows the client to |
| /// break up a set of changes (e.g. a re-computed semantic tree) to the semantic tree into |
| /// FIDL-compatible chunks, but commit them all at once. |
| /// |
| /// If the semantics manager ever receives inconsistent state from the client, such as an |
| /// invalid tree or unrecognized parent node id, the server will close the channel. The client is |
| /// responsible for reconnecting and re-sending its state from scratch. |
| protocol SemanticTree { |
| |
| /// Sends new/updated nodes to the root to add to the cache on the next commit. |
| UpdateSemanticNodes(struct { |
| nodes vector<Node>:MAX_NODES_PER_UPDATE; |
| }); |
| |
| /// Tells the root to remove nodes with node_ids from the semantic tree on the next commit. |
| DeleteSemanticNodes(struct { |
| node_ids vector<uint32>:MAX_NODES_PER_UPDATE; |
| }); |
| |
| /// Commits pending changes to node tree associated with the view using UpdateSemanticNodes and |
| /// DeleteSemanticNodes. Updates are processed in the order in which they are received. If the |
| /// committed updates result in an ill-formed tree (for example a missing root node or a cycle) |
| /// the semantic manager will close the channel. |
| CommitUpdates() -> (); |
| |
| /// Sends a Semantic Event related to this tree. This applies immediately |
| /// and does not wait for CommitUpdates(). It is the caller's |
| /// responsibility to fire events on nodes that have been already commited. |
| /// The return callback is invoked to acknowledge that the event was received. |
| @transitional |
| SendSemanticEvent(struct { |
| semantic_event SemanticEvent; |
| }) -> (); |
| }; |
| |
| /// Results of hit testing on a view's semantic tree which is implemented by |
| /// Runtimes(like Flutter/Chrome) and sent to Accessibility. |
| type Hit = table { |
| /// Unique ID that represents a node in a particular UI. |
| /// Zero is assumed to be the root node and the only entry point to the tree. |
| /// node_id will not be filled when there is no hit. |
| 1: node_id uint32; |
| |
| /// The ordered list of node ids which represent path from root node to the hit node. |
| 2: path_from_root vector<uint32>:MAX_TREE_DEPTH; |
| }; |
| |
| /// A semantic provider is the client-side interface that the manager can use to enable or disable |
| /// semantic updates, and to ask clients to perform accessibility actions. |
| protocol SemanticListener { |
| /// Asks the semantics provider to perform an accessibility action on the |
| /// node with node id in the front-end. |
| OnAccessibilityActionRequested(struct { |
| node_id uint32; |
| action Action; |
| }) -> (struct { |
| handled bool; |
| }); |
| |
| /// Asks the semantics provider to perform hit testing and return the result. |
| @transitional |
| HitTest(struct { |
| local_point fuchsia.math.PointF; |
| }) -> (struct { |
| result Hit; |
| }); |
| |
| /// Callback telling the client whether or not to send updates to the semantic tree. |
| /// The semantics manager will clear all state when this is called with updates_enabled = false. |
| /// When called with updates_enabled = true, the client should sent the full state of the |
| /// current semantic tree. |
| OnSemanticsModeChanged(struct { |
| updates_enabled bool; |
| }) -> (); |
| }; |