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     selectedTextChanged,
  44     selection,
  45     selectionAdd,
  46     selectionRemove,
  47     show,
  48     textChanged,
  49     textInserted,
  50     textRemoved,
  51     textSelectionChanged,
  52     valueChanged
  53   };
  54
  55   // Describes the purpose of an $(ref:automation.AutomationNode).
  56   enum RoleType {
  57     alertDialog,
  58     alert,
  59     annotation,
  60     application,
  61     article,
  62     banner,
  63     browser,
  64     busyIndicator,
  65     button,
  66     buttonDropDown,
  67     canvas,
  68     cell,
  69     checkBox,
  70     client,
  71     colorWell,
  72     columnHeader,
  73     column,
  74     comboBox,
  75     complementary,
  76     contentInfo,
  77     definition,
  78     descriptionListDetail,
  79     descriptionListTerm,
  80     desktop,
  81     dialog,
  82     directory,
  83     disclosureTriangle,
  84     div,
  85     document,
  86     drawer,
  87     editableText,
  88     embeddedObject,
  89     footer,
  90     form,
  91     grid,
  92     group,
  93     growArea,
  94     heading,
  95     helpTag,
  96     horizontalRule,
  97     iframe,
  98     ignored,
  99     imageMapLink,
 100     imageMap,
 101     image,
 102     incrementor,
 103     inlineTextBox,
 104     labelText,
 105     legend,
 106     link,
 107     listBoxOption,
 108     listBox,
 109     listItem,
 110     listMarker,
 111     list,
 112     locationBar,
 113     log,
 114     main,
 115     marquee,
 116     mathElement,
 117     math,
 118     matte,
 119     menuBar,
 120     menuButton,
 121     menuItem,
 122     menuListOption,
 123     menuListPopup,
 124     menu,
 125     navigation,
 126     note,
 127     outline,
 128     pane,
 129     paragraph,
 130     popUpButton,
 131     presentational,
 132     progressIndicator,
 133     radioButton,
 134     radioGroup,
 135     region,
 136     rootWebArea,
 137     rowHeader,
 138     row,
 139     rulerMarker,
 140     ruler,
 141     svgRoot,
 142     scrollArea,
 143     scrollBar,
 144     seamlessWebArea,
 145     search,
 146     sheet,
 147     slider,
 148     sliderThumb,
 149     spinButtonPart,
 150     spinButton,
 151     splitGroup,
 152     splitter,
 153     staticText,
 154     status,
 155     systemWide,
 156     tabGroup,
 157     tabList,
 158     tabPanel,
 159     tab,
 160     tableHeaderContainer,
 161     table,
 162     textArea,
 163     textField,
 164     timer,
 165     titleBar,
 166     toggleButton,
 167     toolbar,
 168     treeGrid,
 169     treeItem,
 170     tree,
 171     unknown,
 172     tooltip,
 173     valueIndicator,
 174     webArea,
 175     window
 176   };
 177
 178   // Describes characteristics of an $(ref:automation.AutomationNode).
 179   enum StateType {
 180     busy,
 181     checked,
 182     collapsed,
 183     default,
 184     disabled,  // ui/views only
 185     editable,  // ui/views only
 186     enabled,   // content only
 187     expanded,
 188     focusable,
 189     focused,
 190     haspopup,
 191     hovered,
 192     indeterminate,
 193     invisible,
 194     linked,
 195     multiselectable,
 196     offscreen,
 197     pressed,
 198     protected,
 199     readOnly,
 200     required,
 201     selectable,
 202     selected,
 203     vertical,
 204     visited
 205   };
 206
 207   dictionary Rect {
 208     long left;
 209     long top;
 210     long width;
 211     long height;
 212   };
 213
 214   // An event in the Automation tree.
 215   [nocompile, noinline_doc] dictionary AutomationEvent {
 216     // The $(ref:automation.AutomationNode) to which the event was targeted.
 217     AutomationNode target;
 218
 219     // The type of the event.
 220     EventType type;
 221
 222     // Stops this event from further processing except for any remaining
 223     // listeners on $(ref:AutomationEvent.target).
 224     static void stopPropagation();
 225   };
 226
 227   // A listener for events on an <code>AutomationNode</code>.
 228   callback AutomationListener = void(AutomationEvent event);
 229
 230   // A single node in an Automation tree.
 231   [nocompile, noinline_doc] dictionary AutomationNode {
 232     // The root node of the tree containing this AutomationNode.
 233     AutomationRootNode root;
 234
 235     // Whether this AutomationNode is an AutomationRootNode.
 236     boolean isRootNode;
 237
 238     // Unique ID to identify this node.
 239     long id;
 240
 241     // The role of this node.
 242     automation.RoleType role;
 243
 244     // The $(ref:automation.StateType)s describing this node.
 245     object state;
 246
 247     // The rendered location (as a bounding box) of this node within the frame.
 248     automation.Rect location;
 249
 250     // A collection of this node's other attributes.
 251     object? attributes;
 252
 253     // The index of this node in its parent node's list of children. If this is
 254     // the root node, this will be undefined.
 255     long? indexInParent;
 256
 257     static AutomationNode[] children();
 258     static AutomationNode parent();
 259     static AutomationNode firstChild();
 260     static AutomationNode lastChild();
 261     static AutomationNode previousSibling();
 262     static AutomationNode nextSibling();
 263
 264     // Does the default action based on this node's role. This is generally
 265     // the same action that would result from clicking the node such as
 266     // expanding a treeitem, toggling a checkbox, selecting a radiobutton,
 267     // or activating a button.
 268     static void doDefault();
 269
 270     // Places focus on this node.
 271     static void focus();
 272
 273     // Scrolls this node to make it visible.
 274     static void makeVisible();
 275
 276     // Sets selection within a text field.
 277     static void setSelection(long startIndex, long endIndex);
 278
 279     // Adds a listener for the given event type and event phase.
 280     static void addEventListener(
 281         EventType eventType, AutomationListener listener, boolean capture);
 282
 283     // Removes a listener for the given event type and event phase.
 284     static void removeEventListener(
 285         EventType eventType, AutomationListener listener, boolean capture);
 286   };
 287
 288   // Called when the <code>AutomationRootNode</code> for the page is available.
 289   callback RootCallback = void(AutomationRootNode rootNode);
 290
 291   // The root node of the automation tree for a single frame or desktop.
 292   // This may be:
 293   // <ul>
 294   //   <li> The desktop
 295   //   <li> The top frame of a page
 296   //   <li> A frame or iframe within a page
 297   // </ul>
 298   // Thus, an <code>AutomationRootNode</code> may be a descendant of one or
 299   // more <code>AutomationRootNode</code>s, and in turn have one or more
 300   // <code>AutomationRootNode</code>s in its descendants. Thus, the
 301   // <code>root</code> property of the <code>AutomationRootNode</code> will be
 302   // the immediate parent <code>AutomationRootNode</code>, or <code>null</code>
 303   // if this is the top-level <code>AutomationRootNode</code>.
 304   //
 305   // Extends $(ref:automation.AutomationNode).
 306   [nocompile, noinline_doc] dictionary AutomationRootNode {
 307     // TODO(aboxhall/dtseng): implement loading. Kept separate to not include
 308     // in generated docs.
 309
 310     // Whether this AutomationRootNode is loaded or not. If false, call load()
 311     // to get the contents.
 312     boolean loaded;
 313
 314     // Load the accessibility tree for this AutomationRootNode.
 315     static void load(RootCallback callback);
 316   };
 317
 318   interface Functions {
 319     // Get the automation tree for the tab with the given tabId, or the current
 320     // tab if no tabID is given, enabling automation if necessary. Returns a
 321     // tree with a placeholder root node; listen for the "loadComplete" event to
 322     // get a notification that the tree has fully loaded (the previous root node
 323     // reference will stop working at or before this point).
 324     [nocompile] static void getTree(optional long tabId, RootCallback callback);
 325
 326     // Get the automation tree for the whole desktop which consists of all on
 327     // screen views. Note this API is currently only supported on Chrome OS.
 328     [nocompile] static void getDesktop(RootCallback callback);
 329   };
 330 };