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