Find and Replace Dialog Boxes

The Find dialog box lets the user specify a string to search for, as well as options to use when searching for text in a document. The Replace dialog box lets the user specify a string to search for and a replacement string, as well as options to control the operation.

You create and display a Find dialog box by initializing a FINDREPLACE structure and passing the structure to the FindText function. You create and display a Replace dialog box by initializing a FINDREPLACE structure and passing the structure to the ReplaceText function.

The following illustration shows a typical Find dialog box.

The following illustration shows a typical Replace dialog box.

Unlike other common dialog boxes, the Find and Replace dialog boxes are modeless. A modeless dialog box allows the user to switch between the dialog box and the window that created it. This is useful for letting the user search for a string, switch to the application window to work on the string, and switch back to the dialog box to search for another string without repeating the command needed to open the dialog box.

If the FindText or ReplaceText function successfully creates the dialog box, it returns a handle to the dialog box. You can use this handle to move and communicate with the dialog box. If the function cannot create the dialog box, it returns NULL. You can determine the cause of an error by calling the CommDlgExtendedError function to retrieve the extended error value.

This section discusses the following topics.

The FINDMSGSTRING Registered Message

Before creating a Find or Replace dialog box, you must call the RegisterWindowMessage function to get a message identifier for the FINDMSGSTRING registered message. You can then use the identifier to detect and process messages sent from the dialog box. When the user clicks the Find Next, Replace, or Replace All button in a dialog box, the dialog box procedure sends a FINDMSGSTRING message to the window procedure of the owner window. When you create the dialog box, the hwndOwner member of the FINDREPLACE structure identifies the owner window.

The lParam parameter of a FINDMSGSTRING message is a pointer to the FINDREPLACE structure that you specified when you created the dialog box. Before sending the message, the dialog box sets the members of this structure with the latest user input, including the string to search for, the replacement string (if any), and options for the find-and-replace operation.

In a FINDMSGSTRING message, the Flags member of the FINDREPLACE structure includes one of the following flags to indicate the event that caused the message.

Flag Meaning
FR_DIALOGTERM The dialog box is closing. After the owner window processes this message, a handle to the dialog box is no longer valid.
FR_FINDNEXT The user clicked the Find Next button in a Find or Replace dialog box. The lpstrFindWhat member specifies the string to search for.
FR_REPLACE The user clicked the Replace button in a Replace dialog box. The lpstrFindWhat member specifies the string to replace and the lpstrReplaceWith member specifies the replacement string.
FR_REPLACEALL The user clicked the Replace All button in a Replace dialog box. The lpstrFindWhat member specifies the string to replace and the lpstrReplaceWith member specifies the replacement string.

For a Find Next or Replace All message, the Flags member can include any combination of the following flags to indicate the search options.

Flag Meaning
FR_DOWN If set, the Down button of the direction radio buttons is selected, indicating that user wants to search from the current location to the end of the document. If FR_DOWN is not set, the Up button is selected so the user wants to search to the beginning of the document.
FR_MATCHCASE If set, the Match Case check box is selected, indicating that the user wants the search to be case sensitive. If FR_MATCHCASE is not set, the check box is unselected so that the search can be case insensitive.
FR_WHOLEWORD If set, the Match Whole Word Only check box is selected, indicating that the user wants to search only for whole words that match the search string. If FR_WHOLEWORD is not set, the check box is unselected so you should also search for word fragments that match the search string.

Customizing the Find or Replace Dialog Box

To customize a Find or Replace dialog box, you can use any of the following methods:

When you create a Find or Replace dialog box, you can set flags in the Flags member of the FINDREPLACE structure to hide or disable any of the search option controls. For example, you can set the FR_NOMATCHCASE flag to disable the Match Case check box or set the FR_HIDEMATCHCASE flag to hide it.

You can provide a custom template for a Find or Replace dialog box, for example, if you want to include additional controls that are unique to your application. The FindText and ReplaceText functions use your custom template in place of the default template.

To provide a custom template for a Find or Replace dialog box

  1. Create the custom template by modifying the default template specified in the Findtext.dlg file. The control identifiers used in the default Find or Replace dialog template are defined in the Dlgs.h file.
  2. Use the FINDREPLACE structure to enable the template as follows:
      • If your custom template is a resource in an application or dynamic-link library, set the FR_ENABLETEMPLATE flag in the Flags member. Use the hInstance and lpTemplateName members of the structure to identify the module and resource name.

         

        -Or-

         

      • If your custom template is already in memory, set the FR_ENABLETEMPLATEHANDLE flag. Use the hInstance member to identify the memory object that contains the template.

You can provide an FRHookProc hook procedure for a Find or Replace dialog box. The hook procedure can process messages sent to the dialog box. If you use a custom template to define additional controls, you must provide a hook procedure to process input for your controls.

To enable a hook procedure for a Find or Replace dialog box

  1. Set the FR_ENABLEHOOK flag in the Flags member of the FINDREPLACE structure.
  2. Specify the address of the hook procedure in the lpfnHook member.

After processing its WM_INITDIALOG message, the dialog box procedure sends a WM_INITDIALOG message to the hook procedure. The lParam parameter of this message is a pointer to the FINDREPLACE structure used to initialize the dialog box.

If the hook procedure returns FALSE in response to the WM_INITDIALOG message, the dialog box will not be shown unless the hook procedure displays it. To do this, first perform any other paint operations, and then call the ShowWindow and UpdateWindow functions. The following code provides an example:

// We've returned FALSE in response to WM_INITDIALOG. 
// We've performed any other paint operations. 
// Now we display the dialog box. 
ShowWindow(hDlg, SW_SHOWNORMAL); 
UpdateWindow(hDlg);

Finding Text

This topic describes sample code that displays and manages a Find dialog box so the user can specify the parameters of a search operation. The dialog box sends messages to your window procedure so you can perform the search operation.

The code for displaying and managing a Replace dialog box is similar, except that it uses the ReplaceText function to display the dialog box. The Replace dialog box also sends messages in response to user clicks on the Replace and Replace All buttons.

To use the Find or Replace dialog box, you must perform three separate tasks:

  1. Get a message identifier for the FINDMSGSTRING registered message.
  2. Display the dialog box.
  3. Process FINDMSGSTRING messages when the dialog box is open.

When you initialize your application, call the RegisterWindowMessage function to get a message identifier for the FINDMSGSTRING registered message.

UINT uFindReplaceMsg;  // message identifier for FINDMSGSTRING 

uFindReplaceMsg = RegisterWindowMessage(FINDMSGSTRING);

To display a Find dialog box, first initialize a FINDREPLACE structure and then call the FindText function. Note that the FINDREPLACE structure and the buffer for the search string should be a global or static variable so it does not go out of scope before the dialog box closes. You must set the hwndOwner member to specify the window that receives the registered messages. After you create the dialog box, you can move or manipulate it by using the returned handle.

When the dialog box is open, your main message loop must include a call to the IsDialogMessage function. Pass a handle to the dialog box as a parameter in the IsDialogMessage call. This ensures that the dialog box correctly processes keyboard messages.

To monitor messages sent from the dialog box, your window procedure must check for the FINDMSGSTRING registered message and process the values passed in the FINDREPLACE structure as in the following example: