accessible/base/ARIAMap.h

   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 mozilla_a11y_aria_ARIAMap_h_
   9 #define mozilla_a11y_aria_ARIAMap_h_
  10
  11 #include "ARIAStateMap.h"
  12 #include "mozilla/a11y/AccTypes.h"
  13 #include "mozilla/a11y/Role.h"
  14
  15 #include "nsAtom.h"
  16 #include "nsIContent.h"
  17 #include "mozilla/dom/Element.h"
  18
  19 class nsINode;
  20
  21 ////////////////////////////////////////////////////////////////////////////////
  22 // Value constants
  23
  24 /**
  25  * Used to define if role requires to expose Value interface.
  26  */
  27 enum EValueRule {
  28   /**
  29    * Value interface isn't exposed.
  30    */
  31   eNoValue,
  32
  33   /**
  34    * Value interface is implemented, supports value, min and max from
  35    * aria-valuenow, aria-valuemin and aria-valuemax.
  36    */
  37   eHasValueMinMax,
  38
  39   /**
  40    * Value interface is implemented, but only if the element is focusable.
  41    * For instance, in ARIA 1.1 the ability for authors to create adjustable
  42    * splitters was provided by supporting the value interface on separators
  43    * that are focusable. Non-focusable separators expose no value information.
  44    */
  45   eHasValueMinMaxIfFocusable
  46 };
  47
  48 ////////////////////////////////////////////////////////////////////////////////
  49 // Action constants
  50
  51 /**
  52  * Used to define if the role requires to expose action.
  53  */
  54 enum EActionRule {
  55   eNoAction,
  56   eActivateAction,
  57   eClickAction,
  58   ePressAction,
  59   eCheckUncheckAction,
  60   eExpandAction,
  61   eJumpAction,
  62   eOpenCloseAction,
  63   eSelectAction,
  64   eSortAction,
  65   eSwitchAction
  66 };
  67
  68 ////////////////////////////////////////////////////////////////////////////////
  69 // Live region constants
  70
  71 /**
  72  * Used to define if role exposes default value of aria-live attribute.
  73  */
  74 enum ELiveAttrRule { eNoLiveAttr, eOffLiveAttr, ePoliteLiveAttr };
  75
  76 ////////////////////////////////////////////////////////////////////////////////
  77 // Role constants
  78
  79 /**
  80  * ARIA role overrides role from native markup.
  81  */
  82 const bool kUseMapRole = true;
  83
  84 /**
  85  * ARIA role doesn't override the role from native markup.
  86  */
  87 const bool kUseNativeRole = false;
  88
  89 ////////////////////////////////////////////////////////////////////////////////
  90 // ARIA attribute characteristic masks
  91
  92 /**
  93  * This mask indicates the attribute should not be exposed as an object
  94  * attribute via the catch-all logic in Accessible::Attributes().
  95  * This means it either isn't mean't to be exposed as an object attribute, or
  96  * that it should, but is already handled in other code.
  97  */
  98 const uint8_t ATTR_BYPASSOBJ = 0x1 << 0;
  99 const uint8_t ATTR_BYPASSOBJ_IF_FALSE = 0x1 << 1;
 100
 101 /**
 102  * This mask indicates the attribute is expected to have an NMTOKEN or bool
 103  * value. (See for example usage in Accessible::Attributes())
 104  */
 105 const uint8_t ATTR_VALTOKEN = 0x1 << 2;
 106
 107 /**
 108  * Indicate the attribute is global state or property (refer to
 109  * http://www.w3.org/TR/wai-aria/states_and_properties#global_states).
 110  */
 111 const uint8_t ATTR_GLOBAL = 0x1 << 3;
 112
 113 ////////////////////////////////////////////////////////////////////////////////
 114 // State map entry
 115
 116 /**
 117  * Used in nsRoleMapEntry.state if no nsIAccessibleStates are automatic for
 118  * a given role.
 119  */
 120 #define kNoReqStates 0
 121
 122 ////////////////////////////////////////////////////////////////////////////////
 123 // Role map entry
 124
 125 /**
 126  * For each ARIA role, this maps the nsIAccessible information.
 127  */
 128 struct nsRoleMapEntry {
 129   /**
 130    * Return true if matches to the given ARIA role.
 131    */
 132   bool Is(nsAtom* aARIARole) const { return roleAtom == aARIARole; }
 133
 134   /**
 135    * Return true if ARIA role has the given accessible type.
 136    */
 137   bool IsOfType(mozilla::a11y::AccGenericType aType) const {
 138     return accTypes & aType;
 139   }
 140
 141   /**
 142    * Return ARIA role.
 143    */
 144   const nsDependentAtomString ARIARoleString() const {
 145     return nsDependentAtomString(roleAtom);
 146   }
 147
 148   // ARIA role: string representation such as "button"
 149   nsStaticAtom* const roleAtom;
 150
 151   // Role mapping rule: maps to enum Role
 152   mozilla::a11y::role role;
 153
 154   // Role rule: whether to use mapped role or native semantics
 155   bool roleRule;
 156
 157   // Value mapping rule: how to compute accessible value
 158   EValueRule valueRule;
 159
 160   // Action mapping rule, how to expose accessible action
 161   EActionRule actionRule;
 162
 163   // 'live' and 'container-live' object attributes mapping rule: how to expose
 164   // these object attributes if ARIA 'live' attribute is missed.
 165   ELiveAttrRule liveAttRule;
 166
 167   // Accessible types this role belongs to.
 168   uint32_t accTypes;
 169
 170   // Automatic state mapping rule: always include in states
 171   uint64_t state;  // or kNoReqStates if no default state for this role
 172
 173   // ARIA properties supported for this role (in other words, the aria-foo
 174   // attribute to accessible states mapping rules).
 175   // Currently you cannot have unlimited mappings, because
 176   // a variable sized array would not allow the use of
 177   // C++'s struct initialization feature.
 178   mozilla::a11y::aria::EStateRule attributeMap1;
 179   mozilla::a11y::aria::EStateRule attributeMap2;
 180   mozilla::a11y::aria::EStateRule attributeMap3;
 181   mozilla::a11y::aria::EStateRule attributeMap4;
 182 };
 183
 184 ////////////////////////////////////////////////////////////////////////////////
 185 // ARIA map
 186
 187 /**
 188  *  These provide the mappings for WAI-ARIA roles, states and properties using
 189  *  the structs defined in this file and ARIAStateMap files.
 190  */
 191 namespace mozilla {
 192 namespace a11y {
 193 namespace aria {
 194
 195 /**
 196  * Empty role map entry. Used by accessibility service to create an accessible
 197  * if the accessible can't use role of used accessible class. For example,
 198  * it is used for table cells that aren't contained by table.
 199  */
 200 extern nsRoleMapEntry gEmptyRoleMap;
 201
 202 /**
 203  * Constants for the role map entry index to indicate that the role map entry
 204  * isn't in sWAIRoleMaps, but rather is a special entry: nullptr,
 205  * gEmptyRoleMap, and sLandmarkRoleMap
 206  */
 207 const uint8_t NO_ROLE_MAP_ENTRY_INDEX = UINT8_MAX - 2;
 208 const uint8_t EMPTY_ROLE_MAP_ENTRY_INDEX = UINT8_MAX - 1;
 209 const uint8_t LANDMARK_ROLE_MAP_ENTRY_INDEX = UINT8_MAX;
 210
 211 /**
 212  * Get the role map entry for a given DOM node. This will use the first
 213  * ARIA role if the role attribute provides a space delimited list of roles.
 214  *
 215  * @param aEl     [in] the DOM node to get the role map entry for
 216  * @return        a pointer to the role map entry for the ARIA role, or nullptr
 217  *                if none
 218  */
 219 const nsRoleMapEntry* GetRoleMap(dom::Element* aEl);
 220
 221 /**
 222  * Get the role map entry pointer's index for a given DOM node. This will use
 223  * the first ARIA role if the role attribute provides a space delimited list of
 224  * roles.
 225  *
 226  * @param aEl     [in] the DOM node to get the role map entry for
 227  * @return        the index of the pointer to the role map entry for the ARIA
 228  *                role, or NO_ROLE_MAP_ENTRY_INDEX if none
 229  */
 230 uint8_t GetRoleMapIndex(dom::Element* aEl);
 231
 232 /**
 233  * Get the role map entry pointer for a given role map entry index.
 234  *
 235  * @param aRoleMapIndex  [in] the role map index to get the role map entry
 236  *                       pointer for
 237  * @return               a pointer to the role map entry for the ARIA role,
 238  *                       or nullptr, if none
 239  */
 240 const nsRoleMapEntry* GetRoleMapFromIndex(uint8_t aRoleMapIndex);
 241
 242 /**
 243  * Get the role map entry index for a given role map entry pointer. If the role
 244  * map entry is within sWAIRoleMaps, return the index within that array,
 245  * otherwise return one of the special index constants listed above.
 246  *
 247  * @param aRoleMap  [in] the role map entry pointer to get the index for
 248  * @return          the index of the pointer to the role map entry, or
 249  *                  NO_ROLE_MAP_ENTRY_INDEX if none
 250  */
 251 uint8_t GetIndexFromRoleMap(const nsRoleMapEntry* aRoleMap);
 252
 253 /**
 254  * Return accessible state from ARIA universal states applied to the given
 255  * element.
 256  */
 257 uint64_t UniversalStatesFor(mozilla::dom::Element* aElement);
 258
 259 /**
 260  * Get the ARIA attribute characteristics for a given ARIA attribute.
 261  *
 262  * @param aAtom  ARIA attribute
 263  * @return       A bitflag representing the attribute characteristics
 264  *               (see above for possible bit masks, prefixed "ATTR_")
 265  */
 266 uint8_t AttrCharacteristicsFor(nsAtom* aAtom);
 267
 268 /**
 269  * Return true if the element has defined aria-hidden.
 270  */
 271 bool HasDefinedARIAHidden(nsIContent* aContent);
 272
 273 /**
 274  * Represents a simple enumerator for iterating through ARIA attributes
 275  * exposed as object attributes on a given accessible.
 276  */
 277 class AttrIterator {
 278  public:
 279   explicit AttrIterator(nsIContent* aContent)
 280       : mElement(Element::FromNode(aContent)), mAttrIdx(0) {
 281     mAttrCount = mElement ? mElement->GetAttrCount() : 0;
 282   }
 283
 284   bool Next(nsAString& aAttrName, nsAString& aAttrValue);
 285
 286  private:
 287   AttrIterator() = delete;
 288   AttrIterator(const AttrIterator&) = delete;
 289   AttrIterator& operator=(const AttrIterator&) = delete;
 290
 291   dom::Element* mElement;
 292   uint32_t mAttrIdx;
 293   uint32_t mAttrCount;
 294 };
 295
 296 }  // namespace aria
 297 }  // namespace a11y
 298 }  // namespace mozilla
 299
 300 #endif