1 // Copyright (c) 2011 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 CHROME_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_ 6 #define CHROME_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_ 7 #pragma once 8 9 #include <map> 10 #include <utility> 11 #include <vector> 12 13 #include "base/basictypes.h" 14 #include "build/build_config.h" 15 #include "webkit/glue/webaccessibility.h" 16 17 class BrowserAccessibilityManager; 18 #if defined(OS_MACOSX) && __OBJC__ 19 @class BrowserAccessibilityCocoa; 20 #elif defined(OS_WIN) 21 class BrowserAccessibilityWin; 22 #endif 23 24 using webkit_glue::WebAccessibility; 25 26 //////////////////////////////////////////////////////////////////////////////// 27 // 28 // BrowserAccessibility 29 // 30 // Class implementing the cross platform interface for the Browser-Renderer 31 // communication of accessibility information, providing accessibility 32 // to be used by screen readers and other assistive technology (AT). 33 // 34 // An implementation for each platform handles platform specific accessibility 35 // APIs. 36 // 37 //////////////////////////////////////////////////////////////////////////////// 38 class BrowserAccessibility { 39 public: 40 // Creates a platform specific BrowserAccessibility. Ownership passes to the 41 // caller. 42 static BrowserAccessibility* Create(); 43 44 virtual ~BrowserAccessibility(); 45 46 // Perform platform specific initialization. This can be called multiple times 47 // during the lifetime of this instance after the members of this base object 48 // have been reset with new values from the renderer process. 49 virtual void Initialize(); 50 51 // Replace a child object. Used when updating the accessibility tree. 52 virtual void ReplaceChild( 53 BrowserAccessibility* old_acc, 54 BrowserAccessibility* new_acc); 55 56 // Initialize this object, reading attributes from |src|. Does not 57 // recurse into children of |src| and build the whole subtree. 58 void Initialize(BrowserAccessibilityManager* manager, 59 BrowserAccessibility* parent, 60 int32 child_id, 61 int32 index_in_parent, 62 const WebAccessibility& src); 63 64 // Add a child of this object. 65 void AddChild(BrowserAccessibility* child); 66 67 // Detach all descendants of this subtree and push all of the node pointers, 68 // including this node, onto the end of |nodes|. 69 void DetachTree(std::vector<BrowserAccessibility*>* nodes); 70 71 // Update the parent and index in parent if this node has been moved. 72 void UpdateParent(BrowserAccessibility* parent, int index_in_parent); 73 74 // Return true if this object is equal to or a descendant of |ancestor|. 75 bool IsDescendantOf(BrowserAccessibility* ancestor); 76 77 // Returns the parent of this object, or NULL if it's the root. 78 BrowserAccessibility* parent() { return parent_; } 79 80 // Returns the number of children of this object. 81 uint32 child_count() const { return children_.size(); } 82 83 // Return a pointer to the child with the given index. 84 BrowserAccessibility* GetChild(uint32 child_index); 85 86 // Return the previous sibling of this object, or NULL if it's the first 87 // child of its parent. 88 BrowserAccessibility* GetPreviousSibling(); 89 90 // Return the next sibling of this object, or NULL if it's the last child 91 // of its parent. 92 BrowserAccessibility* GetNextSibling(); 93 94 // Returns the bounds of this object in screen coordinates. 95 gfx::Rect GetBoundsRect(); 96 97 // Returns the deepest descendant that contains the specified point. 98 BrowserAccessibility* BrowserAccessibilityForPoint(const gfx::Point& point); 99 100 // 101 // Reference counting 102 // 103 // Each object has an internal reference count and many platform 104 // implementations may also use native reference counting. 105 // 106 // The internal reference counting is used because sometimes 107 // multiple references to the same object exist temporarily during 108 // an update. When the internal reference count reaches zero, 109 // NativeReleaseReference is called. 110 // 111 // Native reference counting is used on some platforms because the 112 // operating system may hold onto a reference to a BrowserAccessibility 113 // object even after we're through with it. On these platforms, when 114 // the internal reference count reaches zero, instance_active is set 115 // to zero, and all queries on this object should return failure. 116 // The object isn't actually deleted until the operating system releases 117 // all of its references. 118 // 119 120 // Increment this node's internal reference count. 121 virtual void InternalAddReference(); 122 123 // Decrement this node's internal reference count. If the reference count 124 // reaches zero, call NativeReleaseReference(). 125 virtual void InternalReleaseReference(bool recursive); 126 127 // Subclasses should override this to support platform reference counting. 128 virtual void NativeAddReference() { } 129 130 // Subclasses should override this to support platform reference counting. 131 virtual void NativeReleaseReference(); 132 133 // 134 // Accessors 135 // 136 137 const std::map<int32, string16>& attributes() const { return attributes_; } 138 int32 child_id() const { return child_id_; } 139 const std::vector<BrowserAccessibility*>& children() const { 140 return children_; 141 } 142 const std::vector<std::pair<string16, string16> >& html_attributes() const { 143 return html_attributes_; 144 } 145 int32 index_in_parent() const { return index_in_parent_; } 146 gfx::Rect location() const { return location_; } 147 BrowserAccessibilityManager* manager() const { return manager_; } 148 const string16& name() const { return name_; } 149 int32 renderer_id() const { return renderer_id_; } 150 int32 role() const { return role_; } 151 const string16& role_name() const { return role_name_; } 152 int32 state() const { return state_; } 153 const string16& value() const { return value_; } 154 bool instance_active() const { return instance_active_; } 155 int32 ref_count() const { return ref_count_; } 156 157 #if defined(OS_MACOSX) && __OBJC__ 158 BrowserAccessibilityCocoa* toBrowserAccessibilityCocoa(); 159 #elif defined(OS_WIN) 160 BrowserAccessibilityWin* toBrowserAccessibilityWin(); 161 #endif 162 163 // BrowserAccessibilityCocoa needs access to these methods. 164 // Return true if this attribute is in the attributes map. 165 bool HasAttribute(WebAccessibility::Attribute attribute); 166 167 // Retrieve the string value of an attribute from the attribute map and 168 // returns true if found. 169 bool GetAttribute(WebAccessibility::Attribute attribute, string16* value); 170 171 // Retrieve the value of an attribute from the attribute map and 172 // if found and nonempty, try to convert it to an integer. 173 // Returns true only if both the attribute was found and it was successfully 174 // converted to an integer. 175 bool GetAttributeAsInt( 176 WebAccessibility::Attribute attribute, int* value_int); 177 178 protected: 179 BrowserAccessibility(); 180 181 // The manager of this tree of accessibility objects; needed for 182 // global operations like focus tracking. 183 BrowserAccessibilityManager* manager_; 184 185 // The parent of this object, may be NULL if we're the root object. 186 BrowserAccessibility* parent_; 187 188 // The ID of this object; globally unique within the browser process. 189 int32 child_id_; 190 191 // The index of this within its parent object. 192 int32 index_in_parent_; 193 194 // The ID of this object in the renderer process. 195 int32 renderer_id_; 196 197 // The children of this object. 198 std::vector<BrowserAccessibility*> children_; 199 200 // The number of internal references to this object. 201 int32 ref_count_; 202 203 // Accessibility metadata from the renderer 204 string16 name_; 205 string16 value_; 206 std::map<int32, string16> attributes_; 207 std::vector<std::pair<string16, string16> > html_attributes_; 208 int32 role_; 209 int32 state_; 210 string16 role_name_; 211 gfx::Rect location_; 212 std::vector<int32> indirect_child_ids_; 213 214 // BrowserAccessibility objects are reference-counted on some platforms. 215 // When we're done with this object and it's removed from our accessibility 216 // tree, a client may still be holding onto a pointer to this object, so 217 // we mark it as inactive so that calls to any of this object's methods 218 // immediately return failure. 219 bool instance_active_; 220 221 private: 222 DISALLOW_COPY_AND_ASSIGN(BrowserAccessibility); 223 }; 224 225 #endif // CHROME_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_ 226
