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_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_
    150