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