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