content/browser/accessibility/browser_accessibility.h

   1 // Copyright (c) 2012 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
   5 #ifndef CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_
   6 #define CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_
   7
   8 #include <map>
   9 #include <utility>
  10 #include <vector>
  11
  12 #include "base/basictypes.h"
  13 #include "base/strings/string16.h"
  14 #include "base/strings/string_split.h"
  15 #include "build/build_config.h"
  16 #include "content/common/content_export.h"
  17 #include "third_party/WebKit/public/web/WebAXEnums.h"
  18 #include "ui/accessibility/ax_node.h"
  19 #include "ui/accessibility/ax_node_data.h"
  20 #include "ui/accessibility/ax_text_utils.h"
  21
  22 #if defined(OS_MACOSX) && __OBJC__
  23 @class BrowserAccessibilityCocoa;
  24 #endif
  25
  26 namespace content {
  27 class BrowserAccessibilityManager;
  28 #if defined(OS_WIN)
  29 class BrowserAccessibilityWin;
  30 #elif defined(OS_LINUX) && !defined(OS_CHROMEOS) && defined(USE_X11)
  31 class BrowserAccessibilityAuraLinux;
  32 #endif
  33
  34 ////////////////////////////////////////////////////////////////////////////////
  35 //
  36 // BrowserAccessibility
  37 //
  38 // A BrowserAccessibility object represents one node in the accessibility
  39 // tree on the browser side. It exactly corresponds to one WebAXObject from
  40 // Blink. It's owned by a BrowserAccessibilityManager.
  41 //
  42 // There are subclasses of BrowserAccessibility for each platform where
  43 // we implement native accessibility APIs. This base class is used occasionally
  44 // for tests.
  45 //
  46 ////////////////////////////////////////////////////////////////////////////////
  47 class CONTENT_EXPORT BrowserAccessibility {
  48  public:
  49   // Creates a platform specific BrowserAccessibility. Ownership passes to the
  50   // caller.
  51   static BrowserAccessibility* Create();
  52
  53   virtual ~BrowserAccessibility();
  54
  55   // Called only once, immediately after construction. The constructor doesn't
  56   // take any arguments because in the Windows subclass we use a special
  57   // function to construct a COM object.
  58   virtual void Init(BrowserAccessibilityManager* manager, ui::AXNode* node);
  59
  60   // Called after the object is first initialized and again every time
  61   // its data changes.
  62   virtual void OnDataChanged() {}
  63
  64   virtual void OnSubtreeWillBeDeleted() {}
  65
  66   // Called when the location changed.
  67   virtual void OnLocationChanged() {}
  68
  69   // Return true if this object is equal to or a descendant of |ancestor|.
  70   bool IsDescendantOf(const BrowserAccessibility* ancestor) const;
  71
  72   // Returns true if this object is used only for representing text.
  73   bool IsTextOnlyObject() const;
  74
  75   // Returns true if this is a leaf node on this platform, meaning any
  76   // children should not be exposed to this platform's native accessibility
  77   // layer. Each platform subclass should implement this itself.
  78   // The definition of a leaf may vary depending on the platform,
  79   // but a leaf node should never have children that are focusable or
  80   // that might send notifications.
  81   virtual bool PlatformIsLeaf() const;
  82
  83   // Returns the number of children of this object, or 0 if PlatformIsLeaf()
  84   // returns true.
  85   uint32 PlatformChildCount() const;
  86
  87   // Return a pointer to the child at the given index, or NULL for an
  88   // invalid index. Returns NULL if PlatformIsLeaf() returns true.
  89   BrowserAccessibility* PlatformGetChild(uint32 child_index) const;
  90
  91   // Returns true if an ancestor of this node (not including itself) is a
  92   // leaf node, meaning that this node is not actually exposed to the
  93   // platform.
  94   bool PlatformIsChildOfLeaf() const;
  95
  96   BrowserAccessibility* GetPreviousSibling() const;
  97   BrowserAccessibility* GetNextSibling() const;
  98
  99   // Returns nullptr if there are no children.
 100   BrowserAccessibility* PlatformDeepestFirstChild() const;
 101   // Returns nullptr if there are no children.
 102   BrowserAccessibility* PlatformDeepestLastChild() const;
 103
 104   // Returns the bounds of this object in coordinates relative to the
 105   // top-left corner of the overall web area.
 106   gfx::Rect GetLocalBoundsRect() const;
 107
 108   // Returns the bounds of this object in screen coordinates.
 109   gfx::Rect GetGlobalBoundsRect() const;
 110
 111   // Returns the bounds of the given range in coordinates relative to the
 112   // top-left corner of the overall web area. Only valid when the
 113   // role is WebAXRoleStaticText.
 114   gfx::Rect GetLocalBoundsForRange(int start, int len) const;
 115
 116   // Same as GetLocalBoundsForRange, in screen coordinates. Only valid when
 117   // the role is WebAXRoleStaticText.
 118   gfx::Rect GetGlobalBoundsForRange(int start, int len) const;
 119
 120   // Searches in the given text and from the given offset until the start of
 121   // the next or previous word is found and returns its position.
 122   // In case there is no word boundary before or after the given offset, it
 123   // returns one past the last character, i.e. the text's length.
 124   // If the given offset is already at the start of a word, returns the start
 125   // of the next word if the search is forwards and the given offset if it is
 126   // backwards.
 127   // If the start offset is equal to -1 and the search is in the forwards
 128   // direction, returns the start boundary of the first word.
 129   // Start offsets that are not in the range -1 to text length are invalid.
 130   int GetWordStartBoundary(
 131       int start, ui::TextBoundaryDirection direction) const;
 132
 133   // Returns the deepest descendant that contains the specified point
 134   // (in global screen coordinates).
 135   BrowserAccessibility* BrowserAccessibilityForPoint(const gfx::Point& point);
 136
 137   // Marks this object for deletion, releases our reference to it, and
 138   // nulls out the pointer to the underlying AXNode.  May not delete
 139   // the object immediately due to reference counting.
 140   //
 141   // Reference counting is used on some platforms because the
 142   // operating system may hold onto a reference to a BrowserAccessibility
 143   // object even after we're through with it. When a BrowserAccessibility
 144   // has had Destroy() called but its reference count is not yet zero,
 145   // instance_active() returns false and queries on this object return failure.
 146   virtual void Destroy();
 147
 148   // Subclasses should override this to support platform reference counting.
 149   virtual void NativeAddReference() { }
 150
 151   // Subclasses should override this to support platform reference counting.
 152   virtual void NativeReleaseReference();
 153
 154   //
 155   // Accessors
 156   //
 157
 158   BrowserAccessibilityManager* manager() const { return manager_; }
 159   bool instance_active() const { return node_ != NULL; }
 160   ui::AXNode* node() const { return node_; }
 161
 162   // These access the internal accessibility tree, which doesn't necessarily
 163   // reflect the accessibility tree that should be exposed on each platform.
 164   // Use PlatformChildCount and PlatformGetChild to implement platform
 165   // accessibility APIs.
 166   uint32 InternalChildCount() const;
 167   BrowserAccessibility* InternalGetChild(uint32 child_index) const;
 168
 169   BrowserAccessibility* GetParent() const;
 170   int32 GetIndexInParent() const;
 171
 172   int32 GetId() const;
 173   const ui::AXNodeData& GetData() const;
 174   gfx::Rect GetLocation() const;
 175   int32 GetRole() const;
 176   int32 GetState() const;
 177
 178   typedef base::StringPairs HtmlAttributes;
 179   const HtmlAttributes& GetHtmlAttributes() const;
 180
 181   // Returns true if this is a native platform-specific object, vs a
 182   // cross-platform generic object. Don't call ToBrowserAccessibilityXXX if
 183   // IsNative returns false.
 184   virtual bool IsNative() const;
 185
 186 #if defined(OS_MACOSX) && __OBJC__
 187   BrowserAccessibilityCocoa* ToBrowserAccessibilityCocoa();
 188 #elif defined(OS_WIN)
 189   BrowserAccessibilityWin* ToBrowserAccessibilityWin();
 190 #elif defined(OS_LINUX) && !defined(OS_CHROMEOS) && defined(USE_X11)
 191   BrowserAccessibilityAuraLinux* ToBrowserAccessibilityAuraLinux();
 192 #endif
 193
 194   // Accessing accessibility attributes:
 195   //
 196   // There are dozens of possible attributes for an accessibility node,
 197   // but only a few tend to apply to any one object, so we store them
 198   // in sparse arrays of <attribute id, attribute value> pairs, organized
 199   // by type (bool, int, float, string, int list).
 200   //
 201   // There are three accessors for each type of attribute: one that returns
 202   // true if the attribute is present and false if not, one that takes a
 203   // pointer argument and returns true if the attribute is present (if you
 204   // need to distinguish between the default value and a missing attribute),
 205   // and another that returns the default value for that type if the
 206   // attribute is not present. In addition, strings can be returned as
 207   // either std::string or base::string16, for convenience.
 208
 209   bool HasBoolAttribute(ui::AXBoolAttribute attr) const;
 210   bool GetBoolAttribute(ui::AXBoolAttribute attr) const;
 211   bool GetBoolAttribute(ui::AXBoolAttribute attr, bool* value) const;
 212
 213   bool HasFloatAttribute(ui::AXFloatAttribute attr) const;
 214   float GetFloatAttribute(ui::AXFloatAttribute attr) const;
 215   bool GetFloatAttribute(ui::AXFloatAttribute attr, float* value) const;
 216
 217   bool HasIntAttribute(ui::AXIntAttribute attribute) const;
 218   int GetIntAttribute(ui::AXIntAttribute attribute) const;
 219   bool GetIntAttribute(ui::AXIntAttribute attribute, int* value) const;
 220
 221   bool HasStringAttribute(
 222       ui::AXStringAttribute attribute) const;
 223   const std::string& GetStringAttribute(ui::AXStringAttribute attribute) const;
 224   bool GetStringAttribute(ui::AXStringAttribute attribute,
 225                           std::string* value) const;
 226
 227   bool GetString16Attribute(ui::AXStringAttribute attribute,
 228                             base::string16* value) const;
 229   base::string16 GetString16Attribute(
 230       ui::AXStringAttribute attribute) const;
 231
 232   bool HasIntListAttribute(ui::AXIntListAttribute attribute) const;
 233   const std::vector<int32>& GetIntListAttribute(
 234       ui::AXIntListAttribute attribute) const;
 235   bool GetIntListAttribute(ui::AXIntListAttribute attribute,
 236                            std::vector<int32>* value) const;
 237
 238   // Retrieve the value of a html attribute from the attribute map and
 239   // returns true if found.
 240   bool GetHtmlAttribute(const char* attr, base::string16* value) const;
 241   bool GetHtmlAttribute(const char* attr, std::string* value) const;
 242
 243   // Utility method to handle special cases for ARIA booleans, tristates and
 244   // booleans which have a "mixed" state.
 245   //
 246   // Warning: the term "Tristate" is used loosely by the spec and here,
 247   // as some attributes support a 4th state.
 248   //
 249   // The following attributes are appropriate to use with this method:
 250   // aria-selected  (selectable)
 251   // aria-grabbed   (grabbable)
 252   // aria-expanded  (expandable)
 253   // aria-pressed   (toggleable/pressable) -- supports 4th "mixed" state
 254   // aria-checked   (checkable) -- supports 4th "mixed state"
 255   bool GetAriaTristate(const char* attr_name,
 256                        bool* is_defined,
 257                        bool* is_mixed) const;
 258
 259   // Returns true if the bit corresponding to the given state enum is 1.
 260   bool HasState(ui::AXState state_enum) const;
 261
 262   // Returns true if this node is an cell or an table header.
 263   bool IsCellOrTableHeaderRole() const;
 264
 265   // Returns true if this node is an editable text field of any kind.
 266   bool IsEditableText() const;
 267
 268   // True if this is a web area, and its grandparent is a presentational iframe.
 269   bool IsWebAreaForPresentationalIframe() const;
 270
 271   // Is any control, like a button, text field, etc.
 272   bool IsControl() const;
 273
 274  protected:
 275   BrowserAccessibility();
 276
 277   // The manager of this tree of accessibility objects.
 278   BrowserAccessibilityManager* manager_;
 279
 280   // The underlying node.
 281   ui::AXNode* node_;
 282
 283  private:
 284   // Return the sum of the lengths of all static text descendants,
 285   // including this object if it's static text.
 286   int GetStaticTextLenRecursive() const;
 287
 288   // If a bounding rectangle is empty, compute it based on the union of its
 289   // children, since most accessibility APIs don't like elements with no
 290   // bounds, but "virtual" elements in the accessibility tree that don't
 291   // correspond to a layed-out element sometimes don't have bounds.
 292   void FixEmptyBounds(gfx::Rect* bounds) const;
 293
 294   // Convert the bounding rectangle of an element (which is relative to
 295   // its nearest scrollable ancestor) to local bounds (which are relative
 296   // to the top of the web accessibility tree).
 297   gfx::Rect ElementBoundsToLocalBounds(gfx::Rect bounds) const;
 298
 299   DISALLOW_COPY_AND_ASSIGN(BrowserAccessibility);
 300 };
 301
 302 }  // namespace content
 303
 304 #endif  // CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_