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_ 272
