nsAccUtils.h (11558B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #ifndef nsAccUtils_h_ 7 #define nsAccUtils_h_ 8 9 #include "mozilla/a11y/LocalAccessible.h" 10 #include "mozilla/a11y/DocManager.h" 11 12 #include "nsAccessibilityService.h" 13 #include "nsCoreUtils.h" 14 15 #include "nsIDocShell.h" 16 #include "nsPoint.h" 17 18 namespace mozilla { 19 20 class PresShell; 21 22 namespace dom { 23 class Element; 24 } 25 26 namespace a11y { 27 28 class HyperTextAccessible; 29 class DocAccessible; 30 class Attribute; 31 32 class nsAccUtils { 33 public: 34 /** 35 * Set group attributes ('level', 'setsize', 'posinset'). 36 */ 37 static void SetAccGroupAttrs(AccAttributes* aAttributes, int32_t aLevel, 38 int32_t aSetSize, int32_t aPosInSet); 39 static void SetAccGroupAttrs(AccAttributes* aAttributes, Accessible* aAcc); 40 41 /** 42 * Compute group level for nsIDOMXULContainerItemElement node. 43 */ 44 static int32_t GetLevelForXULContainerItem(nsIContent* aContent); 45 46 /** 47 * Set container-foo live region attributes for the given node. 48 * 49 * @param aAttributes where to store the attributes 50 * @param aStartAcc Accessible to start from 51 */ 52 static void SetLiveContainerAttributes(AccAttributes* aAttributes, 53 Accessible* aStartAcc); 54 55 /** 56 * Any ARIA property of type boolean or NMTOKEN is undefined if the ARIA 57 * property is not present, or is "" or "undefined". Do not call 58 * this method for properties of type string, decimal, IDREF or IDREFS. 59 * 60 * Return true if the ARIA property is defined, otherwise false 61 */ 62 static bool HasDefinedARIAToken(nsIContent* aContent, nsAtom* aAtom); 63 static bool HasDefinedARIAToken(const AttrArray* aAttrs, nsAtom* aAtom); 64 65 /** 66 * If the given ARIA attribute has a specific known token value, return it. 67 * If the specification demands for a fallback value for unknown attribute 68 * values, return that. For all others, return a nullptr. 69 */ 70 static nsStaticAtom* NormalizeARIAToken(const AttrArray* aAttrs, 71 nsAtom* aAttr); 72 static nsStaticAtom* NormalizeARIAToken(mozilla::dom::Element* aElement, 73 nsAtom* aAttr); 74 75 /** 76 * Return document accessible for the given DOM node. 77 */ 78 static DocAccessible* GetDocAccessibleFor(nsINode* aNode) { 79 return GetAccService()->GetDocAccessible( 80 nsCoreUtils::GetPresShellFor(aNode)); 81 } 82 83 /** 84 * Return document accessible for the given docshell. 85 */ 86 static DocAccessible* GetDocAccessibleFor(nsIDocShellTreeItem* aContainer) { 87 nsCOMPtr<nsIDocShell> docShell(do_QueryInterface(aContainer)); 88 return GetAccService()->GetDocAccessible(docShell->GetPresShell()); 89 } 90 91 /** 92 * Return single or multi selectable container for the given item. 93 * 94 * @param aAccessible [in] the item accessible 95 * @param aState [in] the state of the item accessible 96 */ 97 static Accessible* GetSelectableContainer(const Accessible* aAccessible, 98 uint64_t aState); 99 static LocalAccessible* GetSelectableContainer(LocalAccessible* aAccessible, 100 uint64_t aState); 101 102 /** 103 * Return a text container accessible for the given node. 104 */ 105 static HyperTextAccessible* GetTextContainer(nsINode* aNode); 106 107 static Accessible* TableFor(const Accessible* aRow); 108 static LocalAccessible* TableFor(LocalAccessible* aRow); 109 110 static const LocalAccessible* TableFor(const LocalAccessible* aAcc) { 111 return TableFor(const_cast<LocalAccessible*>(aAcc)); 112 } 113 114 /** 115 * Return true if the DOM node of a given accessible has a given attribute 116 * with a value of "true". 117 */ 118 static bool IsDOMAttrTrue(const LocalAccessible* aAccessible, nsAtom* aAttr); 119 120 /** 121 * Return true if the DOM node of given accessible has aria-selected="true" 122 * attribute. 123 */ 124 static inline bool IsARIASelected(const LocalAccessible* aAccessible) { 125 return IsDOMAttrTrue(aAccessible, nsGkAtoms::aria_selected); 126 } 127 128 /** 129 * Return true if the DOM node of given accessible has 130 * aria-multiselectable="true" attribute. 131 */ 132 static inline bool IsARIAMultiSelectable(const LocalAccessible* aAccessible) { 133 return IsDOMAttrTrue(aAccessible, nsGkAtoms::aria_multiselectable); 134 } 135 136 /** 137 * Converts the given coordinates to coordinates relative screen. 138 * 139 * @param aX [in] the given x coord in dev pixels 140 * @param aY [in] the given y coord in dev pixels 141 * @param aCoordinateType [in] specifies coordinates origin (refer to 142 * nsIAccessibleCoordinateType) 143 * @param aAccessible [in] the accessible if coordinates are given 144 * relative it. 145 * @return converted coordinates 146 */ 147 static LayoutDeviceIntPoint ConvertToScreenCoords(int32_t aX, int32_t aY, 148 uint32_t aCoordinateType, 149 Accessible* aAccessible); 150 151 /** 152 * Converts the given coordinates relative screen to another coordinate 153 * system. 154 * 155 * @param aX [in, out] the given x coord in dev pixels 156 * @param aY [in, out] the given y coord in dev pixels 157 * @param aCoordinateType [in] specifies coordinates origin (refer to 158 * nsIAccessibleCoordinateType) 159 * @param aAccessible [in] the accessible if coordinates are given 160 * relative it 161 */ 162 static void ConvertScreenCoordsTo(int32_t* aX, int32_t* aY, 163 uint32_t aCoordinateType, 164 Accessible* aAccessible); 165 166 /** 167 * Returns screen-relative coordinates (in dev pixels) for the parent of the 168 * given accessible. 169 * 170 * @param [in] aAccessible the accessible 171 */ 172 static LayoutDeviceIntPoint GetScreenCoordsForParent(Accessible* aAccessible); 173 174 /** 175 * Returns coordinates in device pixels relative screen for the top level 176 * window. 177 * 178 * @param aAccessible the acc hosted in the window. 179 */ 180 static mozilla::LayoutDeviceIntPoint GetScreenCoordsForWindow( 181 mozilla::a11y::Accessible* aAccessible); 182 183 /** 184 * Get the 'live' or 'container-live' object attribute value from the given 185 * ELiveAttrRule constant. 186 * 187 * @param aRule [in] rule constant (see ELiveAttrRule in nsAccMap.h) 188 * @param aValue [out] object attribute value 189 * 190 * @return true if object attribute should be exposed 191 */ 192 static bool GetLiveAttrValue(uint32_t aRule, nsAString& aValue); 193 194 #ifdef DEBUG 195 /** 196 * Detect whether the given accessible object implements nsIAccessibleText, 197 * when it is text or has text child node. 198 */ 199 static bool IsTextInterfaceSupportCorrect(LocalAccessible* aAccessible); 200 #endif 201 202 /** 203 * Return text length of the given accessible, return 0 on failure. 204 */ 205 static uint32_t TextLength(Accessible* aAccessible); 206 207 /** 208 * Transform nsIAccessibleStates constants to internal state constant. 209 */ 210 static inline uint64_t To64State(uint32_t aState1, uint32_t aState2) { 211 return static_cast<uint64_t>(aState1) + 212 (static_cast<uint64_t>(aState2) << 31); 213 } 214 215 /** 216 * Transform internal state constant to nsIAccessibleStates constants. 217 */ 218 static inline void To32States(uint64_t aState64, uint32_t* aState1, 219 uint32_t* aState2) { 220 *aState1 = aState64 & 0x7fffffff; 221 if (aState2) *aState2 = static_cast<uint32_t>(aState64 >> 31); 222 } 223 224 static uint32_t To32States(uint64_t aState, bool* aIsExtra) { 225 uint32_t extraState = aState >> 31; 226 *aIsExtra = !!extraState; 227 return extraState ? extraState : aState; 228 } 229 230 /** 231 * Return true if the given accessible can't have children. Used when exposing 232 * to platform accessibility APIs, should the children be pruned off? 233 */ 234 static bool MustPrune(Accessible* aAccessible); 235 236 /** 237 * Get the live region setting (polite, etc.) for this Accessible. This does 238 * not walk ancestors. It does account for implicit live regions as 239 * determined from the ARIA role or markup tag name. 240 */ 241 static void GetLiveRegionSetting(Accessible* aAcc, nsAString& aLive); 242 243 /** 244 * If the given Accessible is inside a live region, return the root of the 245 * live region. Otherwise, return null. 246 */ 247 static Accessible* GetLiveRegionRoot(Accessible* aAcc); 248 249 /** 250 * Get the document Accessible which owns a given Accessible. 251 * This function is needed because there is no unified base class for local 252 * and remote documents. 253 * If aAcc is null, null will be returned. 254 */ 255 static Accessible* DocumentFor(Accessible* aAcc); 256 257 /** 258 * Get an Accessible in a given document by its unique id. 259 * An Accessible's id can be obtained using Accessible::ID. 260 * This function is needed because there is no unified base class for local 261 * and remote documents. 262 * If aDoc is nul, null will be returned. 263 */ 264 static Accessible* GetAccessibleByID(Accessible* aDoc, uint64_t aID); 265 266 /** 267 * Get the URL for a given document. 268 * This function is needed because there is no unified base class for local 269 * and remote documents. 270 */ 271 static void DocumentURL(Accessible* aDoc, nsAString& aURL); 272 273 /** 274 * Get the mime type for a given document. 275 * This function is needed because there is no unified base class for local 276 * and remote documents. 277 */ 278 static void DocumentMimeType(Accessible* aDoc, nsAString& aMimeType); 279 280 /** 281 * Accessors for element attributes that are aware of CustomElement ARIA 282 * accessibility defaults. If the element does not have the provided 283 * attribute defined directly on it, we will then attempt to fetch the 284 * default instead. 285 */ 286 static const AttrArray* GetARIADefaults(dom::Element* aElement); 287 static bool HasARIAAttr(dom::Element* aElement, const nsAtom* aName); 288 static bool GetARIAAttr(dom::Element* aElement, const nsAtom* aName, 289 nsAString& aResult); 290 static const nsAttrValue* GetARIAAttr(dom::Element* aElement, 291 const nsAtom* aName); 292 static bool GetARIAElementsAttr(dom::Element* aElement, nsAtom* aName, 293 nsTArray<dom::Element*>& aElements); 294 static bool ARIAAttrValueIs(dom::Element* aElement, const nsAtom* aName, 295 const nsAString& aValue, 296 nsCaseTreatment aCaseSensitive); 297 static bool ARIAAttrValueIs(dom::Element* aElement, const nsAtom* aName, 298 const nsAtom* aValue, 299 nsCaseTreatment aCaseSensitive); 300 static int32_t FindARIAAttrValueIn(dom::Element* aElement, 301 const nsAtom* aName, 302 AttrArray::AttrValuesArray* aValues, 303 nsCaseTreatment aCaseSensitive); 304 305 static bool IsEditableARIACombobox(const LocalAccessible* aAccessible); 306 307 /** 308 * Return true if the CSS positioned target of an anchor is a valid details 309 * related accessible. 310 */ 311 static bool IsValidDetailsTargetForAnchor(const Accessible* aDetails, 312 const Accessible* aTarget); 313 }; 314 315 } // namespace a11y 316 } // namespace mozilla 317 318 #endif