Share via


CPrintDialog Class

Encapsulates the services provided by the Windows common dialog box for printing.

class CPrintDialog : public CCommonDialog

Members

Public Constructors

Name

Description

CPrintDialog::CPrintDialog

Constructs a CPrintDialog object.

Public Methods

Name

Description

CPrintDialog::CreatePrinterDC

Creates a printer device context without displaying the Print dialog box.

CPrintDialog::DoModal

Displays the dialog box and allows the user to make a selection.

CPrintDialog::GetCopies

Retrieves the number of copies requested.

CPrintDialog::GetDefaults

Retrieves device defaults without displaying a dialog box.

CPrintDialog::GetDeviceName

Retrieves the name of the currently selected printer device.

CPrintDialog::GetDevMode

Retrieves the DEVMODE structure.

CPrintDialog::GetDriverName

Retrieves the name of the currently selected printer driver.

CPrintDialog::GetFromPage

Retrieves the starting page of the print range.

CPrintDialog::GetPortName

Retrieves the name of the currently selected printer port.

CPrintDialog::GetPrinterDC

Retrieves a handle to the printer device context.

CPrintDialog::GetToPage

Retrieves the ending page of the print range.

CPrintDialog::PrintAll

Determines whether to print all pages of the document.

CPrintDialog::PrintCollate

Determines whether collated copies are requested.

CPrintDialog::PrintRange

Determines whether to print only a specified range of pages.

CPrintDialog::PrintSelection

Determines whether to print only the currently selected items.

Public Data Members

Name

Description

CPrintDialog::m_pd

A structure used to customize a CPrintDialog object.

Remarks

Common print dialog boxes provide an easy way to implement Print and Print Setup dialog boxes in a manner consistent with Windows standards.

Note

The CPrintDialogEx class encapsulates the services provided by the Windows 2000 Print property sheet. For more information see the CPrintDialogEx overview.

CPrintDialog's functionality is superceded by that of CPageSetupDialog, which is designed to provide you with a common dialog box for both print setup and page setup.

You can rely on the framework to handle many aspects of the printing process for your application. In this case, the framework automatically displays the Windows common dialog box for printing. You can also have the framework handle printing for your application but override the common Print dialog box with your own print dialog box. For more information about using the framework to handle printing tasks, see the article Printing.

If you want your application to handle printing without the framework's involvement, you can use the CPrintDialog class "as is" with the constructor provided, or you can derive your own dialog class from CPrintDialog and write a constructor to suit your needs. In either case, these dialog boxes will behave like standard MFC dialog boxes because they are derived from class CCommonDialog.

To use a CPrintDialog object, first create the object using the CPrintDialog constructor. Once the dialog box has been constructed, you can set or modify any values in the m_pd structure to initialize the values of the dialog box's controls. The m_pd structure is of type PRINTDLG. For more information on this structure, see the Windows SDK.

If you do not supply your own handles in m_pd for the hDevMode and hDevNames members, be sure to call the Windows function GlobalFree for these handles when you are done with the dialog box. When using the framework's Print Setup implementation provided by CWinApp::OnFilePrintSetup, you do not have to free these handles. The handles are maintained by CWinApp and are freed in CWinApp's destructor. It is only necessary to free these handles when using CPrintDialog stand-alone.

After initializing the dialog box controls, call the DoModal member function to display the dialog box and allow the user to select print options. DoModal returns whether the user selected the OK (IDOK) or Cancel (IDCANCEL) button.

If DoModal returns IDOK, you can use one of CPrintDialog's member functions to retrieve the information input by the user.

The CPrintDialog::GetDefaults member function is useful for retrieving the current printer defaults without displaying a dialog box. This member function requires no user interaction.

You can use the Windows CommDlgExtendedError function to determine whether an error occurred during initialization of the dialog box and to learn more about the error. For more information on this function, see the Windows SDK.

CPrintDialog relies on the COMMDLG.DLL file that ships with Windows versions 3.1 and later.

To customize the dialog box, derive a class from CPrintDialog, provide a custom dialog template, and add a message map to process the notification messages from the extended controls. Any unprocessed messages should be passed on to the base class. Customizing the hook function is not required.

To process the same message differently depending on whether the dialog box is Print or Print Setup, you must derive a class for each dialog box. You must also override the Windows AttachOnSetup function, which handles the creation of a new dialog box when the Print Setup button is selected within a Print dialog box.

For more information on using CPrintDialog, see Common Dialog Classes.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CDialog

CCommonDialog

CPrintDialog

Requirements

Header: afxdlgs.h

See Also

Reference

CCommonDialog Class

Hierarchy Chart

CPrintInfo Structure

Concepts

MFC Sample DIBLOOK