accessible/base/nsAccUtils.h

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