content/browser/accessibility/accessibility_tree_formatter.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_ACCESSIBILITY_TREE_FORMATTER_H_
   6 #define CONTENT_BROWSER_ACCESSIBILITY_ACCESSIBILITY_TREE_FORMATTER_H_
   7
   8 #include <vector>
   9
  10 #include "base/files/file_path.h"
  11 #include "base/strings/string16.h"
  12 #include "base/strings/utf_string_conversions.h"
  13 #include "base/values.h"
  14 #include "content/browser/accessibility/browser_accessibility.h"
  15 #include "content/common/content_export.h"
  16
  17 namespace content {
  18
  19 class WebContents;
  20
  21 // A utility class for formatting platform-specific accessibility information,
  22 // for use in testing, debugging, and developer tools.
  23 // This is extended by a subclass for each platform where accessibility is
  24 // implemented.
  25 class CONTENT_EXPORT AccessibilityTreeFormatter {
  26  public:
  27   explicit AccessibilityTreeFormatter(BrowserAccessibility* root);
  28   virtual ~AccessibilityTreeFormatter();
  29
  30   // A single filter specification. See GetAllowString() and GetDenyString()
  31   // for more information.
  32   struct Filter {
  33     enum Type {
  34       ALLOW,
  35       ALLOW_EMPTY,
  36       DENY
  37     };
  38     base::string16 match_str;
  39     Type type;
  40
  41     Filter(base::string16 match_str, Type type)
  42         : match_str(match_str), type(type) {}
  43   };
  44
  45   static AccessibilityTreeFormatter* Create(WebContents* wc);
  46
  47   static bool MatchesFilters(
  48       const std::vector<Filter>& filters,
  49       const base::string16& text,
  50       bool default_result);
  51
  52   // Populates the given DictionaryValue with the accessibility tree.
  53   // The dictionary contains a key/value pair for each attribute of the node,
  54   // plus a "children" attribute containing a list of all child nodes.
  55   // {
  56   //   "AXName": "node",  /* actual attributes will vary by platform */
  57   //   "position": {  /* some attributes may be dictionaries */
  58   //     "x": 0,
  59   //     "y": 0
  60   //   },
  61   //   /* ... more attributes of |node| */
  62   //   "children": [ {  /* list of children created recursively */
  63   //     "AXName": "child node 1",
  64   //     /* ... more attributes */
  65   //     "children": [ ]
  66   //   }, {
  67   //     "AXName": "child name 2",
  68   //     /* ... more attributes */
  69   //     "children": [ ]
  70   //   } ]
  71   // }
  72   scoped_ptr<base::DictionaryValue> BuildAccessibilityTree();
  73
  74   // Dumps a BrowserAccessibility tree into a string.
  75   void FormatAccessibilityTree(base::string16* contents);
  76
  77   // Set regular expression filters that apply to each component of every
  78   // line before it's output.
  79   void SetFilters(const std::vector<Filter>& filters);
  80
  81   // If true, the internal accessibility id of each node will be included
  82   // in its output.
  83   void set_show_ids(bool show_ids) { show_ids_ = show_ids; }
  84
  85   // Suffix of the expectation file corresponding to html file.
  86   // Example:
  87   // HTML test:      test-file.html
  88   // Expected:       test-file-expected-mac.txt.
  89   // Auto-generated: test-file-actual-mac.txt
  90   static const base::FilePath::StringType GetActualFileSuffix();
  91   static const base::FilePath::StringType GetExpectedFileSuffix();
  92
  93   // A platform-specific string that indicates a given line in a file
  94   // is an allow-empty, allow or deny filter. Example:
  95   // Mac values:
  96   //   GetAllowEmptyString() -> "@MAC-ALLOW-EMPTY:"
  97   //   GetAllowString() -> "@MAC-ALLOW:"
  98   //   GetDenyString() -> "@MAC-DENY:"
  99   // Example html:
 100   // <!--
 101   // @MAC-ALLOW-EMPTY:description*
 102   // @MAC-ALLOW:roleDescription*
 103   // @MAC-DENY:subrole*
 104   // -->
 105   // <p>Text</p>
 106   static const std::string GetAllowEmptyString();
 107   static const std::string GetAllowString();
 108   static const std::string GetDenyString();
 109
 110  protected:
 111   void RecursiveFormatAccessibilityTree(const BrowserAccessibility& node,
 112                                         base::string16* contents,
 113                                         int indent);
 114   void RecursiveBuildAccessibilityTree(const BrowserAccessibility& node,
 115                                        base::DictionaryValue* tree_node);
 116   void RecursiveFormatAccessibilityTree(const base::DictionaryValue& tree_node,
 117                                         base::string16* contents,
 118                                         int depth = 0);
 119
 120   // Overridden by each platform to add the required attributes for each node
 121   // into the given dict.
 122   void AddProperties(const BrowserAccessibility& node,
 123                      base::DictionaryValue* dict);
 124
 125   base::string16 FormatCoordinates(const char* name,
 126                                    const char* x_name,
 127                                    const char* y_name,
 128                                    const base::DictionaryValue& value);
 129
 130   // Returns a platform specific representation of a BrowserAccessibility.
 131   base::string16 ToString(const base::DictionaryValue& node);
 132
 133   void Initialize();
 134
 135   bool MatchesFilters(const base::string16& text, bool default_result) const;
 136
 137   // Writes the given attribute string out to |line| if it matches the filters.
 138   void WriteAttribute(bool include_by_default,
 139                       const base::string16& attr,
 140                       base::string16* line);
 141   void WriteAttribute(bool include_by_default,
 142                       const std::string& attr,
 143                       base::string16* line);
 144
 145   BrowserAccessibility* root_;
 146
 147   // Filters used when formatting the accessibility tree as text.
 148   std::vector<Filter> filters_;
 149
 150   // Whether or not node ids should be included in the dump.
 151   bool show_ids_;
 152
 153   DISALLOW_COPY_AND_ASSIGN(AccessibilityTreeFormatter);
 154 };
 155
 156 }  // namespace content
 157
 158 #endif  // CONTENT_BROWSER_ACCESSIBILITY_ACCESSIBILITY_TREE_FORMATTER_H_