FindText

3.1

#include <commdlg.h>

	HWND FindText(lpfr)
	FINDREPLACE FAR* lpfr;	/* address of structure with initialization data	*/

The FindText function creates a system-defined modeless dialog box that makes it possible for the user to find text within a document. The application must perform the search operation.

Parameters

lpfr

Points to a FINDREPLACE structure that contains information used to initialize the dialog box. When the user makes a selection in the dialog box, the system fills this structure with information about the user's selection and then sends a message to the application. This message contains a pointer to the FINDREPLACE structure.

The FINDREPLACE structure has the following form:

#include <commdlg.h>

typedef struct tagFINDREPLACE {    /* fr */
    DWORD     lStructSize;
    HWND      hwndOwner;
    HINSTANCE hInstance;
    DWORD     Flags;
    LPSTR     lpstrFindWhat;
    LPSTR     lpstrReplaceWith;
    UINT      wFindWhatLen;
    UINT      wReplaceWithLen;
    LPARAM    lCustData;
    UINT      (CALLBACK* lpfnHook)(HWND, UINT, WPARAM, LPARAM);
    LPCSTR    lpTemplateName;
} FINDREPLACE;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

Return Value

The return value is the window handle of the dialog box if the function is successful. Otherwise, it is NULL. An application can use this window handle to communicate with or to close the dialog box.

Errors

Use the CommDlgExtendedError function to retrieve the error value, which may be one of the following values:

CDERR_FINDRESFAILURE
CDERR_INITIALIZATION
CDERR_LOCKRESFAILURE
CDERR_LOADRESFAILURE
CDERR_LOADSTRFAILURE
CDERR_MEMALLOCFAILURE
CDERR_MEMLOCKFAILURE
CDERR_NOHINSTANCE
CDERR_NOHOOK
CDERR_NOTEMPLATE
CDERR_STRUCTSIZE
FRERR_BUFFERLENGTHZERO

Comments

The dialog box procedure for the Find dialog box passes user requests to the
application through special messages. The lParam parameter of each of these
messages contains a pointer to a FINDREPLACE structure. The procedure sends the messages to the window identified by the hwndOwner member of the FINDREPLACE structure. An application can register the identifier for these messages by specifying the “commdlg_FindReplace” string in a call to the RegisterWindowMessage function.

For the TAB key to function correctly, any application that calls the FindText function must also call the IsDialogMessage function in its main message loop. (The IsDialogMessage function returns a value that indicates whether messages are intended for the Find dialog box.)

If the hook function (to which the lpfnHook member of the FINDREPLACE structure points) processes the WM_CTLCOLOR message, this function must return a handle of the brush that should be used to paint the control background.

Example

The following example initializes a FINDREPLACE structure and calls the FindText function to display the Find dialog box:

FINDREPLACE fr;

/* Set all structure members to zero. */

memset(&fr, 0, sizeof(FINDREPLACE));

fr.lStructSize = sizeof(FINDREPLACE);
fr.hwndOwner = hwnd;
fr.lpstrFindWhat = szFindWhat;
fr.wFindWhatLen = sizeof(szFindWhat);

hDlg = FindText(&fr);

break;

In addition to initializing the members of the FINDREPLACE structure and calling the FindText function, an application must register the special FINDMSGSTRING message and process messages from the dialog box.

The following example registers the message by using the RegisterWindowMessage function:

UINT uFindReplaceMsg;

/* Register the FindReplace message. */

uFindReplaceMsg = RegisterWindowMessage(FINDMSGSTRING);

After the application registers the FINDMSGSTRING message, it can process messages by using the RegisterWindowMessage return value. An application must check the FR_DIALOGTERM bit in the Flags member of the FINDREPLACE structure when it processes this message, as in the following ex-ample:

LRESULT CALLBACK MainWndProc(HWND hwnd, UINT msg, WPARAM wParam,
    LPARAM lParam)


{
    static FINDREPLACE FAR* lpfr;

    if (msg == uFindReplaceMsg) {
        lpfr = (FINDREPLACE FAR*) lParam;
        SearchFile((BOOL) (lpfr->Flags & FR_DOWN),
            (BOOL) (lpfr->Flags & FR_MATCHCASE));
        return 0;
    }
    SearchFile((BOOL) (lpfr->Flags & FR_DOWN),
        (BOOL) (lpfr->Flags & FR_MATCHCASE));
    return 0;
}