blob: 1452c107d290316a27eadeb01ec3bfda268090bd [file] [log] [blame]
// 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,
anchor,
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);
// 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);
// 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);
};
};