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. This is a tree
   7 // representation, analogous to the DOM tree, which represents the
   8 // <em>semantic</em> structure of a page, and can be used to programmatically
   9 // interact with a page.
  10 [nocompile] namespace automation {
  11   dictionary Rect {
  12     long left;
  13     long top;
  14     long width;
  15     long height;
  16   };
  17
  18   // An event in the Automation tree.
  19   [nocompile] dictionary AutomationEvent {
  20     // The $(ref:automation.AutomationNode) to which the event was targeted.
  21     AutomationNode target;
  22
  23     // The type of the event.
  24     DOMString type;
  25
  26     // Prevents all other event listeners from being triggered for this event
  27     // dispatch.
  28     static void stopPropagation();
  29   };
  30
  31   // A listener for events on an <code>AutomationNode</code>.
  32   callback AutomationListener = void(AutomationEvent event);
  33
  34   // A single node in an <code>AutomationTree</code>.
  35   [nocompile] dictionary AutomationNode {
  36     // Unique ID to identify this node.
  37     long id;
  38
  39     // The role of this node, e.g. button, static text etc.
  40     DOMString role;
  41
  42     // The state of this node, e.g. {pressed": true, "inactive": true} etc.
  43     object state;
  44
  45     // The rendered location (as a bounding box) of this node within the frame.
  46     Rect location;
  47
  48     // A collection of this node's other attributes.
  49     // TODO(aboxhall): Create and use combined list of attributes from
  50     // AXStringAttribute, AXIntAttribute etc.
  51     object? attributes;
  52
  53     // The index of this node in its parent node's list of children. If this is
  54     // the root node, this will be undefined.
  55     long? indexInParent;
  56
  57     // Traversal.
  58     static object[] children();
  59     static object parent();
  60     static object firstChild();
  61     static object lastChild();
  62     static object previousSibling();
  63     static object nextSibling();
  64
  65     // Actions.
  66     static void doDefault();
  67     static void focus();
  68     static void makeVisible();
  69     static void setSelection(long startIndex, long endIndex);
  70
  71     // Events.
  72     static void addEventListener(
  73         DOMString eventType, AutomationListener listener, bool capture);
  74     static void removeEventListener(
  75         DOMString eventType, AutomationListener listener, bool capture);
  76   };
  77
  78   // The automation tree for a single page.
  79   [nocompile] dictionary AutomationTree {
  80     AutomationNode root;
  81
  82     static void addEventListener(
  83         DOMString eventType, AutomationListener listener, bool capture);
  84     static void removeEventListener(
  85         DOMString eventType, AutomationListener listener, bool capture);
  86   };
  87
  88   // Called when the <code>AutomationTree</code> for the page is available.
  89   callback RootCallback = void(AutomationTree tree);
  90
  91   interface Functions {
  92     // Get the automation tree for the current tab, enabling automation if
  93     // necessary. Returns a tree with a placeholder root node; listen for
  94     // the "load_complete" event to get a notification that the tree has fully
  95     // loaded (the previous root node reference will stop working at or before
  96     // this point).
  97     [nocompile] static void getTree(RootCallback callback);
  98
  99     // Get the automation tree for the desktop.
 100     [nocompile] static void getDesktop(RootCallback callback);
 101   };
 102 };