src/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     browser,
  63     busyIndicator,
  64     button,
  65     buttonDropDown,
  66     canvas,
  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     drawer,
  90     editableText,
  91     embeddedObject,
  92     figcaption,
  93     figure,
  94     footer,
  95     form,
  96     grid,
  97     group,
  98     growArea,
  99     heading,
 100     helpTag,
 101     horizontalRule,
 102     iframe,
 103     ignored,
 104     imageMapLink,
 105     imageMap,
 106     image,
 107     incrementor,
 108     inlineTextBox,
 109     labelText,
 110     legend,
 111     link,
 112     listBoxOption,
 113     listBox,
 114     listItem,
 115     listMarker,
 116     list,
 117     locationBar,
 118     log,
 119     main,
 120     marquee,
 121     math,
 122     matte,
 123     menuBar,
 124     menuButton,
 125     menuItem,
 126     menuItemCheckBox,
 127     menuItemRadio,
 128     menuListOption,
 129     menuListPopup,
 130     menu,
 131     meter,
 132     navigation,
 133     note,
 134     outline,
 135     pane,
 136     paragraph,
 137     popUpButton,
 138     pre,
 139     presentational,
 140     progressIndicator,
 141     radioButton,
 142     radioGroup,
 143     region,
 144     rootWebArea,
 145     rowHeader,
 146     row,
 147     rulerMarker,
 148     ruler,
 149     svgRoot,
 150     scrollArea,
 151     scrollBar,
 152     seamlessWebArea,
 153     search,
 154     sheet,
 155     slider,
 156     sliderThumb,
 157     spinButtonPart,
 158     spinButton,
 159     splitGroup,
 160     splitter,
 161     staticText,
 162     status,
 163     systemWide,
 164     tabGroup,
 165     tabList,
 166     tabPanel,
 167     tab,
 168     tableHeaderContainer,
 169     table,
 170     textArea,
 171     textField,
 172     time,
 173     timer,
 174     titleBar,
 175     toggleButton,
 176     toolbar,
 177     treeGrid,
 178     treeItem,
 179     tree,
 180     unknown,
 181     tooltip,
 182     valueIndicator,
 183     webArea,
 184     webView,
 185     window
 186   };
 187
 188   // Describes characteristics of an $(ref:automation.AutomationNode).
 189   enum StateType {
 190     busy,
 191     checked,
 192     collapsed,
 193     default,
 194     disabled,  // ui/views only
 195     editable,  // ui/views only
 196     enabled,   // content only
 197     expanded,
 198     focusable,
 199     focused,
 200     haspopup,
 201     hovered,
 202     indeterminate,
 203     invisible,
 204     linked,
 205     multiselectable,
 206     offscreen,
 207     pressed,
 208     protected,
 209     readOnly,
 210     required,
 211     selectable,
 212     selected,
 213     vertical,
 214     visited
 215   };
 216
 217   dictionary Rect {
 218     long left;
 219     long top;
 220     long width;
 221     long height;
 222   };
 223
 224   // Called when the result for a <code>query</code> is available.
 225   callback QueryCallback = void(AutomationNode node);
 226
 227   // An event in the Automation tree.
 228   [nocompile, noinline_doc] dictionary AutomationEvent {
 229     // The $(ref:automation.AutomationNode) to which the event was targeted.
 230     AutomationNode target;
 231
 232     // The type of the event.
 233     EventType type;
 234
 235     // Stops this event from further processing except for any remaining
 236     // listeners on $(ref:AutomationEvent.target).
 237     static void stopPropagation();
 238   };
 239
 240   // A listener for events on an <code>AutomationNode</code>.
 241   callback AutomationListener = void(AutomationEvent event);
 242
 243   // A single node in an Automation tree.
 244   [nocompile, noinline_doc] dictionary AutomationNode {
 245     // The root node of the tree containing this AutomationNode.
 246     AutomationNode root;
 247
 248     // Whether this AutomationNode is root node.
 249     boolean isRootNode;
 250
 251     // The role of this node.
 252     automation.RoleType role;
 253
 254     // The $(ref:automation.StateType)s describing this node.
 255     object state;
 256
 257     // The rendered location (as a bounding box) of this node within the frame.
 258     automation.Rect location;
 259
 260     // A collection of this node's other attributes.
 261     object? attributes;
 262
 263     // The index of this node in its parent node's list of children. If this is
 264     // the root node, this will be undefined.
 265     long? indexInParent;
 266
 267     static AutomationNode[] children();
 268     static AutomationNode parent();
 269     static AutomationNode firstChild();
 270     static AutomationNode lastChild();
 271     static AutomationNode previousSibling();
 272     static AutomationNode nextSibling();
 273
 274     // Does the default action based on this node's role. This is generally
 275     // the same action that would result from clicking the node such as
 276     // expanding a treeitem, toggling a checkbox, selecting a radiobutton,
 277     // or activating a button.
 278     static void doDefault();
 279
 280     // Places focus on this node.
 281     static void focus();
 282
 283     // Scrolls this node to make it visible.
 284     static void makeVisible();
 285
 286     // Sets selection within a text field.
 287     static void setSelection(long startIndex, long endIndex);
 288
 289     // Adds a listener for the given event type and event phase.
 290     static void addEventListener(
 291         EventType eventType, AutomationListener listener, boolean capture);
 292
 293     // Removes a listener for the given event type and event phase.
 294     static void removeEventListener(
 295         EventType eventType, AutomationListener listener, boolean capture);
 296
 297     // Gets the first node in this node's subtree which matches the given CSS
 298     // selector and is within the same DOM context.
 299     //
 300     // If this node doesn't correspond directly with an HTML node in the DOM,
 301     // querySelector will be run on this node's nearest HTML node ancestor. Note
 302     // that this may result in the query returning a node which is not a
 303     // descendant of this node.
 304     //
 305     // If the selector matches a node which doesn't directly correspond to an
 306     // automation node (for example an element within an ARIA widget, where the
 307     // ARIA widget forms one node of the automation tree, or an element which
 308     // is hidden from accessibility via hiding it using CSS or using
 309     // aria-hidden), this will return the nearest ancestor which does correspond
 310     // to an automation node.
 311     static void querySelector(DOMString selector, QueryCallback callback);
 312   };
 313
 314   // Called when the <code>AutomationNode</code> for the page is available.
 315   callback RootCallback = void(AutomationNode rootNode);
 316
 317   interface Functions {
 318     // Get the automation tree for the tab with the given tabId, or the current
 319     // tab if no tabID is given, enabling automation if necessary. Returns a
 320     // tree with a placeholder root node; listen for the "loadComplete" event to
 321     // get a notification that the tree has fully loaded (the previous root node
 322     // reference will stop working at or before this point).
 323     [nocompile] static void getTree(optional long tabId, RootCallback callback);
 324
 325     // Get the automation tree for the whole desktop which consists of all on
 326     // screen views. Note this API is currently only supported on Chrome OS.
 327     [nocompile] static void getDesktop(RootCallback callback);
 328   };
 329 };