// Copyright 2013 The Chromium Authors. All rights reserved. // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. #ifndef UI_ACCESSIBILITY_AX_NODE_H_ #define UI_ACCESSIBILITY_AX_NODE_H_ #include #include #include #include #include #include "base/optional.h" #include "build/build_config.h" #include "ui/accessibility/ax_export.h" #include "ui/accessibility/ax_node_data.h" #include "ui/accessibility/ax_tree_id.h" namespace ui { class AXTableInfo; struct AXLanguageInfo; // One node in an AXTree. class AX_EXPORT AXNode final { public: // Defines the type used for AXNode IDs. using AXID = int32_t; // If a node is not yet or no longer valid, its ID should have a value of // kInvalidAXID. static constexpr AXID kInvalidAXID = 0; // Interface to the tree class that owns an AXNode. We use this instead // of letting AXNode have a pointer to its AXTree directly so that we're // forced to think twice before calling an AXTree interface that might not // be necessary. class OwnerTree { public: struct Selection { bool is_backward; AXID anchor_object_id; int anchor_offset; ax::mojom::TextAffinity anchor_affinity; AXID focus_object_id; int focus_offset; ax::mojom::TextAffinity focus_affinity; }; // See AXTree::GetAXTreeID. virtual AXTreeID GetAXTreeID() const = 0; // See AXTree::GetTableInfo. virtual AXTableInfo* GetTableInfo(const AXNode* table_node) const = 0; // See AXTree::GetFromId. virtual AXNode* GetFromId(int32_t id) const = 0; virtual base::Optional GetPosInSet(const AXNode& node) = 0; virtual base::Optional GetSetSize(const AXNode& node) = 0; virtual Selection GetUnignoredSelection() const = 0; virtual bool GetTreeUpdateInProgressState() const = 0; virtual bool HasPaginationSupport() const = 0; }; template class ChildIteratorBase { public: ChildIteratorBase(const NodeType* parent, NodeType* child); ChildIteratorBase(const ChildIteratorBase& it); ~ChildIteratorBase() {} bool operator==(const ChildIteratorBase& rhs) const; bool operator!=(const ChildIteratorBase& rhs) const; ChildIteratorBase& operator++(); ChildIteratorBase& operator--(); NodeType* get() const; NodeType& operator*() const; NodeType* operator->() const; protected: const NodeType* parent_; NodeType* child_; }; // The constructor requires a parent, id, and index in parent, but // the data is not required. After initialization, only index_in_parent // and unignored_index_in_parent is allowed to change, the others are // guaranteed to never change. AXNode(OwnerTree* tree, AXNode* parent, int32_t id, size_t index_in_parent, size_t unignored_index_in_parent = 0); virtual ~AXNode(); // Accessors. OwnerTree* tree() const { return tree_; } AXID id() const { return data_.id; } AXNode* parent() const { return parent_; } const AXNodeData& data() const { return data_; } const std::vector& children() const { return children_; } size_t index_in_parent() const { return index_in_parent_; } // Returns ownership of |data_| to the caller; effectively clearing |data_|. AXNodeData&& TakeData(); // Walking the tree skipping ignored nodes. size_t GetUnignoredChildCount() const; AXNode* GetUnignoredChildAtIndex(size_t index) const; AXNode* GetUnignoredParent() const; size_t GetUnignoredIndexInParent() const; size_t GetIndexInParent() const; AXNode* GetFirstUnignoredChild() const; AXNode* GetLastUnignoredChild() const; AXNode* GetDeepestFirstUnignoredChild() const; AXNode* GetDeepestLastUnignoredChild() const; AXNode* GetNextUnignoredSibling() const; AXNode* GetPreviousUnignoredSibling() const; AXNode* GetNextUnignoredInTreeOrder() const; AXNode* GetPreviousUnignoredInTreeOrder() const; using UnignoredChildIterator = ChildIteratorBase; UnignoredChildIterator UnignoredChildrenBegin() const; UnignoredChildIterator UnignoredChildrenEnd() const; // Walking the tree including both ignored and unignored nodes. // These methods consider only the direct children or siblings of a node. AXNode* GetFirstChild() const; AXNode* GetLastChild() const; AXNode* GetPreviousSibling() const; AXNode* GetNextSibling() const; // Returns true if the node has any of the text related roles, including // kStaticText, kInlineTextBox and kListMarker (for Legacy Layout). Does not // include any text field roles. bool IsText() const; // Returns true if the node has any line break related roles or is the child // of a node with line break related roles. bool IsLineBreak() const; // Set the node's accessibility data. This may be done during initialization // or later when the node data changes. void SetData(const AXNodeData& src); // Update this node's location. This is separate from |SetData| just because // changing only the location is common and should be more efficient than // re-copying all of the data. // // The node's location is stored as a relative bounding box, the ID of // the element it's relative to, and an optional transformation matrix. // See ax_node_data.h for details. void SetLocation(int32_t offset_container_id, const gfx::RectF& location, gfx::Transform* transform); // Set the index in parent, for example if siblings were inserted or deleted. void SetIndexInParent(size_t index_in_parent); // Update the unignored index in parent for unignored children. void UpdateUnignoredCachedValues(); // Swap the internal children vector with |children|. This instance // now owns all of the passed children. void SwapChildren(std::vector* children); // This is called when the AXTree no longer includes this node in the // tree. Reference counting is used on some platforms because the // operating system may hold onto a reference to an AXNode // object even after we're through with it, so this may decrement the // reference count and clear out the object's data. void Destroy(); // Return true if this object is equal to or a descendant of |ancestor|. bool IsDescendantOf(const AXNode* ancestor) const; // Gets the text offsets where new lines start either from the node's data or // by computing them and caching the result. std::vector GetOrComputeLineStartOffsets(); // Accessing accessibility attributes. // See |AXNodeData| for more information. bool HasBoolAttribute(ax::mojom::BoolAttribute attribute) const { return data().HasBoolAttribute(attribute); } bool GetBoolAttribute(ax::mojom::BoolAttribute attribute) const { return data().GetBoolAttribute(attribute); } bool GetBoolAttribute(ax::mojom::BoolAttribute attribute, bool* value) const { return data().GetBoolAttribute(attribute, value); } bool HasFloatAttribute(ax::mojom::FloatAttribute attribute) const { return data().HasFloatAttribute(attribute); } float GetFloatAttribute(ax::mojom::FloatAttribute attribute) const { return data().GetFloatAttribute(attribute); } bool GetFloatAttribute(ax::mojom::FloatAttribute attribute, float* value) const { return data().GetFloatAttribute(attribute, value); } bool HasIntAttribute(ax::mojom::IntAttribute attribute) const { return data().HasIntAttribute(attribute); } int GetIntAttribute(ax::mojom::IntAttribute attribute) const { return data().GetIntAttribute(attribute); } bool GetIntAttribute(ax::mojom::IntAttribute attribute, int* value) const { return data().GetIntAttribute(attribute, value); } bool HasStringAttribute(ax::mojom::StringAttribute attribute) const { return data().HasStringAttribute(attribute); } const std::string& GetStringAttribute( ax::mojom::StringAttribute attribute) const { return data().GetStringAttribute(attribute); } bool GetStringAttribute(ax::mojom::StringAttribute attribute, std::string* value) const { return data().GetStringAttribute(attribute, value); } bool GetString16Attribute(ax::mojom::StringAttribute attribute, base::string16* value) const { return data().GetString16Attribute(attribute, value); } base::string16 GetString16Attribute( ax::mojom::StringAttribute attribute) const { return data().GetString16Attribute(attribute); } bool HasIntListAttribute(ax::mojom::IntListAttribute attribute) const { return data().HasIntListAttribute(attribute); } const std::vector& GetIntListAttribute( ax::mojom::IntListAttribute attribute) const { return data().GetIntListAttribute(attribute); } bool GetIntListAttribute(ax::mojom::IntListAttribute attribute, std::vector* value) const { return data().GetIntListAttribute(attribute, value); } bool HasStringListAttribute(ax::mojom::StringListAttribute attribute) const { return data().HasStringListAttribute(attribute); } const std::vector& GetStringListAttribute( ax::mojom::StringListAttribute attribute) const { return data().GetStringListAttribute(attribute); } bool GetStringListAttribute(ax::mojom::StringListAttribute attribute, std::vector* value) const { return data().GetStringListAttribute(attribute, value); } bool GetHtmlAttribute(const char* attribute, base::string16* value) const { return data().GetHtmlAttribute(attribute, value); } bool GetHtmlAttribute(const char* attribute, std::string* value) const { return data().GetHtmlAttribute(attribute, value); } // Return the hierarchical level if supported. base::Optional GetHierarchicalLevel() const; // PosInSet and SetSize public methods. bool IsOrderedSetItem() const; bool IsOrderedSet() const; base::Optional GetPosInSet(); base::Optional GetSetSize(); // Helpers for GetPosInSet and GetSetSize. // Returns true if the role of ordered set matches the role of item. // Returns false otherwise. bool SetRoleMatchesItemRole(const AXNode* ordered_set) const; // Container objects that should be ignored for computing PosInSet and SetSize // for ordered sets. bool IsIgnoredContainerForOrderedSet() const; const std::string& GetInheritedStringAttribute( ax::mojom::StringAttribute attribute) const; base::string16 GetInheritedString16Attribute( ax::mojom::StringAttribute attribute) const; // If this node is a leaf, returns the inner text of this node. This is // equivalent to its visible accessible name. Otherwise, if this node is not a // leaf, represents every non-textual child node with a special "embedded // object character", and every textual child node with its inner text. // Textual nodes include e.g. static text and white space. // // This is how displayed text and embedded objects are represented in // ATK and IAccessible2 APIs. std::string GetHypertext() const; // Returns the text of this node and all descendant nodes; including text // found in embedded objects. // // Only text displayed on screen is included. Text from ARIA and HTML // attributes that is either not displayed on screen, or outside this node, is // not returned. std::string GetInnerText() const; // Returns a string representing the language code. // // This will consider the language declared in the DOM, and may eventually // attempt to automatically detect the language from the text. // // This language code will be BCP 47. // // Returns empty string if no appropriate language was found. std::string GetLanguage() const; // Returns the value of a control such as a text field, a slider, a