Windows Win32 Dialog Boxes

A Comprehensive Guide for Developers

MSDN > Community > Windows > Win32 > Dialog Boxes

Introduction to Win32 Dialog Boxes

Dialog boxes are an integral part of the Windows user interface, providing a way for applications to interact with users for input, confirmation, or to display information. In the Win32 API, dialog boxes can be created using either modeless or modal approaches, each serving different interaction paradigms.

Modal vs. Modeless Dialogs

Understanding the distinction between modal and modeless dialog boxes is crucial for effective UI design:

Creating Dialog Boxes

The Win32 API offers two primary methods for creating dialog boxes:

1. Dialog Templates

This is the most common and recommended approach. You define the dialog's layout, controls, and properties in a resource script file (.rc) which is compiled into your application's resources. The system then creates and manages the dialog window.

Defining a Dialog Template

A typical dialog template in a resource file looks like this:


IDD_MYDIALOG DIALOGEX 0, 0, 200, 100
STYLE DS_SETFONT | DS_MODALFRAME | WS_POPUP | WS_CAPTION | WS_SYSMENU
CAPTION "My Custom Dialog"
FONT 8, "Segoe UI"
{
    DEFPUSHBUTTON "OK", IDOK, 140, 80, 50, 14
    PUSHBUTTON "Cancel", IDCANCEL, 80, 80, 50, 14
    CONTROL "", IDC_EDIT_NAME, "EDITTEXT", ES_LEFT | WS_BORDER | WS_TABSTOP, 70, 20, 120, 20
    LTEXT "Enter Name:", IDC_STATIC, 10, 25, 50, 10
}

Key elements include:

Displaying a Dialog Template

In your C++ code, you can display a modal dialog using the DialogBoxParam function:


#include <windows.h>
#include "resource.h" // Contains definitions for IDD_MYDIALOG, IDOK, IDCANCEL, etc.

// In your window procedure or another suitable function:
INT_PTR CALLBACK MyDialogProc(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam);

void ShowMyModalDialog(HWND hParent)
{
    DialogBoxParam(GetModuleHandle(NULL),
                   MAKEINTRESOURCE(IDD_MYDIALOG),
                   hParent,
                   MyDialogProc,
                   0); // Pass custom data if needed
}

2. Programmatic Dialog Creation

While less common for complex dialogs, you can also create dialog windows entirely in code by creating a window class and using the CreateWindowEx function. This approach offers maximum flexibility but requires more manual setup.

Dialog Procedures

Every dialog box has an associated dialog procedure (a callback function) that handles messages sent to the dialog window. This procedure is responsible for responding to user input, updating controls, and performing actions specific to the dialog's purpose.

A basic dialog procedure structure:


INT_PTR CALLBACK MyDialogProc(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam)
{
    UNREFERENCED_PARAMETER(lParam); // To suppress unused parameter warnings

    switch (message)
    {
        case WM_INITDIALOG:
            // Initialize dialog controls, set text, etc.
            // Example: Set text for an edit control
            // SetDlgItemText(hDlg, IDC_EDIT_NAME, "Default Value");
            return TRUE; // Indicate that focus should be set to the first control

        case WM_COMMAND:
            if (LOWORD(wParam) == IDOK)
            {
                // Handle OK button click
                // Retrieve data from controls
                // TCHAR name[100];
                // GetDlgItemText(hDlg, IDC_EDIT_NAME, name, sizeof(name)/sizeof(TCHAR));

                EndDialog(hDlg, IDOK); // Close the dialog and return IDOK
                return TRUE;
            }
            else if (LOWORD(wParam) == IDCANCEL)
            {
                // Handle Cancel button click
                EndDialog(hDlg, IDCANCEL); // Close the dialog and return IDCANCEL
                return TRUE;
            }
            break;

        case WM_CLOSE:
            EndDialog(hDlg, IDCANCEL); // Treat close button as Cancel
            return TRUE;
    }
    return FALSE; // Let Windows handle unhandled messages
}

Common Dialog Message Handlers

Working with Dialog Controls

You can interact with controls within your dialog procedure using various Win32 API functions:

Example: Handling an Edit Control

To get text from an edit control named IDC_EDIT_NAME when the OK button is pressed:


case WM_COMMAND:
    if (LOWORD(wParam) == IDOK)
    {
        TCHAR buffer[256];
        GetDlgItemText(hDlg, IDC_EDIT_NAME, buffer, sizeof(buffer)/sizeof(TCHAR));

        // Process the retrieved text
        MessageBox(hDlg, buffer, "Entered Name", MB_OK);

        EndDialog(hDlg, IDOK);
        return TRUE;
    }
    // ... other commands

Common Dialog Boxes

The Win32 API provides a set of standard, pre-built dialog boxes that simplify common tasks:

These common dialogs significantly reduce development time and ensure a consistent user experience by adhering to Windows UI guidelines.

Using MessageBox

Displaying a simple informational message:


MessageBox(NULL, "Operation completed successfully.", "Information", MB_OK | MB_ICONINFORMATION);

Best Practices

Always use TCHAR, _T() macros, and Unicode (or `_UNICODE` and `UNICODE` preprocessor definitions) for modern Win32 development to support both ANSI and Wide character sets.

Related Topics