Home | History | Annotate | Download | only in accessibility 
      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   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