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 "AccessibleOrProxy.h"
  13 #include "nsAccessibilityService.h"
  14 #include "nsCoreUtils.h"
  15
  16 #include "nsIDocShell.h"
  17 #include "nsPoint.h"
  18
  19 namespace mozilla {
  20
  21 class PresShell;
  22
  23 namespace dom {
  24 class Element;
  25 }
  26
  27 namespace a11y {
  28
  29 class HyperTextAccessible;
  30 class DocAccessible;
  31 class Attribute;
  32
  33 class nsAccUtils {
  34  public:
  35   /**
  36    * Returns value of attribute from the given attributes container.
  37    *
  38    * @param aAttributes - attributes container
  39    * @param aAttrName - the name of requested attribute
  40    * @param aAttrValue - value of attribute
  41    */
  42   static void GetAccAttr(nsIPersistentProperties* aAttributes,
  43                          nsAtom* aAttrName, nsAString& aAttrValue);
  44
  45   /**
  46    * Set value of attribute for the given attributes container.
  47    *
  48    * @param aAttributes - attributes container
  49    * @param aAttrName - the name of requested attribute
  50    * @param aAttrValue - new value of attribute
  51    */
  52   static void SetAccAttr(nsIPersistentProperties* aAttributes,
  53                          nsAtom* aAttrName, const nsAString& aAttrValue);
  54
  55   static void SetAccAttr(nsIPersistentProperties* aAttributes,
  56                          nsAtom* aAttrName, nsAtom* aAttrValue);
  57
  58   /**
  59    * Set group attributes ('level', 'setsize', 'posinset').
  60    */
  61   static void SetAccGroupAttrs(nsIPersistentProperties* aAttributes,
  62                                int32_t aLevel, int32_t aSetSize,
  63                                int32_t aPosInSet);
  64
  65   /**
  66    * Get default value of the level for the given accessible.
  67    */
  68   static int32_t GetDefaultLevel(const LocalAccessible* aAcc);
  69
  70   /**
  71    * Return ARIA level value or the default one if ARIA is missed for the
  72    * given accessible.
  73    */
  74   static int32_t GetARIAOrDefaultLevel(const LocalAccessible* aAccessible);
  75
  76   /**
  77    * Compute group level for nsIDOMXULContainerItemElement node.
  78    */
  79   static int32_t GetLevelForXULContainerItem(nsIContent* aContent);
  80
  81   /**
  82    * Set container-foo live region attributes for the given node.
  83    *
  84    * @param aAttributes    where to store the attributes
  85    * @param aStartContent  node to start from
  86    */
  87   static void SetLiveContainerAttributes(nsIPersistentProperties* aAttributes,
  88                                          nsIContent* aStartContent);
  89
  90   /**
  91    * Any ARIA property of type boolean or NMTOKEN is undefined if the ARIA
  92    * property is not present, or is "" or "undefined". Do not call
  93    * this method for properties of type string, decimal, IDREF or IDREFS.
  94    *
  95    * Return true if the ARIA property is defined, otherwise false
  96    */
  97   static bool HasDefinedARIAToken(nsIContent* aContent, nsAtom* aAtom);
  98
  99   /**
 100    * Return atomic value of ARIA attribute of boolean or NMTOKEN type.
 101    */
 102   static nsStaticAtom* GetARIAToken(mozilla::dom::Element* aElement,
 103                                     nsAtom* aAttr);
 104
 105   /**
 106    * If the given ARIA attribute has a specific known token value, return it.
 107    * If the specification demands for a fallback value for unknown attribute
 108    * values, return that. For all others, return a nullptr.
 109    */
 110   static nsStaticAtom* NormalizeARIAToken(mozilla::dom::Element* aElement,
 111                                           nsAtom* aAttr);
 112
 113   /**
 114    * Return document accessible for the given DOM node.
 115    */
 116   static DocAccessible* GetDocAccessibleFor(nsINode* aNode) {
 117     return GetAccService()->GetDocAccessible(
 118         nsCoreUtils::GetPresShellFor(aNode));
 119   }
 120
 121   /**
 122    * Return document accessible for the given docshell.
 123    */
 124   static DocAccessible* GetDocAccessibleFor(nsIDocShellTreeItem* aContainer) {
 125     nsCOMPtr<nsIDocShell> docShell(do_QueryInterface(aContainer));
 126     return GetAccService()->GetDocAccessible(docShell->GetPresShell());
 127   }
 128
 129   /**
 130    * Return single or multi selectable container for the given item.
 131    *
 132    * @param  aAccessible  [in] the item accessible
 133    * @param  aState       [in] the state of the item accessible
 134    */
 135   static LocalAccessible* GetSelectableContainer(LocalAccessible* aAccessible,
 136                                                  uint64_t aState);
 137
 138   /**
 139    * Return a text container accessible for the given node.
 140    */
 141   static HyperTextAccessible* GetTextContainer(nsINode* aNode);
 142
 143   static LocalAccessible* TableFor(LocalAccessible* aRow);
 144
 145   /**
 146    * Return true if the DOM node of a given accessible has a given attribute
 147    * with a value of "true".
 148    */
 149   static bool IsDOMAttrTrue(const LocalAccessible* aAccessible, nsAtom* aAttr);
 150
 151   /**
 152    * Return true if the DOM node of given accessible has aria-selected="true"
 153    * attribute.
 154    */
 155   static inline bool IsARIASelected(const LocalAccessible* aAccessible) {
 156     return IsDOMAttrTrue(aAccessible, nsGkAtoms::aria_selected);
 157   }
 158
 159   /**
 160    * Return true if the DOM node of given accessible has
 161    * aria-multiselectable="true" attribute.
 162    */
 163   static inline bool IsARIAMultiSelectable(const LocalAccessible* aAccessible) {
 164     return IsDOMAttrTrue(aAccessible, nsGkAtoms::aria_multiselectable);
 165   }
 166
 167   /**
 168    * Converts the given coordinates to coordinates relative screen.
 169    *
 170    * @param aX               [in] the given x coord
 171    * @param aY               [in] the given y coord
 172    * @param aCoordinateType  [in] specifies coordinates origin (refer to
 173    *                         nsIAccessibleCoordinateType)
 174    * @param aAccessible      [in] the accessible if coordinates are given
 175    *                         relative it.
 176    * @return converted coordinates
 177    */
 178   static nsIntPoint ConvertToScreenCoords(int32_t aX, int32_t aY,
 179                                           uint32_t aCoordinateType,
 180                                           LocalAccessible* aAccessible);
 181
 182   /**
 183    * Converts the given coordinates relative screen to another coordinate
 184    * system.
 185    *
 186    * @param aX               [in, out] the given x coord
 187    * @param aY               [in, out] the given y coord
 188    * @param aCoordinateType  [in] specifies coordinates origin (refer to
 189    *                         nsIAccessibleCoordinateType)
 190    * @param aAccessible      [in] the accessible if coordinates are given
 191    *                         relative it
 192    */
 193   static void ConvertScreenCoordsTo(int32_t* aX, int32_t* aY,
 194                                     uint32_t aCoordinateType,
 195                                     LocalAccessible* aAccessible);
 196
 197   /**
 198    * Returns coordinates relative screen for the parent of the given accessible.
 199    *
 200    * @param [in] aAccessible  the accessible
 201    */
 202   static nsIntPoint GetScreenCoordsForParent(LocalAccessible* aAccessible);
 203
 204   /**
 205    * Get the 'live' or 'container-live' object attribute value from the given
 206    * ELiveAttrRule constant.
 207    *
 208    * @param  aRule   [in] rule constant (see ELiveAttrRule in nsAccMap.h)
 209    * @param  aValue  [out] object attribute value
 210    *
 211    * @return         true if object attribute should be exposed
 212    */
 213   static bool GetLiveAttrValue(uint32_t aRule, nsAString& aValue);
 214
 215 #ifdef DEBUG
 216   /**
 217    * Detect whether the given accessible object implements nsIAccessibleText,
 218    * when it is text or has text child node.
 219    */
 220   static bool IsTextInterfaceSupportCorrect(LocalAccessible* aAccessible);
 221 #endif
 222
 223   /**
 224    * Return text length of the given accessible, return 0 on failure.
 225    */
 226   static uint32_t TextLength(LocalAccessible* aAccessible);
 227
 228   /**
 229    * Transform nsIAccessibleStates constants to internal state constant.
 230    */
 231   static inline uint64_t To64State(uint32_t aState1, uint32_t aState2) {
 232     return static_cast<uint64_t>(aState1) +
 233            (static_cast<uint64_t>(aState2) << 31);
 234   }
 235
 236   /**
 237    * Transform internal state constant to nsIAccessibleStates constants.
 238    */
 239   static inline void To32States(uint64_t aState64, uint32_t* aState1,
 240                                 uint32_t* aState2) {
 241     *aState1 = aState64 & 0x7fffffff;
 242     if (aState2) *aState2 = static_cast<uint32_t>(aState64 >> 31);
 243   }
 244
 245   static uint32_t To32States(uint64_t aState, bool* aIsExtra) {
 246     uint32_t extraState = aState >> 31;
 247     *aIsExtra = !!extraState;
 248     return aState | extraState;
 249   }
 250
 251   /**
 252    * Return true if the given accessible can't have children. Used when exposing
 253    * to platform accessibility APIs, should the children be pruned off?
 254    */
 255   static bool MustPrune(AccessibleOrProxy aAccessible);
 256
 257   static bool PersistentPropertiesToArray(nsIPersistentProperties* aProps,
 258                                           nsTArray<Attribute>* aAttributes);
 259
 260   /**
 261    * Return true if the given accessible is within an ARIA live region; i.e.
 262    * the container-live attribute would be something other than "off" or empty.
 263    */
 264   static bool IsARIALive(const LocalAccessible* aAccessible);
 265 };
 266
 267 }  // namespace a11y
 268 }  // namespace mozilla
 269
 270 #endif