findText Method

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

Syntax

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

Parameters

sText Required. String that specifies the text to find.

iSearchScope Optional. Integer that specifies the number of characters 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. Integer that specifies one or more of the following flags to indicate the type of search:

2 Match whole words only.

4 Match case.

Return Value

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

Remarks

A range has two distinct states: degenerate and nondegenerate.

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. The end points of a degenerate range are adjacent.

A nondegenerate range is like a text editor selection, in that it selects a certain amount of text. The end points of a nondegenerate range are not adjacent.

The value passed for the iSearchScope parameter controls the part of the document, relative to the range, that is searched. The behavior of the findText method depends on whether the state is degenerate or nondegenerate:

If the range is degenerate, passing a large positive number causes the text to the right of the range to be searched. Passing a large negative number causes the text to the left of the range to be searched.
If the range is nondegenerate, passing a large positive number causes the text to the right of the start of the range to be searched. Passing a large negative number causes the text to the left of the end of the range to be searched. Passing 0 causes only the text selected by the range to be searched.

This feature might not be available on non-Win32® platforms. For the latest information about Internet Explorer cross-platform compatibility, see article Q172976 in the Microsoft Knowledge Base.

A text range is not modified if the text specified for the findText method is not found.

Example

This example creates a TextRange over the body of the document, and then uses the findText method to search for text with various flag combinations. The results are indicated in the example code comments.

Sample Code

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

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

Applies To

[ Object Name ]

Platform Version

Win16:

Win32:

Mac:

Unix:

WinCE:

Version data is listed when the mouse hovers over a link, or the link has focus.

TextRange