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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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

NameDescription
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.

 

 

 

Community Additions

ADD
Show:
© 2014 Microsoft