updateNode abstract method

void updateNode({
  1. required int id,
  2. required SemanticsFlags flags,
  3. required int actions,
  4. required int maxValueLength,
  5. required int currentValueLength,
  6. required int textSelectionBase,
  7. required int textSelectionExtent,
  8. required int platformViewId,
  9. required int scrollChildren,
  10. required int scrollIndex,
  11. required int traversalParent,
  12. required double scrollPosition,
  13. required double scrollExtentMax,
  14. required double scrollExtentMin,
  15. required Rect rect,
  16. required String identifier,
  17. required String label,
  18. required List<StringAttribute> labelAttributes,
  19. required String value,
  20. required List<StringAttribute> valueAttributes,
  21. required String increasedValue,
  22. required List<StringAttribute> increasedValueAttributes,
  23. required String decreasedValue,
  24. required List<StringAttribute> decreasedValueAttributes,
  25. required String hint,
  26. required List<StringAttribute> hintAttributes,
  27. required String tooltip,
  28. required TextDirection? textDirection,
  29. required Float64List transform,
  30. required Float64List hitTestTransform,
  31. required Int32List childrenInTraversalOrder,
  32. required Int32List childrenInHitTestOrder,
  33. required Int32List additionalActions,
  34. int headingLevel = 0,
  35. String linkUrl = '',
  36. SemanticsRole role = SemanticsRole.none,
  37. required List<String>? controlsNodes,
  38. SemanticsValidationResult validationResult = SemanticsValidationResult.none,
  39. SemanticsHitTestBehavior hitTestBehavior = SemanticsHitTestBehavior.defer,
  40. required SemanticsInputType inputType,
  41. required Locale? locale,
  42. required String minValue,
  43. required String maxValue,
})

Update the information associated with the node with the given id.

The semantics nodes form a tree, with the root of the tree always having an id of zero. The childrenInTraversalOrder and childrenInHitTestOrder are the ids of the nodes that are immediate children of this node. The former enumerates children in traversal order, and the latter enumerates the same children in the hit test order. The two lists must have the same length and contain the same ids. They may only differ in the order the ids are listed in. For more information about different child orders, see DebugSemanticsDumpOrder.

The system retains the nodes that are currently reachable from the root. A given update need not contain information for nodes that do not change in the update. If a node is not reachable from the root after an update, the node will be discarded from the tree.

The flags are a bit field of SemanticsFlags that apply to this node.

The actions are a bit field of SemanticsActions that can be undertaken by this node. If the user wishes to undertake one of these actions on this node, the PlatformDispatcher.onSemanticsActionEvent will be called with a SemanticsActionEvent specifying the action to be performed. Because the semantics tree is maintained asynchronously, the PlatformDispatcher.onSemanticsActionEvent callback might be called with an action that is no longer possible.

The identifier is a string that describes the node for UI automation tools that work by querying the accessibility hierarchy, such as Android UI Automator, iOS XCUITest, or Appium. It's not exposed to users.

The label is a string that describes this node. The value property describes the current value of the node as a string. The increasedValue string will become the value string after a SemanticsAction.increase action is performed. The decreasedValue string will become the value string after a SemanticsAction.decrease action is performed. The hint string describes what result an action performed on this node has. The reading direction of all these strings is given by textDirection.

The labelAttributes, valueAttributes, hintAttributes, increasedValueAttributes, and decreasedValueAttributes are the lists of StringAttribute carried by the label, value, hint, increasedValue, and decreasedValue respectively. Their contents must not be changed during the semantics update.

The tooltip is a string that describe additional information when user hover or long press on the backing widget of this semantics node.

The fields textSelectionBase and textSelectionExtent describe the currently selected text within value. A value of -1 indicates no current text selection base or extent.

The field maxValueLength is used to indicate that an editable text field has a limit on the number of characters entered. If it is -1 there is no limit on the number of characters entered. The field currentValueLength indicates how much of that limit has already been used up. When maxValueLength is >= 0, currentValueLength must also be

= 0, otherwise it should be specified to be -1.

The field platformViewId references the platform view, whose semantics nodes will be added as children to this node. If a platform view is specified, childrenInHitTestOrder and childrenInTraversalOrder must be empty. A value of -1 indicates that this node is not associated with a platform view.

