accessible/base/nsAccessibilityService.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 __nsAccessibilityService_h__
   7 #define __nsAccessibilityService_h__
   8
   9 #include "mozilla/a11y/DocManager.h"
  10 #include "mozilla/a11y/FocusManager.h"
  11 #include "mozilla/a11y/Platform.h"
  12 #include "mozilla/a11y/Role.h"
  13 #include "mozilla/a11y/SelectionManager.h"
  14 #include "mozilla/Preferences.h"
  15
  16 #include "nsAtomHashKeys.h"
  17 #include "nsIContent.h"
  18 #include "nsIObserver.h"
  19 #include "nsIAccessibleEvent.h"
  20 #include "nsIEventListenerService.h"
  21 #include "nsXULAppAPI.h"
  22 #include "xpcAccessibilityService.h"
  23
  24 class nsImageFrame;
  25 class nsIArray;
  26 class nsITreeView;
  27
  28 namespace mozilla {
  29
  30 class PresShell;
  31 class Monitor;
  32 namespace dom {
  33 class DOMStringList;
  34 class Element;
  35 }  // namespace dom
  36
  37 namespace a11y {
  38
  39 class AccAttributes;
  40 class Accessible;
  41 class ApplicationAccessible;
  42 class xpcAccessibleApplication;
  43
  44 /**
  45  * Return focus manager.
  46  */
  47 FocusManager* FocusMgr();
  48
  49 /**
  50  * Return selection manager.
  51  */
  52 SelectionManager* SelectionMgr();
  53
  54 /**
  55  * Returns the application accessible.
  56  */
  57 ApplicationAccessible* ApplicationAcc();
  58 xpcAccessibleApplication* XPCApplicationAcc();
  59
  60 typedef LocalAccessible*(New_Accessible)(mozilla::dom::Element* aElement,
  61                                          LocalAccessible* aContext);
  62
  63 // These fields are not `nsStaticAtom* const` because MSVC doesn't like it.
  64 struct MarkupAttrInfo {
  65   nsStaticAtom* name;
  66   nsStaticAtom* value;
  67
  68   nsStaticAtom* DOMAttrName;
  69   nsStaticAtom* DOMAttrValue;
  70 };
  71
  72 struct MarkupMapInfo {
  73   nsStaticAtom* const tag;
  74   New_Accessible* new_func;
  75   a11y::role role;
  76   MarkupAttrInfo attrs[4];
  77 };
  78
  79 struct XULMarkupMapInfo {
  80   nsStaticAtom* const tag;
  81   New_Accessible* new_func;
  82 };
  83
  84 /**
  85  * PREF_ACCESSIBILITY_FORCE_DISABLED preference change callback.
  86  */
  87 void PrefChanged(const char* aPref, void* aClosure);
  88
  89 /**
  90  * Read and normalize PREF_ACCESSIBILITY_FORCE_DISABLED preference.
  91  */
  92 EPlatformDisabledState ReadPlatformDisabledState();
  93
  94 }  // namespace a11y
  95 }  // namespace mozilla
  96
  97 class nsAccessibilityService final : public mozilla::a11y::DocManager,
  98                                      public mozilla::a11y::FocusManager,
  99                                      public mozilla::a11y::SelectionManager,
 100                                      public nsIListenerChangeListener,
 101                                      public nsIObserver {
 102  public:
 103   typedef mozilla::a11y::LocalAccessible LocalAccessible;
 104   typedef mozilla::a11y::DocAccessible DocAccessible;
 105
 106   // nsIListenerChangeListener
 107   NS_IMETHOD ListenersChanged(nsIArray* aEventChanges) override;
 108
 109  protected:
 110   ~nsAccessibilityService();
 111
 112  public:
 113   NS_DECL_ISUPPORTS_INHERITED
 114   NS_DECL_NSIOBSERVER
 115
 116   LocalAccessible* GetRootDocumentAccessible(mozilla::PresShell* aPresShell,
 117                                              bool aCanCreate);
 118
 119   /**
 120    * Adds/remove ATK root accessible for gtk+ native window to/from children
 121    * of the application accessible.
 122    */
 123   LocalAccessible* AddNativeRootAccessible(void* aAtkAccessible);
 124   void RemoveNativeRootAccessible(LocalAccessible* aRootAccessible);
 125
 126   bool HasAccessible(nsINode* aDOMNode);
 127
 128   /**
 129    * Get a string equivalent for an accessible role value.
 130    */
 131   void GetStringRole(uint32_t aRole, nsAString& aString);
 132
 133   /**
 134    * Get a string equivalent for an accessible state/extra state.
 135    */
 136   already_AddRefed<mozilla::dom::DOMStringList> GetStringStates(
 137       uint64_t aStates) const;
 138   void GetStringStates(uint32_t aState, uint32_t aExtraState,
 139                        nsISupports** aStringStates);
 140
 141   /**
 142    * Get a string equivalent for an accessible event value.
 143    */
 144   void GetStringEventType(uint32_t aEventType, nsAString& aString);
 145
 146   /**
 147    * Get a string equivalent for an accessible event value.
 148    */
 149   void GetStringEventType(uint32_t aEventType, nsACString& aString);
 150
 151   /**
 152    * Get a string equivalent for an accessible relation type.
 153    */
 154   void GetStringRelationType(uint32_t aRelationType, nsAString& aString);
 155
 156   // nsAccesibilityService
 157   /**
 158    * Notification used to update the accessible tree when new content is
 159    * inserted.
 160    */
 161   void ContentRangeInserted(mozilla::PresShell* aPresShell,
 162                             nsIContent* aStartChild, nsIContent* aEndChild);
 163
 164   /**
 165    * Triggers a re-evaluation of the a11y tree of aContent after the next
 166    * refresh. This is important because whether we create accessibles may
 167    * depend on the frame tree / style.
 168    */
 169   void ScheduleAccessibilitySubtreeUpdate(mozilla::PresShell* aPresShell,
 170                                           nsIContent* aStartChild);
 171
 172   /**
 173    * Notification used to update the accessible tree when content is removed.
 174    */
 175   void ContentRemoved(mozilla::PresShell* aPresShell, nsIContent* aChild);
 176
 177   /**
 178    * Notification used to invalidate the isLayoutTable cache.
 179    */
 180   void TableLayoutGuessMaybeChanged(mozilla::PresShell* aPresShell,
 181                                     nsIContent* aContent);
 182
 183   /**
 184    * Notifies when a combobox <option> text or label changes.
 185    */
 186   void ComboboxOptionMaybeChanged(mozilla::PresShell*,
 187                                   nsIContent* aMutatingNode);
 188
 189   void UpdateText(mozilla::PresShell* aPresShell, nsIContent* aContent);
 190
 191   /**
 192    * Update XUL:tree accessible tree when treeview is changed.
 193    */
 194   void TreeViewChanged(mozilla::PresShell* aPresShell, nsIContent* aContent,
 195                        nsITreeView* aView);
 196
 197   /**
 198    * Notify of input@type="element" value change.
 199    */
 200   void RangeValueChanged(mozilla::PresShell* aPresShell, nsIContent* aContent);
 201
 202   /**
 203    * Update the image map.
 204    */
 205   void UpdateImageMap(nsImageFrame* aImageFrame);
 206
 207   /**
 208    * Update the label accessible tree when rendered @value is changed.
 209    */
 210   void UpdateLabelValue(mozilla::PresShell* aPresShell, nsIContent* aLabelElm,
 211                         const nsString& aNewValue);
 212
 213   /**
 214    * Notify accessibility that anchor jump has been accomplished to the given
 215    * target. Used by layout.
 216    */
 217   void NotifyOfAnchorJumpTo(nsIContent* aTarget);
 218
 219   /**
 220    * Notify that presshell is activated.
 221    */
 222   void PresShellActivated(mozilla::PresShell* aPresShell);
 223
 224   /**
 225    * Recreate an accessible for the given content node in the presshell.
 226    */
 227   void RecreateAccessible(mozilla::PresShell* aPresShell, nsIContent* aContent);
 228
 229   void FireAccessibleEvent(uint32_t aEvent, LocalAccessible* aTarget);
 230
 231   void NotifyOfPossibleBoundsChange(mozilla::PresShell* aPresShell,
 232                                     nsIContent* aContent);
 233
 234   void NotifyOfComputedStyleChange(mozilla::PresShell* aPresShell,
 235                                    nsIContent* aContent);
 236
 237   void NotifyOfTabPanelVisibilityChange(mozilla::PresShell* aPresShell,
 238                                         mozilla::dom::Element* aPanel,
 239                                         bool aVisible);
 240
 241   void NotifyOfResolutionChange(mozilla::PresShell* aPresShell,
 242                                 float aResolution);
 243
 244   void NotifyOfDevPixelRatioChange(mozilla::PresShell* aPresShell,
 245                                    int32_t aAppUnitsPerDevPixel);
 246
 247   /**
 248    * Notify accessibility that an element explicitly set for an attribute is
 249    * about to change. See dom::Element::ExplicitlySetAttrElement.
 250    */
 251   void NotifyAttrElementWillChange(mozilla::dom::Element* aElement,
 252                                    nsAtom* aAttr);
 253
 254   /**
 255    * Notify accessibility that an element explicitly set for an attribute has
 256    * changed. See dom::Element::ExplicitlySetAttrElement.
 257    */
 258   void NotifyAttrElementChanged(mozilla::dom::Element* aElement, nsAtom* aAttr);
 259
 260   // nsAccessibiltiyService
 261
 262   /**
 263    * Return true if accessibility service has been shutdown.
 264    */
 265   static bool IsShutdown() { return gConsumers == 0; };
 266
 267   /**
 268    * Return true if there should be an image accessible for the given element.
 269    */
 270   static bool ShouldCreateImgAccessible(mozilla::dom::Element* aElement,
 271                                         DocAccessible* aDocument);
 272
 273   /**
 274    * Creates an accessible for the given DOM node.
 275    *
 276    * @param  aNode             [in] the given node
 277    * @param  aContext          [in] context the accessible is created in
 278    * @param  aIsSubtreeHidden  [out, optional] indicates whether the node's
 279    *                             frame and its subtree is hidden
 280    */
 281   LocalAccessible* CreateAccessible(nsINode* aNode, LocalAccessible* aContext,
 282                                     bool* aIsSubtreeHidden = nullptr);
 283
 284   mozilla::a11y::role MarkupRole(const nsIContent* aContent) const {
 285     const mozilla::a11y::MarkupMapInfo* markupMap =
 286         GetMarkupMapInfoFor(aContent);
 287     return markupMap ? markupMap->role : mozilla::a11y::roles::NOTHING;
 288   }
 289
 290   /**
 291    * Return the associated value for a given attribute if
 292    * it appears in the MarkupMap. Otherwise, it returns null. This can be
 293    * called with either an nsIContent or an Accessible.
 294    */
 295   template <typename T>
 296   nsStaticAtom* MarkupAttribute(T aSource, nsStaticAtom* aAtom) const {
 297     const mozilla::a11y::MarkupMapInfo* markupMap =
 298         GetMarkupMapInfoFor(aSource);
 299     if (markupMap) {
 300       for (size_t i = 0; i < mozilla::ArrayLength(markupMap->attrs); i++) {
 301         const mozilla::a11y::MarkupAttrInfo* info = markupMap->attrs + i;
 302         if (info->name == aAtom) {
 303           return info->value;
 304         }
 305       }
 306     }
 307     return nullptr;
 308   }
 309
 310   /**
 311    * Set the object attribute defined by markup for the given element.
 312    */
 313   void MarkupAttributes(mozilla::a11y::Accessible* aAcc,
 314                         mozilla::a11y::AccAttributes* aAttributes) const;
 315
 316   /**
 317    * A list of possible accessibility service consumers. Accessibility service
 318    * can only be shut down when there are no remaining consumers.
 319    *
 320    * eXPCOM       - accessibility service is used by XPCOM.
 321    *
 322    * eMainProcess - accessibility service was started by main process in the
 323    *                content process.
 324    *
 325    * ePlatformAPI - accessibility service is used by the platform api in the
 326    *                main process.
 327    */
 328   enum ServiceConsumer {
 329     eXPCOM = 1 << 0,
 330     eMainProcess = 1 << 1,
 331     ePlatformAPI = 1 << 2,
 332   };
 333
 334 #if defined(ANDROID)
 335   static mozilla::Monitor& GetAndroidMonitor();
 336 #endif
 337
 338  private:
 339   // nsAccessibilityService creation is controlled by friend
 340   // GetOrCreateAccService, keep constructors private.
 341   nsAccessibilityService();
 342   nsAccessibilityService(const nsAccessibilityService&);
 343   nsAccessibilityService& operator=(const nsAccessibilityService&);
 344
 345  private:
 346   /**
 347    * Initialize accessibility service.
 348    */
 349   bool Init();
 350
 351   /**
 352    * Shutdowns accessibility service.
 353    */
 354   void Shutdown();
 355
 356   /**
 357    * Create an accessible whose type depends on the given frame.
 358    */
 359   already_AddRefed<LocalAccessible> CreateAccessibleByFrameType(
 360       nsIFrame* aFrame, nsIContent* aContent, LocalAccessible* aContext);
 361
 362   /**
 363    * Notify observers about change of the accessibility service's consumers.
 364    */
 365   void NotifyOfConsumersChange();
 366
 367   /**
 368    * Get a JSON string representing the accessibility service consumers.
 369    */
 370   void GetConsumers(nsAString& aString);
 371
 372   /**
 373    * Set accessibility service consumers.
 374    */
 375   void SetConsumers(uint32_t aConsumers, bool aNotify = true);
 376
 377   /**
 378    * Unset accessibility service consumers.
 379    */
 380   void UnsetConsumers(uint32_t aConsumers);
 381
 382   /**
 383    * Reference for accessibility service instance.
 384    */
 385   static nsAccessibilityService* gAccessibilityService;
 386
 387   /**
 388    * Reference for application accessible instance.
 389    */
 390   static mozilla::a11y::ApplicationAccessible* gApplicationAccessible;
 391   static mozilla::a11y::xpcAccessibleApplication* gXPCApplicationAccessible;
 392
 393   /**
 394    * Contains a set of accessibility service consumers.
 395    */
 396   static uint32_t gConsumers;
 397
 398   // Can be weak because all atoms are known static
 399   using MarkupMap = nsTHashMap<nsAtom*, const mozilla::a11y::MarkupMapInfo*>;
 400   MarkupMap mHTMLMarkupMap;
 401   MarkupMap mMathMLMarkupMap;
 402
 403   const mozilla::a11y::MarkupMapInfo* GetMarkupMapInfoFor(
 404       const nsIContent* aContent) const {
 405     if (aContent->IsHTMLElement()) {
 406       return mHTMLMarkupMap.Get(aContent->NodeInfo()->NameAtom());
 407     }
 408     if (aContent->IsMathMLElement()) {
 409       return mMathMLMarkupMap.Get(aContent->NodeInfo()->NameAtom());
 410     }
 411     // This function can be called by MarkupAttribute, etc. which might in turn
 412     // be called on a XUL, SVG, etc. element. For example, this can happen
 413     // with nsAccUtils::SetLiveContainerAttributes.
 414     return nullptr;
 415   }
 416
 417   const mozilla::a11y::MarkupMapInfo* GetMarkupMapInfoFor(
 418       mozilla::a11y::Accessible* aAcc) const;
 419
 420   nsTHashMap<nsAtom*, const mozilla::a11y::XULMarkupMapInfo*> mXULMarkupMap;
 421
 422   friend nsAccessibilityService* GetAccService();
 423   friend nsAccessibilityService* GetOrCreateAccService(uint32_t);
 424   friend void MaybeShutdownAccService(uint32_t);
 425   friend void mozilla::a11y::PrefChanged(const char*, void*);
 426   friend mozilla::a11y::FocusManager* mozilla::a11y::FocusMgr();
 427   friend mozilla::a11y::SelectionManager* mozilla::a11y::SelectionMgr();
 428   friend mozilla::a11y::ApplicationAccessible* mozilla::a11y::ApplicationAcc();
 429   friend mozilla::a11y::xpcAccessibleApplication*
 430   mozilla::a11y::XPCApplicationAcc();
 431   friend class xpcAccessibilityService;
 432 };
 433
 434 /**
 435  * Return the accessibility service instance. (Handy global function)
 436  */
 437 inline nsAccessibilityService* GetAccService() {
 438   return nsAccessibilityService::gAccessibilityService;
 439 }
 440
 441 /**
 442  * Return accessibility service instance; creating one if necessary.
 443  */
 444 nsAccessibilityService* GetOrCreateAccService(
 445     uint32_t aNewConsumer = nsAccessibilityService::ePlatformAPI);
 446
 447 /**
 448  * Shutdown accessibility service if needed.
 449  */
 450 void MaybeShutdownAccService(uint32_t aFormerConsumer);
 451
 452 /**
 453  * Return true if we're in a content process and not B2G.
 454  */
 455 inline bool IPCAccessibilityActive() { return XRE_IsContentProcess(); }
 456
 457 /**
 458  * Map nsIAccessibleEvents constants to strings. Used by
 459  * nsAccessibilityService::GetStringEventType() method.
 460  */
 461 static const char kEventTypeNames[][40] = {
 462     "unknown",                   //
 463     "show",                      // EVENT_SHOW
 464     "hide",                      // EVENT_HIDE
 465     "reorder",                   // EVENT_REORDER
 466     "focus",                     // EVENT_FOCUS
 467     "state change",              // EVENT_STATE_CHANGE
 468     "name changed",              // EVENT_NAME_CHANGE
 469     "description change",        // EVENT_DESCRIPTION_CHANGE
 470     "value change",              // EVENT_VALUE_CHANGE
 471     "selection",                 // EVENT_SELECTION
 472     "selection add",             // EVENT_SELECTION_ADD
 473     "selection remove",          // EVENT_SELECTION_REMOVE
 474     "selection within",          // EVENT_SELECTION_WITHIN
 475     "alert",                     // EVENT_ALERT
 476     "menu start",                // EVENT_MENU_START
 477     "menu end",                  // EVENT_MENU_END
 478     "menupopup start",           // EVENT_MENUPOPUP_START
 479     "menupopup end",             // EVENT_MENUPOPUP_END
 480     "dragdrop start",            // EVENT_DRAGDROP_START
 481     "scrolling start",           // EVENT_SCROLLING_START
 482     "scrolling end",             // EVENT_SCROLLING_END
 483     "document load complete",    // EVENT_DOCUMENT_LOAD_COMPLETE
 484     "document reload",           // EVENT_DOCUMENT_RELOAD
 485     "document load stopped",     // EVENT_DOCUMENT_LOAD_STOPPED
 486     "text attribute changed",    // EVENT_TEXT_ATTRIBUTE_CHANGED
 487     "text caret moved",          // EVENT_TEXT_CARET_MOVED
 488     "text inserted",             // EVENT_TEXT_INSERTED
 489     "text removed",              // EVENT_TEXT_REMOVED
 490     "text selection changed",    // EVENT_TEXT_SELECTION_CHANGED
 491     "window activate",           // EVENT_WINDOW_ACTIVATE
 492     "window deactivate",         // EVENT_WINDOW_DEACTIVATE
 493     "window maximize",           // EVENT_WINDOW_MAXIMIZE
 494     "window minimize",           // EVENT_WINDOW_MINIMIZE
 495     "window restore",            // EVENT_WINDOW_RESTORE
 496     "object attribute changed",  // EVENT_OBJECT_ATTRIBUTE_CHANGED
 497     "text value change",         // EVENT_TEXT_VALUE_CHANGE
 498     "scrolling",                 // EVENT_SCROLLING
 499     "announcement",              // EVENT_ANNOUNCEMENT
 500     "live region added",         // EVENT_LIVE_REGION_ADDED
 501     "live region removed",       // EVENT_LIVE_REGION_REMOVED
 502     "inner reorder",             // EVENT_INNER_REORDER
 503 };
 504
 505 #endif