Implement UIElementsForSearchPredicate accessibility APIs for OS X.

content/browser/accessibility/accessibility_tree_search.h

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CONTENT_BROWSER_ACCESSIBILITY_ACCESSIBILITY_TREE_SEARCH_H_
+#define CONTENT_BROWSER_ACCESSIBILITY_ACCESSIBILITY_TREE_SEARCH_H_
+
+#include <string>
+#include <vector>
+
+#include "base/macros.h"
+#include "content/common/content_export.h"
+
+namespace content {
+
+class BrowserAccessibility;
+class BrowserAccessibilityManager;
+
+// A function that returns whether or not a given node matches, given the
+// start element of the search as an optional comparator.
+typedef bool (*AccessibilityMatchPredicate)(BrowserAccessibility* start_element,
+                                            BrowserAccessibility* this_element);
+
+// This class provides an interface for searching the accessibility tree from
+// a given starting node, with a few built-in options and allowing an arbitrary
+// number of predicates that can be used to restrict the search.
+//
+// This class is meant to perform one search. Initialize it, then iterate
+// over the matches, and then delete it.

[David Tseng, 2015/05/08 21:58:25]

Rename to *OneShot?

[dmazzoni, 2015/05/13 04:22:20]

Done.

+//
+// This class stores raw pointers to the matches in the tree! Don't keep this
+// object around if the tree is mutating.
+class CONTENT_EXPORT AccessibilityTreeSearch {
+ public:
+  enum Direction { FORWARDS, BACKWARDS };
+
+  AccessibilityTreeSearch(BrowserAccessibilityManager* tree);
+  virtual ~AccessibilityTreeSearch();
+
+  //
+  // Search parameters.  All of these are optional.
+  //
+
+  // Sets the node where the search starts. The first potential match will
+  // be the one immediately following this one. This node will be used as
+  // the first arguement to any predicates.
+  void SetStartNode(BrowserAccessibility* start_node);
+
+  // Search forwards or backwards in an in-order traversal of the tree.
+  void SetDirection(Direction direction);
+
+  // Set the maximum number of results, or -1 for no limit (default).

[David Tseng, 2015/05/08 21:58:25]

Name -1; also, does it even make sense to allow 0 as a value here?

[dmazzoni, 2015/05/13 04:22:20]

Done.

+  void SetResultLimit(int result_limit);
+
+  // If true, only searches descendants of |start_node|.
+  void SetImmediateDescendantsOnly(bool immediate_descendants_only);

[David Tseng, 2015/05/08 21:58:25]

Is there a difference between immediate and non-immediate descendants?

[dmazzoni, 2015/05/13 04:22:20]

Turns out I was wrong about the implementation. I found the WebKit bug where
this was added and it's supposed to mean only the children of the start node.

https://bugs.webkit.org/show_bug.cgi?id=128747

I fixed the code and the test.

+
+  // If true, only considers nodes that aren't invisible or offscreen.
+  void SetVisibleOnly(bool visible_only);
+
+  // Restricts the matches to only nodes where |text| is found as a
+  // substring of any of that node's accessible text, including its
+  // name, description, or value. Case-insensitive.
+  void SetSearchText(const std::string& text);
+
+  // Restricts the matches to only those that satisfy all predicates.
+  void AddPredicate(AccessibilityMatchPredicate predicate);
+
+  //
+  // Calling either of these executes the search.
+  //
+
+  size_t CountMatches();
+  BrowserAccessibility* GetMatchAtIndex(size_t index);
+
+ private:
+  void DoSearch();
+
+  BrowserAccessibilityManager* tree_;
+  BrowserAccessibility* start_node_;
+  Direction direction_;
+  int result_limit_;
+  bool immediate_descendants_only_;
+  bool visible_only_;
+  std::string search_text_;
+
+  std::vector<AccessibilityMatchPredicate> predicates_;
+  std::vector<BrowserAccessibility*> matches_;
+
+  bool did_search_;
+
+  DISALLOW_COPY_AND_ASSIGN(AccessibilityTreeSearch);
+};
+
+}  // namespace content
+
+#endif  // CONTENT_BROWSER_ACCESSIBILITY_ACCESSIBILITY_TREE_SEARCH_H_