Dialog Boxes (Dialog Boxes)

A dialog box is a temporary window an application creates to retrieve user input. An application typically uses dialog boxes to prompt the user for additional information for menu items. A dialog box usually contains one or more controls (child windows) with which the user enters text, chooses options, or directs the action.

Windows also provides predefined dialog boxes that support common menu items such as Open and Print. Applications that use these menu items should use the common dialog boxes to prompt for this user input, regardless of the type of application.

In This Section

Name Description
About Dialog Boxes Discusses using dialog boxes in the user interface for your applications.
Dialog Box Programming Considerations This overview discusses some programming considerations concerning dialog boxes.
Using Dialog Boxes You use dialog boxes to display information and prompt for input from the user.
Dialog Box Reference The API Reference
Common Dialog Box Library Discusses using the common dialog boxes in the user interface for your applications.

Dialog Box Functions

Name Description
CreateDialog Creates a modeless dialog box from a dialog box template resource.
CreateDialogIndirect Creates a modeless dialog box from a dialog box template in memory.
CreateDialogIndirectParam Creates a modeless dialog box from a dialog box template in memory. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.
CreateDialogParam Creates a modeless dialog box from a dialog box template resource. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.
DefDlgProc Calls the default dialog box window procedure to provide default processing for any window messages that a dialog box with a private window class does not process.
DialogBox Creates a modal dialog box from a dialog box template resource. DialogBox does not return control until the specified callback function terminates the modal dialog box by calling the EndDialog function.
DialogBoxIndirect Creates a modal dialog box from a dialog box template in memory. DialogBoxIndirect does not return control until the specified callback function terminates the modal dialog box by calling the EndDialog function.
DialogBoxIndirectParam Creates a modal dialog box from a dialog box template in memory. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.
DialogBoxParam Creates a modal dialog box from a dialog box template resource. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.
DialogProc An application-defined callback function used with the CreateDialog and DialogBox families of functions. It processes messages sent to a modal or modeless dialog box. The DLGPROC type defines a pointer to this callback function. DialogProc is a placeholder for the application-defined function name.
EndDialog Destroys a modal dialog box, causing the system to end any processing for the dialog box.
GetDialogBaseUnits Retrieves the system's dialog base units, which are the average width and height of characters in the system font. For dialog boxes that use the system font, you can use these values to convert between dialog template units, as specified in dialog box templates, and pixels. For dialog boxes that do not use the system font, the conversion from dialog template units to pixels depends on the font used by the dialog box.
GetDlgCtrlID Retrieves the identifier of the specified control.
GetDlgItem Retrieves a handle to a control in the specified dialog box.
GetDlgItemInt Translates the text of a specified control in a dialog box into an integer value.
GetDlgItemText Retrieves the title or text associated with a control in a dialog box.
GetNextDlgGroupItem Retrieves a handle to the first control in a group of controls that precedes (or follows) the specified control in a dialog box.
GetNextDlgTabItem Retrieves a handle to the first control that has the WS_TABSTOP style that precedes (or follows) the specified control.
IsDialogMessage Determines whether a message is intended for the specified dialog box and, if it is, processes the message.
MapDialogRect Converts the specified dialog box units to screen units (pixels). The function replaces the coordinates in the specified RECT structure with the converted coordinates, which allows the structure to be used to create a dialog box or position a control within a dialog box.
MessageBox Displays a modal dialog box that contains a system icon, a set of buttons, and a brief application-specific message, such as status or error information. The message box returns an integer value that indicates which button the user clicked.
MessageBoxEx Creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons. The buttons are in the language of the system user interface.
MessageBoxIndirect Creates, displays, and operates a message box. The message box contains application-defined message text and title, any icon, and any combination of predefined push buttons.
SendDlgItemMessage Sends a message to the specified control in a dialog box.
SetDlgItemInt Sets the text of a control in a dialog box to the string representation of a specified integer value.
SetDlgItemText Sets the title or text of a control in a dialog box.

Dialog Box Messages

Name Description
DM_GETDEFID Retrieves the identifier of the default push button control for a dialog box.
DM_REPOSITION Repositions a top-level dialog box so that it fits within the desktop area. An application can send this message to a dialog box after resizing it to ensure that the entire dialog box remains visible.
DM_SETDEFID Changes the identifier of the default push button for a dialog box.

Dialog Box Notifications

Name Description
WM_CTLCOLORDLG Sent to a dialog box before the system draws the dialog box. By responding to this message, the dialog box can set its text and background colors using the specified display device context handle.
WM_ENTERIDLE Sent to the owner window of a modal dialog box or menu that is entering an idle state. A modal dialog box or menu enters an idle state when no messages are waiting in its queue after it has processed one or more previous messages.
WM_GETDLGCODE Sent to the window procedure associated with a control. By default, the system handles all keyboard input to the control; the system interprets certain types of keyboard input as dialog box navigation keys. To override this default behavior, the control can respond to the WM_GETDLGCODE message to indicate the types of input it wants to process itself.
WM_INITDIALOG Sent to the dialog box procedure immediately before a dialog box is displayed. Dialog box procedures typically use this message to initialize controls and carry out any other initialization tasks that affect the appearance of the dialog box.
WM_NEXTDLGCTL Sent to a dialog box procedure to set the keyboard focus to a different control in the dialog box.

Dialog Box Structures

Name Description
DLGITEMTEMPLATE Defines the dimensions and style of a control in a dialog box. One or more of these structures are combined with a DLGTEMPLATE structure to form a standard template for a dialog box.
DLGITEMTEMPLATEEX Describes an extended dialog box. For a description of the format of an extended dialog box template, see DLGTEMPLATEEX.
DLGTEMPLATE Defines the dimensions and style of a dialog box. This structure, always the first in a standard template for a dialog box, also specifies the number of controls in the dialog box and therefore specifies the number of subsequent DLGITEMTEMPLATE structures in the template.
DLGTEMPLATEEX An extended dialog box template begins with a DLGTEMPLATEEX header that describes the dialog box and specifies the number of controls in the dialog box. For each control in a dialog box, an extended dialog box template has a block of data that uses the DLGITEMTEMPLATEEX format to describe the control.
MSGBOXPARAMS Contains information used to display a message box. The MessageBoxIndirect function uses this structure.