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