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