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