content/browser/accessibility/one_shot_accessibility_tree_search.h

   1 // Copyright 2015 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_ACCESSIBILITY_TREE_SEARCH_H_
   6 #define CONTENT_BROWSER_ACCESSIBILITY_ACCESSIBILITY_TREE_SEARCH_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/macros.h"
  12 #include "content/common/content_export.h"
  13
  14 namespace content {
  15
  16 class BrowserAccessibility;
  17 class BrowserAccessibilityManager;
  18
  19 // A function that returns whether or not a given node matches, given the
  20 // start element of the search as an optional comparator.
  21 typedef bool (*AccessibilityMatchPredicate)(
  22     BrowserAccessibility* start_element,
  23     BrowserAccessibility* this_element);
  24
  25 // This class provides an interface for searching the accessibility tree from
  26 // a given starting node, with a few built-in options and allowing an arbitrary
  27 // number of predicates that can be used to restrict the search.
  28 //
  29 // This class is meant to perform one search. Initialize it, then iterate
  30 // over the matches, and then delete it.
  31 //
  32 // This class stores raw pointers to the matches in the tree! Don't keep this
  33 // object around if the tree is mutating.
  34 class CONTENT_EXPORT OneShotAccessibilityTreeSearch {
  35  public:
  36   enum Direction { FORWARDS, BACKWARDS };
  37
  38   const int UNLIMITED_RESULTS = -1;
  39
  40   OneShotAccessibilityTreeSearch(BrowserAccessibilityManager* tree);
  41   virtual ~OneShotAccessibilityTreeSearch();
  42
  43   //
  44   // Search parameters.  All of these are optional.
  45   //
  46
  47   // Sets the node where the search starts. The first potential match will
  48   // be the one immediately following this one. This node will be used as
  49   // the first arguement to any predicates.
  50   void SetStartNode(BrowserAccessibility* start_node);
  51
  52   // Search forwards or backwards in an in-order traversal of the tree.
  53   void SetDirection(Direction direction);
  54
  55   // Set the maximum number of results, or UNLIMITED_RESULTS
  56   // for no limit (default).
  57   void SetResultLimit(int result_limit);
  58
  59   // If true, only searches children of |start_node| and doesn't
  60   // recurse.
  61   void SetImmediateDescendantsOnly(bool immediate_descendants_only);
  62
  63   // If true, only considers nodes that aren't invisible or offscreen.
  64   void SetVisibleOnly(bool visible_only);
  65
  66   // Restricts the matches to only nodes where |text| is found as a
  67   // substring of any of that node's accessible text, including its
  68   // name, description, or value. Case-insensitive.
  69   void SetSearchText(const std::string& text);
  70
  71   // Restricts the matches to only those that satisfy all predicates.
  72   void AddPredicate(AccessibilityMatchPredicate predicate);
  73
  74   //
  75   // Calling either of these executes the search.
  76   //
  77
  78   size_t CountMatches();
  79   BrowserAccessibility* GetMatchAtIndex(size_t index);
  80
  81  private:
  82   void Search();
  83   void SearchByWalkingTree();
  84   void SearchByIteratingOverChildren();
  85   bool Matches(BrowserAccessibility* node);
  86
  87   BrowserAccessibilityManager* tree_;
  88   BrowserAccessibility* start_node_;
  89   Direction direction_;
  90   int result_limit_;
  91   bool immediate_descendants_only_;
  92   bool visible_only_;
  93   std::string search_text_;
  94
  95   std::vector<AccessibilityMatchPredicate> predicates_;
  96   std::vector<BrowserAccessibility*> matches_;
  97
  98   bool did_search_;
  99
 100   DISALLOW_COPY_AND_ASSIGN(OneShotAccessibilityTreeSearch);
 101 };
 102
 103 }  // namespace content
 104
 105 #endif  // CONTENT_BROWSER_ACCESSIBILITY_ACCESSIBILITY_TREE_SEARCH_H_