accessible/interfaces/nsIAccessible.idl

   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 #include "nsISupports.idl"
   7 #include "nsIArray.idl"
   8
   9 interface nsIPersistentProperties;
  10 interface nsIAccessibleDocument;
  11 interface nsIAccessibleRelation;
  12
  13 webidl Node;
  14
  15 %{C++
  16 #define NS_ACCESSIBLE_CACHE_TOPIC "accessible-cache"
  17 namespace mozilla {
  18 namespace a11y {
  19 class Accessible;
  20 class LocalAccessible;
  21 }
  22 }
  23 %}
  24
  25 [ptr] native InternalAccessible(mozilla::a11y::Accessible);
  26 [ptr] native InternalLocalAccessible(mozilla::a11y::LocalAccessible);
  27
  28 /**
  29  * A cross-platform interface that supports platform-specific
  30  * accessibility APIs like MSAA and ATK. Contains the sum of what's needed
  31  * to support IAccessible as well as ATK's generic accessibility objects.
  32  * Can also be used by in-process accessibility clients to get information
  33  * about objects in the accessible tree. The accessible tree is a subset of
  34  * nodes in the DOM tree -- such as documents, focusable elements and text.
  35  * Mozilla creates the implementations of nsIAccessible on demand.
  36  * See http://www.mozilla.org/projects/ui/accessibility for more information.
  37  */
  38 [scriptable, builtinclass, uuid(de2869d9-563c-4943-996b-31a4daa4d097)]
  39 interface nsIAccessible : nsISupports
  40 {
  41   /**
  42    * Parent node in accessible tree.
  43    */
  44   readonly attribute nsIAccessible parent;
  45
  46   /**
  47    * Next sibling in accessible tree
  48    */
  49   readonly attribute nsIAccessible nextSibling;
  50
  51   /**
  52    * Previous sibling in accessible tree
  53    */
  54   readonly attribute nsIAccessible previousSibling;
  55
  56   /**
  57    * First child in accessible tree
  58    */
  59   readonly attribute nsIAccessible firstChild;
  60
  61   /**
  62    * Last child in accessible tree
  63    */
  64   readonly attribute nsIAccessible lastChild;
  65
  66   /**
  67    * Array of all this element's children.
  68    */
  69   readonly attribute nsIArray children;
  70
  71   /**
  72    * Number of accessible children
  73    */
  74   readonly attribute long childCount;
  75
  76   /**
  77    * The 0-based index of this accessible in its parent's list of children,
  78    * or -1 if this accessible does not have a parent.
  79    */
  80   readonly attribute long indexInParent;
  81
  82   /**
  83    * The unique identifier of the accessible. ID is only guaranteed to be unique
  84    * per document (Windows IDs are unique even across documents, but that is
  85    * Windows specific and not exposed to core).
  86    */
  87   readonly attribute long long uniqueID;
  88
  89   /**
  90    * The DOM node this nsIAccessible is associated with.
  91    */
  92   readonly attribute Node DOMNode;
  93
  94   /**
  95     * For remote accessibles the id of the related DOM node.
  96     */
  97   readonly attribute AString id;
  98
  99   /**
 100    * The document accessible that this access node resides in.
 101    */
 102   readonly attribute nsIAccessibleDocument document;
 103
 104   /**
 105    * The root document accessible that this access node resides in.
 106    */
 107   readonly attribute nsIAccessibleDocument rootDocument;
 108
 109   /**
 110    * The language for the current DOM node, e.g. en, de, etc.
 111    */
 112   readonly attribute AString language;
 113
 114   /**
 115    * Accessible name -- the main text equivalent for this node. The name is
 116    * specified by ARIA or by native markup. Example of ARIA markup is
 117    * aria-labelledby attribute placed on element of this accessible. Example
 118    * of native markup is HTML label linked with HTML element of this accessible.
 119    *
 120    * Value can be string or null. A null value indicates that AT may attempt to
 121    * compute the name. Any string value, including the empty string, should be
 122    * considered author-intentional, and respected.
 123    */
 124   readonly attribute AString name;
 125
 126   /**
 127    * Accessible value -- a number or a secondary text equivalent for this node
 128    * Widgets that use role attribute can force a value using the valuenow attribute
 129    */
 130   readonly attribute AString value;
 131
 132   /**
 133    * Accessible description -- long text associated with this node
 134    */
 135   readonly attribute AString description;
 136
 137   /**
 138    * Provides localized string of accesskey name, such as Alt+D.
 139    * The modifier may be affected by user and platform preferences.
 140    * Usually alt+letter, or just the letter alone for menu items.
 141    */
 142   readonly attribute AString accessKey;
 143
 144   /**
 145    * Provides localized string of global keyboard accelerator for default
 146    * action, such as Ctrl+O for Open file
 147    */
 148   readonly attribute AString keyboardShortcut;
 149
 150   /**
 151    * Enumerated accessible role (see the constants defined in nsIAccessibleRole).
 152    *
 153    * @note  The values might depend on platform because of variations. Widgets
 154    *        can use ARIA role attribute to force the final role.
 155    */
 156   readonly attribute unsigned long role;
 157
 158   /**
 159    * Accessible states -- bit fields which describe boolean properties of node.
 160    * Many states are only valid given a certain role attribute that supports
 161    * them.
 162    *
 163    * @param aState - the first bit field (see nsIAccessibleStates::STATE_*
 164    *                 constants)
 165    * @param aExtraState - the second bit field
 166    *                      (see nsIAccessibleStates::EXT_STATE_* constants)
 167    */
 168   void getState(out unsigned long aState, out unsigned long aExtraState);
 169
 170   /**
 171    * Focused accessible child of node
 172    */
 173   readonly attribute nsIAccessible focusedChild;
 174
 175   /**
 176    * Attributes of accessible
 177    */
 178   readonly attribute nsIPersistentProperties attributes;
 179
 180   /**
 181    * Cached fields from a remote accessible
 182    */
 183   readonly attribute nsIPersistentProperties cache;
 184
 185   /**
 186    * Platform specific interface for accessible
 187    */
 188   readonly attribute nsISupports nativeInterface;
 189
 190   /**
 191    * Returns grouping information. Used for tree items, list items, tab panel
 192    * labels, radio buttons, etc. Also used for collectons of non-text objects.
 193    *
 194    * @param groupLevel - 1-based, similar to ARIA 'level' property
 195    * @param similarItemsInGroup - 1-based, similar to ARIA 'setsize' property,
 196    *                              inclusive of the current item
 197    * @param positionInGroup - 1-based, similar to ARIA 'posinset' property
 198    */
 199   void groupPosition(out long aGroupLevel, out long aSimilarItemsInGroup,
 200                      out long aPositionInGroup);
 201
 202   /**
 203    * Accessible child which contains the coordinate at (x, y) in screen pixels.
 204    * If the point is in the current accessible but not in a child, the
 205    * current accessible will be returned.
 206    * If the point is in neither the current accessible or a child, then
 207    * null will be returned.
 208    *
 209    * @param x  screen's x coordinate
 210    * @param y  screen's y coordinate
 211    * @return   the direct accessible child containing the given point
 212    */
 213   nsIAccessible getChildAtPoint(in long x, in long y);
 214
 215   /**
 216    * Deepest accessible child which contains the coordinate at (x, y) in screen
 217    * pixels. If the point is in the current accessible but not in a child, the
 218    * current accessible will be returned. If the point is in neither the current
 219    * accessible or a child, then null will be returned.
 220    *
 221    * @param x  screen's x coordinate
 222    * @param y  screen's y coordinate
 223    * @return   the deepest accessible child containing the given point
 224    */
 225   nsIAccessible getDeepestChildAtPoint(in long x, in long y);
 226
 227 /**
 228    * Like GetDeepestChildAtPoint, but restricted to the current process.
 229    * If the point is within a remote document, the accessible for the browser
 230    * element containing that document will be returned; i.e. this will not
 231    * descend into the document. If called on an accessible inside a remote
 232    * document, this will fail.
 233    *
 234    * @param x  screen's x coordinate
 235    * @param y  screen's y coordinate
 236    * @return   the deepest accessible child in this process containing the given
 237    *           point
 238    */
 239   nsIAccessible getDeepestChildAtPointInProcess(in long x, in long y);
 240
 241   /**
 242    * Nth accessible child using zero-based index or last child if index less than zero
 243    */
 244   nsIAccessible getChildAt(in long aChildIndex);
 245
 246   /**
 247    * Return accessible relation by the given relation type (see.
 248    * constants defined in nsIAccessibleRelation).
 249    */
 250   nsIAccessibleRelation getRelationByType(in unsigned long aRelationType);
 251
 252   /**
 253    * Returns multiple accessible relations for this object.
 254    */
 255   nsIArray getRelations();
 256
 257   /**
 258    * Return accessible's x and y coordinates relative to the screen and
 259    * accessible's width and height in Dev pixels.
 260    */
 261   void getBounds(out long x, out long y, out long width, out long height);
 262
 263   /**
 264    * Return accessible's x and y coordinates relative to the screen and
 265    * accessible's width and height in CSS pixels.
 266    */
 267   void getBoundsInCSSPixels(out long aX, out long aY, out long aWidth, out long aHeight);
 268
 269   /**
 270    * Add or remove this accessible to the current selection
 271    */
 272   void setSelected(in boolean isSelected);
 273
 274   /**
 275    * Select this accessible node only
 276    */
 277   void takeSelection();
 278
 279   /**
 280    * Focus this accessible node,
 281    * The state STATE_FOCUSABLE indicates whether this node is normally focusable.
 282    * It is the callers responsibility to determine whether this node is focusable.
 283    * accTakeFocus on a node that is not normally focusable (such as a table),
 284    * will still set focus on that node, although normally that will not be visually
 285    * indicated in most style sheets.
 286    */
 287   void takeFocus();
 288
 289   /**
 290    * The number of accessible actions associated with this accessible
 291    */
 292   readonly attribute uint8_t actionCount;
 293
 294   /**
 295    * The name of the accessible action at the given zero-based index
 296    */
 297   AString getActionName(in uint8_t index);
 298
 299   /**
 300    * The description of the accessible action at the given zero-based index
 301    */
 302   AString getActionDescription(in uint8_t aIndex);
 303
 304   /**
 305    * Perform the accessible action at the given zero-based index
 306    * Action number 0 is the default action
 307    */
 308   void doAction(in uint8_t index);
 309
 310   /**
 311    * Makes an object visible on screen.
 312    *
 313    * @param scrollType - defines where the object should be placed on
 314    *                     the screen (see nsIAccessibleScrollType for
 315    *                     available constants).
 316    */
 317   [can_run_script]
 318   void scrollTo(in unsigned long aScrollType);
 319
 320   /**
 321    * Moves the top left of an object to a specified location.
 322    *
 323    * @param coordinateType [in] - specifies whether the coordinates are relative to
 324    *                         the screen or the parent object (for available
 325    *                         constants refer to nsIAccessibleCoordinateType)
 326    * @param x [in] - defines the x coordinate
 327    * @param y [in] - defines the y coordinate
 328   */
 329   void scrollToPoint(in unsigned long coordinateType, in long x, in long y);
 330
 331   /**
 332    * Dispatches an ANNOUNCEMENT event with this accessible as target.
 333    *
 334    * @param announcement [in] - string to use in announcement.
 335    * @param priority [in] - priority for announcement, could be
 336    *                      nsIAccessibleAnnouncementEvent.POLITE or
 337    *                      nsIAccessibleAnnouncementEvent.ASSERTIVE.
 338    */
 339   void announce(in AString announcement, in unsigned short priority);
 340
 341   /**
 342    * Get the role of this Accessible as an ARIA role token. This might have been
 343    * set explicitly (e.g. role="button") or it might be implicit in native
 344    * markup (e.g. <button> returns "button").
 345    */
 346   readonly attribute AString computedARIARole;
 347
 348   [notxpcom, nostdcall] InternalLocalAccessible toInternalAccessible();
 349   [notxpcom, nostdcall] InternalAccessible toInternalGeneric();
 350
 351 };