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
17class BrowserAccessibilityManager;
18#if defined(OS_MACOSX) && __OBJC__
19@class BrowserAccessibilityCocoa;
20#elif defined(OS_WIN)
21class BrowserAccessibilityWin;
22#endif
23
24using 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////////////////////////////////////////////////////////////////////////////////
38class 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