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     blockquote,
  61     browser,
  62     busyIndicator,
  63     button,
  64     buttonDropDown,
  65     canvas,
  66     cell,
  67     checkBox,
  68     client,
  69     colorWell,
  70     columnHeader,
  71     column,
  72     comboBox,
  73     complementary,
  74     contentInfo,
  75     date,
  76     dateTime,
  77     definition,
  78     descriptionListDetail,
  79     descriptionList,
  80     descriptionListTerm,
  81     desktop,
  82     details,
  83     dialog,
  84     directory,
  85     disclosureTriangle,
  86     div,
  87     document,
  88     drawer,
  89     editableText,
  90     embeddedObject,
  91     figcaption,
  92     figure,
  93     footer,
  94     form,
  95     grid,
  96     group,
  97     growArea,
  98     heading,
  99     helpTag,
 100     iframe,
 101     ignored,
 102     imageMapLink,
 103     imageMap,
 104     image,
 105     inlineTextBox,
 106     labelText,
 107     legend,
 108     link,
 109     listBoxOption,
 110     listBox,
 111     listItem,
 112     listMarker,
 113     list,
 114     locationBar,
 115     log,
 116     main,
 117     marquee,
 118     math,
 119     matte,
 120     menuBar,
 121     menuButton,
 122     menuItem,
 123     menuItemCheckBox,
 124     menuItemRadio,
 125     menuListOption,
 126     menuListPopup,
 127     menu,
 128     meter,
 129     navigation,
 130     note,
 131     outline,
 132     pane,
 133     paragraph,
 134     popUpButton,
 135     pre,
 136     presentational,
 137     progressIndicator,
 138     radioButton,
 139     radioGroup,
 140     region,
 141     rootWebArea,
 142     rowHeader,
 143     row,
 144     ruby,
 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     webView,
 183     window
 184   };
 185
 186   // Describes characteristics of an $(ref:automation.AutomationNode).
 187   enum StateType {
 188     busy,
 189     checked,
 190     collapsed,
 191     default,
 192     disabled,  // ui/views only
 193     editable,  // ui/views only
 194     enabled,   // content only
 195     expanded,
 196     focusable,
 197     focused,
 198     haspopup,
 199     hovered,
 200     indeterminate,
 201     invisible,
 202     linked,
 203     multiselectable,
 204     offscreen,
 205     pressed,
 206     protected,
 207     readOnly,
 208     required,
 209     selectable,
 210     selected,
 211     vertical,
 212     visited
 213   };
 214
 215   dictionary Rect {
 216     long left;
 217     long top;
 218     long width;
 219     long height;
 220   };
 221
 222   // Arguments for the find() and findAll() methods.
 223   [nocompile, noinline_doc] dictionary FindParams {
 224     automation.RoleType? role;
 225
 226     // A map of $(ref:automation.StateType) to boolean, indicating for each
 227     // state whether it should be set or not. For example:
 228     // <code>{ StateType.enabled: false }</code> would only match if
 229     // <code>StateType.enabled</code> was <em>not</em> present in the node's
 230     // <code>state</code> object.
 231     object? state;
 232
 233     // A map of attribute name to expected value, for example
 234     // <code>{ name: 'Root directory', button_mixed: true }</code>.
 235     // String attribute values may be specified as a regex, for example
 236     // <code>{ name: /stralia$/</code> }</code>.
 237     // Unless specifying a regex, the expected value must be an exact match
 238     // in type and value for the actual value. Thus, the type of expected value
 239     // must be one of:
 240     // <ul>
 241     // <li>string</li>
 242     // <li>integer</li>
 243     // <li>float</li>
 244     // <li>boolean</li>
 245     // </ul>
 246     object? attributes;
 247   };
 248
 249   // Called when the result for a <code>query</code> is available.
 250   callback QueryCallback = void(AutomationNode node);
 251
 252   // An event in the Automation tree.
 253   [nocompile, noinline_doc] dictionary AutomationEvent {
 254     // The $(ref:automation.AutomationNode) to which the event was targeted.
 255     AutomationNode target;
 256
 257     // The type of the event.
 258     EventType type;
 259
 260     // Stops this event from further processing except for any remaining
 261     // listeners on $(ref:AutomationEvent.target).
 262     static void stopPropagation();
 263   };
 264
 265   // A listener for events on an <code>AutomationNode</code>.
 266   callback AutomationListener = void(AutomationEvent event);
 267
 268   // A single node in an Automation tree.
 269   [nocompile, noinline_doc] dictionary AutomationNode {
 270     // The root node of the tree containing this AutomationNode.
 271     AutomationNode root;
 272
 273     // Whether this AutomationNode is root node.
 274     boolean isRootNode;
 275
 276     // The role of this node.
 277     automation.RoleType role;
 278
 279     // The $(ref:automation.StateType)s describing this node.
 280     object state;
 281
 282     // The rendered location (as a bounding box) of this node within the frame.
 283     automation.Rect location;
 284
 285     // A collection of this node's other attributes.
 286     object? attributes;
 287
 288     // The index of this node in its parent node's list of children. If this is
 289     // the root node, this will be undefined.
 290     long? indexInParent;
 291
 292     static AutomationNode[] children();
 293     static AutomationNode parent();
 294     static AutomationNode firstChild();
 295     static AutomationNode lastChild();
 296     static AutomationNode previousSibling();
 297     static AutomationNode nextSibling();
 298
 299     // Does the default action based on this node's role. This is generally
 300     // the same action that would result from clicking the node such as
 301     // expanding a treeitem, toggling a checkbox, selecting a radiobutton,
 302     // or activating a button.
 303     static void doDefault();
 304
 305     // Places focus on this node.
 306     static void focus();
 307
 308     // Scrolls this node to make it visible.
 309     static void makeVisible();
 310
 311     // Sets selection within a text field.
 312     static void setSelection(long startIndex, long endIndex);
 313
 314     // Adds a listener for the given event type and event phase.
 315     static void addEventListener(
 316         EventType eventType, AutomationListener listener, boolean capture);
 317
 318     // Removes a listener for the given event type and event phase.
 319     static void removeEventListener(
 320         EventType eventType, AutomationListener listener, boolean capture);
 321
 322     // Gets the first node in this node's subtree which matches the given CSS
 323     // selector and is within the same DOM context.
 324     //
 325     // If this node doesn't correspond directly with an HTML node in the DOM,
 326     // querySelector will be run on this node's nearest HTML node ancestor. Note
 327     // that this may result in the query returning a node which is not a
 328     // descendant of this node.
 329     //
 330     // If the selector matches a node which doesn't directly correspond to an
 331     // automation node (for example an element within an ARIA widget, where the
 332     // ARIA widget forms one node of the automation tree, or an element which
 333     // is hidden from accessibility via hiding it using CSS or using
 334     // aria-hidden), this will return the nearest ancestor which does correspond
 335     // to an automation node.
 336     static void domQuerySelector(DOMString selector, QueryCallback callback);
 337
 338     // Finds the first AutomationNode in this node's subtree which matches the
 339     // given search parameters.
 340     static AutomationNode find(FindParams params);
 341
 342     // Finds all the AutomationNodes in this node's subtree which matches the
 343     // given search parameters.
 344     static AutomationNode[] findAll(FindParams params);
 345
 346     // Returns whether this node matches the given $(ref:automation.FindParams).
 347     static boolean matches(FindParams params);
 348   };
 349
 350   // Called when the <code>AutomationNode</code> for the page is available.
 351   callback RootCallback = void(AutomationNode rootNode);
 352
 353   interface Functions {
 354     // Get the automation tree for the tab with the given tabId, or the current
 355     // tab if no tabID is given, enabling automation if necessary. Returns a
 356     // tree with a placeholder root node; listen for the "loadComplete" event to
 357     // get a notification that the tree has fully loaded (the previous root node
 358     // reference will stop working at or before this point).
 359     [nocompile] static void getTree(optional long tabId, RootCallback callback);
 360
 361     // Get the automation tree for the whole desktop which consists of all on
 362     // screen views. Note this API is currently only supported on Chrome OS.
 363     [nocompile] static void getDesktop(RootCallback callback);
 364   };
 365 };