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_serializable_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 class BrowserAccessibilityManager;
  26 #if defined(OS_ANDROID)
  27 class BrowserAccessibilityManagerAndroid;
  28 #endif
  29 #if defined(OS_WIN)
  30 class BrowserAccessibilityManagerWin;
  31 #endif
  32
  33 // For testing.
  34 CONTENT_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.
  52 class 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
  78 class 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.
  88 class 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   ~BrowserAccessibilityManager() override;
  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   void OnNodeWillBeDeleted(ui::AXNode* node) override;
 191   void OnNodeCreated(ui::AXNode* node) override;
 192   void OnNodeChanged(ui::AXNode* node) override;
 193   void OnNodeCreationFinished(ui::AXNode* node) override;
 194   void OnNodeChangeFinished(ui::AXNode* node) override;
 195   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_