accessible/base/nsTextEquivUtils.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:expandtab:shiftwidth=2:tabstop=2:
   3  */
   4 /* This Source Code Form is subject to the terms of the Mozilla Public
   5  * License, v. 2.0. If a copy of the MPL was not distributed with this
   6  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   7
   8 #ifndef _nsTextEquivUtils_H_
   9 #define _nsTextEquivUtils_H_
  10
  11 #include "mozilla/a11y/Accessible.h"
  12 #include "mozilla/a11y/Role.h"
  13
  14 class nsIContent;
  15
  16 namespace mozilla {
  17 namespace a11y {
  18 class LocalAccessible;
  19 }
  20 }  // namespace mozilla
  21
  22 /**
  23  * Text equivalent computation rules (see nsTextEquivUtils::gRoleToNameRulesMap)
  24  */
  25 enum ETextEquivRule {
  26   // No rule.
  27   eNoNameRule = 0x00,
  28
  29   // Walk into subtree only if the currently navigated accessible is not root
  30   // accessible (i.e. if the accessible is part of text equivalent computation).
  31   eNameFromSubtreeIfReqRule = 0x01,
  32
  33   // Text equivalent computation from subtree is allowed.
  34   eNameFromSubtreeRule = 0x03,
  35
  36   // The accessible allows to append its value to text equivalent.
  37   // XXX: This is temporary solution. Once we move accessible value of links
  38   // and linkable accessibles to MSAA part we can remove this.
  39   eNameFromValueRule = 0x04
  40 };
  41
  42 /**
  43  * The class provides utils methods to compute the accessible name and
  44  * description.
  45  */
  46 class nsTextEquivUtils {
  47  public:
  48   typedef mozilla::a11y::LocalAccessible LocalAccessible;
  49   typedef mozilla::a11y::Accessible Accessible;
  50
  51   /**
  52    * Determines if the accessible has a given name rule.
  53    *
  54    * @param aAccessible [in] the given accessible
  55    * @param aRule       [in] a given name rule
  56    * @return true if the accessible has the rule
  57    */
  58   static inline bool HasNameRule(Accessible* aAccessible,
  59                                  ETextEquivRule aRule) {
  60     return (GetRoleRule(aAccessible->Role()) & aRule) == aRule;
  61   }
  62
  63   /**
  64    * Calculates the name from accessible subtree if allowed.
  65    *
  66    * @param aAccessible [in] the given accessible
  67    * @param aName       [out] accessible name
  68    */
  69   static nsresult GetNameFromSubtree(const LocalAccessible* aAccessible,
  70                                      nsAString& aName);
  71
  72   /**
  73    * Calculates text equivalent from the subtree. Similar to GetNameFromSubtree.
  74    * However it returns not empty result for things like HTML p.
  75    */
  76   static void GetTextEquivFromSubtree(const Accessible* aAccessible,
  77                                       nsString& aTextEquiv) {
  78     aTextEquiv.Truncate();
  79
  80     AppendFromAccessibleChildren(aAccessible, &aTextEquiv);
  81     aTextEquiv.CompressWhitespace();
  82   }
  83
  84   /**
  85    * Calculates text equivalent for the given accessible from its IDRefs
  86    * attribute (like aria-labelledby or aria-describedby).
  87    *
  88    * @param aAccessible  [in] the accessible text equivalent is computed for
  89    * @param aIDRefsAttr  [in] IDRefs attribute on DOM node of the accessible
  90    * @param aTextEquiv   [out] result text equivalent
  91    */
  92   static nsresult GetTextEquivFromIDRefs(const LocalAccessible* aAccessible,
  93                                          nsAtom* aIDRefsAttr,
  94                                          nsAString& aTextEquiv);
  95
  96   /**
  97    * Calculates the text equivalent from the given content and its subtree if
  98    * allowed and appends it to the given string.
  99    *
 100    * @param aInitiatorAcc  [in] the accessible text equivalent is computed for
 101    *                       in the end (root accessible of text equivalent
 102    *                       calculation recursion)
 103    * @param aContent       [in] the given content the text equivalent is
 104    *                       computed from
 105    * @param aString        [in, out] the string
 106    */
 107   static nsresult AppendTextEquivFromContent(
 108       const LocalAccessible* aInitiatorAcc, nsIContent* aContent,
 109       nsAString* aString);
 110
 111   /**
 112    * Calculates the text equivalent from the given text content (may be text
 113    * node or html:br) and appends it to the given string.
 114    *
 115    * @param aContent       [in] the text content
 116    * @param aString        [in, out] the string
 117    */
 118   static nsresult AppendTextEquivFromTextContent(nsIContent* aContent,
 119                                                  nsAString* aString);
 120
 121   /**
 122    * Iterates DOM children and calculates text equivalent from each child node.
 123    * Then, appends found text to the given string.
 124    *
 125    * @param aContent      [in] the node to fetch DOM children from
 126    * @param aString       [in, out] the string
 127    */
 128   static nsresult AppendFromDOMChildren(nsIContent* aContent,
 129                                         nsAString* aString);
 130
 131  private:
 132   /**
 133    * Iterates accessible children and calculates text equivalent from each
 134    * child.
 135    */
 136   static nsresult AppendFromAccessibleChildren(const Accessible* aAccessible,
 137                                                nsAString* aString);
 138
 139   /**
 140    * Calculates text equivalent from the given accessible and its subtree if
 141    * allowed.
 142    */
 143   static nsresult AppendFromAccessible(Accessible* aAccessible,
 144                                        nsAString* aString);
 145
 146   /**
 147    * Calculates text equivalent from the value of given accessible.
 148    */
 149   static nsresult AppendFromValue(Accessible* aAccessible, nsAString* aString);
 150
 151   /**
 152    * Calculates text equivalent from the given DOM node and its subtree if
 153    * allowed.
 154    */
 155   static nsresult AppendFromDOMNode(nsIContent* aContent, nsAString* aString);
 156
 157   /**
 158    * Concatenates strings and appends space between them. Returns true if
 159    * text equivalent string was appended.
 160    */
 161   static bool AppendString(nsAString* aString,
 162                            const nsAString& aTextEquivalent);
 163
 164   /**
 165    * Returns the rule (constant of ETextEquivRule) for a given role.
 166    */
 167   static uint32_t GetRoleRule(mozilla::a11y::roles::Role aRole);
 168
 169   /**
 170    * Returns true if a given accessible should be included when calculating
 171    * the text equivalent for the initiator's subtree.
 172    */
 173   static bool ShouldIncludeInSubtreeCalculation(Accessible* aAccessible);
 174
 175   /**
 176    * Returns true if a given accessible is a text leaf containing only
 177    * whitespace.
 178    */
 179   static bool IsWhitespaceLeaf(Accessible* aAccessible);
 180 };
 181
 182 #endif