Win32 API Reference: Dialog Boxes

Dialog boxes are windows that allow users to interact with an application by providing input, making selections, or receiving information. The Win32 API provides a comprehensive set of functions for creating, managing, and processing dialog boxes.

Dialog boxes can be categorized into two main types:

• Modal Dialog Boxes: These dialog boxes must be dismissed by the user before they can interact with the rest of the application.
• Modeless Dialog Boxes: These dialog boxes allow the user to switch focus between the dialog box and the main application window.

Here are some of the fundamental functions used when working with dialog boxes:

• DialogBox / DialogBoxParam: Creates a modal dialog box.
• CreateDialog / CreateDialogParam: Creates a modeless dialog box.
• EndDialog: Closes a dialog box.
• IsDialogMessage: Processes messages for a modeless dialog box.
• GetDlgItem: Retrieves a handle to a control within a dialog box.
• SendDlgItemMessage: Sends a message to a specific control in a dialog box.

Every dialog box has a dialog procedure, which is a callback function that processes messages sent to the dialog box. The dialog procedure typically uses a switch statement to handle different Windows messages.

Example Dialog Procedure Structure:

LRESULT CALLBACK DialogProc(HWND hwndDlg, UINT uMsg, WPARAM wParam, LPARAM lParam) {
    switch (uMsg) {
        case WM_INITDIALOG:
            // Initialize dialog controls, set focus
            return TRUE; // Indicate that the system should set the input focus

        case WM_COMMAND:
            // Handle button clicks, menu selections, etc.
            switch (LOWORD(wParam)) {
                case IDOK: // OK button pressed
                    EndDialog(hwndDlg, IDOK);
                    return TRUE;
                case IDCANCEL: // Cancel button pressed
                    EndDialog(hwndDlg, IDCANCEL);
                    return TRUE;
                // Handle other control IDs
            }
            break;

        case WM_CLOSE: // Window close button pressed
            EndDialog(hwndDlg, IDCANCEL); // Treat close as cancel
            return TRUE;

        // Handle other messages like WM_PAINT, WM_CTLCOLORSTATIC, etc.

        default:
            return FALSE; // Let the system handle messages not explicitly processed
    }
    return FALSE;
}
                

Dialog box templates define the layout and controls of a dialog box. They can be created using resource editors (like those in Visual Studio) and embedded in the application's executable resource file, or created dynamically in memory.

Common Dialog Controls:

• Buttons (Pushbutton, Checkbox, Radiobutton)
• Edit Controls (Edittext)
• Static Controls (Static, Text)
• List Boxes (Listbox)
• Combo Boxes (Combobox)
• Scroll Bars

The Win32 API also provides a set of standard common dialog boxes for common tasks like opening files, saving files, selecting fonts, and printing.

Common Dialog Box Functions:

Function	Description
GetOpenFileName	Displays the Open dialog box.
GetSaveFileName	Displays the Save As dialog box.
ChooseFont	Displays the Font dialog box.
PrintDlg	Displays the Print dialog box.
FindText	Displays the Find dialog box (part of common dialogs).
ReplaceDlg	Displays the Replace dialog box (part of common dialogs).

For detailed information on each function and its parameters, please refer to the specific API documentation linked above or within the Windows SDK.

Creates and manages a modal dialog box. The application's message loop is suspended while the dialog box is displayed.

INT_PTR DialogBox(
  HINSTANCE hInstance,
  LPCTSTR lpTemplate,
  HWND    hWndParent,
  DLGPROC lpDialogFunc
);

INT_PTR DialogBoxParam(
  HINSTANCE hInstance,
  LPCTSTR   lpTemplate,
  HWND      hWndParent,
  DLGPROC   lpDialogFunc,
  LPARAM    dwInitParam
);
                

Return Value: The value specified in the nResult parameter when EndDialog was called, or -1 if an error occurs.

Creates a modeless dialog box. The application's message loop continues to process messages.

HWND CreateDialog(
  HINSTANCE hInstance,
  LPCTSTR   lpTemplate,
  HWND      hWndParent,
  DLGPROC   lpDialogFunc
);

HWND CreateDialogParam(
  HINSTANCE hInstance,
  LPCTSTR   lpTemplate,
  HWND      hWndParent,
  DLGPROC   lpDialogFunc,
  LPARAM    dwInitParam
);
                

Return Value: A handle to the dialog box, or NULL if an error occurs.

Destroys the dialog box and returns a value from the dialog procedure.

BOOL EndDialog(
  HWND hwndDialog,
  INT_PTR nResult
);
                

Parameters:

• hwndDialog: Handle to the dialog box to be destroyed.
• nResult: The value returned by the dialog box.

Determines if the specified message is intended for the given dialog box and, if so, processes the message.

BOOL IsDialogMessage(
  HWND    hDlg,
  LPMSG lpMsg
);
                

Return Value: TRUE if the message was processed; otherwise, FALSE.

Retrieves the handle to a control within a dialog box.

HWND GetDlgItem(
  HWND hDlg,
  int  nIDDlgItem
);
                

Parameters:

• hDlg: Handle to the dialog box.
• nIDDlgItem: Identifier of the control.

Sends a message to a specified control within a dialog box.

LRESULT SendDlgItemMessage(
  HWND   hDlg,
  int    nIDDlgItem,
  UINT   uMessage,
  WPARAM wParam,
  LPARAM lParam
);
                

Return Value: The return value of the message processing. Behavior depends on the message sent.

Displays a standard "Open" file dialog box that allows the user to select a file or a set of files to open.

BOOL GetOpenFileName(
  LPOPENFILENAME lpofn
);
                

Requires filling an OPENFILENAME structure.

Displays a standard "Save As" file dialog box that allows the user to specify a filename to save a file.

BOOL GetSaveFileName(
  LPOPENFILENAME lpofn
);
                

Requires filling an OPENFILENAME structure.

Displays a standard Font dialog box that allows the user to choose a font, font style, and font size.

BOOL ChooseFont(
  LPCHOOSEFONT lpcf
);
                

Requires filling a CHOOSEFONT structure.

Displays a standard Print dialog box that allows the user to select a printer and specify printing options.

BOOL PrintDlg(
  LPPRINTDLG lpprintDialog
);
                

Requires filling a PRINTDLG structure.