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/browser/accessibility/ax_tree_id_registry.h"
  14 #include "content/common/content_export.h"
  15 #include "content/public/browser/ax_event_notification_details.h"
  16 #include "third_party/WebKit/public/web/WebAXEnums.h"
  17 #include "ui/accessibility/ax_node_data.h"
  18 #include "ui/accessibility/ax_serializable_tree.h"
  19 #include "ui/accessibility/ax_tree_update.h"
  20 #include "ui/gfx/native_widget_types.h"
  21
  22 struct AccessibilityHostMsg_LocationChangeParams;
  23
  24 namespace content {
  25 class BrowserAccessibility;
  26 class BrowserAccessibilityManager;
  27 #if defined(OS_ANDROID)
  28 class BrowserAccessibilityManagerAndroid;
  29 #elif defined(OS_WIN)
  30 class BrowserAccessibilityManagerWin;
  31 #elif defined(OS_LINUX) && !defined(OS_CHROMEOS) && defined(USE_X11)
  32 class BrowserAccessibilityManagerAuraLinux;
  33 #endif
  34
  35 using SimpleAXTreeUpdate = ui::AXTreeUpdate<ui::AXNodeData>;
  36
  37 // For testing.
  38 CONTENT_EXPORT SimpleAXTreeUpdate MakeAXTreeUpdate(
  39     const ui::AXNodeData& node,
  40     const ui::AXNodeData& node2 = ui::AXNodeData(),
  41     const ui::AXNodeData& node3 = ui::AXNodeData(),
  42     const ui::AXNodeData& node4 = ui::AXNodeData(),
  43     const ui::AXNodeData& node5 = ui::AXNodeData(),
  44     const ui::AXNodeData& node6 = ui::AXNodeData(),
  45     const ui::AXNodeData& node7 = ui::AXNodeData(),
  46     const ui::AXNodeData& node8 = ui::AXNodeData(),
  47     const ui::AXNodeData& node9 = ui::AXNodeData());
  48
  49 // Class that can perform actions on behalf of the BrowserAccessibilityManager.
  50 // Note: BrowserAccessibilityManager should never cache any of the return
  51 // values from any of these interfaces, especially those that return pointers.
  52 // They may only be valid within this call stack. That policy eliminates any
  53 // concerns about ownership and lifecycle issues; none of these interfaces
  54 // transfer ownership and no return values are guaranteed to be valid outside
  55 // of the current call stack.
  56 class CONTENT_EXPORT BrowserAccessibilityDelegate {
  57  public:
  58   virtual ~BrowserAccessibilityDelegate() {}
  59   virtual void AccessibilitySetFocus(int acc_obj_id) = 0;
  60   virtual void AccessibilityDoDefaultAction(int acc_obj_id) = 0;
  61   virtual void AccessibilityShowContextMenu(int acc_obj_id) = 0;
  62   virtual void AccessibilityScrollToMakeVisible(
  63       int acc_obj_id, const gfx::Rect& subfocus) = 0;
  64   virtual void AccessibilityScrollToPoint(
  65       int acc_obj_id, const gfx::Point& point) = 0;
  66   virtual void AccessibilitySetScrollOffset(
  67       int acc_obj_id, const gfx::Point& offset) = 0;
  68   virtual void AccessibilitySetTextSelection(
  69       int acc_obj_id, int start_offset, int end_offset) = 0;
  70   virtual void AccessibilitySetValue(
  71       int acc_obj_id, const base::string16& value) = 0;
  72   virtual bool AccessibilityViewHasFocus() const = 0;
  73   virtual gfx::Rect AccessibilityGetViewBounds() const = 0;
  74   virtual gfx::Point AccessibilityOriginInScreen(
  75       const gfx::Rect& bounds) const = 0;
  76   virtual void AccessibilityHitTest(
  77       const gfx::Point& point) = 0;
  78   virtual void AccessibilitySetAccessibilityFocus(int acc_obj_id) = 0;
  79   virtual void AccessibilityFatalError() = 0;
  80   virtual gfx::AcceleratedWidget AccessibilityGetAcceleratedWidget() = 0;
  81   virtual gfx::NativeViewAccessible AccessibilityGetNativeViewAccessible() = 0;
  82 };
  83
  84 class CONTENT_EXPORT BrowserAccessibilityFactory {
  85  public:
  86   virtual ~BrowserAccessibilityFactory() {}
  87
  88   // Create an instance of BrowserAccessibility and return a new
  89   // reference to it.
  90   virtual BrowserAccessibility* Create();
  91 };
  92
  93 // This is all of the information about the current find in page result,
  94 // so we can activate it if requested.
  95 struct BrowserAccessibilityFindInPageInfo {
  96   BrowserAccessibilityFindInPageInfo();
  97
  98   // This data about find in text results is updated as the user types.
  99   int request_id;
 100   int match_index;
 101   int start_id;
 102   int start_offset;
 103   int end_id;
 104   int end_offset;
 105
 106   // The active request id indicates that the user committed to a find query,
 107   // e.g. by pressing enter or pressing the next or previous buttons. If
 108   // |active_request_id| == |request_id|, we fire an accessibility event
 109   // to move screen reader focus to that event.
 110   int active_request_id;
 111 };
 112
 113 // Manages a tree of BrowserAccessibility objects.
 114 class CONTENT_EXPORT BrowserAccessibilityManager : public ui::AXTreeDelegate {
 115  public:
 116   // Creates the platform-specific BrowserAccessibilityManager, but
 117   // with no parent window pointer. Only useful for unit tests.
 118   static BrowserAccessibilityManager* Create(
 119       const SimpleAXTreeUpdate& initial_tree,
 120       BrowserAccessibilityDelegate* delegate,
 121       BrowserAccessibilityFactory* factory = new BrowserAccessibilityFactory());
 122
 123   static BrowserAccessibilityManager* FromID(
 124       AXTreeIDRegistry::AXTreeID ax_tree_id);
 125
 126   ~BrowserAccessibilityManager() override;
 127
 128   void Initialize(const SimpleAXTreeUpdate& initial_tree);
 129
 130   static SimpleAXTreeUpdate GetEmptyDocument();
 131
 132   virtual void NotifyAccessibilityEvent(
 133       ui::AXEvent event_type, BrowserAccessibility* node) { }
 134
 135   // Return a pointer to the root of the tree, does not make a new reference.
 136   BrowserAccessibility* GetRoot();
 137
 138   // Returns a pointer to the BrowserAccessibility object for a given AXNode.
 139   BrowserAccessibility* GetFromAXNode(ui::AXNode* node);
 140
 141   // Return a pointer to the object corresponding to the given id,
 142   // does not make a new reference.
 143   BrowserAccessibility* GetFromID(int32 id);
 144
 145   // If this tree has a parent tree, return the parent node in that tree.
 146   BrowserAccessibility* GetParentNodeFromParentTree();
 147
 148   // Called to notify the accessibility manager that its associated native
 149   // view got focused.
 150   virtual void OnWindowFocused();
 151
 152   // Called to notify the accessibility manager that its associated native
 153   // view lost focus.
 154   virtual void OnWindowBlurred();
 155
 156   // Notify the accessibility manager about page navigation.
 157   void UserIsNavigatingAway();
 158   virtual void UserIsReloading();
 159   void NavigationSucceeded();
 160   void NavigationFailed();
 161
 162   // Called to notify the accessibility manager that a mouse down event
 163   // occurred in the tab.
 164   void GotMouseDown();
 165
 166   // Update the focused node to |node|, which may be null.
 167   // If |notify| is true, send a message to the renderer to set focus
 168   // to this node.
 169   void SetFocus(ui::AXNode* node, bool notify);
 170   void SetFocus(BrowserAccessibility* node, bool notify);
 171
 172   // Tell the renderer to do the default action for this node.
 173   void DoDefaultAction(const BrowserAccessibility& node);
 174
 175   // Tell the renderer to scroll to make |node| visible.
 176   // In addition, if it's not possible to make the entire object visible,
 177   // scroll so that the |subfocus| rect is visible at least. The subfocus
 178   // rect is in local coordinates of the object itself.
 179   void ScrollToMakeVisible(
 180       const BrowserAccessibility& node, gfx::Rect subfocus);
 181
 182   // Tell the renderer to scroll such that |node| is at |point|,
 183   // where |point| is in global coordinates of the WebContents.
 184   void ScrollToPoint(
 185       const BrowserAccessibility& node, gfx::Point point);
 186
 187   // If |node| is itself a scrollable container, set its scroll
 188   // offset to |offset|.
 189   void SetScrollOffset(const BrowserAccessibility& node, gfx::Point offset);
 190
 191   // Tell the renderer to set the value of an editable text node.
 192   void SetValue(
 193       const BrowserAccessibility& node, const base::string16& value);
 194
 195   // Tell the renderer to set the text selection on a node.
 196   void SetTextSelection(
 197       const BrowserAccessibility& node, int start_offset, int end_offset);
 198
 199   // Retrieve the bounds of the parent View in screen coordinates.
 200   gfx::Rect GetViewBounds();
 201
 202   // Fire an event telling native assistive technology to move focus to the
 203   // given find in page result.
 204   void ActivateFindInPageResult(int request_id, int match_index);
 205
 206   // Called when the renderer process has notified us of about tree changes.
 207   void OnAccessibilityEvents(
 208       const std::vector<AXEventNotificationDetails>& details);
 209
 210   // Called when the renderer process updates the location of accessibility
 211   // objects.
 212   void OnLocationChanges(
 213       const std::vector<AccessibilityHostMsg_LocationChangeParams>& params);
 214
 215   // Called when a new find in page result is received. We hold on to this
 216   // information and don't activate it until the user requests it.
 217   void OnFindInPageResult(
 218       int request_id, int match_index, int start_id, int start_offset,
 219       int end_id, int end_offset);
 220
 221   // This is called when the user has committed to a find in page query,
 222   // e.g. by pressing enter or tapping on the next / previous result buttons.
 223   // If a match has already been received for this request id,
 224   // activate the result now by firing an accessibility event. If a match
 225   // has not been received, we hold onto this request id and update it
 226   // when OnFindInPageResult is called.
 227   void ActivateFindInPageResult(int request_id);
 228
 229 #if defined(OS_WIN)
 230   BrowserAccessibilityManagerWin* ToBrowserAccessibilityManagerWin();
 231 #endif
 232
 233 #if defined(OS_ANDROID)
 234   BrowserAccessibilityManagerAndroid* ToBrowserAccessibilityManagerAndroid();
 235 #endif
 236
 237 #if defined(OS_LINUX) && !defined(OS_CHROMEOS) && defined(USE_X11)
 238   BrowserAccessibilityManagerAuraLinux*
 239       ToBrowserAccessibilityManagerAuraLinux();
 240 #endif
 241
 242   // Return the object that has focus, if it's a descendant of the
 243   // given root (inclusive). Does not make a new reference.
 244   virtual BrowserAccessibility* GetFocus(BrowserAccessibility* root);
 245
 246   // Return the descentant of the given root that has focus, or that object's
 247   // active descendant if it has one.
 248   BrowserAccessibility* GetActiveDescendantFocus(BrowserAccessibility* root);
 249
 250   // True by default, but some platforms want to treat the root
 251   // scroll offsets separately.
 252   virtual bool UseRootScrollOffsetsWhenComputingBounds();
 253
 254   // Walk the tree.
 255   BrowserAccessibility* NextInTreeOrder(BrowserAccessibility* node) const;
 256   BrowserAccessibility* PreviousInTreeOrder(BrowserAccessibility* node) const;
 257   BrowserAccessibility* NextTextOnlyObject(BrowserAccessibility* node) const;
 258   BrowserAccessibility* PreviousTextOnlyObject(
 259       BrowserAccessibility* node) const;
 260
 261   // AXTreeDelegate implementation.
 262   void OnNodeWillBeDeleted(ui::AXTree* tree, ui::AXNode* node) override;
 263   void OnSubtreeWillBeDeleted(ui::AXTree* tree, ui::AXNode* node) override;
 264   void OnNodeCreated(ui::AXTree* tree, ui::AXNode* node) override;
 265   void OnNodeChanged(ui::AXTree* tree, ui::AXNode* node) override;
 266   void OnAtomicUpdateFinished(
 267       ui::AXTree* tree,
 268       bool root_changed,
 269       const std::vector<ui::AXTreeDelegate::Change>& changes) override;
 270
 271   BrowserAccessibilityDelegate* delegate() const { return delegate_; }
 272   void set_delegate(BrowserAccessibilityDelegate* delegate) {
 273     delegate_ = delegate;
 274   }
 275
 276   // If this BrowserAccessibilityManager is a child frame or guest frame,
 277   // return the BrowserAccessibilityDelegate from the highest ancestor frame
 278   // in the frame tree.
 279   BrowserAccessibilityDelegate* GetDelegateFromRootManager();
 280
 281   // Get a snapshot of the current tree as an AXTreeUpdate.
 282   SimpleAXTreeUpdate SnapshotAXTreeForTesting();
 283
 284  protected:
 285   BrowserAccessibilityManager(
 286       BrowserAccessibilityDelegate* delegate,
 287       BrowserAccessibilityFactory* factory);
 288
 289   BrowserAccessibilityManager(
 290       const SimpleAXTreeUpdate& initial_tree,
 291       BrowserAccessibilityDelegate* delegate,
 292       BrowserAccessibilityFactory* factory);
 293
 294  private:
 295   // The following states keep track of whether or not the
 296   // on-screen keyboard is allowed to be shown.
 297   enum OnScreenKeyboardState {
 298     // Never show the on-screen keyboard because this tab is hidden.
 299     OSK_DISALLOWED_BECAUSE_TAB_HIDDEN,
 300
 301     // This tab was just shown, so don't pop-up the on-screen keyboard if a
 302     // text field gets focus that wasn't the result of an explicit touch.
 303     OSK_DISALLOWED_BECAUSE_TAB_JUST_APPEARED,
 304
 305     // A touch event has occurred within the window, but focus has not
 306     // explicitly changed. Allow the on-screen keyboard to be shown if the
 307     // touch event was within the bounds of the currently focused object.
 308     // Otherwise we'll just wait to see if focus changes.
 309     OSK_ALLOWED_WITHIN_FOCUSED_OBJECT,
 310
 311     // Focus has changed within a tab that's already visible. Allow the
 312     // on-screen keyboard to show anytime that a touch event leads to an
 313     // editable text control getting focus.
 314     OSK_ALLOWED
 315   };
 316
 317  protected:
 318   // The object that can perform actions on our behalf.
 319   BrowserAccessibilityDelegate* delegate_;
 320
 321   // Factory to create BrowserAccessibility objects (for dependency injection).
 322   scoped_ptr<BrowserAccessibilityFactory> factory_;
 323
 324   // The underlying tree of accessibility objects.
 325   scoped_ptr<ui::AXSerializableTree> tree_;
 326
 327   // The node that currently has focus.
 328   ui::AXNode* focus_;
 329
 330   // A mapping from a node id to its wrapper of type BrowserAccessibility.
 331   base::hash_map<int32, BrowserAccessibility*> id_wrapper_map_;
 332
 333   // True if the user has initiated a navigation to another page.
 334   bool user_is_navigating_away_;
 335
 336   // The on-screen keyboard state.
 337   OnScreenKeyboardState osk_state_;
 338
 339   BrowserAccessibilityFindInPageInfo find_in_page_info_;
 340
 341   // The global ID of this accessibility tree.
 342   AXTreeIDRegistry::AXTreeID ax_tree_id_;
 343
 344   // If this tree has a parent tree, this is the cached ID of the parent
 345   // node within that parent tree. It's computed as needed and cached for
 346   // speed so that it can be accessed quickly if it hasn't changed.
 347   int parent_node_id_from_parent_tree_;
 348
 349   DISALLOW_COPY_AND_ASSIGN(BrowserAccessibilityManager);
 350 };
 351
 352 }  // namespace content
 353
 354 #endif  // CONTENT_BROWSER_ACCESSIBILITY_BROWSER_ACCESSIBILITY_MANAGER_H_