nsTextEquivUtils.h (7459B)
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 class AccIterable; 20 } // namespace a11y 21 } // namespace mozilla 22 23 /** 24 * Text equivalent computation rules. These rules are mapped to accessible roles 25 * in RoleMap.h. 26 */ 27 enum ETextEquivRule { 28 // No rule. Equivalent to "name from author." 29 eNoNameRule = 0x00, 30 31 // Walk into subtree only if the currently navigated accessible is not root 32 // accessible (i.e. if the accessible is part of text equivalent computation). 33 eNameFromSubtreeIfReqRule = 0x01, 34 35 // Text equivalent computation from subtree is allowed. Equivalent to "name 36 // from content." 37 eNameFromSubtreeRule = 0x03, 38 39 // The accessible allows to append its value to text equivalent. 40 // XXX: This is temporary solution. Once we move accessible value of links 41 // and linkable accessibles to MSAA part we can remove this. 42 eNameFromValueRule = 0x04 43 }; 44 45 /** 46 * The class provides utils methods to compute the accessible name and 47 * description. Note that, as of the Accessible Name and Description Computation 48 * 1.2 specification, the phrases "text equivalent" and "text alternative" are 49 * used interchangably. 50 */ 51 class nsTextEquivUtils { 52 public: 53 typedef mozilla::a11y::LocalAccessible LocalAccessible; 54 typedef mozilla::a11y::Accessible Accessible; 55 typedef mozilla::a11y::AccIterable AccIterable; 56 57 /** 58 * Determines if the accessible has a given name rule. 59 * 60 * @param aAccessible [in] the given accessible 61 * @param aRule [in] a given name rule 62 * @return true if the accessible has the rule 63 */ 64 static bool HasNameRule(const Accessible* aAccessible, ETextEquivRule aRule); 65 66 /** 67 * Calculates the name from the given accessible's subtree, if allowed. 68 * 69 * @param aAccessible [in] the given accessible 70 * @param aName [out] accessible name 71 */ 72 static nsresult GetNameFromSubtree(const Accessible* aAccessible, 73 nsAString& aName); 74 75 /** 76 * Calculates text equivalent from the subtree. This function is similar to 77 * GetNameFromSubtree, but it returns a non-empty result for things like 78 * HTML:p, since it does not verify that the given accessible allows name 79 * from content. 80 */ 81 static void GetTextEquivFromSubtree(const Accessible* aAccessible, 82 nsString& aTextEquiv) { 83 aTextEquiv.Truncate(); 84 85 AppendFromAccessibleChildren(aAccessible, &aTextEquiv); 86 aTextEquiv.CompressWhitespace(); 87 } 88 89 /** 90 * Calculates the text equivalent for the given accessible from one of its 91 * IDRefs attributes (like aria-labelledby or aria-describedby). 92 * 93 * @param aAccessible [in] the accessible text equivalent is computed for 94 * @param aIDRefsAttr [in] IDRefs attribute on DOM node of the accessible 95 * @param aTextEquiv [out] result text equivalent 96 * @return true if either hidden content was used to compute the text 97 * equivalent, or if the initiator accessible itself was used. 98 */ 99 static bool GetTextEquivFromIDRefs(const LocalAccessible* aAccessible, 100 nsAtom* aIDRefsAttr, 101 nsAString& aTextEquiv); 102 103 static void GetTextEquivFromAccIterable(const Accessible* aAccessible, 104 AccIterable* aIter, 105 nsAString& aTextEquiv); 106 107 /** 108 * Calculates the text equivalent from the given content - and its subtree, if 109 * allowed - and appends it to the given string. 110 * 111 * @param aInitiatorAcc [in] the accessible text equivalent is computed for 112 * in the end (root accessible of text equivalent 113 * calculation recursion) 114 * @param aContent [in] the given content the text equivalent is 115 * computed from 116 * @param aString [in, out] the string 117 * @return true if either hidden content was used to compute the text 118 * equivalent, or if the initiator accessible itself was used. 119 */ 120 static bool AppendTextEquivFromContent(const LocalAccessible* aInitiatorAcc, 121 nsIContent* aContent, 122 nsAString* aString); 123 124 /** 125 * Calculates the text equivalent from the given text content (may be text 126 * node or html:br) and appends it to the given string. 127 * 128 * @param aContent [in] the text content 129 * @param aString [in, out] the string 130 */ 131 static nsresult AppendTextEquivFromTextContent(nsIContent* aContent, 132 nsAString* aString); 133 134 /** 135 * Iterates DOM children and calculates the text equivalent from each child 136 * node. Then, appends the calculated text to the given string. 137 * 138 * @param aContent [in] the node to fetch DOM children from 139 * @param aString [in, out] the string 140 */ 141 static nsresult AppendFromDOMChildren(nsIContent* aContent, 142 nsAString* aString); 143 144 /** 145 * Calculates the text equivalent from the given accessible - and its subtree, 146 * if allowed. Then, appends the calculated text to the given string. 147 */ 148 static nsresult AppendFromAccessible(Accessible* aAccessible, 149 nsAString* aString); 150 151 private: 152 /** 153 * Iterates the given accessible's children and calculates the text equivalent 154 * from each child. Then, appends the calculated text to the given string. 155 */ 156 static nsresult AppendFromAccessibleChildren(const Accessible* aAccessible, 157 nsAString* aString); 158 159 /** 160 * Calculates the text equivalent from the value of the given accessible. 161 * Then, appends the calculated text to the given string. This function 162 * implements the "Embedded Control" section of the AccName spec. 163 */ 164 static nsresult AppendFromValue(Accessible* aAccessible, nsAString* aString); 165 166 /** 167 * Calculates the text equivalent from the given DOM node - and its subtree, 168 * if allowed. Then, appends the calculated text to the given string. 169 */ 170 static nsresult AppendFromDOMNode(nsIContent* aContent, nsAString* aString); 171 172 /** 173 * Concatenates the given strings and appends space between them. Returns true 174 * if the text equivalent string was appended. 175 */ 176 static bool AppendString(nsAString* aString, 177 const nsAString& aTextEquivalent); 178 179 /** 180 * Returns the rule (constant of ETextEquivRule) for a given role. 181 */ 182 static uint32_t GetRoleRule(mozilla::a11y::roles::Role aRole); 183 184 /** 185 * Returns true if a given accessible should be included when calculating 186 * the text equivalent for the initiator's subtree. 187 */ 188 static bool ShouldIncludeInSubtreeCalculation(Accessible* aAccessible); 189 190 /** 191 * Returns true if the given accessible is a text leaf containing only 192 * whitespace. 193 */ 194 static bool IsWhitespaceLeaf(Accessible* aAccessible); 195 }; 196 197 #endif