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 RenderViewHost;
  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   static AccessibilityTreeFormatter* Create(RenderViewHost* rvh);
  31
  32   // Populates the given DictionaryValue with the accessibility tree.
  33   // The dictionary contains a key/value pair for each attribute of the node,
  34   // plus a "children" attribute containing a list of all child nodes.
  35   // {
  36   //   "AXName": "node",  /* actual attributes will vary by platform */
  37   //   "position": {  /* some attributes may be dictionaries */
  38   //     "x": 0,
  39   //     "y": 0
  40   //   },
  41   //   /* ... more attributes of |node| */
  42   //   "children": [ {  /* list of children created recursively */
  43   //     "AXName": "child node 1",
  44   //     /* ... more attributes */
  45   //     "children": [ ]
  46   //   }, {
  47   //     "AXName": "child name 2",
  48   //     /* ... more attributes */
  49   //     "children": [ ]
  50   //   } ]
  51   // }
  52   scoped_ptr<base::DictionaryValue> BuildAccessibilityTree();
  53
  54   // Dumps a BrowserAccessibility tree into a string.
  55   void FormatAccessibilityTree(base::string16* contents);
  56
  57   // A single filter specification. See GetAllowString() and GetDenyString()
  58   // for more information.
  59   struct Filter {
  60     enum Type {
  61       ALLOW,
  62       ALLOW_EMPTY,
  63       DENY
  64     };
  65     base::string16 match_str;
  66     Type type;
  67
  68     Filter(base::string16 match_str, Type type)
  69         : match_str(match_str), type(type) {}
  70   };
  71
  72   // Set regular expression filters that apply to each component of every
  73   // line before it's output.
  74   void SetFilters(const std::vector<Filter>& filters);
  75
  76   // Suffix of the expectation file corresponding to html file.
  77   // Example:
  78   // HTML test:      test-file.html
  79   // Expected:       test-file-expected-mac.txt.
  80   // Auto-generated: test-file-actual-mac.txt
  81   static const base::FilePath::StringType GetActualFileSuffix();
  82   static const base::FilePath::StringType GetExpectedFileSuffix();
  83
  84   // A platform-specific string that indicates a given line in a file
  85   // is an allow-empty, allow or deny filter. Example:
  86   // Mac values:
  87   //   GetAllowEmptyString() -> "@MAC-ALLOW-EMPTY:"
  88   //   GetAllowString() -> "@MAC-ALLOW:"
  89   //   GetDenyString() -> "@MAC-DENY:"
  90   // Example html:
  91   // <!--
  92   // @MAC-ALLOW-EMPTY:description*
  93   // @MAC-ALLOW:roleDescription*
  94   // @MAC-DENY:subrole*
  95   // -->
  96   // <p>Text</p>
  97   static const std::string GetAllowEmptyString();
  98   static const std::string GetAllowString();
  99   static const std::string GetDenyString();
 100
 101  protected:
 102   void RecursiveFormatAccessibilityTree(const BrowserAccessibility& node,
 103                                         base::string16* contents,
 104                                         int indent);
 105   void RecursiveBuildAccessibilityTree(const BrowserAccessibility& node,
 106                                        base::DictionaryValue* tree_node);
 107   void RecursiveFormatAccessibilityTree(const base::DictionaryValue& tree_node,
 108                                         base::string16* contents,
 109                                         int depth = 0);
 110
 111   // Overridden by each platform to add the required attributes for each node
 112   // into the given dict.
 113   void AddProperties(const BrowserAccessibility& node,
 114                      base::DictionaryValue* dict);
 115
 116   base::string16 FormatCoordinates(const char* name,
 117                                    const char* x_name,
 118                                    const char* y_name,
 119                                    const base::DictionaryValue& value);
 120
 121   // Returns a platform specific representation of a BrowserAccessibility.
 122   // Should be zero or more complete lines, each with |prefix| prepended
 123   // (to indent each line).
 124   base::string16 ToString(const base::DictionaryValue& node,
 125                           const base::string16& indent);
 126
 127   void Initialize();
 128
 129   bool MatchesFilters(const base::string16& text, bool default_result) const;
 130
 131   // Writes the given attribute string out to |line| if it matches the filters.
 132   void WriteAttribute(bool include_by_default,
 133                       const base::string16& attr,
 134                       base::string16* line);
 135   void WriteAttribute(bool include_by_default,
 136                       const std::string& attr,
 137                       base::string16* line);
 138
 139   BrowserAccessibility* root_;
 140
 141   // Filters used when formatting the accessibility tree as text.
 142   std::vector<Filter> filters_;
 143
 144   DISALLOW_COPY_AND_ASSIGN(AccessibilityTreeFormatter);
 145 };
 146
 147 }  // namespace content
 148
 149 #endif  // CONTENT_BROWSER_ACCESSIBILITY_ACCESSIBILITY_TREE_FORMATTER_H_