content/browser/accessibility/browser_accessibility_manager.h

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