path: root/chromium/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,
    clicked,
    documentSelectionChanged,
    expandedChanged,
    focus,
    imageFrameUpdated,
    hide,
    hover,
    invalidStatusChanged,
    layoutComplete,
    liveRegionCreated,
    liveRegionChanged,
    loadComplete,
    locationChanged,
    mediaStartedPlaying,
    mediaStoppedPlaying,
    menuEnd,
    menuListItemSelected,
    menuListValueChanged,
    menuPopupEnd,
    menuPopupStart,
    menuStart,
    mouseCanceled,
    mouseDragged,
    mouseMoved,
    mousePressed,
    mouseReleased,
    rowCollapsed,
    rowCountChanged,
    rowExpanded,
    scrollPositionChanged,
    scrolledToAnchor,
    selectedChildrenChanged,
    selection,
    selectionAdd,
    selectionRemove,
    show,
    textChanged,
    textSelectionChanged,
    treeChanged,
    valueChanged
  };

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

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

  // Possible changes to the automation tree. For any given atomic change
  // to the tree, each node that's added, removed, or changed, will appear
  // in exactly one TreeChange, with one of these types.
  //
  //
  // nodeCreated means that this node was added to the tree and its parent is
  // new as well, so it's just one node in a new subtree that was added.
  enum TreeChangeType {
    /**
     * This node was added to the tree and its parent is new as well,
     * so it's just one node in a new subtree that was added.
     */
    nodeCreated,

    /**
     * This node was added to the tree but its parent was already in the
     * tree, so it's possibly the root of a new subtree - it does not mean
     * that it necessarily has children.
     */
    subtreeCreated,

    /**
     * This node changed.
     */
    nodeChanged,

    /**
     * This node's text (name) changed.
     */
    textChanged,

    /**
     * This node was removed.
     */
    nodeRemoved
  };

  // Where the node's name is from.
  enum NameFromType {
    uninitialized,
    attribute,
    contents,
    placeholder,
    relatedElement,
    value
  };

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

  // Arguments for the find() and findAll() methods.
  [nocompile, noinline_doc] dictionary FindParams {
    RoleType? role;

    // A map of $(ref:automation.StateType) to boolean, indicating for each
    // state whether it should be set or not. For example:
    // <code>{ StateType.disabled: false }</code> would only match if
    // <code>StateType.disabled</code> was <em>not</em> present in the node's
    // <code>state</code> object.
    object? state;

    // A map of attribute name to expected value, for example
    // <code>{ name: 'Root directory', checkbox_mixed: true }</code>.
    // String attribute values may be specified as a regex, for example
    // <code>{ name: /stralia$/</code> }</code>.
    // Unless specifying a regex, the expected value must be an exact match
    // in type and value for the actual value. Thus, the type of expected value
    // must be one of:
    // <ul>
    // <li>string</li>
    // <li>integer</li>
    // <li>float</li>
    // <li>boolean</li>
    // </ul>
    object? attributes;
  };

  // Arguments for the setDocumentSelection() function.
  [nocompile, noinline_doc] dictionary SetDocumentSelectionParams {
    // The node where the selection begins.
    [instanceOf=AutomationNode] object anchorObject;
    // The offset in the anchor node where the selection begins.
    long anchorOffset;
    // The node where the selection ends.
    [instanceOf=AutomationNode] object focusObject;
    // The offset within the focus node where the selection ends.
    long focusOffset;
  };

  // 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;

    // The source of this event.
    DOMString eventFrom;

    long mouseX;
    long mouseY;

    // 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 change to the Automation tree.
  [nocompile, noinline_doc] dictionary TreeChange {
    // The $(ref:automation.AutomationNode) that changed.
    AutomationNode target;

    // The type of change.
    TreeChangeType type;
  };

  // Possible tree changes to listen to using addTreeChangeObserver.
  // Note that listening to all tree changes can be expensive.
  enum TreeChangeObserverFilter {
    noTreeChanges,
    liveRegionTreeChanges,
    textMarkerChanges,
    allTreeChanges
  };

  // A listener for changes on the <code>AutomationNode</code> tree.
  callback TreeChangeObserver = void(TreeChange treeChange);

  // 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 a root node.
    boolean isRootNode;

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

    // The $(ref:automation.StateType)s describing this node.
    // <jsexterns>@type {Object<chrome.automation.StateType, boolean>}
    // </jsexterns>
    object? state;

    // The rendered location (as a bounding box) of this node in global
    // screen coordinates.
    Rect? location;

    // Computes the bounding box of a subrange of this node in global screen
    // coordinates. Returns the same as |location| if range information
    // is not available. The start and end indices are zero-based offsets
    // into the node's "name" string attribute.
    static Rect boundsForRange(long startIndex, long endIndex);

    // The purpose of the node, other than the role, if any.
    DOMString? description;

    // The placeholder for this text field, if any.
    DOMString? placeholder;

    // The accessible name for this node, via the
    // <a href="http://www.w3.org/TR/wai-aria/roles#namecalculation">
    // Accessible Name Calculation</a> process.
    DOMString? name;

    // The source of the name.
    NameFromType? nameFrom;

    // The value for this node: for example the <code>value</code> attribute of
    // an <code>&lt;input&gt; element.
    DOMString? value;

    // The HTML tag for this element, if this node is an HTML element.
    DOMString? htmlTag;

    // The level of a heading or tree item.
    long? hierarchicalLevel;

    // The start and end index of each word in an inline text box.
    long[]? wordStarts;
    long[]? wordEnds;

    // The nodes, if any, which this node is specified to control via
    // <a href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-controls">
    // <code>aria-controls</code></a>.
    AutomationNode[]? controls;

    // The nodes, if any, which form a description for this node.
    AutomationNode[]? describedBy;

    // The nodes, if any, which may optionally be navigated to after this
    // one. See
    // <a href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-flowto">
    // <code>aria-flowto</code></a>.
    AutomationNode[]? flowTo;

    // The nodes, if any, which form a label for this element. Generally, the
    // text from these elements will also be exposed as the element's accessible
    // name, via the $(ref:automation.AutomationNode.name) attribute.
    AutomationNode[]? labelledBy;

    // The node referred to by <code>aria-activedescendant</code>, where
    // applicable
    AutomationNode? activeDescendant;

    //
    // Link attributes.
    //

    // The URL that this link will navigate to.
    DOMString? url;

    //
    // Document attributes.
    //

    // The URL of this document.
    DOMString? docUrl;

    // The title of this document.
    DOMString? docTitle;

    // Whether this document has finished loading.
    boolean? docLoaded;

    // The proportion (out of 1.0) that this doc has completed loading.
    double? docLoadingProgress;

    //
    // Scrollable container attributes.
    //

    long? scrollX;
    long? scrollXMin;
    long? scrollXMax;
    long? scrollY;
    long? scrollYMin;
    long? scrollYMax;

    //
    // Editable text field attributes.
    //

    // The character index of the start of the selection within this editable
    // text element; -1 if no selection.
    long? textSelStart;

    // The character index of the end of the selection within this editable
    // text element; -1 if no selection.
    long? textSelEnd;

    // The input type, like email or number.
    DOMString? textInputType;

    // An array of indexes of the break between lines in editable text.
    long[] lineBreaks;

    // An array of indexes of the start position of each text marker.
    long[] markerStarts;

    // An array of indexes of the end position of each text marker.
    long[] markerEnds;

    // An array of numerical types indicating the type of each text marker,
    // such as a spelling error.
    long[] markerTypes;

    //
    // Tree selection attributes (available on root nodes only)
    //

    // The anchor node of the tree selection, if any.
    AutomationNode? anchorObject;
    // The anchor offset of the tree selection, if any.
    long? anchorOffset;
    // The affinity of the tree selection anchor, if any.
    DOMString? anchorAffinity;
    // The focus node of the tree selection, if any.
    AutomationNode? focusObject;
    // The focus offset of the tree selection, if any.
    long? focusOffset;
    // The affinity of the tree selection focus, if any.
    DOMString? focusAffinity;

    //
    // Range attributes.
    //

    // The current value for this range.
    double? valueForRange;

    // The minimum possible value for this range.
    double? minValueForRange;

    // The maximum possible value for this range.
    double? maxValueForRange;

    //
    // List attributes.
    //

    // The 1-based index of an item in a set.
    long? posInSet;

    // The number of items in a set;
    long? setSize;

    //
    // Table attributes.
    //

    // The number of rows in this table.
    long? tableRowCount;

    // The number of columns in this table.
    long? tableColumnCount;

    //
    // Table cell attributes.
    //

    // The zero-based index of the column that this cell is in.
    long? tableCellColumnIndex;

    // The number of columns that this cell spans (default is 1).
    long? tableCellColumnSpan;

    // The zero-based index of the row that this cell is in.
    long? tableCellRowIndex;

    // The number of rows that this cell spans (default is 1).
    long? tableCellRowSpan;

    // The corresponding column header for this cell.
    AutomationNode? tableColumnHeader;

    // The corresponding row header for this cell.
    AutomationNode? tableRowHeader;

    //
    // Live region attributes.
    //

    // The type of region if this is the root of a live region.
    // Possible values are 'polite' and 'assertive'.
    DOMString? liveStatus;

    // The value of aria-relevant for a live region.
    DOMString? liveRelevant;

    // The value of aria-atomic for a live region.
    boolean? liveAtomic;

    // The value of aria-busy for a live region.
    boolean? liveBusy;

    // The type of live region if this node is inside a live region.
    DOMString? containerLiveStatus;

    // The value of aria-relevant if this node is inside a live region.
    DOMString? containerLiveRelevant;

    // The value of aria-atomic if this node is inside a live region.
    boolean? containerLiveAtomic;

    // The value of aria-busy if this node is inside a live region.
    boolean? containerLiveBusy;

    //
    // Miscellaneous attributes.
    //

    // A map containing all HTML attributes and their values
    // <jsexterns>@type {Object<string>}</jsexterns>
    object? htmlAttributes;

    // The input type of a text field, such as "text" or "email".
    DOMString? inputType;

    // The key that activates this widget.
    DOMString? accessKey;

    // The value of the aria-invalid attribute, indicating the error type.
    DOMString? ariaInvalidValue;

    // The value of the aria-readonly attribute, if applicable.
    boolean? ariaReadonly;

    // The CSS display attribute for this node, if applicable.
    DOMString? display;

    // A data url with the contents of this object's image or thumbnail.
    DOMString? imageDataUrl;

    // The language code for this subtree.
    DOMString? language;

    // If a checkbox or toggle button is in the mixed state.
    boolean? buttonMixed;

    // The RGBA foreground color of this subtree, as an integer.
    long? color;

    // The RGBA background color of this subtree, as an integer.
    long? backgroundColor;

    // The RGBA color of an input element whose value is a color.
    long? colorValue;

    //
    // Walking the tree.
    //

    AutomationNode[] children;
    AutomationNode? parent;
    AutomationNode? firstChild;
    AutomationNode? lastChild;
    AutomationNode? previousSibling;
    AutomationNode? nextSibling;
    AutomationNode? nextOnLine;
    AutomationNode? previousOnLine;

    // 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;

    //
    // Actions.
    //

    // 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();

    // Request a data url for the contents of an image, optionally
    // resized.  Pass zero for maxWidth and/or maxHeight for the
    // original size.
    static void getImageData(long maxWidth, long maxHeight);

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

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

    // Clears focus and sets this node as the starting point for the next
    // time the user presses Tab or Shift+Tab.
    static void setSequentialFocusNavigationStartingPoint();

    // Show the context menu for this element, as if the user right-clicked.
    static void showContextMenu();

    // Resume playing any media within this tree.
    static void resumeMedia();

    // Start ducking any media within this tree.
    static void startDuckingMedia();

    // Stop ducking any media within this tree.
    static void stopDuckingMedia();

    // Suspend any media playing within this tree.
    static void suspendMedia();

    // 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 domQuerySelector(DOMString selector, QueryCallback callback);

    // Finds the first AutomationNode in this node's subtree which matches the
    // given search parameters.
    static AutomationNode find(FindParams params);

    // Finds all the AutomationNodes in this node's subtree which matches the
    // given search parameters.
    static AutomationNode[] findAll(FindParams params);

    // Returns whether this node matches the given $(ref:automation.FindParams).
    static boolean matches(FindParams params);
  };

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

  // Called with the <code>AutomationNode</code> that currently has focus.
  callback FocusCallback = void(AutomationNode focusedNode);

  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);

    // Get the automation node that currently has focus, globally. Will return
    // null if none of the nodes in any loaded trees have focus.
    [nocompile] static void getFocus(FocusCallback callback);

    // Add a tree change observer. Tree change observers are static/global, they
    // listen to changes across all trees. Pass a filter to determine what
    // specific tree changes to listen to, and note that listnening to all
    // tree changes can be expensive.
    [nocompile] static void addTreeChangeObserver(
        TreeChangeObserverFilter filter, TreeChangeObserver observer);

    // Remove a tree change observer.
    [nocompile] static void removeTreeChangeObserver(
        TreeChangeObserver observer);

    // Sets the selection in a tree. This creates a selection in a single
    // tree (anchorObject and focusObject must have the same root).
    // Everything in the tree between the two node/offset pairs gets included
    // in the selection. The anchor is where the user started the selection,
    // while the focus is the point at which the selection gets extended
    // e.g. when dragging with a mouse or using the keyboard. For nodes with
    // the role staticText, the offset gives the character offset within
    // the value where the selection starts or ends, respectively.
    [nocompile] static void setDocumentSelection(
        SetDocumentSelectionParams params);
  };
};