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 a Print 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.