TextRange | NN n/a IE 4(Win) DOM n/a
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).
A TextRange object is created via the createTextRange( ) method associated with the body, button, text, or textarea objects. You can also turn a user selection into a range via the selection object's createRange( ) (note the slight difference in the method name). Once you have created a text range, use its methods to adjust its start and end points to encompass a desired segment of the text (such as text that matches a search string). Once the range has been narrowed to the target text, assign values to its htmlText and text properties to change, remove, or insert text. A library of direct commands that perform specific textual modifications can also be invoked to act on the text range. See Chapter 5 for details and examples of using the TextRange object.
Shared properties and methods from the list at the start of this chapter are: offsetLeft, offsetTop, getBoundingClientRect( ), getClientRects( ), and scrollIntoView( ). Note that the TextRange object and all associated facilities are available only in the Win32 version of Internet Explorer.
Object Model Reference
    objectRef.createTextRange( )
    selectionObjectRef.createRange( )
Object-Specific Properties

boundingHeight | boundingLeft | boundingTop | boundingWidth
htmlText | text |  |

Object-Specific Methods

collapse( ) | compareEndPoints( ) | duplicate( )
execCommand( ) | expand( ) | findText( )
getBookmark( ) | inRange( ) | isEqual( )
move( ) | moveEnd( ) | moveStart( )
moveToBookmark( ) | moveToElementText( ) | moveToPoint( )
parentElement( ) | pasteHTML( ) | queryCommandEnabled( )
queryCommandIndeterm( ) | queryCommandState( ) | queryCommandSupported( )
queryCommandText( ) | queryCommandValue( ) | select( )
setEndPoint( ) |  |

boundingHeight, boundingWidth | NN n/a IE 4(Win) DOM n/a
| Read-only
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.
Example
    var rangeWidth = document.forms[0].myTextArea.createTextRange( ).boundingWidth;
Value
Integer.
Default
None.

boundingLeft, boundingTop | NN n/a IE 4(Win) DOM n/a
| Read-only
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.
Example
    var rangeOffH = document.forms[0].myTextArea.createTextRange( ).boundingLeft;
Value
Integer.
Default
None.

htmlText | NN n/a IE 4(Win) DOM n/a
| Read-only
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.
Example
    var rangeHTML = document.body.createTextRange( ).htmlText;
Value
String.
Default
None.

text | NN n/a IE 4(Win) DOM n/a
| Read/Write
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.
Example
    var rangeText = document.body.createTextRange( ).text;
Value
String.
Default
None.

collapse( ) | NN n/a IE 4(Win) DOM n/a
collapse([start]) |
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.
Parameters

- Optional Boolean value that controls whether the insertion point goes to the beginning (true) of the original range or the end (false). The default value is true.

Returned Value
None.

compareEndPoints( ) | NN n/a IE 4(Win) DOM n/a
compareEndPoints("type", comparisonRange) |
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)
If r1 ends where r2 starts (the insertion point between two characters), the returned value is 0.
Parameters

- One of the following constants (as a string): StartToEnd | StartToStart | EndToStart | EndToEnd.
- A TextRange object created earlier and saved to a variable.

Returned Value
-1, 0, or 1.

duplicate( ) | NN n/a IE 4(Win) DOM n/a
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).
Parameters
None.
Returned Value
TextRange object.

execCommand( ) | NN n/a IE 4(Win) DOM n/a
execCommand("commandName"[, UIFlag[, value]]) |
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.
Parameters

- A case-insensitive string value of the command name. See Appendix D.
- Optional Boolean value: true to display any user interface triggered by the command (if any); false to prevent such display.
- A parameter value for the command.

Returned Value
Boolean value: true if command is successful; false if unsuccessful.

expand( ) | NN n/a IE 4(Win) DOM n/a
expand("unit") |
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");
If the starting range extends across multiple units, the expand( ) method expands the range outward to the next nearest unit.
Parameters

- A case-insensitive string value of the desired unit: character | word | sentence | textedit. The textedit value expands the range to the entire original range.

Returned Value
Boolean value: true if method is successful; false if unsuccessful.

findText( ) | NN n/a IE 4(Win) DOM n/a
findText("string"[, searchScope][, flags]) |
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( )).
Optional parameters let you limit the scope of the search within the range to a desired number of characters after the range's start point, or dictate additional matching requirements, such as partial or whole words.
Parameters

- A case-insensitive string to be searched.
- Integer for the number of characters to search relative to the range's start point. A positive number searches forward; a negative number searches backward, to text earlier in the document than the start point of the text range.
- Integer for search detail codes: 0 (match partial words); 1 (match backwards); 2 (match whole words only); 4 (match case).

Returned Value
Boolean value: true if a match is found; false if unsuccessful.

getBookmark( ), moveToBookmark( ) | NN n/a IE 4(Win) DOM n/a
getBookmark( ) moveToBookmark(bookmarkString) |
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);
Parameters

