[email protected] | c5c2a67 | 2010-10-01 23:28:04 | [diff] [blame] | 1 | // Copyright (c) 2010 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 | |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 9 | #include <map> |
| 10 | #include <utility> |
| 11 | #include <vector> |
| 12 | |
[email protected] | c5c2a67 | 2010-10-01 23:28:04 | [diff] [blame] | 13 | #include "base/basictypes.h" |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 14 | #include "build/build_config.h" |
| 15 | #include "webkit/glue/webaccessibility.h" |
| 16 | |
| 17 | class BrowserAccessibilityManager; |
[email protected] | 0d7dad6 | 2010-10-19 21:18:50 | [diff] [blame] | 18 | #if defined(OS_MACOSX) && __OBJC__ |
| 19 | @class BrowserAccessibilityCocoa; |
[email protected] | 1dbadbd | 2010-10-13 18:50:10 | [diff] [blame] | 20 | #elif defined(OS_WIN) |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 21 | class BrowserAccessibilityWin; |
| 22 | #endif |
| 23 | |
| 24 | using webkit_glue::WebAccessibility; |
[email protected] | c5c2a67 | 2010-10-01 23:28:04 | [diff] [blame] | 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: |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 40 | // Creates a platform specific BrowserAccessibility. Ownership passes to the |
[email protected] | c5c2a67 | 2010-10-01 23:28:04 | [diff] [blame] | 41 | // caller. |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 42 | static BrowserAccessibility* Create(); |
| 43 | |
[email protected] | c5c2a67 | 2010-10-01 23:28:04 | [diff] [blame] | 44 | virtual ~BrowserAccessibility(); |
| 45 | |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 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. |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 49 | virtual void Initialize(); |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 50 | |
[email protected] | 405acd1cd | 2010-10-29 23:53:17 | [diff] [blame] | 51 | // Replace a child object. Used when updating the accessibility tree. |
| 52 | virtual void ReplaceChild( |
| 53 | BrowserAccessibility* old_acc, |
| 54 | BrowserAccessibility* new_acc); |
| 55 | |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 56 | // Initialize this object, reading attributes from |src|. Does not |
| 57 | // recurse into children of |src| and build the whole subtree. |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 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 | |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 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 | |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 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* GetParent(); |
| 79 | |
| 80 | // Returns the number of children of this object. |
| 81 | uint32 GetChildCount(); |
| 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 | |
[email protected] | 02747d4e | 2010-11-03 19:10:00 | [diff] [blame] | 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 | |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 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. |
[email protected] | 402da9f | 2011-03-08 19:45:41 | [diff] [blame^] | 131 | virtual void NativeReleaseReference(); |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 132 | |
| 133 | // |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 134 | // Accessors |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 135 | // |
| 136 | |
[email protected] | 0d7dad6 | 2010-10-19 21:18:50 | [diff] [blame] | 137 | const std::map<int32, string16>& attributes() const { return attributes_; } |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 138 | int32 child_id() const { return child_id_; } |
| 139 | const std::vector<BrowserAccessibility*>& children() const { |
| 140 | return children_; |
| 141 | } |
[email protected] | 0d7dad6 | 2010-10-19 21:18:50 | [diff] [blame] | 142 | const std::vector<std::pair<string16, string16> >& html_attributes() const { |
| 143 | return html_attributes_; |
| 144 | } |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 145 | int32 index_in_parent() const { return index_in_parent_; } |
| 146 | WebKit::WebRect location() const { return location_; } |
[email protected] | 0d7dad6 | 2010-10-19 21:18:50 | [diff] [blame] | 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_; } |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 154 | bool instance_active() const { return instance_active_; } |
| 155 | int32 ref_count() const { return ref_count_; } |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 156 | |
[email protected] | 0d7dad6 | 2010-10-19 21:18:50 | [diff] [blame] | 157 | #if defined(OS_MACOSX) && __OBJC__ |
| 158 | BrowserAccessibilityCocoa* toBrowserAccessibilityCocoa(); |
[email protected] | 1dbadbd | 2010-10-13 18:50:10 | [diff] [blame] | 159 | #elif defined(OS_WIN) |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 160 | BrowserAccessibilityWin* toBrowserAccessibilityWin(); |
| 161 | #endif |
| 162 | |
[email protected] | aa50cea8 | 2010-11-05 23:02:38 | [diff] [blame] | 163 | // BrowserAccessibilityCocoa needs access to these methods. |
[email protected] | 02747d4e | 2010-11-03 19:10:00 | [diff] [blame] | 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 | |
[email protected] | aa50cea8 | 2010-11-05 23:02:38 | [diff] [blame] | 178 | protected: |
| 179 | BrowserAccessibility(); |
| 180 | |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 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 | |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 200 | // The number of internal references to this object. |
| 201 | int32 ref_count_; |
| 202 | |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 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 | WebKit::WebRect location_; |
[email protected] | 8368e3c | 2011-03-08 19:26:24 | [diff] [blame] | 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_; |
[email protected] | f27e81c | 2010-10-07 05:20:23 | [diff] [blame] | 220 | |
[email protected] | c5c2a67 | 2010-10-01 23:28:04 | [diff] [blame] | 221 | private: |
| 222 | DISALLOW_COPY_AND_ASSIGN(BrowserAccessibility); |
| 223 | }; |
| 224 | |
| 225 | #endif // CHROME_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_ |