The TextRange object--similar in concept to the Netscape 6 and W3C DOM Range objectrepresents the text of zero or more characters in a document. When a text range consists of zero characters, it represents an insertion point between two characters (or before the first or after the last character).

Return the pixel measure of the imaginary space occupied by the TextRange object. Although you do not see a TextRange object in the document (unless a script selects it), the area of a TextRange object is identical to the area that a selection highlight would occupy. These values cinch up to measure only as wide or tall as the widest and tallest part of the range. You would arrive at these same values by performing arithmetic on values returned from the getBoundingClientRect( ) method.

Return the pixel distance between the top or left of the browser window or frame and the top or left edges of the imaginary space occupied by the TextRange object. Although you do not see a TextRange object in the document (unless a script selects it), the area of a TextRange object is identical to the area that a selection highlight would occupy. Values for these properties are measured from the fixed window or frame edges and not the top and left of the document, which may scroll out of view. Therefore, as a document scrolls, these values change.

Specifies all HTML of the document for a given element when that element is used as the basis for a TextRange object. For example, if you create a TextRange for the body element (document.body.createTextRange( )), the htmlText property contains all HTML content between (but not including) the body element tags.

Indicates the text contained by the text range. In the case of a TextRange object of a body element, this consists of only the text that is rendered, but none of the HTML tags behind the scenes.

Reduces the TextRange object to a length of zero (creating an insertion point) at the beginning or end of the text range before it collapsed.

Compares the relative position of the boundary (start and end) points of two ranges (the current range and one that had been previously saved to a variable). The first parameter defines which boundary points in each range you wish to compare. If the result of the comparison is that the first point is earlier in the range than the other point, the returned value is -1. If the result shows both points to be in the same location, the returned value is 0. If the result shows the first point to be later in the range than the other point, the returned value is 1. For example, if you have saved the first range to a variable r1 and created a new range as r2, you can see the physical relationship between the end of r2 and the start of r1:

r1.compareEndPoints("EndToStart", r2)

Creates a new TextRange object with the same values as the current range. The new object is an independent object (the old and new do not equal each other), but their values are initially identical (until you start modifying one range or the other).

Executes the named command on the current TextRange object. Many commands work best when the TextRange object is an insertion point. See Appendix D for a list of commands.

Expands the current text range (including a collapsed range) to encompass the textual unit passed as a parameter. For example, if someone selects some characters from a document, you can create the range and expand it to encompass the entire sentence in which the selection takes place:

var rng = document.selection.createRange( );
rng.expand("sentence");

Searches the current TextRange object for a match of a string passed as the required first parameter. By default, matching is done on a case-insensitive basis. If there is a match, the TextRange object repositions its start and end points to surround the found text. To continue searching in the document, you must reposition the start point of the text range to the end of the found string (with collapse( )).

These two methods work together as a way to temporarily save a text range specification and restore it when needed. The getBookmark( ) method returns an opaque string (containing binary data that is of no value to human users). Once that value is stored in a variable, the range can be modified as needed for the script. Some time later, the bookmarked text range can be restored with the moveToBookmark( ) method:

var rangeMark = myRange.getBookmark( );
...
myRange.moveToBookmark(rangeMark);

Determines whether the comparison range is within or equal to the physical range of the current text range.

Determines whether the comparison range is identical to the current text range.

Collapses the current text range to an insertion point at the end of the current range and moves it forward or backward from the current position by one or more units.

Moves only the end or start point (respectively) of the current text range by one or more units. An optional parameter lets you specify both the number of units and direction. To shift the start point of a text range toward the beginning of the original range, be sure to specify a negative value. When moving the end point forward by word units, be aware that a word ends with a whitespace character (including a period). Therefore, if a findText( ) method sets the range to a found string that does not end in a space, the first moveEnd("word") method moves the ending point to the spot past the space after the found string rather than to the following word.

See getBookmark( ).

Moves the current TextRange object's start and end points to encase the specified HTML element object. The resulting text range includes the HTML for the element, as well.

Collapses the text range to an insertion pointer and sets its location to the spot indicated by the horizontal and vertical coordinates in the browser window or frame. This is as if the user had clicked on a spot in the window to define an insertion point. Use methods such as expand( ) to enlarge the text range to include a character, word, sentence, or entire text range.

Returns an object reference to the next outermost element that fully contains the TextRange object.

Replaces the current text range with the HTML content supplied as a parameter string. Typically, this method is used on a zero-length text range object acting as an insertion pointer. All tags are rendered as if they were part of the original source code.

Indicates whether the command can be invoked in light of the current state of the document or selection.

Indicates whether the command is in an indeterminate state.

Determines the current state of the named command.

Determines whether the named command is supported by the document object.

Returns text associated with the command.

Returns the value associated with the command, such as the name font of the selection.

Selects all the text that is included in the current TextRange object. This method brings some visual confirmation to users that a script knows about a particular block of text. For example, if you were scripting a search with the findText( ) method, you would then use the scrollIntoView( ) and select( ) methods on that range to show the user where the matching text is.

Sets the end point of the current TextRange object to the end point of another range that had previously been preserved as a variable reference.