// 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,
    documentTitleChanged,
    expandedChanged,
    focus,
    focusContext,
    imageFrameUpdated,
    hide,
    hitTestResult,
    hover,
    invalidStatusChanged,
    layoutComplete,
    liveRegionCreated,
    liveRegionChanged,
    loadComplete,
    loadStart,
    locationChanged,
    mediaStartedPlaying,
    mediaStoppedPlaying,
    menuEnd,
    menuListItemSelected,
    menuListValueChanged,
    menuPopupEnd,
    menuPopupHide,
    menuPopupStart,
    menuStart,
    mouseCanceled,
    mouseDragged,
    mouseMoved,
    mousePressed,
    mouseReleased,
    rowCollapsed,
    rowCountChanged,
    rowExpanded,
    scrollPositionChanged,
    scrolledToAnchor,
    selectedChildrenChanged,
    selection,
    selectionAdd,
    selectionRemove,
    show,
    stateChanged,
    textChanged,
    textSelectionChanged,
    windowActivated,
    windowDeactivated,
    treeChanged,
    valueChanged
  };

  // Describes the purpose of an $(ref:automation.AutomationNode).
  enum RoleType {
    abbr,
    alert,
    alertDialog,
    anchor,
    annotation,
    application,
    article,
    audio,
    banner,
    blockquote,
    button,
    canvas,
    caption,
    caret,
    cell,
    checkBox,
    client,
    colorWell,
    column,
    columnHeader,
    comboBoxGrouping,
    comboBoxMenuButton,
    complementary,
    contentDeletion,
    contentInsertion,
    contentInfo,
    date,
    dateTime,
    definition,
    descriptionList,
    descriptionListDetail,
    descriptionListTerm,
    desktop,
    details,
    dialog,
    directory,
    disclosureTriangle,
    // --------------------------------------------------------------
    // DPub Roles:
    // https://www.w3.org/TR/dpub-aam-1.0/#mapping_role_table
    docAbstract,
    docAcknowledgments,
    docAfterword,
    docAppendix,
    docBackLink,
    docBiblioEntry,
    docBibliography,
    docBiblioRef,
    docChapter,
    docColophon,
    docConclusion,
    docCover,
    docCredit,
    docCredits,
    docDedication,
    docEndnote,
    docEndnotes,
    docEpigraph,
    docEpilogue,
    docErrata,
    docExample,
    docFootnote,
    docForeword,
    docGlossary,
    docGlossRef,
    docIndex,
    docIntroduction,
    docNoteRef,
    docNotice,
    docPageBreak,
    docPageList,
    docPart,
    docPreface,
    docPrologue,
    docPullquote,
    docQna,
    docSubtitle,
    docTip,
    docToc,
    // End DPub roles.
    // --------------------------------------------------------------
    document,
    embeddedObject,
    feed,
    figcaption,
    figure,
    footer,
    form,
    genericContainer,
    // --------------------------------------------------------------
    // ARIA Graphics module roles:
    // https://rawgit.com/w3c/graphics-aam/master/#mapping_role_table
    graphicsDocument,
    graphicsObject,
    graphicsSymbol,
    // End ARIA Graphics module roles.
    // --------------------------------------------------------------
    grid,
    group,
    heading,
    iframe,
    iframePresentational,
    ignored,
    image,
    imageMap,
    inlineTextBox,
    inputTime,
    keyboard,
    labelText,
    layoutTable,
    layoutTableCell,
    layoutTableColumn,
    layoutTableRow,
    legend,
    lineBreak,
    link,
    list,
    listBox,
    listBoxOption,
    listGrid,  // Native
    listItem,
    listMarker,
    log,
    main,
    mark,
    marquee,
    math,
    menu,
    menuBar,
    menuButton,
    menuItem,
    menuItemCheckBox,
    menuItemRadio,
    menuListOption,
    menuListPopup,
    meter,
    navigation,
    note,
    pane,
    paragraph,
    popUpButton,
    pre,
    presentational,
    progressIndicator,
    radioButton,
    radioGroup,
    region,
    rootWebArea,
    row,
    rowHeader,
    ruby,
    scrollBar,
    scrollView,
    search,
    searchBox,
    slider,
    sliderThumb,
    spinButton,
    splitter,
    staticText,
    status,
    svgRoot,
    switch,
    tab,
    tabList,
    tabPanel,
    table,
    tableHeaderContainer,
    term,
    textField,
    textFieldWithComboBox,
    time,
    timer,
    titleBar,
    toggleButton,
    toolbar,
    tooltip,
    tree,
    treeGrid,
    treeItem,
    unknown,
    video,
    webArea,
    webView,
    window
  };

  // Describes characteristics of an $(ref:automation.AutomationNode).
  enum StateType {
    autofillAvailable,
    collapsed,
    default,
    editable,
    expanded,
    focusable,
    focused,
    horizontal,
    hovered,
    ignored,
    invisible,
    linked,
    multiline,
    multiselectable,
    offscreen,
    protected,
    required,
    richlyEditable,
    vertical,
    visited
  };

  // All possible actions that can be performed on automation nodes.
  enum ActionType {
    annotatePageImages,
    blur,
    clearAccessibilityFocus,
    customAction,
    decrement,
    doDefault,
    focus,
    getImageData,
    getTextLocation,
    hitTest,
    increment,
    loadInlineTextBoxes,
    replaceSelectedText,
    scrollBackward,
    scrollDown,
    scrollForward,
    scrollLeft,
    scrollRight,
    scrollUp,
    scrollToMakeVisible,
    scrollToPoint,
    setAccessibilityFocus,
    setScrollOffset,
    setSelection,
    setSequentialFocusNavigationStartingPoint,
    setValue,
    showContextMenu
  };

  // 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,
    /**
     * This subtree has finished an update.
     */
    subtreeUpdateEnd
  };

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

  // The input restriction for a object -- even non-controls can be disabled.
  enum Restriction {
    disabled,
    readOnly
  };

  // Indicates the availability and type of interactive popup element
  enum HasPopup {
    true,
    menu,
    listbox,
    tree,
    grid,
    dialog
  };

  // Describes possible actions when performing a do default action.
  enum DefaultActionVerb {
    activate,
    check,
    click,
    clickAncestor,
    jump,
    open,
    press,
    select,
    uncheck
};

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

  // Callback called for actions with a response.
  callback PerformActionCallback = void(boolean result);
  callback PerformActionCallbackWithNode = void(AutomationNode node);
  callback BoundsForRangeCallback = void(Rect bounds);


  dictionary CustomAction {
    long id;
    DOMString description;
  };

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

    // Determines the location of the text within the node specified by
    // |startIndex| and |endIndex|, inclusively. Invokes |callback| with the
    // bounding rectangle, in screen coordinates. |callback| can be invoked
    // either synchronously or asynchronously.
    static void boundsForRange(long startIndex, long endIndex,
        BoundsForRangeCallback callback);

    // The location (as a bounding box) of this node in global screen
    // coordinates without applying any clipping from ancestors.
    Rect? unclippedLocation;

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

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

    // The role description for this node.
    DOMString? roleDescription;

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

    // Reverse relationship for active descendant.
    AutomationNode[]? activeDescendantFor;

    // The target of an in-page link.
    AutomationNode? inPageLinkTarget;

    // A node that provides more details about the current node.
    AutomationNode? details;

    // A node that provides an error message for a current node.
    AutomationNode? errorMessage;

    // Reverse relationship for details.
    AutomationNode[]? detailsFor;

    // Reverse relationship for errorMessage.
    AutomationNode[]? errorMessageFor;

    // Reverse relationship for controls.
    AutomationNode[]? controlledBy;

    // Reverse relationship for describedBy.
    AutomationNode[]? descriptionFor;

    // Reverse relationship for flowTo.
    AutomationNode[]? flowFrom;

    // Reverse relationship for labelledBy.
    AutomationNode[]? labelFor;

    // The column header nodes for a table cell.
    AutomationNode[]? tableCellColumnHeaders;

    // The row header nodes for a table cell.
    AutomationNode[]? tableCellRowHeaders;

    // An array of standard actions available on this node.
    ActionType[]? standardActions;

    // An array of custom actions.
    CustomAction[]? customActions;

    // The action taken by calling <code>doDefault</code>.
    DefaultActionVerb? defaultActionVerb;

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

    // Indicates whether this node is scrollable.
    boolean? scrollable;

    //
    // 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 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 as specified in the DOM.
    long? tableRowCount;

    // The number of rows in this table as specified by the page author.
    long? ariaRowCount;

    // The number of columns in this table as specified in the DOM.
    long? tableColumnCount;

    // The number of columns in this table as specified by the page author.
    long? ariaColumnCount;

    //
    // Table cell attributes.
    //

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

    // The ARIA column index as specified by the page author.
    long? ariaCellColumnIndex;

    // 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 as specified in the
    // DOM.
    long? tableCellRowIndex;

    // The ARIA row index as specified by the page author.
    long? ariaCellRowIndex;

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

    // The column index of this column node.
    long? tableColumnIndex;

    // The row index of this row node.
    long? tableRowIndex;

    //
    // 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 or any other element.
    boolean? busy;

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

    // Aria auto complete.
    DOMString? autoComplete;

    // The name of the programmatic backing object.
    DOMString? className;

    // Marks this subtree as modal.
    boolean? modal;

    // 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 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 author-provided language code for this subtree.
    DOMString? language;

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

    // Indicates the availability and type of interactive popup element
    // true - the popup is a menu
    // menu - the popup is a menu
    // listbox - the popup is a listbox
    // tree - the popup is a tree
    // grid - the popup is a grid
    // dialog - the popup is a dialog
    DOMString? hasPopup;

    // Input restriction, if any, such as readonly or disabled:
    // undefined - enabled control or other object that is not disabled
    // Restriction.DISABLED - disallows input in itself + any descendants
    // Restriction.READONLY - allow focus/selection but not input
    DOMString? restriction;

    // Tri-state describing checkbox or radio button:
    // 'false' | 'true' | 'mixed'
    DOMString? checked;

    // The inner html of this element. Only populated for math content.
    DOMString? innerHtml;

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

    // Indicates node text is subscript.
    boolean subscript;

    // Indicates node text is superscript.
    boolean superscript;

    // Indicates node text is bold.
    boolean bold;

    // Indicates node text is italic.
    boolean italic;

    // Indicates node text is underline.
    boolean underline;

    // Indicates node text is line through.
    boolean lineThrough;

    // Indicates whether this node is selected, unselected, or neither.
    boolean? selected;

    //
    // Walking the tree.
    //

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

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

    // Does a hit test of the given global screen coordinates, and fires
    // eventToFire on the resulting object.
    static void hitTest(
        long x,
        long y,
        EventType eventToFire);

    // Does a $(ref:automation.AutomationNode.hitTest), and receives a callback
    // with the resulting hit node.
    static void hitTestWithReply(
        long x,
        long y,
        PerformActionCallbackWithNode callback);

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

    // Performs custom action.
    static void performCustomAction(long customActionId);

    // Convenience method to perform a standard action supported by this node.
    // For actions requiring additional arguments, call the specific binding
    // e.g. <code>setSelection</code>.
    static void performStandardAction(ActionType actionType);

    // Replaces the selected text within a text field.
    static void replaceSelectedText(DOMString value);

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

    // Sets the value of a text field.
    static void setValue(DOMString value);

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

    // Scrolls this scrollable container backward.
    static void scrollBackward(PerformActionCallback callback);

    // Scrolls this scrollable container forward.
    static void scrollForward(PerformActionCallback callback);

    // Scrolls this scrollable container up.
    static void scrollUp(PerformActionCallback callback);

    // Scrolls this scrollable container down.
    static void scrollDown(PerformActionCallback callback);

    // Scrolls this scrollable container left.
    static void scrollLeft(PerformActionCallback callback);

    // Scrolls this scrollable container right.
    static void scrollRight(PerformActionCallback callback);

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

    static AutomationNode getNextTextMatch(
        DOMString searchStr, boolean backward);
  };

  // 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,
                                    optional 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);
  };
};