ReplaceText

3.1

The ReplaceText function creates a system-defined modeless dialog box that makes it possible for the user to find and replace text within a document. The application must perform the actual find and replace operations.

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, or it is NULL if an error occurs. An application can use this 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:

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

Comments

The dialog box procedure for the ReplaceText function 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 ReplaceText 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 Replace dialog box.)

Example

This example initializes a FINDREPLACE structure and calls the ReplaceText function to display the Replace dialog box:

static FINDREPLACE fr;
char szFindWhat[256] = "";      /* string to find    */
char szReplaceWith[256] = "";   /* string to replace */

/* Set all structure fields to zero. */

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

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

hDlg = ReplaceText(&fr);

In addition to initializing the members of the FINDREPLACE structure and calling the ReplaceText function, an application must register the special FINDMSGSTRING message and process messages from the dialog box. Refer to the description of the FindText function for an example that shows how an application registers and processes a message.

See Also

FindText, IsDialogMessage, RegisterWindowMessage