nsIAccessible.idl (11539B)
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 };