// Copyright 2021 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
/**
* @fileoverview Structures related to ranges, which are pairs of cursors over
* the automation tree.
*/
import {AutomationPredicate} from '../automation_predicate.js';
import {AutomationUtil} from '../automation_util.js';
import {constants} from '../constants.js';
import {TestImportManager} from '../testing/test_import_manager.js';
import {Cursor, CURSOR_NODE_INDEX, CursorMovement, CursorUnit, WrappingCursor} from './cursor.js';
type AutomationNode = chrome.automation.AutomationNode;
const RoleType = chrome.automation.RoleType;
const StateType = chrome.automation.StateType;
/**
* Represents a range in the automation tree. There is no visible selection on
* the page caused by usage of this object.
* It is assumed that the caller provides |start| and |end| in document order.
*/
export class CursorRange {
constructor(private start_: Cursor, private end_: Cursor) {}
/** Convenience method to construct a Range surrounding one node. */
static fromNode(node: AutomationNode): CursorRange {
const cursor = WrappingCursor.fromNode(node);
return new CursorRange(cursor, cursor);
}
/**
* Given |rangeA| and |rangeB| in order, determine which |constants.Dir|
* relates them.
*/
static getDirection(rangeA: CursorRange, rangeB: CursorRange): constants.Dir {
if (!rangeA || !rangeB) {
return constants.Dir.FORWARD;
}
if (!rangeA.start.node || !rangeA.end.node || !rangeB.start.node ||
!rangeB.end.node) {
return constants.Dir.FORWARD;
}
// They are the same range.
if (rangeA.start.node === rangeB.start.node &&
rangeB.end.node === rangeA.end.node) {
return constants.Dir.FORWARD;
}
const testDirA =
AutomationUtil.getDirection(rangeA.start.node, rangeB.end.node);
const testDirB =
AutomationUtil.getDirection(rangeB.start.node, rangeA.end.node);
// The two ranges are either partly overlapping or non overlapping.
if (testDirA === constants.Dir.FORWARD &&
testDirB === constants.Dir.BACKWARD) {
return constants.Dir.FORWARD;
} else if (
testDirA === constants.Dir.BACKWARD &&
testDirB === constants.Dir.FORWARD) {
return constants.Dir.BACKWARD;
} else {
return testDirA;
}
}
/**
* Returns true if |rhs| is equal to this range.
* Use this for strict equality between ranges.
*/
equals(rhs: CursorRange): boolean {
return this.start_.equals(rhs.start) && this.end_.equals(rhs.end);
}
/**
* Similar to above equals(), but does not trigger recovery in either start or
* end cursor. Use this for strict equality between ranges.
*/
equalsWithoutRecovery(rhs: CursorRange): boolean {
return this.start_.equalsWithoutRecovery(rhs.start) &&
this.end_.equalsWithoutRecovery(rhs.end);
}
/**
* Returns true if |rhs| is equal to this range.
* Use this for loose equality between ranges.
*/
contentEquals(rhs: CursorRange): boolean {
return this.start_.contentEquals(rhs.start) &&
this.end_.contentEquals(rhs.end);
}
/**
* Gets the directed end cursor of this range.
* @param dir Which endpoint cursor to return;
* constants.Dir.FORWARD for end,
* constants.Dir.BACKWARD for start.
*/
getBound(dir: constants.Dir): Cursor {
return dir === constants.Dir.FORWARD ? this.end_ : this.start_;
}
/**
* Returns true if either start or end of this range requires recovery.
*/
requiresRecovery(): boolean {
return this.start_.requiresRecovery() || this.end_.requiresRecovery();
}
get start(): Cursor {
return this.start_;
}
get end(): Cursor {
return this.end_;
}
/** Returns true if this range covers less than a node. */
isSubNode(): boolean {
const startIndex = this.start.index;
const endIndex = this.end.index;
return this.start.node === this.end.node && startIndex !== -1 &&
endIndex !== -1 && startIndex !== endIndex &&
(startIndex !== 0 || endIndex !== this.start.getText().length);
}
/**
* Returns true if this range covers inline text (i.e. each end points to an
* inlineTextBox).
*/
isInlineText(): boolean {
return this.start.node && this.end.node &&
this.start.node.role === this.end.node.role &&
this.start.node.role === RoleType.INLINE_TEXT_BOX;
}
/**
* Makes a Range which has been moved from this range by the given unit and
* direction.
*/
move(unit: CursorUnit, dir: constants.Dir): CursorRange {
let newStart = this.start_;
if (!newStart.node) {
return this;
}
let newEnd;
switch (unit) {
case CursorUnit.CHARACTER:
newStart = newStart.move(unit, CursorMovement.DIRECTIONAL, dir);
newEnd = newStart.move(
unit, CursorMovement.DIRECTIONAL, constants.Dir.FORWARD);
// Character crossed a node; collapses to the end of the node.
if (newStart.node !== newEnd.node) {
newEnd = new Cursor(newStart.node, newStart.index + 1);
}
break;
case CursorUnit.WORD:
case CursorUnit.LINE:
newStart = newStart.move(unit, CursorMovement.DIRECTIONAL, dir);
newStart =
newStart.move(unit, CursorMovement.BOUND, constants.Dir.BACKWARD);
newEnd =
newStart.move(unit, CursorMovement.BOUND, constants.Dir.FORWARD);
break;
case CursorUnit.NODE:
case CursorUnit.GESTURE_NODE:
newStart = newStart.move(unit, CursorMovement.DIRECTIONAL, dir);
newEnd = newStart;
break;
default:
throw Error('Invalid unit: ' + unit);
}
return new CursorRange(newStart, newEnd);
}
/** Select the text contained within this range. */
select(): void {
let start = this.start_;
let end = this.end_;
if (this.start.compare(this.end) === constants.Dir.BACKWARD) {
start = this.end;
end = this.start;
}
const startNode = start.selectionNode;
const endNode = end.selectionNode;
if (!startNode || !endNode) {
return;
}
// Only allow selections within the same web tree.
if (startNode.root && startNode.root.role === RoleType.ROOT_WEB_AREA &&
startNode.root === endNode.root) {
// We want to adjust to select the entire node for node offsets;
// otherwise, use the plain character offset.
const startIndex = start.selectionIndex;
let endIndex = end.index === CURSOR_NODE_INDEX ? end.selectionIndex + 1 :
end.selectionIndex;
// If the range covers more than one node, ends on the node, and is over
// text, then adjust the selection to cover the entire end node.
if (start.node !== end.node && end.index === CURSOR_NODE_INDEX &&
AutomationPredicate.text(end.node)) {
endIndex = end.getText().length;
}
// Richly editables should always set a caret, but not select. This
// makes it possible to navigate through content editables using
// ChromeVox keys and not hear selections as you go.
// TODO(b/314203187): Not nulls asserted, check these to make sure they
// are correct.
if (startNode.state![StateType.RICHLY_EDITABLE] ||
endNode.state![StateType.RICHLY_EDITABLE]) {
endIndex = startIndex;
}
chrome.automation.setDocumentSelection({
anchorObject: startNode,
anchorOffset: startIndex,
focusObject: endNode,
focusOffset: endIndex,
});
}
}
/**
* Returns a new range that matches to the given unit and direction in the
* current range. If no matching range is found, then null is returned.
* Note that there is a chance that new range's end spans beyond the current
* end when the given unit is larger than the current range.
*/
sync(unit: CursorUnit, dir: constants.Dir): CursorRange|null {
switch (unit) {
case CursorUnit.CHARACTER:
case CursorUnit.WORD:
let startCursor = this.start;
if (!AutomationPredicate.leafWithWordStop(startCursor.node)) {
let startNode: AutomationNode|null = startCursor.node;
// TODO(b/314203187): Not nulls asserted, check these to make sure
// they are correct.
if (dir === constants.Dir.FORWARD) {
startNode = AutomationUtil.findNextNode(
startNode!, constants.Dir.FORWARD,
AutomationPredicate.leafWithWordStop,
{skipInitialSubtree: false});
} else {
startNode = AutomationUtil.findNodePost(
startNode!, dir, AutomationPredicate.leafWithWordStop);
}
if (!startNode) {
return null;
}
startCursor = WrappingCursor.fromNode(startNode);
}
const start = startCursor.move(unit, CursorMovement.SYNC, dir);
if (!start) {
return null;
}
let end = start.move(unit, CursorMovement.BOUND, constants.Dir.FORWARD);
if (start.node !== end.node || start.equals(end)) {
// Character crossed a node or reached the end.
// Collapses to the end of the node.
end = new WrappingCursor(start.node, start.getText().length);
}
return new CursorRange(start, end);
case CursorUnit.LINE:
let newNode;
if (dir === constants.Dir.FORWARD) {
newNode = AutomationUtil.findNodeUntil(
this.start.node, dir, AutomationPredicate.linebreak);
} else {
newNode = AutomationUtil.findLastNode(
this.start.node, AutomationPredicate.leaf);
}
if (!newNode) {
return null;
}
return CursorRange.fromNode(newNode);
case CursorUnit.TEXT:
case CursorUnit.NODE:
case CursorUnit.GESTURE_NODE:
const pred = Cursor.getLeafPredForUnit(unit);
let node;
if (dir === constants.Dir.FORWARD) {
node = AutomationUtil.findNextNode(
this.start.node, constants.Dir.FORWARD, pred,
{skipInitialSubtree: false});
} else {
node = AutomationUtil.findNodePost(this.start.node, dir, pred);
}
if (!node) {
return null;
}
return CursorRange.fromNode(node);
default:
throw Error('Invalid unit: ' + unit);
}
}
/** Returns true if this range has either cursor end on web content. */
isWebRange(): boolean {
// TODO(b/314203187): Not nulls asserted, check these to make sure they
// are correct.
return this.isValid() &&
(this.start.node.root!.role !== RoleType.DESKTOP ||
this.end.node.root!.role !== RoleType.DESKTOP);
}
/** Returns whether this range has valid start and end cursors. */
isValid(): boolean {
return this.start.isValid() && this.end.isValid();
}
/**
* Compares this range with |rhs|.
* @return constants.Dir.BACKWARD if |rhs| comes
* before this range in
* document order. constants.Dir.FORWARD if |rhs| comes after this range.
* Undefined otherwise.
*/
compare(rhs: CursorRange): constants.Dir|undefined {
const startDir = this.start.compare(rhs.start);
const endDir = this.end.compare(rhs.end);
if (startDir !== endDir) {
return undefined;
}
return startDir;
}
/** Returns an undirected version of this range. */
normalize(): CursorRange {
if (this.start.compare(this.end) === constants.Dir.BACKWARD) {
return new CursorRange(this.end, this.start);
}
return this;
}
/**
* Returns true if this range was created after wrapping. For example, moving
* from a range at the end of a web contents to [this] range at the beginning
* of the document.
*/
get wrapped(): boolean {
return this.start_.wrapped || this.end_.wrapped;
}
}
TestImportManager.exportForTesting(CursorRange);
Codebase Browser
chromium