JavaScript Selections: TextRange Object Properties and Methods - Doc JavaScript | WebReference

JavaScript Selections: TextRange Object Properties and Methods - Doc JavaScript


TextRange Object Properties and Methods

In this section of the column we'll discuss the properties and methods of a TextRange object. They provide the capability to change text and elements on the page. We'll use the sample document from the previous section for our demonstrations. Here's a reminder:

<HTML>
<HEAD>
<TITLE>Sample Page</TITLE>
</HEAD>
<BODY>
<H1>This is a sample page.</H1>
<P>This is some sample text.</P>
</BODY>
</HTML>

We'll refer to the TextRange object reflecting the entire document -- the one returned by the following method:

var range = document.body.createTextRange();

Here's a rundown of the TextRange object's properties:

PropertyDescription
htmlText

Returns the HTML fragment for the selected text range. This is a read-only property.

<H1>This is a sample page.</H1>
<P>This is some sample text.</P>

text

Sets or retrieves the text contained within the range. This is a read-write property, meaning you can change as well as retrieve its current value.

This is a sample page.
This is some sample text.

boundingWidth

Retrieves the width of the rectangle that bounds the text range.

305

boundingHeight

Retrieves the height of the rectangle that bounds the text range.

74

boundingLeft

Retrieves the left coordinate of the rectangle that bounds the text range.

12

boundingTop

Retrieves the top coordinate of the rectangle that bounds the text range.

17

offsetLeft

Retrieves the left coordinate of the rectangle that bounds the text range.

12

This property is not exactly the same as boundingLeft. For example, if you put the sample code in a <DIV STYLE="position: absolute; left: 200">...</DIV> definition, this property would evaluate to 212.

offsetTop

Retrieves the top coordinate of the rectangle that bounds the text range.

17

This property is not exactly the same as boundingLeft. For example, if you put the sample code in a <DIV STYLE="position: absolute; top: 200">...</DIV> definition, this property would evaluate to 217.

The TextRange object also features many methods. Here's a listing of the most useful ones:

MethodDescription
collapse([start])Moves the insertion point to the beginning (default) or the end of the current text range (if a false argument is specified).
expand(unit)

Expands the range so that partial units are completely contained. This method returns true if it successfully expands the range, or false otherwise. unit can be one of the following string values:

"character"
Expands a character.
"word"
Expands a word. A word is a collection of characters terminated by a space or other white-space character.
"sentence"
Expands a sentence. A sentence is a collection of words terminated by a punctuation character, such as a period.
"textedit"
Expands to enclose the entire range. In other words, this expands the range to its original dimensions.

The following script segment creates a TextRange object for the current selection, and ensure that any word partially enclosed by the range becomes entirely enclosed in the range:

var range = document.selection.createRange();
range.expand("word");

duplicate()Returns a duplicate of the parent text range (the method's TextRange object).
parentElement()Returns the parent element for the given text range. The parent element is the smallest element that encloses the text in the range.
inRange(otherRange)Returns a Boolean value indicating whether or not one range (the argument) is contained within another (the object).
isEqual(otherRange)Returns a Boolean value indicating whether or not one range (the argument) is equal to another (the object).
scrollIntoView([start])Causes the object to scroll into view, aligning it at either the top or bottom of the window. If the start argument is false, the bottom of the object is visible at the bottom of the window. Otherwise, the object scrolls to the top by default.
setEndPoint(type, range)Sets an endpoint of one range according to one of the endpoints of another range. The type argument is a string that specifies what endpoint to transfer, and what endpoint of the parent range it should replace. It accepts one of the following strings: "StartToEnd", "StartToStart", "EndToStart", or "EndToEnd". The second argument, range, is the text range from which the source endpoint is taken.
compareEndPoints(type, range)Determines if the parent text range (the method's TextRange object) and the one specified as an argument (range) share a common endpoint. This method returns -1 (less than), 0 (equal to), or 1 (greater than). The type argument must be "StartToEnd", "StartToStart", "EndToStart", or "EndToEnd". As you can see, it describes the endpoint to compare. Note that the term "endpoint" doesn't necessarily refer to last position of the text range. It can be the either the first position or the last one, depending on what you specify for the type argument.
select()Makes the active selection in the page equal to the current text range.

The preceding table lists the most important general methods of a TextRange object. The following table lists the range movement methods. After you select a TextRange object, you can move its starting and ending points by using the range movement methods. Note that they do not actually move any of the text on the page. They simply move the boundaries of the range itself, thereby affecting the text that is selected by the text range. Here's the rundown of these methods:

MethodDescription
move(unit [, count])Changes the start and end points of a text range to cover different text. This method moves the text range, not the text itself. The first argument accepts one of the following strings:
"character"
Moves one or more characters.
"word"
Moves one or more words. A word is a collection of characters terminated by a space or other white-space character.
"sentence"
Moves one or more sentences. A sentence is a collection of words terminated by a punctuation character, such as a period.
"textedit"
Moves to the start and end of the original text range.
The second argument, count, specifies the number of units to move (positive or negative). It defaults to 1 if omitted. This method returns the actual number of units moved.
moveStart(unit [, count])This method is the same as move(), but it only moves the range's start position. It changes the scope of the range by moving the start position of the range.
moveEnd(unit [, count])This method is the same as move(), but it only moves the range's end position. It changes the scope of the range by moving the end position of the range.
pasteHTML(htmlText)Pastes the specified HTML text into the given text range. The text completely replaces any previous text and HTML elements in the range. This method cannot be used while the document is loading. Also note that the inserted text and HTML elements should fit the given text range. For example, attempting to paste a table cell into a text range that does not contain a table might cause the method to insert a TABLE element.

Remember that text ranges aren't supported in the Mac version of Internet Explorer 4.0x. These methods and properties are only relevant to Win32 versions of Internet Explorer 4.0x. This page only discusses the basics of text ranges, because this column focuses on selections, not text ranges. For more information on the TextRange object, refer to Microsoft's documentation. In the next section of this column we'll take a look at cross-browser selection handling.

https://www.internet.com


Created: January 29, 1998
Revised: January 29, 1998

URL: https://www.webreference.com/js/column12/trmethods.html