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_data.h"
  18
  19 #if defined(OS_MACOSX) && __OBJC__
  20 @class BrowserAccessibilityCocoa;
  21 #endif
  22
  23 namespace content {
  24 class BrowserAccessibilityManager;
  25 #if defined(OS_WIN)
  26 class BrowserAccessibilityWin;
  27 #elif defined(TOOLKIT_GTK)
  28 class BrowserAccessibilityGtk;
  29 #endif
  30
  31 ////////////////////////////////////////////////////////////////////////////////
  32 //
  33 // BrowserAccessibility
  34 //
  35 // Class implementing the cross platform interface for the Browser-Renderer
  36 // communication of accessibility information, providing accessibility
  37 // to be used by screen readers and other assistive technology (AT).
  38 //
  39 // An implementation for each platform handles platform specific accessibility
  40 // APIs.
  41 //
  42 ////////////////////////////////////////////////////////////////////////////////
  43 class CONTENT_EXPORT BrowserAccessibility {
  44  public:
  45   // Creates a platform specific BrowserAccessibility. Ownership passes to the
  46   // caller.
  47   static BrowserAccessibility* Create();
  48
  49   virtual ~BrowserAccessibility();
  50
  51   // Detach all descendants of this subtree and push all of the node pointers,
  52   // including this node, onto the end of |nodes|.
  53   virtual void DetachTree(std::vector<BrowserAccessibility*>* nodes);
  54
  55   // Perform platform-specific initialization. This can be called multiple times
  56   // during the lifetime of this instance after the members of this base object
  57   // have been reset with new values from the renderer process.
  58   // Child dependent initialization can be done here.
  59   virtual void PostInitialize() {}
  60
  61   // Returns true if this is a native platform-specific object, vs a
  62   // cross-platform generic object.
  63   virtual bool IsNative() const;
  64
  65   // Initialize the tree structure of this object.
  66   void InitializeTreeStructure(
  67       BrowserAccessibilityManager* manager,
  68       BrowserAccessibility* parent,
  69       int32 renderer_id,
  70       int32 index_in_parent);
  71
  72   // Initialize this object's data.
  73   void InitializeData(const ui::AXNodeData& src);
  74
  75   virtual void SwapChildren(std::vector<BrowserAccessibility*>& children);
  76
  77   // Update the parent and index in parent if this node has been moved.
  78   void UpdateParent(BrowserAccessibility* parent, int index_in_parent);
  79
  80   // Update this node's location, leaving everything else the same.
  81   virtual void SetLocation(const gfx::Rect& new_location);
  82
  83   // Return true if this object is equal to or a descendant of |ancestor|.
  84   bool IsDescendantOf(BrowserAccessibility* ancestor);
  85
  86   // Returns the parent of this object, or NULL if it's the root.
  87   BrowserAccessibility* parent() const { return parent_; }
  88
  89   // Returns the number of children of this object.
  90   uint32 child_count() const { return children_.size(); }
  91
  92   // Returns true if this is a leaf node on this platform, meaning any
  93   // children should not be exposed to this platform's native accessibility
  94   // layer. Each platform subclass should implement this itself.
  95   // The definition of a leaf may vary depending on the platform,
  96   // but a leaf node should never have children that are focusable or
  97   // that might send notifications.
  98   virtual bool PlatformIsLeaf() const;
  99
 100   // Returns the number of children of this object, or 0 if PlatformIsLeaf()
 101   // returns true.
 102   uint32 PlatformChildCount() const;
 103
 104   // Return a pointer to the child at the given index, or NULL for an
 105   // invalid index. Returns NULL if PlatformIsLeaf() returns true.
 106   BrowserAccessibility* PlatformGetChild(uint32 child_index) const;
 107
 108   // Return the previous sibling of this object, or NULL if it's the first
 109   // child of its parent.
 110   BrowserAccessibility* GetPreviousSibling();
 111
 112   // Return the next sibling of this object, or NULL if it's the last child
 113   // of its parent.
 114   BrowserAccessibility* GetNextSibling();
 115
 116   // Returns the bounds of this object in coordinates relative to the
 117   // top-left corner of the overall web area.
 118   gfx::Rect GetLocalBoundsRect() const;
 119
 120   // Returns the bounds of this object in screen coordinates.
 121   gfx::Rect GetGlobalBoundsRect() const;
 122
 123   // Returns the bounds of the given range in coordinates relative to the
 124   // top-left corner of the overall web area. Only valid when the
 125   // role is WebAXRoleStaticText.
 126   gfx::Rect GetLocalBoundsForRange(int start, int len) const;
 127
 128   // Same as GetLocalBoundsForRange, in screen coordinates. Only valid when
 129   // the role is WebAXRoleStaticText.
 130   gfx::Rect GetGlobalBoundsForRange(int start, int len) const;
 131
 132   // Returns the deepest descendant that contains the specified point
 133   // (in global screen coordinates).
 134   BrowserAccessibility* BrowserAccessibilityForPoint(const gfx::Point& point);
 135
 136   // Marks this object for deletion, releases our reference to it, and
 137   // recursively calls Destroy() on its children.  May not delete
 138   // immediately due to reference counting.
 139   //
 140   // Reference counting is used on some platforms because the
 141   // operating system may hold onto a reference to a BrowserAccessibility
 142   // object even after we're through with it. When a BrowserAccessibility
 143   // has had Destroy() called but its reference count is not yet zero,
 144   // queries on this object return failure
 145   virtual void Destroy();
 146
 147   // Subclasses should override this to support platform reference counting.
 148   virtual void NativeAddReference() { }
 149
 150   // Subclasses should override this to support platform reference counting.
 151   virtual void NativeReleaseReference();
 152
 153   //
 154   // Accessors
 155   //
 156
 157   const std::vector<BrowserAccessibility*>& children() const {
 158     return children_;
 159   }
 160   const std::vector<std::pair<std::string, std::string> >&
 161   html_attributes() const {
 162     return html_attributes_;
 163   }
 164   int32 index_in_parent() const { return index_in_parent_; }
 165   gfx::Rect location() const { return location_; }
 166   BrowserAccessibilityManager* manager() const { return manager_; }
 167   const std::string& name() const { return name_; }
 168   const std::string& value() const { return value_; }
 169   int32 renderer_id() const { return renderer_id_; }
 170   int32 role() const { return role_; }
 171   int32 state() const { return state_; }
 172   bool instance_active() const { return instance_active_; }
 173
 174   void set_name(const std::string& name) { name_ = name; }
 175   void set_value(const std::string& value) { value_ = value; }
 176
 177 #if defined(OS_MACOSX) && __OBJC__
 178   BrowserAccessibilityCocoa* ToBrowserAccessibilityCocoa();
 179 #elif defined(OS_WIN)
 180   BrowserAccessibilityWin* ToBrowserAccessibilityWin();
 181 #elif defined(TOOLKIT_GTK)
 182   BrowserAccessibilityGtk* ToBrowserAccessibilityGtk();
 183 #endif
 184
 185   // Accessing accessibility attributes:
 186   //
 187   // There are dozens of possible attributes for an accessibility node,
 188   // but only a few tend to apply to any one object, so we store them
 189   // in sparse arrays of <attribute id, attribute value> pairs, organized
 190   // by type (bool, int, float, string, int list).
 191   //
 192   // There are three accessors for each type of attribute: one that returns
 193   // true if the attribute is present and false if not, one that takes a
 194   // pointer argument and returns true if the attribute is present (if you
 195   // need to distinguish between the default value and a missing attribute),
 196   // and another that returns the default value for that type if the
 197   // attribute is not present. In addition, strings can be returned as
 198   // either std::string or base::string16, for convenience.
 199
 200   bool HasBoolAttribute(ui::AXBoolAttribute attr) const;
 201   bool GetBoolAttribute(ui::AXBoolAttribute attr) const;
 202   bool GetBoolAttribute(ui::AXBoolAttribute attr, bool* value) const;
 203
 204   bool HasFloatAttribute(ui::AXFloatAttribute attr) const;
 205   float GetFloatAttribute(ui::AXFloatAttribute attr) const;
 206   bool GetFloatAttribute(ui::AXFloatAttribute attr, float* value) const;
 207
 208   bool HasIntAttribute(ui::AXIntAttribute attribute) const;
 209   int GetIntAttribute(ui::AXIntAttribute attribute) const;
 210   bool GetIntAttribute(ui::AXIntAttribute attribute, int* value) const;
 211
 212   bool HasStringAttribute(
 213       ui::AXStringAttribute attribute) const;
 214   const std::string& GetStringAttribute(ui::AXStringAttribute attribute) const;
 215   bool GetStringAttribute(ui::AXStringAttribute attribute,
 216                           std::string* value) const;
 217
 218   bool GetString16Attribute(ui::AXStringAttribute attribute,
 219                             base::string16* value) const;
 220   base::string16 GetString16Attribute(
 221       ui::AXStringAttribute attribute) const;
 222
 223   bool HasIntListAttribute(ui::AXIntListAttribute attribute) const;
 224   const std::vector<int32>& GetIntListAttribute(
 225       ui::AXIntListAttribute attribute) const;
 226   bool GetIntListAttribute(ui::AXIntListAttribute attribute,
 227                            std::vector<int32>* value) const;
 228
 229   void SetStringAttribute(ui::AXStringAttribute attribute,
 230                           const std::string& value);
 231
 232   // Retrieve the value of a html attribute from the attribute map and
 233   // returns true if found.
 234   bool GetHtmlAttribute(const char* attr, base::string16* value) const;
 235   bool GetHtmlAttribute(const char* attr, std::string* value) const;
 236
 237   // Utility method to handle special cases for ARIA booleans, tristates and
 238   // booleans which have a "mixed" state.
 239   //
 240   // Warning: the term "Tristate" is used loosely by the spec and here,
 241   // as some attributes support a 4th state.
 242   //
 243   // The following attributes are appropriate to use with this method:
 244   // aria-selected  (selectable)
 245   // aria-grabbed   (grabbable)
 246   // aria-expanded  (expandable)
 247   // aria-pressed   (toggleable/pressable) -- supports 4th "mixed" state
 248   // aria-checked   (checkable) -- supports 4th "mixed state"
 249   bool GetAriaTristate(const char* attr_name,
 250                        bool* is_defined,
 251                        bool* is_mixed) const;
 252
 253   // Returns true if the bit corresponding to the given state enum is 1.
 254   bool HasState(ui::AXState state_enum) const;
 255
 256   // Returns true if this node is an editable text field of any kind.
 257   bool IsEditableText() const;
 258
 259   // Append the text from this node and its children.
 260   std::string GetTextRecursive() const;
 261
 262  protected:
 263   // Perform platform specific initialization. This can be called multiple times
 264   // during the lifetime of this instance after the members of this base object
 265   // have been reset with new values from the renderer process.
 266   // Perform child independent initialization in this method.
 267   virtual void PreInitialize() {}
 268
 269   BrowserAccessibility();
 270
 271   // The manager of this tree of accessibility objects; needed for
 272   // global operations like focus tracking.
 273   BrowserAccessibilityManager* manager_;
 274
 275   // The parent of this object, may be NULL if we're the root object.
 276   BrowserAccessibility* parent_;
 277
 278  private:
 279   // Return the sum of the lengths of all static text descendants,
 280   // including this object if it's static text.
 281   int GetStaticTextLenRecursive() const;
 282
 283   // The index of this within its parent object.
 284   int32 index_in_parent_;
 285
 286   // The ID of this object in the renderer process.
 287   int32 renderer_id_;
 288
 289   // The children of this object.
 290   std::vector<BrowserAccessibility*> children_;
 291
 292   // Accessibility metadata from the renderer
 293   std::string name_;
 294   std::string value_;
 295   std::vector<std::pair<
 296       ui::AXBoolAttribute, bool> > bool_attributes_;
 297   std::vector<std::pair<
 298       ui::AXFloatAttribute, float> > float_attributes_;
 299   std::vector<std::pair<
 300       ui::AXIntAttribute, int> > int_attributes_;
 301   std::vector<std::pair<
 302       ui::AXStringAttribute, std::string> > string_attributes_;
 303   std::vector<std::pair<
 304       ui::AXIntListAttribute, std::vector<int32> > >
 305           intlist_attributes_;
 306   std::vector<std::pair<std::string, std::string> > html_attributes_;
 307   int32 role_;
 308   int32 state_;
 309   gfx::Rect location_;
 310
 311   // BrowserAccessibility objects are reference-counted on some platforms.
 312   // When we're done with this object and it's removed from our accessibility
 313   // tree, a client may still be holding onto a pointer to this object, so
 314   // we mark it as inactive so that calls to any of this object's methods
 315   // immediately return failure.
 316   bool instance_active_;
 317
 318  private:
 319   DISALLOW_COPY_AND_ASSIGN(BrowserAccessibility);
 320 };
 321
 322 }  // namespace content
 323
 324 #endif  // CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_