accessible/basetypes/Accessible.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 _Accessible_H_
   7 #define _Accessible_H_
   8
   9 #include "mozilla/a11y/Role.h"
  10 #include "mozilla/a11y/AccTypes.h"
  11 #include "nsString.h"
  12 #include "nsRect.h"
  13 #include "Units.h"
  14
  15 class nsAtom;
  16 class nsStaticAtom;
  17
  18 struct nsRoleMapEntry;
  19
  20 class nsIURI;
  21
  22 namespace mozilla {
  23 namespace a11y {
  24
  25 class AccAttributes;
  26 class AccGroupInfo;
  27 class HyperTextAccessibleBase;
  28 class LocalAccessible;
  29 class Relation;
  30 enum class RelationType;
  31 class RemoteAccessible;
  32 class TableAccessible;
  33 class TableCellAccessible;
  34
  35 /**
  36  * Name type flags.
  37  */
  38 enum ENameValueFlag {
  39   /**
  40    * Name either
  41    *  a) present (not empty): !name.IsEmpty()
  42    *  b) no name (was missed): name.IsVoid()
  43    */
  44   eNameOK,
  45
  46   /**
  47    * Name was computed from the subtree.
  48    */
  49   eNameFromSubtree,
  50
  51   /**
  52    * Tooltip was used as a name.
  53    */
  54   eNameFromTooltip
  55 };
  56
  57 /**
  58  * Group position (level, position in set and set size).
  59  */
  60 struct GroupPos {
  61   GroupPos() : level(0), posInSet(0), setSize(0) {}
  62   GroupPos(int32_t aLevel, int32_t aPosInSet, int32_t aSetSize)
  63       : level(aLevel), posInSet(aPosInSet), setSize(aSetSize) {}
  64
  65   int32_t level;
  66   int32_t posInSet;
  67   int32_t setSize;
  68 };
  69
  70 /**
  71  * Represent key binding associated with accessible (such as access key and
  72  * global keyboard shortcuts).
  73  */
  74 class KeyBinding {
  75  public:
  76   /**
  77    * Modifier mask values.
  78    */
  79   static const uint32_t kShift = 1;
  80   static const uint32_t kControl = 2;
  81   static const uint32_t kAlt = 4;
  82   static const uint32_t kMeta = 8;
  83   static const uint32_t kOS = 16;
  84
  85   static uint32_t AccelModifier();
  86
  87   KeyBinding() : mKey(0), mModifierMask(0) {}
  88   KeyBinding(uint32_t aKey, uint32_t aModifierMask)
  89       : mKey(aKey), mModifierMask(aModifierMask) {}
  90   explicit KeyBinding(uint64_t aSerialized) : mSerialized(aSerialized) {}
  91
  92   inline bool IsEmpty() const { return !mKey; }
  93   inline uint32_t Key() const { return mKey; }
  94   inline uint32_t ModifierMask() const { return mModifierMask; }
  95
  96   /**
  97    * Serialize this KeyBinding to a uint64_t for use in the parent process
  98    * cache. This is simpler than custom IPDL serialization for this simple case.
  99    */
 100   uint64_t Serialize() { return mSerialized; }
 101
 102   enum Format { ePlatformFormat, eAtkFormat };
 103
 104   /**
 105    * Return formatted string for this key binding depending on the given format.
 106    */
 107   inline void ToString(nsAString& aValue,
 108                        Format aFormat = ePlatformFormat) const {
 109     aValue.Truncate();
 110     AppendToString(aValue, aFormat);
 111   }
 112   inline void AppendToString(nsAString& aValue,
 113                              Format aFormat = ePlatformFormat) const {
 114     if (mKey) {
 115       if (aFormat == ePlatformFormat) {
 116         ToPlatformFormat(aValue);
 117       } else {
 118         ToAtkFormat(aValue);
 119       }
 120     }
 121   }
 122
 123  private:
 124   void ToPlatformFormat(nsAString& aValue) const;
 125   void ToAtkFormat(nsAString& aValue) const;
 126
 127   union {
 128     struct {
 129       uint32_t mKey;
 130       uint32_t mModifierMask;
 131     };
 132     uint64_t mSerialized;
 133   };
 134 };
 135
 136 /**
 137  * The base type for an accessibility tree node. Methods and attributes in this
 138  * class are available in both the content process and the parent process.
 139  * Overrides for these methods live primarily in LocalAccessible and
 140  * RemoteAccessibleBase.
 141  */
 142 class Accessible {
 143  protected:
 144   Accessible();
 145
 146   Accessible(AccType aType, AccGenericType aGenericTypes,
 147              uint8_t aRoleMapEntryIndex);
 148
 149  public:
 150   /**
 151    * Return an id for this Accessible which is unique within the document.
 152    * Use nsAccUtils::GetAccessibleByID to retrieve an Accessible given an id
 153    * returned from this method.
 154    */
 155   virtual uint64_t ID() const = 0;
 156
 157   virtual Accessible* Parent() const = 0;
 158
 159   virtual role Role() const = 0;
 160
 161   /**
 162    * Return child accessible at the given index.
 163    */
 164   virtual Accessible* ChildAt(uint32_t aIndex) const = 0;
 165
 166   virtual Accessible* NextSibling() const = 0;
 167   virtual Accessible* PrevSibling() const = 0;
 168
 169   virtual uint32_t ChildCount() const = 0;
 170
 171   virtual int32_t IndexInParent() const = 0;
 172
 173   bool HasChildren() const { return !!FirstChild(); }
 174
 175   inline Accessible* FirstChild() const {
 176     return ChildCount() ? ChildAt(0) : nullptr;
 177   }
 178
 179   inline Accessible* LastChild() const {
 180     uint32_t childCount = ChildCount();
 181     return childCount ? ChildAt(childCount - 1) : nullptr;
 182   }
 183
 184   /**
 185    * Return true if this Accessible is before another Accessible in the tree.
 186    */
 187   bool IsBefore(const Accessible* aAcc) const;
 188
 189   bool IsAncestorOf(const Accessible* aAcc) const {
 190     for (const Accessible* parent = aAcc->Parent(); parent;
 191          parent = parent->Parent()) {
 192       if (parent == this) {
 193         return true;
 194       }
 195     }
 196     return false;
 197   }
 198
 199   /**
 200    * Used by ChildAtPoint() method to get direct or deepest child at point.
 201    */
 202   enum class EWhichChildAtPoint { DirectChild, DeepestChild };
 203
 204   virtual Accessible* ChildAtPoint(int32_t aX, int32_t aY,
 205                                    EWhichChildAtPoint aWhichChild) = 0;
 206
 207   /**
 208    * Return the focused child if any.
 209    */
 210   virtual Accessible* FocusedChild();
 211
 212   /**
 213    * Return ARIA role map if any.
 214    */
 215   const nsRoleMapEntry* ARIARoleMap() const;
 216
 217   /**
 218    * Return true if ARIA role is specified on the element.
 219    */
 220   bool HasARIARole() const;
 221   bool IsARIARole(nsAtom* aARIARole) const;
 222   bool HasStrongARIARole() const;
 223
 224   /**
 225    * Return true if the accessible belongs to the given accessible type.
 226    */
 227   bool HasGenericType(AccGenericType aType) const;
 228
 229   /**
 230    * Return group position (level, position in set and set size).
 231    */
 232   virtual GroupPos GroupPosition();
 233
 234   /**
 235    * Return embedded accessible children count.
 236    */
 237   virtual uint32_t EmbeddedChildCount() = 0;
 238
 239   /**
 240    * Return embedded accessible child at the given index.
 241    */
 242   virtual Accessible* EmbeddedChildAt(uint32_t aIndex) = 0;
 243
 244   /**
 245    * Return index of the given embedded accessible child.
 246    */
 247   virtual int32_t IndexOfEmbeddedChild(Accessible* aChild) = 0;
 248
 249   // Methods that potentially access a cache.
 250
 251   /*
 252    * Get the name of this accessible.
 253    */
 254   virtual ENameValueFlag Name(nsString& aName) const = 0;
 255
 256   /*
 257    * Get the description of this accessible.
 258    */
 259   virtual void Description(nsString& aDescription) const = 0;
 260
 261   /**
 262    * Get the value of this accessible.
 263    */
 264   virtual void Value(nsString& aValue) const = 0;
 265
 266   virtual double CurValue() const = 0;
 267   virtual double MinValue() const = 0;
 268   virtual double MaxValue() const = 0;
 269   virtual double Step() const = 0;
 270   virtual bool SetCurValue(double aValue) = 0;
 271
 272   /**
 273    * Return boundaries in screen coordinates in device pixels.
 274    */
 275   virtual LayoutDeviceIntRect Bounds() const = 0;
 276
 277   /**
 278    * Return boundaries in screen coordinates in app units.
 279    */
 280   virtual nsRect BoundsInAppUnits() const = 0;
 281
 282   /**
 283    * Return boundaries in screen coordinates in CSS pixels.
 284    */
 285   virtual nsIntRect BoundsInCSSPixels() const;
 286
 287   /**
 288    * Returns text of accessible if accessible has text role otherwise empty
 289    * string.
 290    *
 291    * @param aText         [in] returned text of the accessible
 292    * @param aStartOffset  [in, optional] start offset inside of the accessible,
 293    *                        if missed entire text is appended
 294    * @param aLength       [in, optional] required length of text, if missed
 295    *                        then text from start offset till the end is appended
 296    */
 297   virtual void AppendTextTo(nsAString& aText, uint32_t aStartOffset = 0,
 298                             uint32_t aLength = UINT32_MAX) = 0;
 299
 300   /**
 301    * Return all states of accessible (including ARIA states).
 302    */
 303   virtual uint64_t State() = 0;
 304
 305   /**
 306    * Return the start offset of the embedded object within the parent
 307    * HyperTextAccessibleBase.
 308    */
 309   virtual uint32_t StartOffset();
 310
 311   /**
 312    * Return the end offset of the link within the parent
 313    * HyperTextAccessibleBase.
 314    */
 315   virtual uint32_t EndOffset();
 316
 317   /**
 318    * Return object attributes for the accessible.
 319    */
 320   virtual already_AddRefed<AccAttributes> Attributes() = 0;
 321
 322   virtual already_AddRefed<nsAtom> DisplayStyle() const = 0;
 323
 324   virtual float Opacity() const = 0;
 325
 326   /**
 327    * Get the live region attributes (if any) for this single Accessible. This
 328    * does not propagate attributes from ancestors. If any argument is null, that
 329    * attribute is not fetched.
 330    */
 331   virtual void LiveRegionAttributes(nsAString* aLive, nsAString* aRelevant,
 332                                     Maybe<bool>* aAtomic,
 333                                     nsAString* aBusy) const = 0;
 334
 335   /**
 336    * Get the aria-selected state. aria-selected not being specified is not
 337    * always the same as aria-selected="false". If not specified, Nothing() will
 338    * be returned.
 339    */
 340   virtual Maybe<bool> ARIASelected() const = 0;
 341
 342   LayoutDeviceIntSize Size() const;
 343
 344   LayoutDeviceIntPoint Position(uint32_t aCoordType);
 345
 346   virtual Maybe<int32_t> GetIntARIAAttr(nsAtom* aAttrName) const = 0;
 347
 348   /**
 349    * Get the relation of the given type.
 350    */
 351   virtual Relation RelationByType(RelationType aType) const = 0;
 352
 353   /**
 354    * Get the language associated with the accessible.
 355    */
 356   virtual void Language(nsAString& aLocale) = 0;
 357
 358   /**
 359    * Get the role of this Accessible as an ARIA role token. This might have been
 360    * set explicitly (e.g. role="button") or it might be implicit in native
 361    * markup (e.g. <button> returns "button").
 362    */
 363   nsStaticAtom* ComputedARIARole() const;
 364
 365   // Methods that interact with content.
 366
 367   virtual void TakeFocus() const = 0;
 368
 369   /**
 370    * Scroll the accessible into view.
 371    */
 372   MOZ_CAN_RUN_SCRIPT
 373   virtual void ScrollTo(uint32_t aHow) const = 0;
 374
 375   /**
 376    * Scroll the accessible to the given point.
 377    */
 378   virtual void ScrollToPoint(uint32_t aCoordinateType, int32_t aX,
 379                              int32_t aY) = 0;
 380
 381   /**
 382    * Return tag name of associated DOM node.
 383    */
 384   virtual nsAtom* TagName() const = 0;
 385
 386   /**
 387    * Return input `type` attribute
 388    */
 389   virtual already_AddRefed<nsAtom> InputType() const = 0;
 390
 391   /**
 392    * Return a landmark role if applied.
 393    */
 394   nsStaticAtom* LandmarkRole() const;
 395
 396   /**
 397    * Return the id of the dom node this accessible represents.
 398    */
 399   virtual void DOMNodeID(nsString& aID) const = 0;
 400
 401   //////////////////////////////////////////////////////////////////////////////
 402   // ActionAccessible
 403
 404   /**
 405    * Return the number of actions that can be performed on this accessible.
 406    */
 407   virtual uint8_t ActionCount() const = 0;
 408
 409   /**
 410    * Return action name at given index.
 411    */
 412   virtual void ActionNameAt(uint8_t aIndex, nsAString& aName) = 0;
 413
 414   /**
 415    * Default to localized action name.
 416    */
 417   void ActionDescriptionAt(uint8_t aIndex, nsAString& aDescription) {
 418     nsAutoString name;
 419     ActionNameAt(aIndex, name);
 420     TranslateString(name, aDescription);
 421   }
 422
 423   /**
 424    * Invoke the accessible action.
 425    */
 426   virtual bool DoAction(uint8_t aIndex) const = 0;
 427
 428   /**
 429    * Return access key, such as Alt+D.
 430    */
 431   virtual KeyBinding AccessKey() const = 0;
 432
 433   //////////////////////////////////////////////////////////////////////////////
 434   // SelectAccessible
 435
 436   /**
 437    * Return an array of selected items.
 438    */
 439   virtual void SelectedItems(nsTArray<Accessible*>* aItems) = 0;
 440
 441   /**
 442    * Return the number of selected items.
 443    */
 444   virtual uint32_t SelectedItemCount() = 0;
 445
 446   /**
 447    * Return selected item at the given index.
 448    */
 449   virtual Accessible* GetSelectedItem(uint32_t aIndex) = 0;
 450
 451   /**
 452    * Determine if item at the given index is selected.
 453    */
 454   virtual bool IsItemSelected(uint32_t aIndex) = 0;
 455
 456   /**
 457    * Add item at the given index the selection. Return true if success.
 458    */
 459   virtual bool AddItemToSelection(uint32_t aIndex) = 0;
 460
 461   /**
 462    * Remove item at the given index from the selection. Return if success.
 463    */
 464   virtual bool RemoveItemFromSelection(uint32_t aIndex) = 0;
 465
 466   /**
 467    * Select all items. Return true if success.
 468    */
 469   virtual bool SelectAll() = 0;
 470
 471   /**
 472    * Unselect all items. Return true if success.
 473    */
 474   virtual bool UnselectAll() = 0;
 475
 476   virtual void TakeSelection() = 0;
 477
 478   virtual void SetSelected(bool aSelect) = 0;
 479
 480   // Type "is" methods
 481
 482   bool IsDoc() const { return HasGenericType(eDocument); }
 483
 484   bool IsTableRow() const { return HasGenericType(eTableRow); }
 485
 486   bool IsTableCell() const {
 487     // The eTableCell type defined in the ARIA map is used in
 488     // nsAccessibilityService::CreateAccessible to specify when
 489     // ARIAGridCellAccessible should be used for object creation. However, an
 490     // invalid table structure might cause this class not to be used after all.
 491     // To make sure we're really dealing with a cell, only check the generic
 492     // type defined by the class, not the type defined in the ARIA map.
 493     return mGenericTypes & eTableCell;
 494   }
 495
 496   bool IsTable() const { return HasGenericType(eTable); }
 497
 498   bool IsHyperText() const { return HasGenericType(eHyperText); }
 499
 500   bool IsSelect() const { return HasGenericType(eSelect); }
 501
 502   bool IsActionable() const { return HasGenericType(eActionable); }
 503
 504   bool IsText() const { return mGenericTypes & eText; }
 505
 506   bool IsImage() const { return mType == eImageType; }
 507
 508   bool IsApplication() const { return mType == eApplicationType; }
 509
 510   bool IsAlert() const { return HasGenericType(eAlert); }
 511
 512   bool IsButton() const { return HasGenericType(eButton); }
 513
 514   bool IsCombobox() const { return HasGenericType(eCombobox); }
 515
 516   virtual bool IsLink() const = 0;
 517
 518   /**
 519    * Return true if the used ARIA role (if any) allows the hypertext accessible
 520    * to expose text interfaces.
 521    */
 522   bool IsTextRole();
 523
 524   bool IsGenericHyperText() const { return mType == eHyperTextType; }
 525
 526   bool IsHTMLBr() const { return mType == eHTMLBRType; }
 527   bool IsHTMLCaption() const { return mType == eHTMLCaptionType; }
 528   bool IsHTMLCombobox() const { return mType == eHTMLComboboxType; }
 529   bool IsHTMLFileInput() const { return mType == eHTMLFileInputType; }
 530
 531   bool IsHTMLListItem() const { return mType == eHTMLLiType; }
 532
 533   bool IsHTMLLink() const { return mType == eHTMLLinkType; }
 534
 535   bool IsHTMLOptGroup() const { return mType == eHTMLOptGroupType; }
 536
 537   bool IsHTMLRadioButton() const { return mType == eHTMLRadioButtonType; }
 538
 539   bool IsHTMLTable() const { return mType == eHTMLTableType; }
 540   bool IsHTMLTableCell() const { return mType == eHTMLTableCellType; }
 541   bool IsHTMLTableRow() const { return mType == eHTMLTableRowType; }
 542
 543   bool IsImageMap() const { return mType == eImageMapType; }
 544
 545   bool IsList() const { return HasGenericType(eList); }
 546
 547   bool IsListControl() const { return HasGenericType(eListControl); }
 548
 549   bool IsMenuButton() const { return HasGenericType(eMenuButton); }
 550
 551   bool IsMenuPopup() const { return mType == eMenuPopupType; }
 552
 553   bool IsOuterDoc() const { return mType == eOuterDocType; }
 554
 555   bool IsProgress() const { return mType == eProgressType; }
 556
 557   bool IsRoot() const { return mType == eRootType; }
 558
 559   bool IsPassword() const { return mType == eHTMLTextPasswordFieldType; }
 560
 561   bool IsTextLeaf() const { return mType == eTextLeafType; }
 562
 563   bool IsXULLabel() const { return mType == eXULLabelType; }
 564
 565   bool IsXULListItem() const { return mType == eXULListItemType; }
 566
 567   bool IsXULTabpanels() const { return mType == eXULTabpanelsType; }
 568
 569   bool IsXULTooltip() const { return mType == eXULTooltipType; }
 570
 571   bool IsXULTree() const { return mType == eXULTreeType; }
 572
 573   bool IsAutoCompletePopup() const {
 574     return HasGenericType(eAutoCompletePopup);
 575   }
 576
 577   bool IsTextField() const {
 578     return mType == eHTMLTextFieldType || mType == eHTMLTextPasswordFieldType;
 579   }
 580
 581   bool IsDateTimeField() const { return mType == eHTMLDateTimeFieldType; }
 582
 583   bool IsSearchbox() const;
 584
 585   virtual bool HasNumericValue() const = 0;
 586
 587   /**
 588    * Returns true if this is a generic container element that has no meaning on
 589    * its own.
 590    */
 591   bool IsGeneric() const {
 592     role accRole = Role();
 593     return accRole == roles::TEXT || accRole == roles::TEXT_CONTAINER ||
 594            accRole == roles::SECTION;
 595   }
 596
 597   /**
 598    * Returns the nearest ancestor which is not a generic element.
 599    */
 600   Accessible* GetNonGenericParent() const {
 601     for (Accessible* parent = Parent(); parent; parent = parent->Parent()) {
 602       if (!parent->IsGeneric()) {
 603         return parent;
 604       }
 605     }
 606     return nullptr;
 607   }
 608
 609   /**
 610    * Returns true if the accessible is non-interactive.
 611    */
 612   bool IsNonInteractive() const {
 613     if (IsGeneric()) {
 614       return true;
 615     }
 616     const role accRole = Role();
 617     return accRole == role::LANDMARK || accRole == role::REGION;
 618   }
 619
 620   /**
 621    * Return true if the link is valid (e. g. points to a valid URL).
 622    */
 623   bool IsLinkValid();
 624
 625   /**
 626    * Return the number of anchors within the link.
 627    */
 628   uint32_t AnchorCount();
 629
 630   /**
 631    * Returns an anchor URI at the given index.
 632    */
 633   virtual already_AddRefed<nsIURI> AnchorURIAt(uint32_t aAnchorIndex) const;
 634
 635   /**
 636    * Returns an anchor accessible at the given index.
 637    */
 638   Accessible* AnchorAt(uint32_t aAnchorIndex) const;
 639
 640   // Remote/Local types
 641
 642   virtual bool IsRemote() const = 0;
 643   RemoteAccessible* AsRemote();
 644
 645   bool IsLocal() const { return !IsRemote(); }
 646   LocalAccessible* AsLocal();
 647
 648   virtual HyperTextAccessibleBase* AsHyperTextBase() { return nullptr; }
 649
 650   virtual TableAccessible* AsTable() { return nullptr; }
 651   virtual TableCellAccessible* AsTableCell() { return nullptr; }
 652
 653 #ifdef A11Y_LOG
 654   /**
 655    * Provide a human readable description of the accessible,
 656    * including memory address, role, name, DOM tag and DOM ID.
 657    */
 658   void DebugDescription(nsCString& aDesc) const;
 659
 660   static void DebugPrint(const char* aPrefix, const Accessible* aAccessible);
 661 #endif
 662
 663   /**
 664    * Return the localized string for the given key.
 665    */
 666   static void TranslateString(const nsString& aKey, nsAString& aStringOut);
 667
 668  protected:
 669   // Some abstracted group utility methods.
 670
 671   /**
 672    * Get ARIA group attributes.
 673    */
 674   virtual void ARIAGroupPosition(int32_t* aLevel, int32_t* aSetSize,
 675                                  int32_t* aPosInSet) const = 0;
 676
 677   /**
 678    * Return group info if there is an up-to-date version.
 679    */
 680   virtual AccGroupInfo* GetGroupInfo() const = 0;
 681
 682   /**
 683    * Return group info or create and update.
 684    */
 685   virtual AccGroupInfo* GetOrCreateGroupInfo() = 0;
 686
 687   /*
 688    * Return calculated group level based on accessible hierarchy.
 689    *
 690    * @param aFast  [in] Don't climb up tree. Calculate level from aria and
 691    *                    roles.
 692    */
 693   virtual int32_t GetLevel(bool aFast) const;
 694
 695   /**
 696    * Calculate position in group and group size ('posinset' and 'setsize') based
 697    * on accessible hierarchy.
 698    *
 699    * @param  aPosInSet  [out] accessible position in the group
 700    * @param  aSetSize   [out] the group size
 701    */
 702   virtual void GetPositionAndSetSize(int32_t* aPosInSet, int32_t* aSetSize);
 703
 704   /**
 705    * Return the nearest ancestor that has a primary action, or null.
 706    */
 707   const Accessible* ActionAncestor() const;
 708
 709   /**
 710    * Return true if accessible has a primary action directly related to it, like
 711    * "click", "activate", "press", "jump", "open", "close", etc. A non-primary
 712    * action would be a complementary one like "showlongdesc".
 713    * If an accessible has an action that is associated with an ancestor, it is
 714    * not a primary action either.
 715    */
 716   virtual bool HasPrimaryAction() const = 0;
 717
 718   /**
 719    * Apply states which are implied by other information common to both
 720    * LocalAccessible and RemoteAccessible.
 721    */
 722   void ApplyImplicitState(uint64_t& aState) const;
 723
 724  private:
 725   static const uint8_t kTypeBits = 6;
 726   static const uint8_t kGenericTypesBits = 18;
 727
 728   void StaticAsserts() const;
 729
 730  protected:
 731   uint32_t mType : kTypeBits;
 732   uint32_t mGenericTypes : kGenericTypesBits;
 733   uint8_t mRoleMapEntryIndex;
 734
 735   friend class DocAccessibleChild;
 736   friend class AccGroupInfo;
 737 };
 738
 739 }  // namespace a11y
 740 }  // namespace mozilla
 741
 742 #endif