chrome/common/extensions/api/automation.idl

// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// The <code>chrome.automation</code> API allows developers to access the
// automation (accessibility) tree for the browser. The tree resembles the DOM
// tree, but only exposes the <em>semantic</em> structure of a page. It can be
// used to programmatically interact with a page by examining names, roles, and
// states, listening for events, and performing actions on nodes.
[nocompile] namespace automation {
  // Keep the following enums in sync with 'ui/accessibility/ax_enums.idl'.
  // They are kept here purely for extension docs generation.

  // Possible events fired on an $(ref:automation.AutomationNode).
  enum EventType {
    activedescendantchanged,
    alert,
    ariaAttributeChanged,
    autocorrectionOccured,
    blur,
    checkedStateChanged,
    childrenChanged,
    focus,
    hide,
    hover,
    invalidStatusChanged,
    layoutComplete,
    liveRegionChanged,
    loadComplete,
    locationChanged,
    menuEnd,
    menuListItemSelected,
    menuListValueChanged,
    menuPopupEnd,
    menuPopupStart,
    menuStart,
    rowCollapsed,
    rowCountChanged,
    rowExpanded,
    scrollPositionChanged,
    scrolledToAnchor,
    selectedChildrenChanged,
    selection,
    selectionAdd,
    selectionRemove,
    show,
    textChanged,
    textSelectionChanged,
    valueChanged
  };

  // Describes the purpose of an $(ref:automation.AutomationNode).
  enum RoleType {
    alertDialog,
    alert,
    annotation,
    application,
    article,
    banner,
    blockquote,
    browser,
    busyIndicator,
    button,
    buttonDropDown,
    canvas,
    cell,
    checkBox,
    client,
    colorWell,
    columnHeader,
    column,
    comboBox,
    complementary,
    contentInfo,
    date,
    dateTime,
    definition,
    descriptionListDetail,
    descriptionList,
    descriptionListTerm,
    desktop,
    details,
    dialog,
    directory,
    disclosureTriangle,
    div,
    document,
    drawer,
    editableText,
    embeddedObject,
    figcaption,
    figure,
    footer,
    form,
    grid,
    group,
    growArea,
    heading,
    helpTag,
    horizontalRule,
    iframe,
    ignored,
    imageMapLink,
    imageMap,
    image,
    incrementor,
    inlineTextBox,
    labelText,
    legend,
    link,
    listBoxOption,
    listBox,
    listItem,
    listMarker,
    list,
    locationBar,
    log,
    main,
    marquee,
    math,
    matte,
    menuBar,
    menuButton,
    menuItem,
    menuItemCheckBox,
    menuItemRadio,
    menuListOption,
    menuListPopup,
    menu,
    meter,
    navigation,
    note,
    outline,
    pane,
    paragraph,
    popUpButton,
    pre,
    presentational,
    progressIndicator,
    radioButton,
    radioGroup,
    region,
    rootWebArea,
    rowHeader,
    row,
    rulerMarker,
    ruler,
    svgRoot,
    scrollArea,
    scrollBar,
    seamlessWebArea,
    search,
    sheet,
    slider,
    sliderThumb,
    spinButtonPart,
    spinButton,
    splitGroup,
    splitter,
    staticText,
    status,
    systemWide,
    tabGroup,
    tabList,
    tabPanel,
    tab,
    tableHeaderContainer,
    table,
    textArea,
    textField,
    time,
    timer,
    titleBar,
    toggleButton,
    toolbar,
    treeGrid,
    treeItem,
    tree,
    unknown,
    tooltip,
    valueIndicator,
    webArea,
    webView,
    window
  };

  // Describes characteristics of an $(ref:automation.AutomationNode).
  enum StateType {
    busy,
    checked,
    collapsed,
    default,
    disabled,  // ui/views only
    editable,  // ui/views only
    enabled,   // content only
    expanded,
    focusable,
    focused,
    haspopup,
    hovered,
    indeterminate,
    invisible,
    linked,
    multiselectable,
    offscreen,
    pressed,
    protected,
    readOnly,
    required,
    selectable,
    selected,
    vertical,
    visited
  };

  dictionary Rect {
    long left;
    long top;
    long width;
    long height;
  };

  // Called when the result for a <code>query</code> is available.
  callback QueryCallback = void(AutomationNode node);

  // An event in the Automation tree.
  [nocompile, noinline_doc] dictionary AutomationEvent {
    // The $(ref:automation.AutomationNode) to which the event was targeted.
    AutomationNode target;

    // The type of the event.
    EventType type;

    // Stops this event from further processing except for any remaining
    // listeners on $(ref:AutomationEvent.target).
    static void stopPropagation();
  };

  // A listener for events on an <code>AutomationNode</code>.
  callback AutomationListener = void(AutomationEvent event);

  // A single node in an Automation tree.
  [nocompile, noinline_doc] dictionary AutomationNode {
    // The root node of the tree containing this AutomationNode.
    AutomationNode root;

    // Whether this AutomationNode is root node.
    boolean isRootNode;

    // The role of this node.
    automation.RoleType role;

    // The $(ref:automation.StateType)s describing this node.
    object state;

    // The rendered location (as a bounding box) of this node within the frame.
    automation.Rect location;

    // A collection of this node's other attributes.
    object? attributes;

    // The index of this node in its parent node's list of children. If this is
    // the root node, this will be undefined.
    long? indexInParent;

    static AutomationNode[] children();
    static AutomationNode parent();
    static AutomationNode firstChild();
    static AutomationNode lastChild();
    static AutomationNode previousSibling();
    static AutomationNode nextSibling();

    // Does the default action based on this node's role. This is generally
    // the same action that would result from clicking the node such as
    // expanding a treeitem, toggling a checkbox, selecting a radiobutton,
    // or activating a button.
    static void doDefault();

    // Places focus on this node.
    static void focus();

    // Scrolls this node to make it visible.
    static void makeVisible();

    // Sets selection within a text field.
    static void setSelection(long startIndex, long endIndex);

    // Adds a listener for the given event type and event phase.
    static void addEventListener(
        EventType eventType, AutomationListener listener, boolean capture);

    // Removes a listener for the given event type and event phase.
    static void removeEventListener(
        EventType eventType, AutomationListener listener, boolean capture);

    // Gets the first node in this node's subtree which matches the given CSS
    // selector and is within the same DOM context.
    //
    // If this node doesn't correspond directly with an HTML node in the DOM,
    // querySelector will be run on this node's nearest HTML node ancestor. Note
    // that this may result in the query returning a node which is not a
    // descendant of this node.
    //
    // If the selector matches a node which doesn't directly correspond to an
    // automation node (for example an element within an ARIA widget, where the
    // ARIA widget forms one node of the automation tree, or an element which
    // is hidden from accessibility via hiding it using CSS or using
    // aria-hidden), this will return the nearest ancestor which does correspond
    // to an automation node.
    static void querySelector(DOMString selector, QueryCallback callback);
  };

  // Called when the <code>AutomationNode</code> for the page is available.
  callback RootCallback = void(AutomationNode rootNode);

  interface Functions {
    // Get the automation tree for the tab with the given tabId, or the current
    // tab if no tabID is given, enabling automation if necessary. Returns a
    // tree with a placeholder root node; listen for the "loadComplete" event to
    // get a notification that the tree has fully loaded (the previous root node
    // reference will stop working at or before this point).
    [nocompile] static void getTree(optional long tabId, RootCallback callback);

    // Get the automation tree for the whole desktop which consists of all on
    // screen views. Note this API is currently only supported on Chrome OS.
    [nocompile] static void getDesktop(RootCallback callback);
  };
};