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