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_MANAGER_H_
6#define CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_MANAGER_H_
7
8#include <vector>
9
10#include "base/containers/hash_tables.h"
11#include "base/memory/scoped_ptr.h"
12#include "build/build_config.h"
13#include "content/common/content_export.h"
14#include "third_party/WebKit/public/web/WebAXEnums.h"
15#include "ui/accessibility/ax_node_data.h"
16#include "ui/accessibility/ax_serializable_tree.h"
17#include "ui/accessibility/ax_tree_update.h"
18#include "ui/gfx/native_widget_types.h"
19
20struct AccessibilityHostMsg_EventParams;
21struct AccessibilityHostMsg_LocationChangeParams;
22
23namespace content {
24class BrowserAccessibility;
25class BrowserAccessibilityManager;
26#if defined(OS_ANDROID)
27class BrowserAccessibilityManagerAndroid;
28#endif
29#if defined(OS_WIN)
30class BrowserAccessibilityManagerWin;
31#endif
32
33// For testing.
34CONTENT_EXPORT ui::AXTreeUpdate MakeAXTreeUpdate(
35    const ui::AXNodeData& node,
36    const ui::AXNodeData& node2 = ui::AXNodeData(),
37    const ui::AXNodeData& node3 = ui::AXNodeData(),
38    const ui::AXNodeData& node4 = ui::AXNodeData(),
39    const ui::AXNodeData& node5 = ui::AXNodeData(),
40    const ui::AXNodeData& node6 = ui::AXNodeData(),
41    const ui::AXNodeData& node7 = ui::AXNodeData(),
42    const ui::AXNodeData& node8 = ui::AXNodeData(),
43    const ui::AXNodeData& node9 = ui::AXNodeData());
44
45// Class that can perform actions on behalf of the BrowserAccessibilityManager.
46// Note: BrowserAccessibilityManager should never cache any of the return
47// values from any of these interfaces, especially those that return pointers.
48// They may only be valid within this call stack. That policy eliminates any
49// concerns about ownership and lifecycle issues; none of these interfaces
50// transfer ownership and no return values are guaranteed to be valid outside
51// of the current call stack.
52class CONTENT_EXPORT BrowserAccessibilityDelegate {
53 public:
54  virtual ~BrowserAccessibilityDelegate() {}
55  virtual void AccessibilitySetFocus(int acc_obj_id) = 0;
56  virtual void AccessibilityDoDefaultAction(int acc_obj_id) = 0;
57  virtual void AccessibilityShowMenu(const gfx::Point& global_point) = 0;
58  virtual void AccessibilityScrollToMakeVisible(
59      int acc_obj_id, const gfx::Rect& subfocus) = 0;
60  virtual void AccessibilityScrollToPoint(
61      int acc_obj_id, const gfx::Point& point) = 0;
62  virtual void AccessibilitySetTextSelection(
63      int acc_obj_id, int start_offset, int end_offset) = 0;
64  virtual bool AccessibilityViewHasFocus() const = 0;
65  virtual gfx::Rect AccessibilityGetViewBounds() const = 0;
66  virtual gfx::Point AccessibilityOriginInScreen(
67      const gfx::Rect& bounds) const = 0;
68  virtual void AccessibilityHitTest(
69      const gfx::Point& point) = 0;
70  virtual void AccessibilityFatalError() = 0;
71  virtual gfx::AcceleratedWidget AccessibilityGetAcceleratedWidget() = 0;
72  virtual gfx::NativeViewAccessible AccessibilityGetNativeViewAccessible() = 0;
73  virtual BrowserAccessibilityManager* AccessibilityGetChildFrame(
74      int accessibility_node_id) = 0;
75  virtual BrowserAccessibility* AccessibilityGetParentFrame() = 0;
76};
77
78class CONTENT_EXPORT BrowserAccessibilityFactory {
79 public:
80  virtual ~BrowserAccessibilityFactory() {}
81
82  // Create an instance of BrowserAccessibility and return a new
83  // reference to it.
84  virtual BrowserAccessibility* Create();
85};
86
87// Manages a tree of BrowserAccessibility objects.
88class CONTENT_EXPORT BrowserAccessibilityManager : public ui::AXTreeDelegate {
89 public:
90  // Creates the platform-specific BrowserAccessibilityManager, but
91  // with no parent window pointer. Only useful for unit tests.
92  static BrowserAccessibilityManager* Create(
93      const ui::AXTreeUpdate& initial_tree,
94      BrowserAccessibilityDelegate* delegate,
95      BrowserAccessibilityFactory* factory = new BrowserAccessibilityFactory());
96
97  virtual ~BrowserAccessibilityManager();
98
99  void Initialize(const ui::AXTreeUpdate& initial_tree);
100
101  static ui::AXTreeUpdate GetEmptyDocument();
102
103  virtual void NotifyAccessibilityEvent(
104      ui::AXEvent event_type, BrowserAccessibility* node) { }
105
106  // Return a pointer to the root of the tree, does not make a new reference.
107  BrowserAccessibility* GetRoot();
108
109  // Returns a pointer to the BrowserAccessibility object for a given AXNode.
110  BrowserAccessibility* GetFromAXNode(ui::AXNode* node);
111
112  // Return a pointer to the object corresponding to the given id,
113  // does not make a new reference.
114  BrowserAccessibility* GetFromID(int32 id);
115
116  // Called to notify the accessibility manager that its associated native
117  // view got focused.
118  virtual void OnWindowFocused();
119
120  // Called to notify the accessibility manager that its associated native
121  // view lost focus.
122  virtual void OnWindowBlurred();
123
124  // Called to notify the accessibility manager that a mouse down event
125  // occurred in the tab.
126  void GotMouseDown();
127
128  // Update the focused node to |node|, which may be null.
129  // If |notify| is true, send a message to the renderer to set focus
130  // to this node.
131  void SetFocus(ui::AXNode* node, bool notify);
132  void SetFocus(BrowserAccessibility* node, bool notify);
133
134  // Tell the renderer to do the default action for this node.
135  void DoDefaultAction(const BrowserAccessibility& node);
136
137  // Tell the renderer to scroll to make |node| visible.
138  // In addition, if it's not possible to make the entire object visible,
139  // scroll so that the |subfocus| rect is visible at least. The subfocus
140  // rect is in local coordinates of the object itself.
141  void ScrollToMakeVisible(
142      const BrowserAccessibility& node, gfx::Rect subfocus);
143
144  // Tell the renderer to scroll such that |node| is at |point|,
145  // where |point| is in global coordinates of the WebContents.
146  void ScrollToPoint(
147      const BrowserAccessibility& node, gfx::Point point);
148
149  // Tell the renderer to set the text selection on a node.
150  void SetTextSelection(
151      const BrowserAccessibility& node, int start_offset, int end_offset);
152
153  // Retrieve the bounds of the parent View in screen coordinates.
154  gfx::Rect GetViewBounds();
155
156  // Called when the renderer process has notified us of about tree changes.
157  void OnAccessibilityEvents(
158      const std::vector<AccessibilityHostMsg_EventParams>& params);
159
160  // Called when the renderer process updates the location of accessibility
161  // objects.
162  void OnLocationChanges(
163      const std::vector<AccessibilityHostMsg_LocationChangeParams>& params);
164
165#if defined(OS_WIN)
166  BrowserAccessibilityManagerWin* ToBrowserAccessibilityManagerWin();
167#endif
168
169#if defined(OS_ANDROID)
170  BrowserAccessibilityManagerAndroid* ToBrowserAccessibilityManagerAndroid();
171#endif
172
173  // Return the object that has focus, if it's a descandant of the
174  // given root (inclusive). Does not make a new reference.
175  virtual BrowserAccessibility* GetFocus(BrowserAccessibility* root);
176
177  // Return the descentant of the given root that has focus, or that object's
178  // active descendant if it has one.
179  BrowserAccessibility* GetActiveDescendantFocus(BrowserAccessibility* root);
180
181  // True by default, but some platforms want to treat the root
182  // scroll offsets separately.
183  virtual bool UseRootScrollOffsetsWhenComputingBounds();
184
185  // Walk the tree.
186  BrowserAccessibility* NextInTreeOrder(BrowserAccessibility* node);
187  BrowserAccessibility* PreviousInTreeOrder(BrowserAccessibility* node);
188
189  // AXTreeDelegate implementation.
190  virtual void OnNodeWillBeDeleted(ui::AXNode* node) OVERRIDE;
191  virtual void OnNodeCreated(ui::AXNode* node) OVERRIDE;
192  virtual void OnNodeChanged(ui::AXNode* node) OVERRIDE;
193  virtual void OnNodeCreationFinished(ui::AXNode* node) OVERRIDE;
194  virtual void OnNodeChangeFinished(ui::AXNode* node) OVERRIDE;
195  virtual void OnRootChanged(ui::AXNode* new_root) OVERRIDE {}
196
197  BrowserAccessibilityDelegate* delegate() const { return delegate_; }
198  void set_delegate(BrowserAccessibilityDelegate* delegate) {
199    delegate_ = delegate;
200  }
201
202  // Get a snapshot of the current tree as an AXTreeUpdate.
203  ui::AXTreeUpdate SnapshotAXTreeForTesting();
204
205 protected:
206  BrowserAccessibilityManager(
207      BrowserAccessibilityDelegate* delegate,
208      BrowserAccessibilityFactory* factory);
209
210  BrowserAccessibilityManager(
211      const ui::AXTreeUpdate& initial_tree,
212      BrowserAccessibilityDelegate* delegate,
213      BrowserAccessibilityFactory* factory);
214
215  // Called at the end of updating the tree.
216  virtual void OnTreeUpdateFinished() {}
217
218 private:
219  // The following states keep track of whether or not the
220  // on-screen keyboard is allowed to be shown.
221  enum OnScreenKeyboardState {
222    // Never show the on-screen keyboard because this tab is hidden.
223    OSK_DISALLOWED_BECAUSE_TAB_HIDDEN,
224
225    // This tab was just shown, so don't pop-up the on-screen keyboard if a
226    // text field gets focus that wasn't the result of an explicit touch.
227    OSK_DISALLOWED_BECAUSE_TAB_JUST_APPEARED,
228
229    // A touch event has occurred within the window, but focus has not
230    // explicitly changed. Allow the on-screen keyboard to be shown if the
231    // touch event was within the bounds of the currently focused object.
232    // Otherwise we'll just wait to see if focus changes.
233    OSK_ALLOWED_WITHIN_FOCUSED_OBJECT,
234
235    // Focus has changed within a tab that's already visible. Allow the
236    // on-screen keyboard to show anytime that a touch event leads to an
237    // editable text control getting focus.
238    OSK_ALLOWED
239  };
240
241 protected:
242  // The object that can perform actions on our behalf.
243  BrowserAccessibilityDelegate* delegate_;
244
245  // Factory to create BrowserAccessibility objects (for dependency injection).
246  scoped_ptr<BrowserAccessibilityFactory> factory_;
247
248  // The underlying tree of accessibility objects.
249  scoped_ptr<ui::AXSerializableTree> tree_;
250
251  // The node that currently has focus.
252  ui::AXNode* focus_;
253
254  // A mapping from a node id to its wrapper of type BrowserAccessibility.
255  base::hash_map<int32, BrowserAccessibility*> id_wrapper_map_;
256
257  // The on-screen keyboard state.
258  OnScreenKeyboardState osk_state_;
259
260  DISALLOW_COPY_AND_ASSIGN(BrowserAccessibilityManager);
261};
262
263}  // namespace content
264
265#endif  // CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_MANAGER_H_
266