Creating Dialog Boxes

A dialog box is a temporary window that contains controls. A dialog box is used to display status information and to prompt the user for input. Windows CE supports two types of dialog boxes: modal and modeless. A modal dialog box requires the user to supply information or dismiss the dialog box before enabling the application to continue. Applications use modal dialog boxes in conjunction with commands that require additional information before they can proceed. A modeless dialog box enables the user to supply information and return to a previous task without closing the dialog box. Modal dialog boxes are simpler to manage than their modeless counterparts because they are created and destroyed by calling a single function.

To create either a modal or modeless dialog box, you must define a dialog box template to describe the dialog box style and content. The dialog box template is a binary description of the dialog box and the controls that it contains. You must also supply a dialog box procedure to execute tasks. You can create this template as a resource that you can load from your executable file.

    To define a dialog box template

1. Define an identifier for the dialog box in a header file.
2. Define a dialog box in the application resource file with the DIALOG statement. The statement defines the position and dimensions of the dialog box on the screen as well as the dialog box style, and has the parameters described in the following table.

For a listing of option and control statements, see the Windows CE API Reference.

The following code example shows how to use the DIALOG statement to define a dialog box template.

#include <windows.h>

#define IDD_REPLACE                     106
#define IDC_FINDWHAT                    1000
#define IDC_REPLACE                     1001
#define IDC_BTNREPLACE                  1008
#define IDC_BTNREPLACEALL               1009
#define IDC_BTNFINDNEXT                 1010
#define IDC_STATIC1                     1011
#define IDC_STATIC2                     1012

IDD_REPLACE DIALOG DISCARDABLE  0, 0, 191, 73
STYLE DS_MODALFRAME | DS_CENTER | WS_POPUP | WS_CAPTION | WS_SYSMENU
CAPTION "Replace"
FONT 8, "MS Sans Serif"
BEGIN
    EDITTEXT        IDC_FINDWHAT,55,4,128,14,ES_AUTOHSCROLL
    EDITTEXT        IDC_REPLACE,55,21,128,14,ES_AUTOHSCROLL
    PUSHBUTTON      "&Find Next",IDC_BTNFINDNEXT,18,38,71,14
    PUSHBUTTON      "&Replace",IDC_BTNREPLACE,18,55,71,14
    PUSHBUTTON      "Replace &All",IDC_BTNREPLACEALL,101,38,71,14
    PUSHBUTTON      "Cancel",IDCANCEL,101,55,71,14
    LTEXT           "Fi&nd what:",IDC_STATIC1,7,4,43,8
    LTEXT           "Re&place with:",IDC_STATIC2,7,21,43,8
END

The dialog box procedure is an application-defined callback function that the system calls when it has input for the dialog box or tasks for the dialog box to execute. A dialog box procedure is similar to a window procedure in that the system sends messages to the procedure when it has data or tasks to execute. Although a dialog box procedure is similar to a window procedure, it does not have the same responsibilities. Unlike a window procedure, a dialog box procedure never calls the DefWindowProc function. Rather, it returns TRUE if it processes a message or FALSE if it does not.

The following code example shows the form of a dialog box procedure.

BOOL CALLBACK ReplaceDialogProc (
                    HWND hwndDlg,   // Handle to the dialog box.
                    UINT uMsg,      // Message.
                    WPARAM wParam,  // First message parameter.
                    LPARAM lParam)  // Second message parameter.
{
  switch(uMsg)
  {
    case WM_INITDIALOG:
      // Insert code here to put the string (to find and replace with)
      // into the edit controls.
      // ...
      return TRUE;  

    case WM_COMMAND:
      switch (LOWORD(wParam))
      {
        case IDC_BTNFINDNEXT:
          // Insert code here to handle the case of pushing the
          // "Find Next" button.
          // ...
          break;

        case IDC_BTNREPLACE:
          // Insert code here to handle the case of pushing the
          // "Replace" button.
          // ...
          break;

        case IDC_BTNREPLACEALL:
          // Insert code here to handle the case of pushing the
          // "Replace All" button.
          // ...
          break;

        case IDCANCEL:
          EndDialog(hwndDlg, 0);
          break;
      }
      return TRUE;
  }
  return FALSE;
}

Here, the hwndDlg parameter receives the window handle of the dialog box.

Most dialog box procedures process the WM_INITDIALOG message and the WM_COMMAND messages sent by the controls, but process few if any other messages. If a dialog box procedure does not process a message, it must return FALSE to direct the system to process the messages internally. The only exception to this rule is the WM_INITDIALOG message. Typically, you initialize the dialog box and its contents while processing the WM_INITDIALOG message. The most common task you perform with the WM_INITDIALOG message is to initialize the controls to reflect the current dialog box settings. Another common task is to center a dialog box on the screen or within its owner window. A useful task for some dialog boxes is to set the input focus to a given control rather than accept the default input focus. The dialog box procedure must return TRUE to direct the system to process the WM_INITDIALOG message.

Typically, you create a dialog box by calling either the DialogBox or CreateDialog function. DialogBox creates a modal dialog box; CreateDialog creates a modeless dialog box. When calling these functions, you must specify the identifier or name of a dialog box template resource and the address of the dialog box procedure. The DialogBox and CreateDialog functions load the specified dialog box template, display the dialog box, and process all user input until the user closes the dialog box.

The following code example shows how to create a modal dialog box.

DialogBox (
      g_hInst,                        // Handle to the application instance.
      MAKEINTRESOURCE (IDD_REPLACE),  // Identifies the dialog box template.
      g_hwndMain,                     // Handle to the owner window.
      (DLGPROC) ReplaceDialogProc);   // Pointer to the dialog box procedure.

The following code example shows how to create a modeless dialog box.

CreateDialog (
      g_hInst,                        // Handle to the application instance.
      MAKEINTRESOURCE (IDD_REPLACE),  // Identifies the dialog box template.
      g_hwndMain,                     // Handle to the owner window
      (DLGPROC) ReplaceDialogProc);   // Pointer to the dialog box procedure.

Dialog boxes usually belong to a predefined, exclusive window class. The system uses this window class and its corresponding window procedure for both modal and modeless dialog boxes. When the function is called, it creates the window for the dialog box, as well as the windows for the controls in the dialog box, and then it sends selected messages to the dialog box procedure. While the dialog box is visible, the predefined window procedure manages all messages, processing some messages and passing others to the dialog box procedure so that the procedure can execute tasks. You do not have direct access to the predefined window class or window procedure, but you can use the dialog box template and dialog box procedure to modify the style and behavior of a dialog box.

The following table shows dialog box types.