Searches for text in the document and positions the start and end points of the range to encompass the search string.
HRESULT findText( BSTR String, long count, long Flags, VARIANT_BOOL *Success );
- [in] BSTR that specifies the text to find.
- [in] long 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.
- [in] long that specifies one or more of the following flags to indicate the type of search:
- Default. Match partial words.
- Match in reverse.
- Match whole words only.
- Match case.
- Match bytes.
- Match diacritical marks.
- Match Kashida character.
- Match AlefHamza character.
- [out, retval] Pointer to a VARIANT_BOOL that returns one of the following values:
- The search text was found.
- The search text was not found.
Returns S_OK if successful, or an error value otherwise.
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 count parameter controls the part of the document, relative to the range, that is searched. The behavior of the IHTMLTxtRange::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- Microsoft Win32 platforms.
A text range is not modified if the text specified for the IHTMLTxtRange::findText method is not found.