The TextRange Object

The Internet Explorer TextRange object enables you to work with a range of text in a web page. In fact, we've already seen an example using text ranges in Chapter 9, "Using the document and body Objects"that example enabled you to access text the user selected with the mouse in a web page. In the Internet Explorer, you use the document.selection property, then create a text range from that property using the createRange method, and use the text range's text property to find the selected text. Here's what that looked like (Listing 09-07.html on the web site):

 <HTML>      <HEAD>          <TITLE>Reading Selected Text</TITLE>          <SCRIPT LANGUAGE="JavaScript">              <!--             function getSelected()              {  if (navigator.appName == "Microsoft Internet Explorer") {   docum+ent.form1.text1.value = document.selection.createRange().text  }                  if(navigator.appName == "Netscape") {                      document.form1.text1.value = document.getSelection()                  }              }              // -->          </SCRIPT>      </HEAD>      <BODY ONMOUSEUP="getSelected()">          <H1>Reading Selected Text</H1>          Select some of this text!          <BR>          <FORM NAME="form1">              You selected: <INPUT TYPE="TEXT" NAME="text1">          </FORM>      </BODY>  </HTML>

You can see the results in Chapter 9, in Figure 9.4, where I'm selecting some text and the code is displaying what text was selected.

In this and similar ways, the TextRange object gives you access to the text in a web page. You can find the properties and methods of the TextRange object in Table 11.13 in overview. You can find the properties of this object in depth in Table 11.14, and its methods in Table 11.15.

Table 11.13. Overview of the Properties and Methods of the TextRange Object

Properties	Methods
`boundingHeight`	`collapse`
`boundingLeft`	`compareEndPoints`
`boundingTop`	`duplicate`
`boundingWidth`	`execCommand`
`htmlText`	`expand`
`offsetLeft`	`findText`
`offsetTop`	`getBookmark`
`text`	`getBoundingClientRect`
	`getClientRects`
	`inRange`
	`isEqual`
	`move`
	`moveEnd`
	`moveStart`
	`moveToBookmark`
	`moveToElementText`
	`moveToPoint`
	`parentElement`
	`pasteHTML`
	`queryCommandEnabled`
	`queryCommandIndeterm`
	`queryCommandState`
	`queryCommandSupported`
	`queryCommandValue`
	`scrollIntoView`
	`select`
	`setEndPoint`

Table 11.14. The Properties of the TextRange Object

Property	NS2	IE4	IE5	IE5.5	IE6
`boundingHeight`		x	x	x	x
	Read-only
	Holds the height of the rectangle that bounds the `TextRange` object. This is an integer value measured in pixels.
`boundingLeft`		x	x	x	x
	Read-only
	Holds the distance between the left edge of the `TextRange` object and the left side of the object that contains the `TextRange` . This is an integer value measured in pixels.
`boundingTop`		x	x	x	x
	Read-only
	Holds the distance between the top of the `TextRange` object and the top side of the object that contains the `TextRange` . This is an integer value measured in pixels.
`boundingWidth`		x	x	x	x
	Read-only
	Holds the width of the rectangle that bounds the `TextRange` object. This is an integer value measured in pixels.
`htmlText`		x	x	x	x
	Read-only
	Holds the HTML of the text in the `TextRange` object as a string that is a valid HTML fragment.
`offsetLeft`	See Chapter 5.
`offsetTop`	See Chapter 5.
`text`		x	x	x	x
	Read/write
	Sets or gets the text in the range, as a string. See "Creating Text Ranges" in this chapter.

Table 11.15. The Methods of the TextRange Object

Method	NS2	IE4	IE5	IE5.5	IE6
`collapse`		x	x	x	x
	Returns: Nothing
	Shrinks a text range down to an insertion point.
	Syntax: `TextRange` `.collapse([` `start` `])` . Here, start can be true (the default) to move the insertion point to the beginning of the text range, or false to move the insertion point to the end of the text range.
`compareEndPoints`		x	x	x	x
	Returns: Integer
	Compares an end point of a `TextRange` object with an end point of another range.
	Syntax: `TextRange` `.compareEndPoints(` `type` `,` `range` `)` , where the possible values of `type` are `StartToEnd` (compares the start of the `TextRange` object with the end of the `range` parameter), `StartToStart` (compares the start of the `TextRange` object with the start of the `range` parameter), `EndToStart` (compares the end of the `TextRange` object with the start of the `range` parameter), `EndToEnd` (compares the end of the `TextRange` object with the end of the `range` parameter). The `range` parameter holds the range to compare the current one to. Returns `-1` if the comparison point in the `TextRange` object is further to the left than the comparison point in `range` , if the comparison point the `TextRange` object is at the same location as the comparison point in `range` , and `1` if the comparison point in the `TextRange` object is farther to the right than the comparison point in `range` .
`duplicate`		x	x	x	x
	Returns: `TextRange` object
	Duplicates and returns a new copy of the text range.
	Syntax: `TextRange` `.duplicate()` .
`execCommand`		x	x	x	x
	Returns: Boolean
	This is a big onesee "Using `execCommand` " in Chapter 9 for the syntax and possible parameters (listed in Table 9.6) of this method.
