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