ax_tree_update.h 4.0 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798
  1. // Copyright 2013 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef UI_ACCESSIBILITY_AX_TREE_UPDATE_H_
  5. #define UI_ACCESSIBILITY_AX_TREE_UPDATE_H_
  6. #include <stddef.h>
  7. #include <stdint.h>
  8. #include <string>
  9. #include <vector>
  10. #include "ui/accessibility/ax_base_export.h"
  11. #include "ui/accessibility/ax_enums.mojom.h"
  12. #include "ui/accessibility/ax_event_intent.h"
  13. #include "ui/accessibility/ax_node_data.h"
  14. #include "ui/accessibility/ax_tree_data.h"
  15. namespace ui {
  16. // An AXTreeUpdate is a serialized representation of an atomic change
  17. // to an AXTree. The sender and receiver must be in sync; the update
  18. // is only meant to bring the tree from a specific previous state into
  19. // its next state. Trying to apply it to the wrong tree should immediately
  20. // die with a fatal assertion.
  21. //
  22. // An AXTreeUpdate consists of an optional node id to clear (meaning
  23. // that all of that node's children and their descendants are deleted),
  24. // followed by an ordered vector of zero or more AXNodeData structures to
  25. // be applied to the tree in order. An update may also include an optional
  26. // update to the AXTreeData structure that applies to the tree as a whole.
  27. //
  28. // Suppose that the next AXNodeData to be applied is |node|. The following
  29. // invariants must hold:
  30. // 1. Either
  31. // a) |node.id| is already in the tree, or
  32. // b) the tree is empty, and
  33. // |node| is the new root of the tree, and
  34. // |node.role| == WebAXRoleRootWebArea.
  35. // 2. Every child id in |node.child_ids| must either be already a child
  36. // of this node, or a new id not previously in the tree. It is not
  37. // allowed to "reparent" a child to this node without first removing
  38. // that child from its previous parent.
  39. // 3. When a new id appears in |node.child_ids|, the tree should create a
  40. // new uninitialized placeholder node for it immediately. That
  41. // placeholder must be updated within the same AXTreeUpdate, otherwise
  42. // it's a fatal error. This guarantees the tree is always complete
  43. // before or after an AXTreeUpdate.
  44. struct AX_BASE_EXPORT AXTreeUpdate {
  45. AXTreeUpdate();
  46. AXTreeUpdate(const AXTreeUpdate& other);
  47. ~AXTreeUpdate();
  48. // If |has_tree_data| is true, the value of |tree_data| should be used
  49. // to update the tree data, otherwise it should be ignored.
  50. bool has_tree_data = false;
  51. AXTreeData tree_data;
  52. // The id of a node to clear, before applying any updates,
  53. // or 0 if no nodes should be cleared. Clearing a node means deleting
  54. // all of its children and their descendants, but leaving that node in
  55. // the tree. It's an error to clear a node but not subsequently update it
  56. // as part of the tree update.
  57. AXNodeID node_id_to_clear = kInvalidAXNodeID;
  58. // The id of the root of the tree, if the root is changing. This is
  59. // required to be set if the root of the tree is changing or Unserialize
  60. // will fail. If the root of the tree is not changing this is optional
  61. // and it is allowed to pass 0.
  62. AXNodeID root_id = kInvalidAXNodeID;
  63. // A vector of nodes to update, according to the rules above.
  64. std::vector<AXNodeData> nodes;
  65. // The source of the event which generated this tree update.
  66. ax::mojom::EventFrom event_from = ax::mojom::EventFrom::kNone;
  67. // The accessibility action that caused this tree update.
  68. ax::mojom::Action event_from_action = ax::mojom::Action::kNone;
  69. // The event intents associated with this tree update.
  70. std::vector<AXEventIntent> event_intents;
  71. // Return a multi-line indented string representation, for logging.
  72. std::string ToString() const;
  73. };
  74. // Two tree updates can be merged into one if the second one
  75. // doesn't clear a subtree, doesn't have new tree data, and
  76. // doesn't have a new root id - in other words the second tree
  77. // update consists of only changes to nodes.
  78. bool AX_BASE_EXPORT TreeUpdatesCanBeMerged(const AXTreeUpdate& u1,
  79. const AXTreeUpdate& u2);
  80. } // namespace ui
  81. #endif // UI_ACCESSIBILITY_AX_TREE_UPDATE_H_