`expand`		x	x	x	x
	Returns: Boolean
	This method expands a range (even if it was not collapsed ) to the next word, character, and so on.
	Syntax: `TextRange.expand(` `unit` `)` , where `unit` is one of `"character"` (expands by a character), `"word"` (expands by a word), `" sentence "` (expands by a sentence), or `"textedit"` (expands to enclose the entire range). This method returns true if successful, and false otherwise .
`findText`		x	x	x	x
	Returns: Boolean
	Searches a range for text. See "Finding and Replacing Text" in this chapter for the syntax and an example.
`getBookmark`		x	x	x	x
	Returns: Bookmark (string)
	Gets a bookmark (a string) that you can use with the `moveToBookmark` method to move back to the same range.
	Syntax: `TextRange` `.getBookmark()` . Returns a bookmark if successful, or null otherwise.
`getBoundingClientRect`	See Chapter 6.
`getClientRects`	See Chapter 6.
`inRange`		x	x	x	x
	Returns: Boolean
	Returns a value indicating whether one range is contained within another.
	Syntax: `TextRange` `.inRange(` `range` `)` . Returns true if `range` is in (or is equal to) `TextRange` , false otherwise.
`isEqual`		x	x	x	x
	Returns: Boolean
	Indicates whether one range is equal to another.
	Syntax: `TextRange` `.isEqual(` `range` `)` . Returns true if `TextRange` equals `range` . Returns false otherwise.
`move`		x	x	x	x
	Returns: Integer
	Moves a range a specified number of items, such as characters , words, or sentences.
	Syntax: `TextRange` `.move(` `item` `[,` `count` `])` . Here, `item` can be one of `"character"` (moves by a character), `"word"` (moves by a word), `"sentence"` (moves by a sentence), or `"textedit"` (moves to the start of end of the original range); and `count` is the number of items to move by (can be positive or negative). Returns the number of items the range was moved by.
`moveEnd`		x	x	x	x
	Returns: Integer
	Moves the end of the range.
	Syntax: `TextRange` `.moveEnd(` `item` `[,` `count` `])` . Here, `item` can be one of `"character"` (moves the end by a character), `"word"` (moves the end by a word), `"sentence"` (moves the end by a sentence), or `"textedit"` (moves to the end of the original range); and `count` is the number of items to move the end by (can be positive or negative). Returns the number of items the end of the range was moved by.
`moveStart`		x	x	x	x
	Returns: Integer
	Moves the start of the range.
	Syntax: `TextRange` `.moveStart(` `item` `[,` `count` `])` . Here, `item` can be one of `"character"` (moves the start by a character), `"word"` (moves the start by a word), `"sentence"` (moves the start by a sentence), or `"textedit"` (moves to the start of the original range); and `count` is the number of items to move the start by (can be positive or negative). Returns the number of items the start of the range was moved by.
`moveToBookmark`		x	x	x	x
	Returns: Boolean
	Moves the range to a bookmark set with `getBookmark` .
	Syntax: `TextRange` `.moveToBookmark(` `bookmark` `)` , where `bookmark` is a string returned by `getBookmark` . Returns true if successful, false otherwise.
`moveToElementText`			x	x	x
	Returns: Nothing
	Moves the text range so that the start and end positions of the range surround the text in the given element.
	Syntax: `TextRange` `.moveToElementText(` `element` `)` , where `element` is the element whose text you want to enclose.
`moveToPoint`		x	x	x	x
	Returns: Nothing
	Moves the start and end positions of the text range to the given point, collapsing the range to that point.
	Syntax: `TextRange` `.moveToPoint(` `x` `,` `y` `)` where `x` and `y` give the location of the point to move to, measured with respect to the upper left of the browser's client area, in pixels.
`parentElement`		x	x	x	x
	Returns: Element
	Returns the parent element of the text range if successful, null otherwise.
	Syntax: `TextRange` `.parentElement()` .
`pasteHTML`		x	x	x	x
	Pastes HTML text into the given text range, replacing any previous text and HTML elements in the range.
	Syntax: `TextRange` `.pasteHTML(` `HTMLText` `)` , where `HTMLText` is the HTML to paste into the range. See "Creating Text Ranges" in this chapter for an example.
`queryCommandEnabled`	See Chapter 9 (Table 9.5).
`queryCommandIndeterm`	See Chapter 9 (Table 9.5).
`queryCommandState`	See Chapter 9 (Table 9.5).
`queryCommandSupported`	See Chapter 9 (Table 9.5).
`queryCommandValue`	See Chapter 9 (Table 9.5).
`scrollIntoView`	See Chapter 6
`select`		x	x	x	x
	Returns: Nothing
	Selects the contents of the text range, making the selection visible in the browser.
	Syntax: `TextRange` `.select()` . See "Selecting Text" in this chapter for an example.
`setEndPoint`		x	x	x	x
	Returns: Nothing
	Sets the end point of one range based on the end point of another range.
	Syntax: `TextRange` `.` `setEndPoint(` `type` `,` `range` `)` , where the possible values of `type` are `StartToEnd` (moves the start of the `TextRange` object to the end of the `range` parameter), `StartToStart` (moves the start of the `TextRange` object to the start of the `range` parameter), `EndToStart` (moves the end of the `TextRange` object to the start of the `range` parameter), `EndToEnd` (moves the end of the `TextRange` object to the end of the `range` parameter). The `range` parameter holds the range to move with respect to.

These two tables give us the details on text ranges. Now let's put them to work.