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