For scrollable nodes scrollPosition describes the current scroll position in logical pixel. scrollExtentMax and scrollExtentMin describe the maximum and minimum in-range values that scrollPosition can be. Both or either may be infinity to indicate unbound scrolling. The value for scrollPosition can (temporarily) be outside this range, for example during an overscroll. scrollChildren is the count of the total number of child nodes that contribute semantics and scrollIndex is the index of the first visible child node that contributes semantics.

The traversalParent specifies the ID of the semantics node that serves as the logical parent of this node for accessibility traversal. This parameter is only used by the web engine to establish parent-child relationships between nodes that are not directly connected in paint order. To ensure correct accessibility traversal, traversalParent should be set to the logical traversal parent node ID. This parameter is web-specific because other platforms can complete grafting when generating the semantics tree in traversal order. After grafting, the traversal order and hit-test order will be different, which is acceptable for other platforms. However, the web engine assumes these two orders are exactly the same, so grafting cannot be performed ahead of time on web. Instead, the traversal order is updated in the web engine by setting the aria-owns attribute through this parameter. A value of -1 indicates no special traversal parent. This parameter has no effect on other platforms.

The rect is the region occupied by this node in its own coordinate system.

The transform is a matrix that maps this node's coordinate system into its parent's coordinate system.

The headingLevel describes that this node is a heading and the hierarchy level this node represents as a heading. A value of 0 indicates that this node is not a heading. A value of 1 or greater indicates that this node is a heading at the specified level. The valid value range is from 1 to 6, inclusive. This attribute is only used for Web platform, and it will have no effect on other platforms.

The linkUrl describes the URI that this node links to. If the node is not a link, this should be an empty string.

The role describes the role of this node. Defaults to SemanticsRole.none if not set.

The locale describes the language of the content in this node. i.e. label, value, and hint.

If validationResult is not null, indicates the result of validating a form field. If null, indicates that the node is not being validated, or that the result is unknown. Form fields that validate user input but do not use this argument should use other ways to communicate validation errors to the user, such as embedding validation error text in the label.

The hitTestBehavior describes how this node should behave during hit testing. When set to SemanticsHitTestBehavior.defer (the default), the platform will infer appropriate behavior based on other semantic properties of the node itself (not inherited from parent). Different platforms may implement this differently.

For example, modal surfaces like dialogs can set this to SemanticsHitTestBehavior.opaque to block pointer events from reaching content behind them, while non-interactive decorative elements can set it to SemanticsHitTestBehavior.transparent to allow pointer events to pass through.

See also:

Implementation

void updateNode({
  required int id,
  required SemanticsFlags flags,
  required int actions,
  required int maxValueLength,
  required int currentValueLength,
  required int textSelectionBase,
  required int textSelectionExtent,
  required int platformViewId,
  required int scrollChildren,
  required int scrollIndex,
  required int traversalParent,
  required double scrollPosition,
  required double scrollExtentMax,
  required double scrollExtentMin,
  required Rect rect,
  required String identifier,
  required String label,
  required List<StringAttribute> labelAttributes,
  required String value,
  required List<StringAttribute> valueAttributes,
  required String increasedValue,
  required List<StringAttribute> increasedValueAttributes,
  required String decreasedValue,
  required List<StringAttribute> decreasedValueAttributes,
  required String hint,
  required List<StringAttribute> hintAttributes,
  required String tooltip,
  required TextDirection? textDirection,
  required Float64List transform,
  required Float64List hitTestTransform,
  required Int32List childrenInTraversalOrder,
  required Int32List childrenInHitTestOrder,
  required Int32List additionalActions,
  int headingLevel = 0,
  String linkUrl = '',
  SemanticsRole role = SemanticsRole.none,
  required List<String>? controlsNodes,
  SemanticsValidationResult validationResult = SemanticsValidationResult.none,
  SemanticsHitTestBehavior hitTestBehavior = SemanticsHitTestBehavior.defer,
  required SemanticsInputType inputType,
  required Locale? locale,
  required String minValue,
  required String maxValue,
});