| // Copyright (c) 2012 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 CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_ |
| #define CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_ |
| |
| #include <stdint.h> |
| |
| #include <map> |
| #include <memory> |
| #include <set> |
| #include <string> |
| #include <utility> |
| #include <vector> |
| |
| #include "base/macros.h" |
| #include "base/optional.h" |
| #include "base/strings/string16.h" |
| #include "base/strings/string_split.h" |
| #include "build/build_config.h" |
| #include "content/browser/accessibility/accessibility_buildflags.h" |
| #include "content/browser/accessibility/browser_accessibility_position.h" |
| #include "content/common/content_export.h" |
| #include "third_party/blink/public/web/web_ax_enums.h" |
| #include "ui/accessibility/ax_enums.mojom.h" |
| #include "ui/accessibility/ax_node.h" |
| #include "ui/accessibility/ax_node_data.h" |
| #include "ui/accessibility/ax_node_position.h" |
| #include "ui/accessibility/ax_range.h" |
| #include "ui/accessibility/ax_text_boundary.h" |
| #include "ui/accessibility/ax_text_utils.h" |
| #include "ui/accessibility/platform/ax_platform_node.h" |
| #include "ui/accessibility/platform/ax_platform_node_delegate.h" |
| |
| // Set PLATFORM_HAS_NATIVE_ACCESSIBILITY_IMPL if this platform has |
| // a platform-specific subclass of BrowserAccessibility and |
| // BrowserAccessibilityManager. |
| #undef PLATFORM_HAS_NATIVE_ACCESSIBILITY_IMPL |
| |
| #if defined(OS_WIN) |
| #define PLATFORM_HAS_NATIVE_ACCESSIBILITY_IMPL 1 |
| #endif |
| |
| #if defined(OS_MACOSX) |
| #define PLATFORM_HAS_NATIVE_ACCESSIBILITY_IMPL 1 |
| #endif |
| |
| #if defined(OS_ANDROID) && !defined(USE_AURA) |
| #define PLATFORM_HAS_NATIVE_ACCESSIBILITY_IMPL 1 |
| #endif |
| |
| #if BUILDFLAG(USE_ATK) |
| #define PLATFORM_HAS_NATIVE_ACCESSIBILITY_IMPL 1 |
| #endif |
| |
| #if defined(OS_MACOSX) && __OBJC__ |
| @class BrowserAccessibilityCocoa; |
| #endif |
| |
| namespace content { |
| class BrowserAccessibilityManager; |
| |
| //////////////////////////////////////////////////////////////////////////////// |
| // |
| // BrowserAccessibility |
| // |
| // A BrowserAccessibility object represents one node in the accessibility |
| // tree on the browser side. It exactly corresponds to one WebAXObject from |
| // Blink. It's owned by a BrowserAccessibilityManager. |
| // |
| // There are subclasses of BrowserAccessibility for each platform where |
| // we implement native accessibility APIs. This base class is used occasionally |
| // for tests. |
| // |
| //////////////////////////////////////////////////////////////////////////////// |
| class CONTENT_EXPORT BrowserAccessibility : public ui::AXPlatformNodeDelegate { |
| public: |
| // Creates a platform specific BrowserAccessibility. Ownership passes to the |
| // caller. |
| static BrowserAccessibility* Create(); |
| |
| ~BrowserAccessibility() override; |
| |
| // Called only once, immediately after construction. The constructor doesn't |
| // take any arguments because in the Windows subclass we use a special |
| // function to construct a COM object. |
| virtual void Init(BrowserAccessibilityManager* manager, ui::AXNode* node); |
| |
| // Called after the object is first initialized and again every time |
| // its data changes. |
| virtual void OnDataChanged() {} |
| |
| virtual void OnSubtreeWillBeDeleted() {} |
| |
| // Called when the location changed. |
| virtual void OnLocationChanged() {} |
| |
| // This is called when the platform-specific attributes for a node need |
| // to be recomputed, which may involve firing native events, due to a |
| // change other than an update from OnAccessibilityEvents. |
| virtual void UpdatePlatformAttributes() {} |
| |
| // Return true if this object is equal to or a descendant of |ancestor|. |
| bool IsDescendantOf(const BrowserAccessibility* ancestor) const; |
| |
| bool IsDocument() const; |
| |
| bool IsEditField() const; |
| |
| // Returns true if this object is used only for representing text. |
| bool IsTextOnlyObject() const; |
| |
| bool IsLineBreakObject() const; |
| |
| // Returns true if this is a leaf node on this platform, meaning any |
| // children should not be exposed to this platform's native accessibility |
| // layer. Each platform subclass should implement this itself. |
| // The definition of a leaf may vary depending on the platform, |
| // but a leaf node should never have children that are focusable or |
| // that might send notifications. |
| virtual bool PlatformIsLeaf() const; |
| |
| // Returns true if this object can fire events. |
| virtual bool CanFireEvents() const; |
| |
| // Returns the number of children of this object, or 0 if PlatformIsLeaf() |
| // returns true. |
| virtual uint32_t PlatformChildCount() const; |
| |
| // Return a pointer to the child at the given index, or NULL for an |
| // invalid index. Returns NULL if PlatformIsLeaf() returns true. |
| virtual BrowserAccessibility* PlatformGetChild(uint32_t child_index) const; |
| |
| BrowserAccessibility* PlatformGetParent() const; |
| |
| // Return a pointer to the first ancestor that is a selection container |
| BrowserAccessibility* PlatformGetSelectionContainer() const; |
| |
| // Returns true if an ancestor of this node (not including itself) is a |
| // leaf node, meaning that this node is not actually exposed to the |
| // platform. |
| bool PlatformIsChildOfLeaf() const; |
| |
| // If this object is exposed to the platform, returns this object. Otherwise, |
| // returns the platform leaf under which this object is found. |
| BrowserAccessibility* GetClosestPlatformObject() const; |
| |
| BrowserAccessibility* GetPreviousSibling() const; |
| BrowserAccessibility* GetNextSibling() const; |
| |
| bool IsPreviousSiblingOnSameLine() const; |
| bool IsNextSiblingOnSameLine() const; |
| |
| // Returns nullptr if there are no children. |
| BrowserAccessibility* PlatformDeepestFirstChild() const; |
| // Returns nullptr if there are no children. |
| BrowserAccessibility* PlatformDeepestLastChild() const; |
| |
| // Returns nullptr if there are no children. |
| BrowserAccessibility* InternalDeepestFirstChild() const; |
| // Returns nullptr if there are no children. |
| BrowserAccessibility* InternalDeepestLastChild() const; |
| |
| // Derivative utils for AXPlatformNodeDelegate::GetBoundsRect |
| gfx::Rect GetClippedScreenBoundsRect( |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| gfx::Rect GetUnclippedScreenBoundsRect( |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| gfx::Rect GetClippedRootFrameBoundsRect( |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| gfx::Rect GetUnclippedRootFrameBoundsRect( |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| gfx::Rect GetClippedFrameBoundsRect( |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| |
| // Derivative utils for AXPlatformNodeDelegate::GetHypertextRangeBoundsRect |
| gfx::Rect GetUnclippedRootFrameHypertextRangeBoundsRect( |
| const int start_offset, |
| const int end_offset, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| |
| // Derivative utils for AXPlatformNodeDelegate::GetInnerTextRangeBoundsRect |
| gfx::Rect GetUnclippedScreenInnerTextRangeBoundsRect( |
| const int start_offset, |
| const int end_offset, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| gfx::Rect GetUnclippedRootFrameInnerTextRangeBoundsRect( |
| const int start_offset, |
| const int end_offset, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| |
| // DEPRECATED: Prefer using the interfaces provided by AXPlatformNodeDelegate |
| // when writing new code. |
| gfx::Rect GetScreenHypertextRangeBoundsRect( |
| int start, |
| int len, |
| const ui::AXClippingBehavior clipping_behavior, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| |
| // Returns the bounds of the given range in coordinates relative to the |
| // top-left corner of the overall web area. Only valid when the role is |
| // WebAXRoleStaticText. |
| // DEPRECATED (for public use): Prefer using the interfaces provided by |
| // AXPlatformNodeDelegate when writing new non-private code. |
| gfx::Rect GetRootFrameHypertextRangeBoundsRect( |
| int start, |
| int len, |
| const ui::AXClippingBehavior clipping_behavior, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| |
| // This is to handle the cases such as ARIA textbox, where the value should |
| // be calculated from the object's inner text. |
| virtual base::string16 GetValue() const; |
| |
| // This is an approximate hit test that only uses the information in |
| // the browser process to compute the correct result. It will not return |
| // correct results in many cases of z-index, overflow, and absolute |
| // positioning, so BrowserAccessibilityManager::CachingAsyncHitTest |
| // should be used instead, which falls back on calling ApproximateHitTest |
| // automatically. |
| BrowserAccessibility* ApproximateHitTest(const gfx::Point& screen_point); |
| |
| // Marks this object for deletion, releases our reference to it, and |
| // nulls out the pointer to the underlying AXNode. May not delete |
| // the object immediately due to reference counting. |
| // |
| // Reference counting is used on some platforms because the |
| // operating system may hold onto a reference to a BrowserAccessibility |
| // object even after we're through with it. When a BrowserAccessibility |
| // has had Destroy() called but its reference count is not yet zero, |
| // instance_active() returns false and queries on this object return failure. |
| virtual void Destroy(); |
| |
| // Subclasses should override this to support platform reference counting. |
| virtual void NativeAddReference() {} |
| |
| // Subclasses should override this to support platform reference counting. |
| virtual void NativeReleaseReference(); |
| |
| // |
| // Accessors |
| // |
| |
| BrowserAccessibilityManager* manager() const { return manager_; } |
| bool instance_active() const { return node_ && manager_; } |
| ui::AXNode* node() const { return node_; } |
| |
| // These access the internal unignored accessibility tree, which doesn't |
| // necessarily reflect the accessibility tree that should be exposed on each |
| // platform. Use PlatformChildCount and PlatformGetChild to implement platform |
| // accessibility APIs. |
| uint32_t InternalChildCount() const; |
| BrowserAccessibility* InternalGetChild(uint32_t child_index) const; |
| BrowserAccessibility* InternalGetParent() const; |
| |
| int32_t GetId() const; |
| gfx::RectF GetLocation() const; |
| ax::mojom::Role GetRole() const; |
| int32_t GetState() const; |
| |
| typedef base::StringPairs HtmlAttributes; |
| const HtmlAttributes& GetHtmlAttributes() const; |
| |
| // Returns true if this is a native platform-specific object, vs a |
| // cross-platform generic object. Don't call ToBrowserAccessibilityXXX if |
| // IsNative returns false. |
| virtual bool IsNative() const; |
| |
| // Accessing accessibility attributes: |
| // |
| // There are dozens of possible attributes for an accessibility node, |
| // but only a few tend to apply to any one object, so we store them |
| // in sparse arrays of <attribute id, attribute value> pairs, organized |
| // by type (bool, int, float, string, int list). |
| // |
| // There are three accessors for each type of attribute: one that returns |
| // true if the attribute is present and false if not, one that takes a |
| // pointer argument and returns true if the attribute is present (if you |
| // need to distinguish between the default value and a missing attribute), |
| // and another that returns the default value for that type if the |
| // attribute is not present. In addition, strings can be returned as |
| // either std::string or base::string16, for convenience. |
| |
| bool HasBoolAttribute(ax::mojom::BoolAttribute attr) const; |
| bool GetBoolAttribute(ax::mojom::BoolAttribute attr) const; |
| bool GetBoolAttribute(ax::mojom::BoolAttribute attr, bool* value) const; |
| |
| bool HasFloatAttribute(ax::mojom::FloatAttribute attr) const; |
| float GetFloatAttribute(ax::mojom::FloatAttribute attr) const; |
| bool GetFloatAttribute(ax::mojom::FloatAttribute attr, float* value) const; |
| |
| bool HasInheritedStringAttribute(ax::mojom::StringAttribute attribute) const; |
| const std::string& GetInheritedStringAttribute( |
| ax::mojom::StringAttribute attribute) const; |
| base::string16 GetInheritedString16Attribute( |
| ax::mojom::StringAttribute attribute) const; |
| |
| bool HasIntAttribute(ax::mojom::IntAttribute attribute) const; |
| int GetIntAttribute(ax::mojom::IntAttribute attribute) const; |
| bool GetIntAttribute(ax::mojom::IntAttribute attribute, int* value) const; |
| |
| bool HasStringAttribute(ax::mojom::StringAttribute attribute) const; |
| const std::string& GetStringAttribute( |
| ax::mojom::StringAttribute attribute) const; |
| bool GetStringAttribute(ax::mojom::StringAttribute attribute, |
| std::string* value) const; |
| |
| base::string16 GetString16Attribute( |
| ax::mojom::StringAttribute attribute) const; |
| bool GetString16Attribute(ax::mojom::StringAttribute attribute, |
| base::string16* value) const; |
| |
| bool HasIntListAttribute(ax::mojom::IntListAttribute attribute) const; |
| const std::vector<int32_t>& GetIntListAttribute( |
| ax::mojom::IntListAttribute attribute) const; |
| bool GetIntListAttribute(ax::mojom::IntListAttribute attribute, |
| std::vector<int32_t>* value) const; |
| |
| // Retrieve the value of a html attribute from the attribute map and |
| // returns true if found. |
| bool GetHtmlAttribute(const char* attr, std::string* value) const; |
| bool GetHtmlAttribute(const char* attr, base::string16* value) const; |
| |
| // Returns true if the bit corresponding to the given enum is 1. |
| bool HasState(ax::mojom::State state_enum) const; |
| bool HasAction(ax::mojom::Action action_enum) const; |
| |
| // Returns true if the caret or selection is visible on this object. |
| bool HasVisibleCaretOrSelection() const; |
| |
| // True if this is a web area, and its grandparent is a presentational iframe. |
| bool IsWebAreaForPresentationalIframe() const; |
| |
| virtual bool IsClickable() const; |
| bool IsPlainTextField() const; |
| bool IsRichTextField() const; |
| |
| // Return true if the accessible name was explicitly set to "" by the author |
| bool HasExplicitlyEmptyName() const; |
| |
| // If an object is focusable but has no accessible name, use this |
| // to compute a name from its descendants. |
| std::string ComputeAccessibleNameFromDescendants() const; |
| |
| // Get text to announce for a live region change if AT does not implement. |
| std::string GetLiveRegionText() const; |
| |
| // Creates a text position rooted at this object. Does not conver to a |
| // leaf text position - see CreatePositionForSelectionAt, below. |
| BrowserAccessibilityPosition::AXPositionInstance CreatePositionAt( |
| int offset, |
| ax::mojom::TextAffinity affinity = |
| ax::mojom::TextAffinity::kDownstream) const; |
| |
| // |offset| could either be a text character or a child index in case of |
| // non-text objects. Converts to a leaf text position if you pass a |
| // character offset on a container node. |
| BrowserAccessibilityPosition::AXPositionInstance CreatePositionForSelectionAt( |
| int offset) const; |
| |
| // Gets the text offsets where new lines start. |
| std::vector<int> GetLineStartOffsets() const; |
| |
| virtual gfx::NativeViewAccessible GetNativeViewAccessible(); |
| |
| // AXPosition Support |
| |
| // Returns the text that is present inside this node, where the representation |
| // of text found in descendant nodes depends on the platform. For example some |
| // platforms may include descendant text while while other platforms may use a |
| // special character to represent descendant text. Prefer either GetHypertext |
| // or GetInnerText so it's clear which API is called. |
| virtual base::string16 GetText() const; |
| |
| // AXPlatformNodeDelegate. |
| base::string16 GetAuthorUniqueId() const override; |
| const ui::AXNodeData& GetData() const override; |
| const ui::AXTreeData& GetTreeData() const override; |
| ui::AXNodePosition::AXPositionInstance CreateTextPositionAt( |
| int offset, |
| ax::mojom::TextAffinity affinity = |
| ax::mojom::TextAffinity::kDownstream) const override; |
| gfx::NativeViewAccessible GetNSWindow() override; |
| gfx::NativeViewAccessible GetParent() override; |
| int GetChildCount() override; |
| gfx::NativeViewAccessible ChildAtIndex(int index) override; |
| base::string16 GetHypertext() const override; |
| bool SetHypertextSelection(int start_offset, int end_offset) override; |
| base::string16 GetInnerText() const override; |
| gfx::Rect GetBoundsRect( |
| const ui::AXCoordinateSystem coordinate_system, |
| const ui::AXClippingBehavior clipping_behavior, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const override; |
| gfx::Rect GetHypertextRangeBoundsRect( |
| const int start_offset, |
| const int end_offset, |
| const ui::AXCoordinateSystem coordinate_system, |
| const ui::AXClippingBehavior clipping_behavior, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const override; |
| gfx::Rect GetInnerTextRangeBoundsRect( |
| const int start_offset, |
| const int end_offset, |
| const ui::AXCoordinateSystem coordinate_system, |
| const ui::AXClippingBehavior clipping_behavior, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const override; |
| gfx::NativeViewAccessible HitTestSync(int x, int y) override; |
| gfx::NativeViewAccessible GetFocus() override; |
| ui::AXPlatformNode* GetFromNodeID(int32_t id) override; |
| int GetIndexInParent() const override; |
| gfx::AcceleratedWidget GetTargetForNativeAccessibilityEvent() override; |
| |
| base::Optional<int> FindTextBoundary( |
| ui::AXTextBoundary boundary, |
| int offset, |
| ui::TextBoundaryDirection direction, |
| ax::mojom::TextAffinity affinity) const override; |
| |
| const std::vector<gfx::NativeViewAccessible> GetDescendants() const override; |
| |
| bool IsTable() const override; |
| base::Optional<int> GetTableColCount() const override; |
| base::Optional<int> GetTableRowCount() const override; |
| base::Optional<int> GetTableAriaColCount() const override; |
| base::Optional<int> GetTableAriaRowCount() const override; |
| base::Optional<int> GetTableCellCount() const override; |
| std::vector<int32_t> GetColHeaderNodeIds() const override; |
| std::vector<int32_t> GetColHeaderNodeIds(int col_index) const override; |
| std::vector<int32_t> GetRowHeaderNodeIds() const override; |
| std::vector<int32_t> GetRowHeaderNodeIds(int row_index) const override; |
| ui::AXPlatformNode* GetTableCaption() const override; |
| |
| bool IsTableRow() const override; |
| base::Optional<int> GetTableRowRowIndex() const override; |
| |
| bool IsTableCellOrHeader() const override; |
| base::Optional<int> GetTableCellIndex() const override; |
| base::Optional<int> GetTableCellColIndex() const override; |
| base::Optional<int> GetTableCellRowIndex() const override; |
| base::Optional<int> GetTableCellColSpan() const override; |
| base::Optional<int> GetTableCellRowSpan() const override; |
| base::Optional<int> GetTableCellAriaColIndex() const override; |
| base::Optional<int> GetTableCellAriaRowIndex() const override; |
| base::Optional<int32_t> GetCellId(int row_index, |
| int col_index) const override; |
| base::Optional<int32_t> CellIndexToId(int cell_index) const override; |
| |
| bool IsCellOrHeaderOfARIATable() const override; |
| bool IsCellOrHeaderOfARIAGrid() const override; |
| |
| bool AccessibilityPerformAction(const ui::AXActionData& data) override; |
| base::string16 GetLocalizedStringForImageAnnotationStatus( |
| ax::mojom::ImageAnnotationStatus status) const override; |
| base::string16 GetLocalizedRoleDescriptionForUnlabeledImage() const override; |
| base::string16 GetLocalizedStringForLandmarkType() const override; |
| base::string16 GetStyleNameAttributeAsLocalizedString() const override; |
| bool ShouldIgnoreHoveredStateForTesting() override; |
| bool IsOffscreen() const override; |
| bool IsMinimized() const override; |
| bool IsWebContent() const override; |
| ui::AXPlatformNode* GetTargetNodeForRelation( |
| ax::mojom::IntAttribute attr) override; |
| std::set<ui::AXPlatformNode*> GetTargetNodesForRelation( |
| ax::mojom::IntListAttribute attr) override; |
| std::set<ui::AXPlatformNode*> GetReverseRelations( |
| ax::mojom::IntAttribute attr) override; |
| std::set<ui::AXPlatformNode*> GetReverseRelations( |
| ax::mojom::IntListAttribute attr) override; |
| bool IsOrderedSetItem() const override; |
| bool IsOrderedSet() const override; |
| base::Optional<int> GetPosInSet() const override; |
| base::Optional<int> GetSetSize() const override; |
| |
| protected: |
| using BrowserAccessibilityPositionInstance = |
| BrowserAccessibilityPosition::AXPositionInstance; |
| using AXPlatformRange = |
| ui::AXRange<BrowserAccessibilityPositionInstance::element_type>; |
| |
| BrowserAccessibility(); |
| |
| // The manager of this tree of accessibility objects. |
| BrowserAccessibilityManager* manager_; |
| |
| // The underlying node. |
| ui::AXNode* node_; |
| |
| // Protected so that it can't be called directly on a BrowserAccessibility |
| // where it could be confused with an id that comes from the node data, |
| // which is only unique to the Blink process. |
| // Does need to be called by subclasses such as BrowserAccessibilityAndroid. |
| const ui::AXUniqueId& GetUniqueId() const override; |
| |
| private: |
| // Return the bounds after converting from this node's coordinate system |
| // (which is relative to its nearest scrollable ancestor) to the coordinate |
| // system specified. If the clipping behavior is set to clipped, clipping is |
| // applied to all bounding boxes so that the resulting rect is within the |
| // window. If the clipping behavior is unclipped, the resulting rect may be |
| // outside of the window or offscreen. If an offscreen result address is |
| // provided, it will be populated depending on whether the returned bounding |
| // box is onscreen or offscreen. |
| gfx::Rect RelativeToAbsoluteBounds( |
| gfx::RectF bounds, |
| const ui::AXCoordinateSystem coordinate_system, |
| const ui::AXClippingBehavior clipping_behavior, |
| ui::AXOffscreenResult* offscreen_result) const; |
| |
| // Return a rect for a 1-width character past the end of text. This is what |
| // ATs expect when getting the character extents past the last character in a |
| // line, and equals what the caret bounds would be when past the end of the |
| // text. |
| gfx::Rect GetRootFrameHypertextBoundsPastEndOfText( |
| const ui::AXClippingBehavior clipping_behavior, |
| ui::AXOffscreenResult* offscreen_result = nullptr) const; |
| |
| // Return the bounds of inline text in this node's coordinate system (which is |
| // relative to its container node specified in AXRelativeBounds). |
| gfx::RectF GetInlineTextRect(const int start_offset, |
| const int end_offset, |
| const int max_length) const; |
| |
| // Recursive helper function for GetInnerTextRangeBounds. |
| gfx::Rect GetInnerTextRangeBoundsRectInSubtree( |
| const int start_offset, |
| const int end_offset, |
| const ui::AXCoordinateSystem coordinate_system, |
| const ui::AXClippingBehavior clipping_behavior, |
| ui::AXOffscreenResult* offscreen_result) const; |
| |
| // Given a set of node ids, return the nodes in this delegate's tree to |
| // which they correspond. |
| std::set<ui::AXPlatformNode*> GetNodesForNodeIdSet( |
| const std::set<int32_t>& ids); |
| |
| // A unique ID, since node IDs are frame-local. |
| ui::AXUniqueId unique_id_; |
| |
| DISALLOW_COPY_AND_ASSIGN(BrowserAccessibility); |
| }; |
| |
| } // namespace content |
| |
| #endif // CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_ |