| // 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.ui.gfx; |
| |
| /// Max number of elements in a semantic set. |
| const MAX_SET_ELEMENTS uint32 = 100; |
| |
| /// Represents actions that can be applied to Nodes. |
| type Action = strict enum { |
| /// The default action associated with the element. |
| DEFAULT = 1; |
| /// The secondary action associated with the element. This may correspond to a long press |
| /// (touchscreens) or right click (mouse). |
| SECONDARY = 2; |
| /// Set (input/non-accessibility) focus on this element. |
| SET_FOCUS = 3; |
| /// Set the element's value. |
| SET_VALUE = 4; |
| /// Scroll node to make it visible. |
| SHOW_ON_SCREEN = 5; |
| /// Decrement a slider by one step value. The step size is defined by the |
| /// owner of the semantic node that executes this action. For example, a |
| /// volume slider may want to make steps 1, 2, 3, while a time slider may |
| /// want to skip 30 seconds each step change. |
| DECREMENT = 6; |
| /// Increment a slider by one step value. The step size is defined by the |
| /// owner of the semantic node that executes this action. For example, a |
| /// volume slider may want to make steps 1, 2, 3, while a time slider may |
| /// want to skip 30 seconds each step change. |
| INCREMENT = 7; |
| }; |
| |
| /// Represents a role of an element on a UI. |
| type Role = strict enum { |
| /// Role used to represent elements which role is not currently supported. |
| UNKNOWN = 1; |
| /// Something on screen that can be clicked/activated, that has a single function. |
| BUTTON = 2; |
| /// Header text, e.g. something tagged <h1> in HTML. |
| HEADER = 3; |
| /// An image or graphic. |
| IMAGE = 4; |
| /// A field containing text that is not a header. |
| TEXT_FIELD = 5; |
| /// A slider, e.g. a volume slider or a time slider of a video. |
| SLIDER = 6; |
| /// A link, e.g. a link on a webpage. |
| LINK = 7; |
| /// A check box that can be toggled. |
| CHECK_BOX = 8; |
| /// A radio button that selects an option among a group of options. |
| RADIO_BUTTON = 9; |
| |
| /// Role used to represent lists. |
| LIST = 10; |
| |
| /// Role used to represent a list marker (e.g. a bullet point, number, roman |
| /// numeral, etc.). |
| LIST_ELEMENT_MARKER = 12; |
| |
| /// Role used to represent immutable text. |
| STATIC_TEXT = 13; |
| |
| /// Role used to represent toggle switch. |
| TOGGLE_SWITCH = 14; |
| |
| /// Role used to represent a table of elements. |
| TABLE = 15; |
| |
| /// Role used to represent a grid. For example, an element with the |
| /// aria-grid role. |
| GRID = 16; |
| |
| /// Role used to represent the row of a table. |
| TABLE_ROW = 17; |
| |
| /// Role used to represent the cell of a table or grid. |
| CELL = 18; |
| |
| /// Role used to represent a column header. For example, an element with |
| /// the html tag <th>. |
| COLUMN_HEADER = 19; |
| |
| /// Role used to represent an aria-rowgroup-like element. |
| ROW_GROUP = 20; |
| |
| /// Role used to represent a paragraph of text. |
| PARAGRAPH = 21; |
| }; |
| |
| /// The possible origins of a label. |
| type LabelOrigin = strict enum { |
| /// The node does not have a label yet. |
| UNITIALIZED = 1; |
| /// An attribute of this element in the runtime UI explicitly sets its |
| /// label. For example, an element with aria-label. |
| ATTRIBUTE = 2; |
| /// An attribute of this element in the runtime UI explicitly sets its |
| /// label to be empty. |
| ATTRIBUTE_EMPTY = 3; |
| /// This label serves as the caption for a table-like element. Because some |
| /// assistive technology have special modes to deal with tables, a runtime |
| /// should mark its label with this type of origin so that users know what |
| /// the table is about when they navigate in the table mode. For example, |
| /// a <caption> html tag sets the label. |
| CAPTION = 4; |
| /// This node receives its label from the contents present in the |
| /// application. For example, text from a web page becomes the label of |
| /// this node. |
| CONTENTS = 5; |
| /// An element that can receive user entered value and has a suggested |
| /// input. For example, the placeholder attribute on an html input field. |
| PLACEHOLDER = 6; |
| /// Another element provides the label for this element. For example, via |
| /// aria-labeledby. |
| RELATED_ELEMENT = 7; |
| /// This element's label is represented by a visual tooltip. For example, |
| /// as if from a <title> html tag. |
| TITLE = 8; |
| /// The label comes from an user-entered value. |
| VALUE = 9; |
| }; |
| |
| /// Slider / range control attributes. |
| type RangeAttributes = table { |
| /// The minimum value a range control element can take. |
| 1: min_value float32; |
| /// The maximum value a range control element can take. |
| 2: max_value float32; |
| /// The step delta the element applies when the action DECREMENT or |
| /// INCREMENT are invoked. |
| 3: step_delta float32; |
| }; |
| |
| /// Set attributes that control how an element is connected to others in the |
| /// same set. For example, a group of radio buttons in html containing the same |
| /// name attribute are part of the same set. |
| type SetAttributes = table { |
| /// Size of the set. |
| 1: size uint32; |
| /// Element index in the set, starting from one. |
| 2: index uint32; |
| /// Node ids of other elements in this set. |
| 3: set_element_ids vector<uint32>:MAX_SET_ELEMENTS; |
| }; |
| |
| /// Attributes that control how a cell inside of a table behaves. |
| type TableAttributes = table { |
| /// The number of columns this table cell spans. |
| 1: column_span uint32; |
| /// The number of rows this table cell spans. |
| 2: row_span uint32; |
| }; |
| |
| /// An attribute is an essential property to describe an element. Unlike states, attributes do not |
| /// change over the life of an element. |
| /// Example: A button with a label attribute 'ok' should never change to 'cancel', as this is not |
| /// the same element. |
| type Attributes = table { |
| /// The primary label for an element. If longer than MAX_LABEL_SIZE the client is responsible |
| /// for truncating the label. |
| 1: label string:MAX_LABEL_SIZE; |
| |
| /// The secondary label for an element. If longer than MAX_LABEL_SIZE the client is responsible |
| /// for truncating the label. |
| 2: secondary_label string:MAX_LABEL_SIZE; |
| |
| /// A description of what the secondary action on a node (equivalent to long press or right click) should do. |
| 3: secondary_action_description string:MAX_LABEL_SIZE; |
| |
| /// The range attributes are filled if the element is a slider / a range |
| /// control. |
| 4: range RangeAttributes; |
| |
| /// Set attributes are filled if the element is part of some type of set. |
| /// For example, radio buttons that are related are part of the same set. |
| 5: set SetAttributes; |
| |
| /// The list attributes are filled iff the node is a list. |
| /// Note that only the size and set_element_ids may be filled for a list node. |
| 6: list_attributes SetAttributes; |
| |
| /// The list element attributes are filled iff the node is a child of a list node. |
| 7: list_element_attributes SetAttributes; |
| |
| /// The hierarchical level of an element. For example, a header can be of |
| /// level 1 to 6 in html or markdown. |
| 8: hierarchical_level uint32; |
| |
| /// The table attributes are filled when the element is a cell. |
| 9: table_attributes TableAttributes; |
| |
| /// The origin of the label of this element. |
| 10: label_origin LabelOrigin; |
| |
| /// Whether the element is part of a virtual keyboard. For example, a key |
| /// on an onscreen keyboard. |
| 11: is_keyboard_key bool; |
| }; |
| |
| /// Represents the state of a UI checkbox. |
| type CheckedState = strict enum { |
| /// Used when no data is entered or the element is not a check box. |
| NONE = 1; |
| /// Checked |
| CHECKED = 2; |
| /// Unchecked |
| UNCHECKED = 3; |
| /// Indeterminate state |
| MIXED = 4; |
| }; |
| |
| /// Represents the state of a UI toggle switch. |
| type ToggledState = strict enum { |
| /// Toggle switch is on. |
| ON = 1; |
| /// Toggle switch is off. |
| OFF = 2; |
| /// Toggle switch is in Indeterminate state. |
| INDETERMINATE = 3; |
| }; |
| |
| /// A state is a dynamic property of an element that may change in response to |
| /// user action or automated processes. Thus, they are different from attributes |
| /// in an important point, which is frequency of change. |
| type States = table { |
| /// DEPRECATED |
| 1: checked bool; |
| |
| /// State of a checkbox. |
| /// This field is mutually exclusive with ToggledState. |
| 2: checked_state CheckedState; |
| |
| /// Whether the element is currently selected. |
| 3: selected bool; |
| |
| /// Whether the element is currently hidden or marked invisible by the framework. |
| 4: hidden bool; |
| |
| /// The user-entered value of the element, if applicable. If longer than MAX_VALUE_SIZE the |
| /// client is responsible for truncating. |
| 5: value string:MAX_VALUE_SIZE; |
| |
| /// If the element is a slider or a range control, this field contains the |
| /// current value. Note that this is not the same as the value field above, |
| /// as this is generated by the client and just adjusted by the user. |
| 6: range_value float32; |
| |
| // If the element is a scrollable viewport, this field contains the x and |
| // y offsets within this node's coordinate space to apply to the children. |
| // This offsetting is used to position the children within the viewport to |
| // reflect the current scrolling of the element. There are no constraints |
| // on these values other than they must be finite. |
| 7: viewport_offset fuchsia.ui.gfx.vec2; |
| |
| /// State of a toggle switch. |
| /// This field must only be set if the element is a toggle switch element |
| /// and is mutually exclusive with CheckedState. |
| 8: toggled_state ToggledState; |
| |
| /// Whether this element is focusable in the UI. Note that this is not the |
| /// a11y focus, but the input focus. |
| 9: focusable bool; |
| |
| /// Whether this element has the input focus. This corresponds to the |
| /// system focus. Only one element can have this value set. The behavior is |
| /// undetermined if more than one node sets this value to 'true'. |
| 10: has_input_focus bool; |
| }; |
| |
| /// The Node represents a semantic element on an interface. This may |
| /// be a button, a text field, a checkbox or any element that has a relevant |
| /// semantic meaning so that assistive technology can understand the current UI. |
| type Node = 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. |
| /// No forest is allowed. |
| 1: node_id uint32; |
| |
| /// Role of this element, e.g. button, checkbox, etc. |
| 2: role Role; |
| |
| /// A table of states of this object, e.g. checked, editable, etc. |
| 3: states States; |
| |
| /// A table of attributes of this node. |
| 4: attributes Attributes; |
| |
| /// A list of actions that can be performed on this node. |
| 5: actions vector<Action>:100; |
| |
| /// The list of child IDs of this node, in traversal order. Runtimes supplying semantic tree |
| /// information are responsible for ensuring the tree does not contain cycles. Each node may |
| /// have only one parent. |
| 6: child_ids vector<uint32>:MAX_FAN_OUT; |
| |
| /// Local bounding box of this element. |
| 7: location fuchsia.ui.gfx.BoundingBox; |
| |
| /// Transform from this node's coordinate space to its container's space. 4x4 for compatibility |
| /// with scenic. This matrix is required to have the form |
| /// |
| /// [ Sx 0 0 Tx ] |
| /// [ 0 Sy 0 Ty ] |
| /// [ 0 0 Sz Tz ] |
| /// [ 0 0 0 1 ] |
| /// |
| /// where Sx, Sy, and Sz are scale factors and Tx, Ty, Tz are the translation factors for |
| /// the x, y, and z components |
| 8: transform fuchsia.ui.gfx.mat4; |
| |
| /// Node ID of the ancestor of this node that is used as the target of |transform|. |
| /// If not present, this is interpreted as this node's parent. |
| 9: container_id uint32; |
| }; |