findText

Contents  Index  Topic Contents

Previous Topic: expand
Next Topic: focus

findText

Description

Searches for text in the document. Positions the start and end points of the range to encompass the search string.

Syntax

bFound = object.findText(sText [, iSearchScope] [, iFlags])

Parameter

Description

sText

String specifying the text to find.

iSearchScope

Optional. An integer indicating the direction to search from the starting point of the range. A positive integer indicates a forward search; a negative integer indicates a backward search.

iFlags

Optional. A combination of one or more of the following flags indicating the type of search:

2	match whole words only.
4	match case.

Return Value

Returns true if the search text is found, or false otherwise.

Remarks

A range has two distinct states: degenerate and non-degenerate. Analogous to a text editor, a degenerate range is like a text editor caret (insertion point); it does not actually select any characters. Instead it specifies a point between two characters. A degenerate range’s endpoints are effectively next to each other. On the other hand, a non-degenerate range is like a text editor selection. A certain amount of text is selected, and the end points of the range are not next to each other.

The degenerate state of the range has a significant impact on the behavior of the findText method. The value passed for the iSearchScope parameter controls the part of the document, relative to the range, that is searched. If the range is degenerate, either a large positive or a large negative number can be passed to indicate the direction of the search. If the range is non-degenerate, passing 0 will cause only the text selected by the range to be searched. Passing a large positive number will cause the text to the right of the start of the range to be searched. Passing a large negative number will cause the text to the left of the end of the range to be searched. For all intensive purposes, a large positive and a large negative number are 9999999 and -9999999, respectively. Passing anything else for iSearchScope may not be compatible with future versions of Internet Explorer.

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following example creates a Text Range over the body of the document and searches for text with various flag combinations. The results are indicated in the code comments.

<HTML>
<BODY>
Leonardo da Vinci was one of the great masters of the High Renaissance, 
especially in painting, sculpture, architecture, engineering, and science.
</BODY>
</HTML>

<SCRIPT>
   var oRange = document.body.createTextRange();
   var sBookMark = oRange.getBookmark(); // record the current position in a bookmark
   oRange.findText('leo');               // true. case insensitive and partial word match.
   oRange.moveToBookmark(sBookMark);	 // reset the range using the bookmark
   oRange.findText('engineer', 0, 2);    // false. matches whole words only.
   oRange.moveToBookmark(sBookMark);
   oRange.findText('high', 0, 4);        // false. case sensitive.
   oRange.moveToBookmark(sBookMark);
   oRange.findText('Leonardo', 0, 6);    // true. case sensitive and matches whole words.

   // the degenerate case
   oRange.moveToBookmark(sBookMark);
   oRange.collapse();                    // make the range degenerate
   oRange.findText('Leonardo', 0, 6);    // false. must specify large character count in this case
   oRange.findText('Leonardo');          // true. no third parameter passed, so no count needed
   oRange.findText('Leonardo', 1000000000, 6);    // true. a large count covers the range.
</SCRIPT>

Applies To


		Contents Index Topic Contents
	Previous Topic: expand Next Topic: focus