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