- An opaque string returned by the getBookmark( ) method.

Returned Value
Boolean value: true if the operation is successful; false if unsuccessful.

inRange( ) | NN n/a IE 4(Win) DOM n/a
inRange(comparisonRange) |
Determines whether the comparison range is within or equal to the physical range of the current text range.
Parameters

- TextRange object created earlier and saved to a variable.

Returned Value
Boolean value: true if the comparison range is in or equal to the current range; false if not.

isEqual( ) | NN n/a IE 4(Win) DOM n/a
isEqual(comparisonRange) |
Determines whether the comparison range is identical to the current text range.
Parameters

- A TextRange object created earlier and saved to a variable.

Returned Value
Boolean value: true if the comparison range is equal to the current range; false if not.

move( ) | NN n/a IE 4(Win) DOM n/a
move("unit"[, count]) |
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.
Parameters

- A case-insensitive string value of the desired unit: character | word | sentence | textedit. The textedit value moves the insertion pointer to the start or end of the entire original range.
- An optional integer of the number of units to move the insertion pointer. Positive values move the pointer forward; negative values move the pointer backward. Default value is 1.

Returned Value
Integer of the number of units moved.

moveEnd( ), moveStart( ) | NN n/a IE 4(Win) DOM n/a
moveEnd("unit"[, count]) moveStart("unit"[, count]) |
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.
Parameters

- A case-insensitive string value of the desired unit: character | word | sentence | textedit. The textedit value moves the insertion pointer to the start or end of the entire original range.
- An optional integer of the number of units to move the insertion pointer. Positive values move the pointer forward; negative values move the pointer backward. Default value is 1.

Returned Value
Integer of the number of units moved.

moveToBookmark( ) |
See getBookmark( ).

moveToElementText( ) | NN n/a IE 4(Win) DOM n/a
moveToElementText(elementObject) |
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.
Parameters

- A scripted reference to the object. This can be in the form of a direct reference (document.getElementById("elementID") or a variable containing the same kind of value.

Returned Value
None.

moveToPoint( ) | NN n/a IE 4(Win) DOM n/a
moveToPoint(x, y) |
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.
Parameters

- Horizontal coordinate of the insertion point in pixels relative to the left edge of the window or frame.
- Vertical coordinate of the insertion point in pixels relative to the top edge of the window or frame.

Returned Value
None.

parentElement( ) | NN n/a IE 4(Win) DOM n/a
Returns an object reference to the next outermost element that fully contains the TextRange object.
Parameters
None.
Returned Value
Element object reference.

pasteHTML( ) | NN n/a IE 4(Win) DOM n/a
pasteHTML("HTMLText") |
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.
Parameters

- Document source code to be inserted into the document.

Returned Value
None.

queryCommandEnabled( ) | NN n/a IE 4(Win) DOM n/a
queryCommandEnabled("commandName") |
Indicates whether the command can be invoked in light of the current state of the document or selection.
Parameters

commandName

  A case-insensitive string value of the command name.

Returned Value
Boolean value: true if enabled; false if not.

queryCommandIndeterm( ) | NN n/a IE 4(Win) DOM n/a
queryCommandIndeterm("commandName") |
Indicates whether the command is in an indeterminate state.
Parameters

commandName

  A case-insensitive string value of the command name.

Returned Value
Boolean value: true | false.

queryCommandState( ) | NN n/a IE 4(Win) DOM n/a
queryCommandState("commandName") |
Determines the current state of the named command.
Parameters

commandName

  A case-insensitive string value of the command name.

Returned Value
true if the command has been completed; false if the command has not completed; null if the state cannot be accurately determined.

queryCommandSupported( ) | NN n/a IE 4(Win) DOM n/a
queryCommandSupported("commandName") |
Determines whether the named command is supported by the document object.
Parameters

commandName

  A case-insensitive string value of the command name.

Returned Value
Boolean value: true | false.

queryCommandText( ) | NN n/a IE 4(Win) DOM n/a
queryCommandText("commandName") |
Returns text associated with the command.
Parameters

commandName

  A case-insensitive string value of the command name.

Returned Value
String.

queryCommandValue( ) | NN n/a IE 4(Win) DOM n/a
queryCommandValue("commandName") |
Returns the value associated with the command, such as the name font of the selection.
Parameters

commandName

  A case-insensitive string value of the command name.

Returned Value
Depends on the command.

select( ) | NN n/a IE 4(Win) DOM n/a
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.
Parameters
None.
Returned Value
None.

setEndPoint( ) | NN n/a IE 4(Win) DOM n/a
setEndPoint("type", comparisonRange) |
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.
Parameters

- One of the following constants (as a string): StartToEnd | StartToStart | EndToStart | EndToEnd.
- A TextRange object created earlier and saved to a variable.

Returned Value
None.