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.

Overviews

Color Dialog Box

Displays a modal dialog box that allows the user to choose a specific color value. The user can choose a color from either a set of basic or custom color palettes. Alternatively, the user can generate a color value by modifying the RGB or hue, saturation, luminosity (HSL) color values of the dialog box user interface.

Common Dialog Box Initialization Flags

Flags are used to modify the behavior and appearance of a common dialog box.

Customizing Common Dialog Boxes

This topic discusses how to use common dialog boxes.

Dialog Box Types

This topic discusses the different dialog boxes.

Find and Replace Dialog Boxes

Displays a modeless dialog box that allows the user to specify a string to search for, as well as options to use when searching for text in a document.

Font Dialog Box

The Font dialog box lets the user choose attributes for a logical font, such as font family and associated font style, point size, effects (underline, strikeout, and text color), and a script (or character set).

Open and Save As Dialog Boxes

The Open dialog box lets the user specify the drive, directory, and the name of a file or set of files to open.

Page Setup Dialog Box

Displays a modal dialog box that allows the user to choose settings that include the paper type, paper source, page orientation, and the width of the page margins.

Print Dialog Box

The Print dialog box lets the user select options for a particular print job.

Print Property Sheet

The Print property sheet is a standard user interface that enables the user to specify the properties of a particular print job.

Using Common Dialog Boxes

This section covers tasks that invoke common dialog boxes.

Functions

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.

The LPCCHOOKPROC type defines a pointer to this callback function. CCHookProc is a placeholder for the application-defined function name.

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. The FRHookProc hook procedure is an application-defined or library-defined callback function that is used with the FindText or ReplaceText function.

The LPFRHOOKPROC type defines a pointer to this callback function. FRHookProc is a placeholder for the application-defined function name.

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. The OFNHookProc hook procedure 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. The OFNHookProcOldStyle hook procedure 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. The PagePaintHook hook procedure is an application-defined or library-defined callback function used with the PageSetupDlg function.

The LPPAGEPAINTHOOK type defines a pointer to this callback function. PagePaintHook is a placeholder for the application-defined or library-defined function name.

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. The PageSetupHook hook procedure is an application-defined or library-defined callback function used with the PageSetupDlg function.

The LPPAGESETUPHOOK type defines a pointer to this callback function. PageSetupHook is a placeholder for the application-defined or library-defined function name.

PrintDlg

Displays a Print Dialog Box. The Print dialog box enables the user to specify the properties of a particular print job.

Windows 2000/XP: The PrintDlg function has been superseded by the PrintDlgEx function. PrintDlgEx displays a Print Property Sheet, which has a General page containing controls similar to the Print dialog box.

PrintDlgEx

Displays a Print property sheet that enables the user to specify the properties of a particular print job. A Print property 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. The PrintHookProc hook procedure is an application-defined or library-defined callback function that is used with the PrintDlg function.

The LPPRINTHOOKPROC type defines a pointer to this callback function. PrintHookProc is a placeholder for the application-defined or library-defined function name.

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

The SetupHookProc hook procedure is 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.

The LPSETUPHOOKPROC type defines a pointer to this callback function. SetupHookProc is a placeholder for the application-defined or library-defined function name.

Interfaces

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

CDM_GETFILEPATH

The CDM_GETFILEPATH message 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

The CDM_GETFOLDERIDLIST message 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

The CDM_GETFOLDERPATH message 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

The CDM_GETSPEC message 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

The CDM_HIDECONTROL message 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

The CDM_SETCONTROLTEXT message 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

The CDM_SETDEFEXT message 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

CDN_FILEOK

The CDN_FILEOK notification message is sent by an Explorer-style Open or Save As dialog box when the user specifies a file name and clicks the OK button.

Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_FOLDERCHANGE

The CDN_FOLDERCHANGE notification message is sent by an Explorer-style Open or Save As dialog box when a new folder is opened.

Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_HELP

The CDN_HELP notification message is sent by an Explorer-style Open or Save As dialog box when the user clicks the Help button.

Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_INCLUDEITEM

The CDN_INCLUDEITEM notification message is 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.

Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_INITDONE

The CDN_INITDONE notification message is 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.

Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_SELCHANGE

The CDN_SELCHANGE notification message is 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.

Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_SHAREVIOLATION

The CDN_SHAREVIOLATION notification message is 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.

Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

CDN_TYPECHANGE

The CDN_TYPECHANGE notification message is 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.

Your OFNHookProc hook procedure receives this message in the form of a WM_NOTIFY message.

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

The WM_PSD_ENVSTAMPRECT message 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

The WM_PSD_FULLPAGERECT message informs 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

The WM_PSD_GREEKTEXTRECT message 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

The WM_PSD_MARGINRECT message 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

The WM_PSD_MINMARGINRECT message informs 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

The WM_PSD_PAGESETUPDLG message 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

The WM_PSD_YAFULLPAGERECT message 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

CHOOSECOLOR

The CHOOSECOLOR structure 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

The CHOOSEFONT structure 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

The DEVNAMES structure 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

The FINDREPLACE structure 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

The OFNOTIFY structure contains 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

The OFNOTIFYEX structure contains information about a CDN_INCLUDEITEM notification message.

OPENFILENAME

The OPENFILENAME structure 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

The OPENFILENAME_NT4 structure is identical to OPENFILENAME with _WIN32_WINNT set to 0x0400. It allows an application to take advantage of other post-Microsoft Windows NT 4.0 features while running on Windows NT 4.0. Also, MFC42 applications must use OPENFILENAME_NT4 to avoid heap corruption. This is because Microsoft Foundation Classes (MFC) has classes with embedded OPENFILENAME structures, and you must use the same structure size.

PAGESETUPDLG

The PAGESETUPDLG structure 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

The PRINTDLG structure 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

The PRINTDLGEX structure 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

The PRINTPAGERANGE structure 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.