chrome/common/extensions/api/automation.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // The <code>chrome.automation</code> API allows developers to access the
   6 // automation (accessibility) tree for the browser. The tree resembles the DOM
   7 // tree, but only exposes the <em>semantic</em> structure of a page. It can be
   8 // used to programmatically interact with a page by examining names, roles, and
   9 // states, listening for events, and performing actions on nodes.
  10 [nocompile] namespace automation {
  11   // Keep the following enums in sync with 'ui/accessibility/ax_enums.idl'.
  12   // They are kept here purely for extension docs generation.
  13
  14   // Possible events fired on an $(ref:automation.AutomationNode).
  15   enum EventType {
  16     activedescendantchanged,
  17     alert,
  18     ariaAttributeChanged,
  19     autocorrectionOccured,
  20     blur,
  21     checkedStateChanged,
  22     childrenChanged,
  23     focus,
  24     hide,
  25     hover,
  26     invalidStatusChanged,
  27     layoutComplete,
  28     liveRegionChanged,
  29     loadComplete,
  30     locationChanged,
  31     menuEnd,
  32     menuListItemSelected,
  33     menuListValueChanged,
  34     menuPopupEnd,
  35     menuPopupStart,
  36     menuStart,
  37     rowCollapsed,
  38     rowCountChanged,
  39     rowExpanded,
  40     scrollPositionChanged,
  41     scrolledToAnchor,
  42     selectedChildrenChanged,
  43     selection,
  44     selectionAdd,
  45     selectionRemove,
  46     show,
  47     textChanged,
  48     textSelectionChanged,
  49     treeChanged,
  50     valueChanged
  51   };
  52
  53   // Describes the purpose of an $(ref:automation.AutomationNode).
  54   enum RoleType {
  55     alertDialog,
  56     alert,
  57     annotation,
  58     application,
  59     article,
  60     banner,
  61     blockquote,
  62     busyIndicator,
  63     button,
  64     buttonDropDown,
  65     canvas,
  66     caption,
  67     cell,
  68     checkBox,
  69     client,
  70     colorWell,
  71     columnHeader,
  72     column,
  73     comboBox,
  74     complementary,
  75     contentInfo,
  76     date,
  77     dateTime,
  78     definition,
  79     descriptionListDetail,
  80     descriptionList,
  81     descriptionListTerm,
  82     desktop,
  83     details,
  84     dialog,
  85     directory,
  86     disclosureTriangle,
  87     div,
  88     document,
  89     embeddedObject,
  90     figcaption,
  91     figure,
  92     footer,
  93     form,
  94     grid,
  95     group,
  96     heading,
  97     iframe,
  98     iframePresentational,
  99     ignored,
 100     imageMapLink,
 101     imageMap,
 102     image,
 103     inlineTextBox,
 104     labelText,
 105     legend,
 106     lineBreak,
 107     link,
 108     listBoxOption,
 109     listBox,
 110     listItem,
 111     listMarker,
 112     list,
 113     locationBar,
 114     log,
 115     main,
 116     marquee,
 117     math,
 118     menuBar,
 119     menuButton,
 120     menuItem,
 121     menuItemCheckBox,
 122     menuItemRadio,
 123     menuListOption,
 124     menuListPopup,
 125     menu,
 126     meter,
 127     navigation,
 128     note,
 129     outline,
 130     pane,
 131     paragraph,
 132     popUpButton,
 133     pre,
 134     presentational,
 135     progressIndicator,
 136     radioButton,
 137     radioGroup,
 138     region,
 139     rootWebArea,
 140     rowHeader,
 141     row,
 142     ruby,
 143     ruler,
 144     svgRoot,
 145     scrollArea,
 146     scrollBar,
 147     seamlessWebArea,
 148     search,
 149     slider,
 150     sliderThumb,
 151     spinButtonPart,
 152     spinButton,
 153     splitter,
 154     staticText,
 155     status,
 156     tabGroup,
 157     tabList,
 158     tabPanel,
 159     tab,
 160     tableHeaderContainer,
 161     table,
 162     textArea,
 163     textField,
 164     time,
 165     timer,
 166     titleBar,
 167     toggleButton,
 168     toolbar,
 169     treeGrid,
 170     treeItem,
 171     tree,
 172     unknown,
 173     tooltip,
 174     webArea,
 175     webView,
 176     window
 177   };
 178
 179   // Describes characteristics of an $(ref:automation.AutomationNode).
 180   enum StateType {
 181     busy,
 182     checked,
 183     collapsed,
 184     default,
 185     disabled,  // ui/views only
 186     editable,  // ui/views only
 187     enabled,   // content only
 188     expanded,
 189     focusable,
 190     focused,
 191     haspopup,
 192     horizontal,
 193     hovered,
 194     indeterminate,
 195     invisible,
 196     linked,
 197     multiselectable,
 198     offscreen,
 199     pressed,
 200     protected,
 201     readOnly,
 202     required,
 203     selectable,
 204     selected,
 205     vertical,
 206     visited
 207   };
 208
 209   dictionary Rect {
 210     long left;
 211     long top;
 212     long width;
 213     long height;
 214   };
 215
 216   // Arguments for the find() and findAll() methods.
 217   [nocompile, noinline_doc] dictionary FindParams {
 218     automation.RoleType? role;
 219
 220     // A map of $(ref:automation.StateType) to boolean, indicating for each
 221     // state whether it should be set or not. For example:
 222     // <code>{ StateType.enabled: false }</code> would only match if
 223     // <code>StateType.enabled</code> was <em>not</em> present in the node's
 224     // <code>state</code> object.
 225     object? state;
 226
 227     // A map of attribute name to expected value, for example
 228     // <code>{ name: 'Root directory', button_mixed: true }</code>.
 229     // String attribute values may be specified as a regex, for example
 230     // <code>{ name: /stralia$/</code> }</code>.
 231     // Unless specifying a regex, the expected value must be an exact match
 232     // in type and value for the actual value. Thus, the type of expected value
 233     // must be one of:
 234     // <ul>
 235     // <li>string</li>
 236     // <li>integer</li>
 237     // <li>float</li>
 238     // <li>boolean</li>
 239     // </ul>
 240     object? attributes;
 241   };
 242
 243   // Called when the result for a <code>query</code> is available.
 244   callback QueryCallback = void(AutomationNode node);
 245
 246   // An event in the Automation tree.
 247   [nocompile, noinline_doc] dictionary AutomationEvent {
 248     // The $(ref:automation.AutomationNode) to which the event was targeted.
 249     AutomationNode target;
 250
 251     // The type of the event.
 252     EventType type;
 253
 254     // Stops this event from further processing except for any remaining
 255     // listeners on $(ref:AutomationEvent.target).
 256     static void stopPropagation();
 257   };
 258
 259   // A listener for events on an <code>AutomationNode</code>.
 260   callback AutomationListener = void(AutomationEvent event);
 261
 262   // A single node in an Automation tree.
 263   [nocompile, noinline_doc] dictionary AutomationNode {
 264     // The root node of the tree containing this AutomationNode.
 265     AutomationNode root;
 266
 267     // Whether this AutomationNode is root node.
 268     boolean isRootNode;
 269
 270     // The role of this node.
 271     automation.RoleType role;
 272
 273     // TODO(aboxhall): expose states as mixins instead
 274
 275     // The $(ref:automation.StateType)s describing this node.
 276     object state;
 277
 278     // The rendered location (as a bounding box) of this node within the frame.
 279     automation.Rect location;
 280
 281     // The purpose of the node, other than the role, if any.
 282     DOMString description;
 283
 284     // The help text for the node, if any.
 285     DOMString help;
 286
 287     // The accessible name for this node, via the
 288     // <a href="http://www.w3.org/TR/wai-aria/roles#namecalculation">
 289     // Accessible Name Calculation</a> process.
 290     DOMString name;
 291
 292     // The value for this node: for example the <code>value</code> attribute of
 293     // an <code>&lt;input&gt; element.
 294     DOMString value;
 295
 296     // The nodes, if any, which this node is specified to control via
 297     // <a href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-controls">
 298     // <code>aria-controls</code></a>.
 299     AutomationNode[] controls;
 300
 301     // The nodes, if any, which form a description for this node.
 302     AutomationNode[] describedBy;
 303
 304     // The nodes, if any, which may optionally be navigated to after this
 305     // one. See
 306     // <a href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-flowto">
 307     // <code>aria-flowto</code></a>.
 308     AutomationNode[] flowTo;
 309
 310     // The nodes, if any, which form a label for this element. Generally, the
 311     // text from these elements will also be exposed as the element's accessible
 312     // name, via the $(ref:automation.AutomationNode.name) attribute.
 313     AutomationNode[] labelledBy;
 314
 315     // The nodes, if any, which are to be considered children of this node but
 316     // are not children in the DOM tree.
 317     AutomationNode[] owns;
 318
 319     // TODO(aboxhall): Make this private?
 320
 321     // A collection of this node's other attributes.
 322     object? attributes;
 323
 324     // The index of this node in its parent node's list of children. If this is
 325     // the root node, this will be undefined.
 326     long? indexInParent;
 327
 328     AutomationNode[] children;
 329     AutomationNode parent;
 330     AutomationNode firstChild;
 331     AutomationNode lastChild;
 332     AutomationNode previousSibling;
 333     AutomationNode nextSibling;
 334
 335     // Does the default action based on this node's role. This is generally
 336     // the same action that would result from clicking the node such as
 337     // expanding a treeitem, toggling a checkbox, selecting a radiobutton,
 338     // or activating a button.
 339     static void doDefault();
 340
 341     // Places focus on this node.
 342     static void focus();
 343
 344     // Scrolls this node to make it visible.
 345     static void makeVisible();
 346
 347     // Sets selection within a text field.
 348     static void setSelection(long startIndex, long endIndex);
 349
 350     // Adds a listener for the given event type and event phase.
 351     static void addEventListener(
 352         EventType eventType, AutomationListener listener, boolean capture);
 353
 354     // Removes a listener for the given event type and event phase.
 355     static void removeEventListener(
 356         EventType eventType, AutomationListener listener, boolean capture);
 357
 358     // Gets the first node in this node's subtree which matches the given CSS
 359     // selector and is within the same DOM context.
 360     //
 361     // If this node doesn't correspond directly with an HTML node in the DOM,
 362     // querySelector will be run on this node's nearest HTML node ancestor. Note
 363     // that this may result in the query returning a node which is not a
 364     // descendant of this node.
 365     //
 366     // If the selector matches a node which doesn't directly correspond to an
 367     // automation node (for example an element within an ARIA widget, where the
 368     // ARIA widget forms one node of the automation tree, or an element which
 369     // is hidden from accessibility via hiding it using CSS or using
 370     // aria-hidden), this will return the nearest ancestor which does correspond
 371     // to an automation node.
 372     static void domQuerySelector(DOMString selector, QueryCallback callback);
 373
 374     // Finds the first AutomationNode in this node's subtree which matches the
 375     // given search parameters.
 376     static AutomationNode find(FindParams params);
 377
 378     // Finds all the AutomationNodes in this node's subtree which matches the
 379     // given search parameters.
 380     static AutomationNode[] findAll(FindParams params);
 381
 382     // Returns whether this node matches the given $(ref:automation.FindParams).
 383     static boolean matches(FindParams params);
 384   };
 385
 386   dictionary ActiveDescendantMixin {
 387     // The node referred to by <code>aria-activedescendant</code>, where
 388     // applicable
 389     AutomationNode activedescendant;
 390   };
 391
 392   // Attributes which are mixed in to an AutomationNode if it is a link.
 393   dictionary LinkMixins {
 394     // TODO(aboxhall): Add visited state
 395
 396     // The URL that this link will navigate to.
 397     DOMString url;
 398   };
 399
 400   // Attributes which are mixed in to an AutomationNode if it is a document.
 401   dictionary DocumentMixins {
 402     // The URL of this document.
 403     DOMString docUrl;
 404
 405     // The title of this document.
 406     DOMString docTitle;
 407
 408     // Whether this document has finished loading.
 409     boolean docLoaded;
 410
 411     // The proportion (out of 1.0) that this doc has completed loading.
 412     double docLoadingProgress;
 413   };
 414
 415   // TODO(aboxhall): document ScrollableMixins (e.g. what is scrollXMin? is it
 416   // ever not 0?)
 417
 418   // Attributes which are mixed in to an AutomationNode if it is scrollable.
 419   dictionary ScrollableMixins {
 420     long scrollX;
 421     long scrollXMin;
 422     long scrollXMax;
 423     long scrollY;
 424     long scrollYMin;
 425     long scrollYMax;
 426   };
 427
 428   // Attributes which are mixed in to an AutomationNode if it is editable text.
 429   dictionary EditableTextMixins {
 430     // The character index of the start of the selection within this editable
 431     // text element; -1 if no selection.
 432     long textSelStart;
 433
 434     // The character index of the end of the selection within this editable
 435     // text element; -1 if no selection.
 436     long textSelEnd;
 437   };
 438
 439   // Attributes which are mixed in to an AutomationNode if it is a range.
 440   dictionary RangeMixins {
 441     // The current value for this range.
 442     double valueForRange;
 443
 444     // The minimum possible value for this range.
 445     double minValueForRange;
 446
 447     // The maximum possible value for this range.
 448     double maxValueForRange;
 449   };
 450
 451   // TODO(aboxhall): live region mixins.
 452
 453   // Attributes which are mixed in to an AutomationNode if it is a table.
 454   dictionary TableMixins {
 455     // The number of rows in this table.
 456     long tableRowCount;
 457
 458     // The number of columns in this table.
 459     long tableColumnCount;
 460   };
 461
 462   // Attributes which are mixed in to an AutomationNode if it is a table cell.
 463   dictionary TableCellMixins {
 464     // The zero-based index of the column that this cell is in.
 465     long tableCellColumnIndex;
 466
 467     // The number of columns that this cell spans (default is 1).
 468     long tableCellColumnSpan;
 469
 470     // The zero-based index of the row that this cell is in.
 471     long tableCellRowIndex;
 472
 473     // The number of rows that this cell spans (default is 1).
 474     long tableCellRowSpan;
 475   };
 476
 477   // Called when the <code>AutomationNode</code> for the page is available.
 478   callback RootCallback = void(AutomationNode rootNode);
 479
 480   interface Functions {
 481     // Get the automation tree for the tab with the given tabId, or the current
 482     // tab if no tabID is given, enabling automation if necessary. Returns a
 483     // tree with a placeholder root node; listen for the "loadComplete" event to
 484     // get a notification that the tree has fully loaded (the previous root node
 485     // reference will stop working at or before this point).
 486     [nocompile] static void getTree(optional long tabId, RootCallback callback);
 487
 488     // Get the automation tree for the whole desktop which consists of all on
 489     // screen views. Note this API is currently only supported on Chrome OS.
 490     [nocompile] static void getDesktop(RootCallback callback);
 491   };
 492 };