The Common Dialog Box Library provides a creation function and a structure for each type of common dialog box. To use a common dialog box in its simplest form, you call its creation function and specify a pointer to a structure containing initial values and option flags. After initializing the dialog box, the dialog box procedure uses the structure to return information about the user's input. You can also customize a common dialog box to suit the needs of your application.
The following table provides a brief description of the different types of common dialog boxes, and shows the function and structure used with each type.
| Common Dialog Box | Description |
|---|---|
| Color | Displays available colors and optionally lets the user create custom colors. The user can select a basic or custom color. Use the ChooseColor function and CHOOSECOLOR structure. |
| Find | Displays a dialog box in which the user can type the string to find. The user can also specify search options, such as the search direction and whether the search is case sensitive. Use the FindText function and FINDREPLACE structure. |
| Font | Displays lists of available fonts, point sizes, and other font attributes that the user can select. Use the ChooseFont function and CHOOSEFONT structure. |
| Open | Displays lists of drives, directories, and filename extensions from which the user can select to display a list of filenames. The user can type a filename or select one from the list to identify the file to be opened. Use the GetOpenFileName function and OPENFILENAME structure. |
| Displays information about the installed printer and its configuration. The user can select print job options, such as the range of pages to print and the number of copies, and start the printing process. Use the PrintDlg function and PRINTDLG structure. Windows NT 5.0 and later: To display a Print property sheet rather than a Print dialog box, use the PrintDlgEx function with the PRINTDLGEX structure. The General page of the property sheet is similar to the Print dialog box. The property sheet can also have additional application-specific and driver-specific property pages following the General page. |
|
| Page Setup | Displays the current page configuration. The user can select page configuration options, such as paper orientation, size, source, and margins. Use the PageSetupDlg function and PAGESETUPDLG structure. |
| Replace | Displays a dialog box in which the user can type the string to find and the replacement string. The user can specify search options, such as whether the search is case sensitive, and replacement options, such as the scope of replacement. Use the ReplaceText function and FINDREPLACE structure. |
| Save As | Displays lists of drives, directories, and filename extensions from which the user can select to display a list of filenames. The user can type a filename or select one from the list to specify the name with which to save the file. Use the GetSaveFileName function and OPENFILENAME structure. |
Note Although a Print Setup dialog box is also available, it has been superseded by the Page Setup dialog box. New applications written for Windows 95 or for Windows NT versions 3.51 or later should use the Page Setup dialog box rather than the Print Setup dialog box.
All common dialog boxes are modal, except the Find and Replace dialog boxes. Modal dialog boxes must be closed by the user before the function used to create the dialog box can return. The Find and Replace dialog boxes are modeless; the function returns before the dialog box closes. If you use the Find and Replace dialog boxes, you must also use the IsDialogMessage function in the main message loop of your application to ensure that these dialog boxes correctly process keyboard input, such as the tab and esc keys.