Common Dialog Box Library
The Common Dialog Box Library contains a set of dialog boxes for performing common application tasks, such as opening files, choosing color values, and printing documents. The common dialog boxes allow you to implement a consistent approach to your application's user interface. This reduces the amount of effort that users spend in learning user interface behavior for your application.
This section describes the common dialog boxes which include the Open and Save As file dialog boxes; the Find and Replace editing dialog boxes; the Print, Print Setup, Print Property Sheet, and Page Setup printing dialog boxes; and the Color and Font dialog boxes.
Note
Starting with Windows Vista, the Open and Save As common dialog boxes have been superseded by the Common Item Dialog. We recommended that you use the Common Item Dialog API instead of these dialog boxes from the Common Dialog Box Library.
In This Section
| Name | Description |
|---|---|
| Common Dialog Box Types | Discusses the different dialog boxes. |
| Common Dialog Box Initialization Flags | Discusses how flags are used to modify the behavior and appearance of a common dialog box. |
| Customizing Common Dialog Boxes | Discusses how to use common dialog boxes. |
| Using Common Dialog Boxes | Covers tasks that invoke common dialog boxes. |
| Common Dialog Box Reference | Contains the API reference. |
Functions
| Name | Description |
|---|---|
| CCHookProc | Receives messages or notifications intended for the default dialog box procedure of the Color dialog box. This is an application-defined or library-defined callback function that is used with the ChooseColor function. |
| CFHookProc | Receives messages or notifications intended for the default dialog box procedure of the Font dialog box. This is an application-defined or library-defined callback procedure that is used with the ChooseFont function. |
| ChooseColor | Creates a Color dialog box that enables the user to select a color. |
| ChooseFont | Creates a Font dialog box that enables the user to choose attributes for a logical font. These attributes include a font family and associated font style, a point size, effects (underline, strikeout, and text color), and a script (or character set). |
| CommDlgExtendedError | Returns a common dialog box error code. This code indicates the most recent error to occur during the execution of one of the common dialog box functions. |
| FindText | Creates a system-defined modeless Find dialog box that lets the user specify a string to search for and options to use when searching for text in a document. |
| FRHookProc | Receives messages or notifications intended for the default dialog box procedure of the Find or Replace dialog box. This is an application-defined or library-defined callback function that is used with the FindText or ReplaceText function. |
| GetFileTitle | Retrieves the name of the specified file. |
| GetOpenFileName | Creates an Open dialog box that lets the user specify the drive, directory, and the name of a file or set of files to open. |
| GetSaveFileName | Creates a Save dialog box that lets the user specify the drive, directory, and name of a file to save. |
| OFNHookProc | Receives notification messages sent from the dialog box. The function also receives messages for any additional controls that you defined by specifying a child dialog template. This is an application-defined or library-defined callback function that is used with the Explorer-style Open and Save As dialog boxes. |
| OFNHookProcOldStyle | Receives messages or notifications intended for the dialog box procedure. This is an application-defined or library-defined callback function that is used with the Open and Save As dialog boxes. |
| PagePaintHook | Receives messages that allow you to customize drawing of the sample page in the Page Setup dialog box. This is an application-defined or library-defined callback function used with the PageSetupDlg function. |
| PageSetupDlg | Creates a Page Setup dialog box that enables the user to specify the attributes of a printed page. These attributes include the paper size and source, the page orientation (portrait or landscape), and the width of the page margins. |
| PageSetupHook | Receives messages or notifications intended for the default dialog box procedure of the Page Setup dialog box. This is an application-defined or library-defined callback function used with thePageSetupDlgfunction. |
| PrintDlg | Displays aPrint Dialog Box. The Print dialog box enables the user to specify the properties of a particular print job. |
| PrintDlgEx | Displays a Print property sheet that enables the user to specify the properties of a particular print job.APrintproperty sheet has a General page that contains controls similar to the Print dialog box. The property sheet can also have additional application-specific and driver-specific property pages as well as the General page. |
| PrintHookProc | Receives messages or notifications intended for the default dialog box procedure of the Print dialog box. This is an application-defined or library-defined callback function that is used with the PrintDlg function. |
| ReplaceText | Creates a system-defined modeless dialog box that lets the user specify a string to search for and a replacement string, as well as options to control the find and replace operations. |
| SetupHookProc | An application-defined or library-defined callback function used with the PrintDlg function. The hook procedure receives messages or notifications intended for the default dialog box procedure of the Print Setup dialog box. |
Interfaces
| Name | Description |
|---|---|
| IPrintDialogCallback | Provides methods that enable an application to receive notifications and messages from the PrintDlgEx function while the Print Property Sheet is displayed. |
| IPrintDialogServices | Provides methods that enable an application using the PrintDlgEx function to retrieve information about the currently selected printer. |
Messages
| Name | Description |
|---|---|
| CDM_GETFILEPATH | Retrieves the path and file name of the selected file in an Explorer-style Open or Save As dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails. |
| CDM_GETFOLDERIDLIST | Retrieves the address of the item identifier list corresponding to the folder that an Explorer-style Open or Save As dialog box currently has open. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails. |
| CDM_GETFOLDERPATH | Retrieves the path of the currently open folder or directory for an Explorer-style Open or Save As dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails. |
| CDM_GETSPEC | Retrieves the file name (not including the path) of the currently selected file in an Explorer-style Open or Save As dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails. |
| CDM_HIDECONTROL | Hides the specified control in an Explorer-style Open or Save As dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails. |
| CDM_SETCONTROLTEXT | Sets the text for the specified control in an Explorer-style Open or Save As dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails. |
| CDM_SETDEFEXT | Sets the default file name extension for an Explorer-style Open or Save As dialog box. The dialog box must have been created with the OFN_EXPLORER flag; otherwise, the message fails. |
| SETRGBSTRING | The hook procedure of a Color dialog box, CCHookProc, can send the SETRGBSTRING registered message to the dialog box to set the current color selection. |
| WM_CHOOSEFONT_GETLOGFONT | An application sends the WM_CHOOSEFONT_GETLOGFONT message to a Font dialog box to retrieve information about the user's current font selections. |
| WM_CHOOSEFONT_SETFLAGS | An application sends the WM_CHOOSEFONT_SETFLAGS message to a Font dialog box to set the display options for the dialog box. |
| WM_CHOOSEFONT_SETLOGFONT | An application sends the WM_CHOOSEFONT_SETLOGFONT message to a Font dialog box to set the current logical font information. |
Notifications
| Name | Description |
|---|---|
| CDN_FILEOK | Sent by an Explorer-style Open or Save As dialog box when the user specifies a file name and clicks the OK button. |
| CDN_FOLDERCHANGE | Sent by an Explorer-style Open or Save As dialog box when a new folder is opened. |
| CDN_HELP | Sent by an Explorer-style Open or Save As dialog box when the user clicks the Help button. |
| CDN_INCLUDEITEM | Sent by an Open or Save As dialog box to determine whether the dialog box should display an item in a shell folder's item list. When the user opens a folder, the dialog box sends a CDN_INCLUDEITEM notification for each item in the folder. The dialog box sends this notification only if the OFN_ENABLEINCLUDENOTIFY flag was set when the dialog box was created. |
| CDN_INITDONE | Sent by an Explorer-style Open or Save As dialog box when the system has finished arranging the controls in the dialog box. The system moves the standard controls to make room for the controls of the child dialog box. |
| CDN_SELCHANGE | Sent by an Explorer-style Open or Save As dialog box when the selection changes in the list box that displays the contents of the currently opened folder or directory. |
| CDN_SHAREVIOLATION | Sent by an Explorer-style Open or Save As dialog box when the user clicks the OK button and a network sharing violation occurs for the selected file. |
| CDN_TYPECHANGE | Sent by an Explorer-style Open or Save As dialog box when the user selects a new file type from the file types combo box. |
| COLOROKSTRING | A Color dialog box sends the COLOROKSTRING registered message to your hook procedure, CCHookProc, when the user selects a color and clicks the OK button. The hook procedure can accept the color and allow the dialog box to close, or reject the color and force the dialog box to remain open. |
| FILEOKSTRING | An Open or Save As dialog box sends the FILEOKSTRING registered message to your hook procedure, OFNHookProc, when the user specifies a file name and clicks the OK button. The hook procedure can accept the file name and allow the dialog box to close, or reject the file name and force the dialog box to remain open. |
| FINDMSGSTRING | A Find or Replace dialog box sends the FINDMSGSTRING registered message to the window procedure of its owner window when the user clicks the Find Next, Replace, or Replace All button, or closes the dialog box. |
| HELPMSGSTRING | A common dialog box sends the HELPMSGSTRING registered message to the window procedure of its owner window when the user clicks the Help button. |
| LBSELCHSTRING | An Open or Save As dialog box sends the LBSELCHSTRING registered message to your hook procedure when the selection changes in any of the list boxes or combo boxes of the dialog box. |
| SHAREVISTRING | An Open or Save As dialog box sends the SHAREVISTRING registered message to your hook procedure, OFNHookProc, if a sharing violation occurs for the selected file when the user clicks the OK button. |
| WM_PSD_ENVSTAMPRECT | Notifies the hook procedure of a Page Setup dialog box, PagePaintHook, that the dialog box is about to draw the envelope-stamp rectangle of the sample page. |
| WM_PSD_FULLPAGERECT | Notifies a PagePaintHook hook procedure of the coordinates of the sample page rectangle in the Page Setup dialog box. The dialog box sends this message when it is about to draw the contents of the sample page. |
| WM_PSD_GREEKTEXTRECT | Notifies the hook procedure of a Page Setup dialog box, PagePaintHook, that the dialog box is about to draw Greek text inside the margin rectangle of the sample page. |
| WM_PSD_MARGINRECT | Notifies the hook procedure of a Page Setup dialog box, PagePaintHook, that the dialog box is about to draw the margin rectangle of the sample page. |
| WM_PSD_MINMARGINRECT | Notifies a PagePaintHook hook procedure of the coordinates of the margin rectangle in the sample page. A Page Setup dialog box sends this message when it is about to draw the contents of the sample page. |
| WM_PSD_PAGESETUPDLG | Notifies a PagePaintHook hook procedure that the Page Setup dialog box is about to draw the contents of the sample page. The hook procedure can use this message to carry out initialization tasks related to drawing the contents of the sample page. |
| WM_PSD_YAFULLPAGERECT | Notifies the hook procedure of a Page Setup dialog box, PagePaintHook, that the dialog box is about to draw the return address portion of an envelope sample page. |
Structures
| Name | Description |
|---|---|
| CHOOSECOLOR | Contains information the ChooseColor function uses to initialize the Color dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure. |
| CHOOSEFONT | Contains information that the ChooseFont function uses to initialize the Font dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure. |
| DEVNAMES | Contains strings that identify the driver, device, and output port names for a printer. The PrintDlgEx and PrintDlg functions use these strings to initialize the system-defined Print Property Sheet or Print Dialog Box. When the user closes the property sheet or dialog box, information about the selected printer is returned in this structure. |
| FINDREPLACE | Contains information that the FindText and ReplaceText functions use to initialize the Find and Replace dialog boxes. The FINDMSGSTRING registered message uses this structure to pass the user's search or replacement input to the owner window of a Find or Replace dialog box. |
| OFNOTIFY | Ccontains information about a WM_NOTIFY message sent to an OFNHookProc hook procedure for an Open or Save As dialog box. The lParam parameter of the WM_NOTIFY message is a pointer to an OFNOTIFY structure. |
| OFNOTIFYEX | Contains information about a CDN_INCLUDEITEM notification message. |
| OPENFILENAME | Contains information that the GetOpenFileName and GetSaveFileName functions use to initialize an Open or Save As dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure. |
| OPENFILENAME_NT4 | Identical to OPENFILENAME with _WIN32_WINNT set to 0x0400. |
| PAGESETUPDLG | Contains information the PageSetupDlg function uses to initialize the Page Setup dialog box. After the user closes the dialog box, the system returns information about the user-defined page parameters in this structure. |
| PRINTDLG | Contains information that the PrintDlg function uses to initialize the Print Dialog Box. After the user closes the dialog box, the system uses this structure to return information about the user's selections. |
| PRINTDLGEX | Contains information that the PrintDlgEx function uses to initialize the Print property sheet. After the user closes the property sheet, the system uses this structure to return information about the user's selections. |
| PRINTPAGERANGE | Specifies a range of pages in a print job. A print job can have more than one page range. This information is supplied in the PRINTDLGEX structure when calling the PrintDlgEx function. |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for