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. For more information about using common dialog boxes in your applications, see Common Dialog Box.
There are many functions, messages, and predefined controls to help create and manage dialog boxes, thus making it easier to develop the user interface for an application. This overview describes the dialog box functions and messages and explains how to use them to create and use dialog boxes.
| ENABLE | ADDSTYLE |
| VISIBLE | DELSTYLE |
| TEXT | STYLE |
| RECT | SIZING |
DIALOG support COMMON WINDOWS-STYLES, and also own:
| DS_3DLOOK | Draws three-dimensional borders around control windows in the dialog box; used only in WINDOW95 |
| DS_ABSALIGN | Indicates that the coordinates of the dialog box are screen coordinates. If this style is not specified, the coordinates are client coordinates. |
| DS_CENTER | Centers the dialog box in the working area of the monitor that contains the owner window; used only in WINDOW95 |
| DS_CENTERMOUSE | Centers the dialog box on the mouse cursor; used only in WINDOW95. |
| DS_CONTEXTHELP | Includes a question mark in the title bar of the dialog box. A question mark sets a context-sensitive Help. When the dialog box is created, the system checks for DS_CONTEXTHELP and, if it is there, adds WS_EX_CONTEXTHELP to the extended style of the dialog box. |
| DS_CONTROL | Creates a dialog box that works well as a child window of another dialog box. |
| DS_FIXEDSYS | Causes the dialog box to use the SYSTEM_FIXED_FONT instead of the default SYSTEM_FONT. Used only in WINDOW95. |
| DS_MODALFRAME | Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and window menu by specifying the WS_CAPTION and WS_SYSMENU styles. |
| DS_NOFAILCREATE | Creates the dialog box even if errors occur. |
| DS_NOIDELMSG | Suppresses WM_ENTERIDLE messages that the system would otherwise send to the owner of the dialog box while the dialog box is displayed. |
| DS_SETFONT | Indicates that the header of the dialog box template (either standard or extended) contains additional data specifying the font to use for text in the client area and controls of the dialog box. The system passes a handle to the font to the dialog box and to each control by sending them the WM_SETFONT message. |
| DS_SETFOREGROUND | Causes the system to use the SETFEGROUNDWINDOW function to bring the dialog box to the foreground. |
| DS_SYSMODAL | This style is obsolete. If you specify this style, the system creates the dialog box with the WS_EX_TOPMOST style. Do not combine this style with the DS_CONTROL style. |
| DS_NOMODAL | Creates nomodal dialog box. |
| DS_LOCALEDIT | Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application's data segment. Otherwise, edit controls allocate storage from a global memory object |
| DS_SHELLFONT | Indicates that the dialog box should use the system font. The typeface member of the extended dialog box template must be set to MS Shell Dlg. The system passes a handle to the font to the dialog box and to each control by sending them the WM_SETFONT message. |
| GP.CREATEDLG | Creates a dialog box |
| GP.DELETEDLG | Deletes a dialog box |
| GP.ADDDLGMESSAGE | Adds a message |
| GP.DELALLDLGMESSAGE | Deletes all messages |
| GP.DELDLGMESSAGE | Deletes a message |
| GP.DLGFN | Executes dialog box method and returns results |
| GP.DLGSUB | Executes a method of the dialog box |
| GP.DLGPROPERTY | SETS DIALOG properties |
| GP.DLGGETDATA | RETURNS A VALUE OF THE DLGDATA marix element in COMMON-area |
| GP.DLGSETDATA | SETS A VALUE OF THE DLGDATA marix element in COMMON-area |
| GP.DLGGETDATAMAT | Returns data from DlgData marix in COMMON-area |
| GP.DLGSETDATAMAT | Fills DlgData marix in COMMON-area |
| GP.DlgGetObjId | Gets object identifier |
| GP.DLGSETNAME | Sets dialog box name |
| GP.GETFREEDLGID | Gets next free dialog identifier |
| GP.GETDLGID | Gets dialog name accoding to identifier |
| GP.DLGOBJADDMMSG | Automated properties setting or methods performance at originating events. |
| GP.DLGOBJDELMMSG | Deletes event from processing for automated properties setting or methods performance. |
| GP.DLGOBJDELALLMMSG | Deletes all events from processing for automated properties setting or methods performance. |
Dialog methods
| AddScroller | To add automatic scrolling |
| AutoSetAutoSizing | Analize objects and automaticaly set autosizing properties. |
| AutoSizingPause | Locks autosizing operations. |
| AutoSizingReinitSize | Sets curent sizes as initial size. |
| AutoSizingReset | Resets all definitions. |
| AutoSizingResume | Resume autosizing operations. |
| DelScroller | To remove automatic scrolling |
| EnableThemeDialogTexture | Enables or disables the visual style of a dialog window's background. |
| EnsureVisibleScroller | Ensures that an object is at least partially visible. |
| GetDefID | Gets the identifier of the default push button control for a dialog box. |
| GetObjectByHWND | Returns object ID by object windows handler |
| GetObjectsList | Returns list of objects that dialog contain. |
| GotoDlgCtrl | Moves the focus to the specified control in the dialog box. |
| MapDialogRect | Converts the specified dialog box units to screen units (pixels). |
| NextDlgCtrl | Moves the focus to the next control in the dialog box. |
| PrevDlgCtrl | Sets the focus to the previous control in the dialog box. |
| SetDefID | Changes the default push button control for a dialog box. |
| SetHelpID | Sets a context-sensitive Help identifier for the dialog box. |
| SetRepositionOrder | Sets a Reposition order of the elements sizes |
| SetScroller | Establishes parameters of automatic scrolling |
| SetScrollerPos | Establishes a position scrolled windows |
| UpdateGroup | Adds or removes users from the group. |
| UpdateScroller | To update automatic scrolling |
Using a dialog box is the only recommended way for an application to retrieve the input. For example, a typical Open menu item requires the name of a file to open, so an application should use a dialog box to prompt the user for the name. In such cases, the application creates the dialog box when the user clicks the menu item and destroys the dialog box immediately after the user supplies the information.
Many applications also use dialog boxes to display information or options while the user works in another window. For example, word processing applications often use a dialog box with a text-search option. While the application searches for the text, the dialog box remains on the screen. The user can then return to the dialog box and search for the same word again; or the user can change the entry in the dialog box and search for a new word. Applications that use dialog boxes in this way typically create one when the user clicks the menu item and continue to display it for as long as the application runs or until the user explicitly closes the dialog box.
To support the different ways applications use dialog boxes, there are two types of dialog box: modal and modeless. A modal dialog box requires the user to supply information or cancel the dialog box before allowing the application to continue. Applications use modal dialog boxes in conjunction with menu items that require additional information before they can proceed. A modeless dialog box allows the user to supply information and return to the previous task without closing the dialog box. Modal dialog boxes are simpler to manage than modeless dialog boxes because they are created, perform their task, and are destroyed by calling a single function.
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, then 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 carry out tasks.
Most dialog boxes have an owner window (or more simply, an owner). When creating the dialog box, the application sets the owner by specifying the owner's window. The system uses the owner to determine the position of the dialog box in the Z order so that the dialog box is always positioned above its owner. Also, the system can send messages to the window procedure of the owner, notifying it of events in the dialog box.
The system automatically hides or destroys the dialog box whenever its owner is hidden or destroyed. This means the dialog box procedure requires no special processing to detect changes to the state of the owner window.
Because the typical dialog box is used in conjunction with a menu item, the owner window is usually the window containing the menu. Although it is possible to create a dialog box that has no owner, it is not recommended. For example, when a modal dialog box has no owner, the system does not disable any of the application's other windows and allows the user to continue to carry out work in the other windows, defeating the purpose of the modal dialog box.
When a modeless dialog box has no owner, the system neither hides nor destroys the dialog box when other windows in the application are hidden or destroyed. Although this does not defeat the purpose of the modeless dialog box, it requires that the application carry out special processing to ensure the dialog box is hidden and destroyed at appropriate times.
A modal dialog box should be a pop-up window having a window menu, a title bar, and a thick border; that is, the dialog box template should specify the WS_POPUP, WS_SYSMENU, WS_CAPTION, and DS_MODALFRAME styles. Although an application can designate the WS_VISIBLE style, the system always displays a modal dialog box regardless of whether the dialog box template specifies the WS_VISIBLE style.
When the owner window is not already disabled, the system automatically disables the window and any child windows belonging to it when it creates the modal dialog box. The owner window remains disabled until the dialog box is destroyed. Although a dialog box procedure could potentially enable the owner window at any time, enabling the owner defeats the purpose of the modal dialog box and is not recommended. When the dialog box procedure is destroyed, the system enables the owner window again, but only if the modal dialog box caused the owner to be disabled.
The system sends the WM_ENTERIDLE message to the owner window whenever the application message queue is empty. The application can use this message to carry out a background task while the dialog box remains on the screen.
A modeless dialog box should be a pop-up window having a window menu, a title bar, and a thin border; that is, the dialog box template should specify the WS_POPUP, WS_CAPTION, WS_BORDER, and WS_SYSMENU styles. The system does not automatically display the dialog box unless the template specifies the WS_VISIBLE style. The application can display the dialog box by passing the window handle to the ShowWindow function.
A modeless dialog box neither disables the owner window nor sends messages to it. When creating the dialog box, the system makes it the active window, but the user or the application can change the active window at any time. If the dialog box does become inactive, it remains above the owner window in the Z order, even if the owner window is active.
These measurements are device independent. The measurements are specified in dialog units. To convert measurements from dialog units to screen units (pixels), use the MapDialogRect function, which takes into account the font used by the dialog box and correctly converts a rectangle from dialog units into pixels. For dialog boxes that use the system font, you can use the GetDialogBaseUnits function to perform the conversion calculations yourself, although using MapDialogRect is simpler.
The application must specify the initial coordinates of the upper left corner of the dialog box. Usually the coordinates are relative to the upper left corner of the owner window's client area. When the template specifies the DS_ABSALIGN style or the dialog box has no owner, the position is relative to the upper left corner of the screen. The system sets this initial position when creating the dialog box, but permits an application to adjust the position before displaying the dialog box. For example, an application can retrieve the dimensions of the owner window, calculate a new position that centers the dialog box in the owner window, and then set the position by using the SetWindowPos function.
The application should specify a dialog box width and height that does not exceed the width and height of the screen and ensures that all controls are within the client area of the dialog box. Although the system permits a dialog box to be any size, creating one that is too small or too large can prevent the user from providing input, defeating the purpose of the dialog box. Many applications use more than one dialog box when there are a large number of controls. In such cases, the initial dialog box usually contains one or more buttons that the user can choose to display the next dialog box.
The application specifies the position, width, height, style, identifier, and window class for each control in the dialog box. Controls are created in the order they are specified. The application should specify the appropriate number, type, and order of controls to ensure that the user can enter the input needed to complete the task associated with the dialog box.
For each control, the application specifies style values that define the appearance and operation of the control. Every control is a child window and therefore must have the WS_CHILD style. To ensure that the control is visible when the dialog box is displayed, each control must also have the WS_VISIBLE style. Other commonly used window styles are WS_BORDER for controls that have optional borders, WS_DISABLED for controls that should be disabled when the dialog box is initially created, and WS_TABSTOP and WS_GROUP for controls that can be accessed using the keyboard. The WS_TABSTOP and WS_GROUP styles are used in conjunction with the dialog keyboard interface described later in this topic.
The application may also specify control styles specific to the control's window class. For example, a template that specifies a button control must give a button control style such as BS_PUSHBUTTON or BS_CHECKBOX. The system passes the control styles to the control, allowing the procedure to adapt the appearance and operation of the control.
The system converts the position coordinates and the width and height measurements from dialog base units to pixels, before creates. When the system creates a control, it specifies the dialog box as the parent window. This means the system always interprets the position coordinates of the control as client coordinates, relative to the upper left corner of the dialog box's client area.
When the user clicks Close, the system sends a WM_COMMAND message to the dialog box procedure with the wParam parameter set to IDCANCEL. This is identical to the message sent by the Cancel button when the user clicks it. The recommended action for this message is to close the dialog box and cancel the requested task.
The system uses the average character width of the dialog box font to calculate the position and dimensions of the dialog box. By default, the system draws all text in a dialog box using the SYSTEM_FONT font.
When the dialog box has the DS_SETFONT or DS_SHELLFONT style, the system sends a WM_SETFONT message to the dialog box procedure and to each control as it creates the control. The dialog box procedure is responsible for saving the font handle passed with the WM_SETFONT message and selecting the handle into the display device context whenever it writes text to the window. Predefined controls do this by default.
Microsoft® Windows® 2000/Windows XP: The system font can vary between different versions of Windows. To have your application use the system font no matter which system it is running on, use DS_SHELLFONT with the typeface MS Shell Dlg, and use the DIALOGEX Resource instead of the DIALOG Resource. The system maps this typeface such that your dialog box will use the Tahoma font on Windows 2000/Windows XP, and the MS Sans Serif font on earlier systems. Note that DS_SHELLFONT has no effect if the typeface is not MS Shell Dlg.
Numbers of methods are given in the table: