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

Syntax

HRESULT findText(      
    BSTR String,
    long count,
    long Flags,
    VARIANT_BOOL *Success
);

Parameters

String

[in] BSTR that specifies the text to find.

count

[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.

Flags

[in] long that specifies one or more of the following flags to indicate the type of search:

0

Default. Match partial words.

1

Match in reverse.

2

Match whole words only.

4

Match case.

0x20000

Match bytes.

0x20000000

Match diacritical marks.

0x40000000

Match Kashida character.

0x80000000

Match AlefHamza character.

Success

[out, retval] Pointer to a VARIANT_BOOL that returns one of the following values:

VARIANT_TRUE

The search text was found.

VARIANT_FALSE

The search text was not found.

Return Value

Returns S_OK if successful, or an error value 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 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.