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