blob: fd2f1e171033bbeb55064bfce30db34b8870aef3 [file] [log] [blame]
[email protected]c5c2a672010-10-01 23:28:041// 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]f27e81c2010-10-07 05:20:239#include <map>
10#include <utility>
11#include <vector>
12
[email protected]c5c2a672010-10-01 23:28:0413#include "base/basictypes.h"
[email protected]f27e81c2010-10-07 05:20:2314#include "build/build_config.h"
15#include "webkit/glue/webaccessibility.h"
16
17class BrowserAccessibilityManager;
[email protected]0d7dad62010-10-19 21:18:5018#if defined(OS_MACOSX) && __OBJC__
19@class BrowserAccessibilityCocoa;
[email protected]1dbadbd2010-10-13 18:50:1020#elif defined(OS_WIN)
[email protected]f27e81c2010-10-07 05:20:2321class BrowserAccessibilityWin;
22#endif
23
24using webkit_glue::WebAccessibility;
[email protected]c5c2a672010-10-01 23:28:0425
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////////////////////////////////////////////////////////////////////////////////
38class BrowserAccessibility {
39 public:
[email protected]f27e81c2010-10-07 05:20:2340 // Creates a platform specific BrowserAccessibility. Ownership passes to the
[email protected]c5c2a672010-10-01 23:28:0441 // caller.
[email protected]f27e81c2010-10-07 05:20:2342 static BrowserAccessibility* Create();
43
[email protected]c5c2a672010-10-01 23:28:0444 virtual ~BrowserAccessibility();
45
[email protected]f27e81c2010-10-07 05:20:2346 // 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]8368e3c2011-03-08 19:26:2449 virtual void Initialize();
[email protected]f27e81c2010-10-07 05:20:2350
[email protected]405acd1cd2010-10-29 23:53:1751 // 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]8368e3c2011-03-08 19:26:2456 // Initialize this object, reading attributes from |src|. Does not
57 // recurse into children of |src| and build the whole subtree.
[email protected]f27e81c2010-10-07 05:20:2358 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]8368e3c2011-03-08 19:26:2467 // 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]f27e81c2010-10-07 05:20:2374 // 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]02747d4e2010-11-03 19:10:0094 // 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]8368e3c2011-03-08 19:26:24100 //
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]402da9f2011-03-08 19:45:41131 virtual void NativeReleaseReference();
[email protected]8368e3c2011-03-08 19:26:24132
133 //
[email protected]f27e81c2010-10-07 05:20:23134 // Accessors
[email protected]8368e3c2011-03-08 19:26:24135 //
136
[email protected]0d7dad62010-10-19 21:18:50137 const std::map<int32, string16>& attributes() const { return attributes_; }
[email protected]f27e81c2010-10-07 05:20:23138 int32 child_id() const { return child_id_; }
139 const std::vector<BrowserAccessibility*>& children() const {
140 return children_;
141 }
[email protected]0d7dad62010-10-19 21:18:50142 const std::vector<std::pair<string16, string16> >& html_attributes() const {
143 return html_attributes_;
144 }
[email protected]f27e81c2010-10-07 05:20:23145 int32 index_in_parent() const { return index_in_parent_; }
146 WebKit::WebRect location() const { return location_; }
[email protected]0d7dad62010-10-19 21:18:50147 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]8368e3c2011-03-08 19:26:24154 bool instance_active() const { return instance_active_; }
155 int32 ref_count() const { return ref_count_; }
[email protected]f27e81c2010-10-07 05:20:23156
[email protected]0d7dad62010-10-19 21:18:50157#if defined(OS_MACOSX) && __OBJC__
158 BrowserAccessibilityCocoa* toBrowserAccessibilityCocoa();
[email protected]1dbadbd2010-10-13 18:50:10159#elif defined(OS_WIN)
[email protected]f27e81c2010-10-07 05:20:23160 BrowserAccessibilityWin* toBrowserAccessibilityWin();
161#endif
162
[email protected]aa50cea82010-11-05 23:02:38163 // BrowserAccessibilityCocoa needs access to these methods.
[email protected]02747d4e2010-11-03 19:10:00164 // 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]aa50cea82010-11-05 23:02:38178 protected:
179 BrowserAccessibility();
180
[email protected]f27e81c2010-10-07 05:20:23181 // 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]8368e3c2011-03-08 19:26:24200 // The number of internal references to this object.
201 int32 ref_count_;
202
[email protected]f27e81c2010-10-07 05:20:23203 // 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]8368e3c2011-03-08 19:26:24212 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]f27e81c2010-10-07 05:20:23220
[email protected]c5c2a672010-10-01 23:28:04221 private:
222 DISALLOW_COPY_AND_ASSIGN(BrowserAccessibility);
223};
224
225#endif // CHROME_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_H_