`CPrintDialog` Class

Article
03/09/2022

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

Syntax

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 Print property sheet. For more information, see the CPrintDialogEx overview.

CPrintDialog's functionality is superseded 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're 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 don't 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're done with the dialog box. When using the framework's Print Setup implementation provided by CWinApp::OnFilePrintSetup, you don't have to free these handles. The handles are maintained by CWinApp and are freed in CWinApp's destructor. It's 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 isn't 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

CPrintDialog

Requirements

Header: afxdlgs.h

`CPrintDialog::CPrintDialog`

Constructs either a Windows Print or Print Setup dialog object.

CPrintDialog(
    BOOL bPrintSetupOnly,
    DWORD dwFlags = PD_ALLPAGES | PD_USEDEVMODECOPIES | PD_NOPAGENUMS | PD_HIDEPRINTTOFILE | PD_NOSELECTION,
    CWnd* pParentWnd = NULL);

Parameters

bPrintSetupOnly
Specifies whether the standard Windows Print dialog box or Print Setup dialog box is displayed. Set this parameter to TRUE to display the standard Windows Print Setup dialog box. Set it to FALSE to display the Windows Print dialog box. If bPrintSetupOnly is FALSE, a Print Setup option button is still displayed in the Print dialog box.

dwFlags
One or more flags you can use to customize the settings of the dialog box, combined using the bitwise OR operator. For example, the PD_ALLPAGES flag sets the default print range to all pages of the document. See the PRINTDLG structure in the Windows SDK for more information on these flags.

pParentWnd
A pointer to the dialog box's parent or owner window.

Remarks

This member function only constructs the object. Use the DoModal member function to display the dialog box.

Note that when you call the constructor with bPrintSetupOnly set to FALSE, the PD_RETURNDC flag is automatically used. After calling DoModal, GetDefaults, or GetPrinterDC, a printer DC will be returned in m_pd.hDC. This DC must be freed with a call to DeleteDC by the caller of CPrintDialog.

Example

// Display the Windows Print dialog box with "All" radio button 
// initially selected. All other radio buttons are disabled.
CPrintDialog dlg1(FALSE);

// Display the Windows Print dialog box with Collate check box checked.  
CPrintDialog dlg2(FALSE, PD_ALLPAGES | PD_COLLATE | PD_NOPAGENUMS | PD_HIDEPRINTTOFILE);

// Display the Windows Print dialog box with "Selection" radio
// button initially selected. "All" radio button is enabled
// but "Pages" radio button is disabled.
CPrintDialog dlg3(FALSE, PD_SELECTION | PD_USEDEVMODECOPIES);

`CPrintDialog::CreatePrinterDC`

Creates a printer device context (DC) from the DEVMODE and DEVNAMES structures.

HDC CreatePrinterDC();

Return Value

Handle to the newly created printer device context.

Remarks

This DC is assumed to be the current printer DC, and any other previously obtained printer DCs must be deleted by the user. This function can be called, and the resulting DC used, without ever displaying the Print dialog box.

Example

// Display the Windows Print dialog box with "All" radio button 
// initially selected. All other radio buttons are disabled.
CPrintDialog dlg(FALSE);
if (dlg.DoModal() == IDOK)
{
   // Create a printer device context (DC) based on the information
   // selected from the Print dialog.
   HDC hdc = dlg.CreatePrinterDC();
   ASSERT(hdc);
}

`CPrintDialog::DoModal`

Displays the Windows common print dialog box and allows the user to select various printing options such as the number of copies, page range, and whether copies should be collated.

virtual INT_PTR DoModal();

Return Value

IDOK or IDCANCEL. If IDCANCEL is returned, call the Windows CommDlgExtendedError function to determine whether an error occurred.

IDOK and IDCANCEL are constants that indicate whether the user selected the OK or Cancel button.

Remarks

If you want to initialize the various print dialog options by setting members of the m_pd structure, you should do this before calling DoModal, but after the dialog object is constructed.

After calling DoModal, you can call other member functions to retrieve the settings or information input by the user into the dialog box.

Example

See the example for CPrintDialog::CreatePrinterDC.

`CPrintDialog::GetCopies`

Retrieves the number of copies requested.

int GetCopies() const;

Return Value

The number of copies requested.

Remarks

Call this function after calling DoModal to retrieve the number of copies requested.

Example

See the example for CPrintDialog::PrintCollate.

`CPrintDialog::GetDefaults`

Retrieves the device defaults of the default printer without displaying a dialog box.

BOOL GetDefaults();

Return Value

Nonzero if the function was successful; otherwise 0.

Remarks

The retrieved values are placed in the m_pd structure.

In some cases, a call to this function will call the constructor for CPrintDialog with bPrintSetupOnly set to FALSE. In these cases, a printer DC and hDevNames and hDevMode (two handles located in the m_pd data member) are automatically allocated.

If the constructor for CPrintDialog was called with bPrintSetupOnly set to FALSE, this function won't only return hDevNames and hDevMode located in m_pd.hDevNames and m_pd.hDevMode) to the caller, but will also return a printer DC in m_pd.hDC. It's the responsibility of the caller to delete the printer DC and call the Windows GlobalFree function on the handles when you're finished with the CPrintDialog object.

Example

This code fragment gets the default printer's device context and reports to the user the resolution of the printer in dots per inch. (This attribute of the printer's capabilities is often referred to as DPI.)

CPrintDialog dlg(FALSE);

if (!dlg.GetDefaults())
{
   AfxMessageBox(_T("You have no default printer!"));
}
else
{
   // attach to the DC we were given
   CDC dc;
   dc.Attach(dlg.m_pd.hDC);

   // ask for the measurements
   int nHorz = dc.GetDeviceCaps(LOGPIXELSX);
   int nVert = dc.GetDeviceCaps(LOGPIXELSY);

   // almost always the same in both directions, but sometimes not!
   CString str;
   if (nHorz == nVert)
   {
      str.Format(_T("Your printer supports %d pixels per inch"), nHorz);
   }
   else
   {
      str.Format(_T("Your printer supports %d pixels per inch ")
         _T("horizontal resolution, and %d pixels per inch vertical ")
         _T("resolution"), nHorz, nVert);
   }

   // tell the user
   AfxMessageBox(str);

   // Note: no need to call Detach() because we want the CDC destructor
   // to call FreeDC() on the DC we borrowed from the common dialog
}

`CPrintDialog::GetDeviceName`

Retrieves the name of the currently selected printer device.

CString GetDeviceName() const;

Return Value

The name of the currently selected printer.

Remarks

Call this function after calling DoModal to retrieve the name of the currently selected printer, or after calling GetDefaults to retrieve the current device defaults of the default printer. Use a pointer to the CString object returned by GetDeviceName as the value of lpszDeviceName in a call to CDC::CreateDC.

Example

This code fragment shows the user's default printer name and the port it's connected to, along with the spooler name the printer uses. The code might show a message box that says, "Your default printer is HP LaserJet IIIP on \\server\share using winspool.", for example.

CPrintDialog dlg(FALSE);

if (!dlg.GetDefaults())
{
   AfxMessageBox(_T("You have no default printer!"));
}
else
{
   CString strDescription;

   strDescription.Format(_T("Your default printer is %s on %s using %s."),
      (LPCTSTR)dlg.GetDeviceName(),
      (LPCTSTR)dlg.GetPortName(),
      (LPCTSTR)dlg.GetDriverName());

   AfxMessageBox(strDescription);
}

`CPrintDialog::GetDevMode`

Retrieves the DEVMODE structure.

LPDEVMODE GetDevMode() const;

Return Value

The DEVMODE data structure, which contains information about the device initialization and environment of a print driver. You must unlock the memory taken by this structure with the Windows GlobalUnlock function, which is described in the Windows SDK.

Remarks

Call this function after calling DoModal or GetDefaults to retrieve information about the printing device.

Example

See the example for CPrintDialog::PrintCollate.

`CPrintDialog::GetDriverName`

Retrieves the name of the currently selected printer driver.

CString GetDriverName() const;

Return Value

A CString specifying the system-defined driver name.

Remarks

Call this function after calling DoModal or GetDefaults to retrieve the name of the system-defined printer device driver. Use a pointer to the CString object returned by GetDriverName as the value of lpszDriverName in a call to CDC::CreateDC.

Example

See the example for CPrintDialog::GetDeviceName.

`CPrintDialog::GetFromPage`

Retrieves the starting page of the print range.

int GetFromPage() const;

Return Value

The starting page number in the range of pages to be printed.

Remarks

Call this function after calling DoModal to retrieve the starting page number in the range of pages to be printed.

Example

See the example for CPrintDialog::m_pd.

`CPrintDialog::GetPortName`

Retrieves the name of the currently selected printer port.

CString GetPortName() const;

Return Value

The name of the currently selected printer port.

Remarks

Call this function after calling DoModal or GetDefaults to retrieve the name of the currently selected printer port.

Example

See the example for CPrintDialog::GetDeviceName.

`CPrintDialog::GetPrinterDC`

Retrieves a handle to the printer device context.

HDC GetPrinterDC() const;

Return Value

A handle to the printer device context if successful; otherwise NULL.

Remarks

If the bPrintSetupOnly parameter of the CPrintDialog constructor was FALSE (indicating that the Print dialog box is displayed), then GetPrinterDC returns a handle to the printer device context. You must call the Windows DeleteDC function to delete the device context when you're done using it.

Example

CPrintDialog dlg(FALSE);
CPrintDialog dlg(FALSE);
if (dlg.DoModal() == IDOK)
{
   // Get a handle to the printer device context (DC).
   HDC hdc = dlg.GetPrinterDC();
   ASSERT(hdc);

   // Do something with the HDC...

   // Clean up.
   CDC::FromHandle(hdc)->DeleteDC();
}

`CPrintDialog::GetToPage`

Retrieves the ending page of the print range.

int GetToPage() const;

Return Value

The ending page number in the range of pages to be printed.

Remarks

Call this function after calling DoModal to retrieve the ending page number in the range of pages to be printed.

Example

See the example for CPrintDialog::m_pd.

`CPrintDialog::m_pd`

A structure whose members store the characteristics of the dialog object.

PRINTDLG& m_pd;

Remarks

After constructing a CPrintDialog object, you can use m_pd to set various aspects of the dialog box before calling the DoModal member function. For more information on the m_pd structure, see PRINTDLG in the Windows SDK.

If you modify the m_pd data member directly, you'll override any default behavior.

Example

// Display the Windows Print dialog box with "Pages" radio button
// initially selected. "All" and "Pages" radio buttons are
// enabled as well.
CPrintDialog dlg(FALSE, PD_PAGENUMS | PD_USEDEVMODECOPIES);
dlg.m_pd.nMinPage = dlg.m_pd.nFromPage = 1;
dlg.m_pd.nMaxPage = dlg.m_pd.nToPage = 10;
if (dlg.DoModal() == IDOK)
{
   // Determine the starting and ending page numbers for the range 
   // of pages to be printed.

   int from_page = -1, to_page = -1;
   if (dlg.PrintAll())              // print all pages in the document
   {
      from_page = dlg.m_pd.nMinPage;
      to_page = dlg.m_pd.nMaxPage;
   }
   else if (dlg.PrintRange())       // print only a range of pages 
   {                                // in the document 
      from_page = dlg.GetFromPage();
      to_page = dlg.GetToPage();
   }
   else if (dlg.PrintSelection())   // print only the currently selected 
                                    // items
   {
      from_page = to_page = -1;     // -1 to denote unknown yet
   }

   TRACE(_T("Print from %d to %d\n"), from_page, to_page);
}

`CPrintDialog::PrintAll`

Determines whether to print all pages of the document.

BOOL PrintAll() const;

Return Value

Nonzero if all pages in the document are to be printed; otherwise 0.

Remarks

Call this function after calling DoModal to determine whether to print all pages in the document.

Example

See the example for CPrintDialog::m_pd.

`CPrintDialog::PrintCollate`

Determines whether collated copies are requested.

BOOL PrintCollate() const;

Return Value

Nonzero if the user selects the collate check box in the dialog box; otherwise 0.

Remarks

Call this function after calling DoModal to determine whether the printer should collate all printed copies of the document.

Example

// Display the Windows Print dialog box with Collate check box checked.
CPrintDialog dlg(FALSE, PD_ALLPAGES | PD_COLLATE | PD_NOPAGENUMS |
   PD_HIDEPRINTTOFILE);
if (dlg.DoModal() == IDOK)
{
   // If the collate check box is selected, then GetCopies() will return
   // the number of copies printed. Otherwise, GetCopies() always 
   // returns 1. Then, the number of copies printed can be found from the
   // DEVMODE structure of the printing device.
   if (dlg.PrintCollate())
   {
      int num = dlg.GetCopies();
      TRACE(_T("Number of copies printed = %d\n"), num);
   }
   else
   {
      LPDEVMODE devmode = dlg.GetDevMode();
      TRACE(_T("Number of copies printed = %d\n"), devmode->dmCopies);
   }
}

`CPrintDialog::PrintRange`

Determines whether to print only a specified range of pages.

BOOL PrintRange() const;

Return Value

Nonzero if only a range of pages in the document are to be printed; otherwise 0.

Remarks

Call this function after calling DoModal to determine whether to print only a range of pages in the document.

Example

See the example for CPrintDialog::m_pd.

`CPrintDialog::PrintSelection`

Determines whether to print only the currently selected items.

BOOL PrintSelection() const;

Return Value

Nonzero if only the selected items are to be printed; otherwise 0.

Remarks

Call this function after calling DoModal to determine whether to print only the currently selected items.

Example

See the example for CPrintDialog::m_pd.

Share via

CPrintDialog Class

Syntax

Members

Public Constructors

Public Methods

Public Data Members

Remarks

Inheritance Hierarchy

Requirements

CPrintDialog::CPrintDialog

Parameters

Remarks

Example

CPrintDialog::CreatePrinterDC

Return Value

Remarks

Example

CPrintDialog::DoModal

Return Value

Remarks

Example

CPrintDialog::GetCopies

Return Value

Remarks

Example

CPrintDialog::GetDefaults

Return Value

Remarks

Example

CPrintDialog::GetDeviceName

Return Value

Remarks

Example

CPrintDialog::GetDevMode

Return Value

Remarks

Example

CPrintDialog::GetDriverName

Return Value

Remarks

Example

CPrintDialog::GetFromPage

Return Value

Remarks

Example

CPrintDialog::GetPortName

Return Value

Remarks

Example

CPrintDialog::GetPrinterDC

Return Value

Remarks

Example

CPrintDialog::GetToPage

Return Value

Remarks

Example

CPrintDialog::m_pd

Remarks

Example

CPrintDialog::PrintAll

Return Value

Remarks

Example

CPrintDialog::PrintCollate

Return Value

Remarks

Example

CPrintDialog::PrintRange

Return Value

Remarks

Example

CPrintDialog::PrintSelection

Return Value

Remarks

Example

See also

Feedback

Additional resources

`CPrintDialog` Class

`CPrintDialog::CPrintDialog`

`CPrintDialog::CreatePrinterDC`

`CPrintDialog::DoModal`

`CPrintDialog::GetCopies`

`CPrintDialog::GetDefaults`

`CPrintDialog::GetDeviceName`

`CPrintDialog::GetDevMode`

`CPrintDialog::GetDriverName`

`CPrintDialog::GetFromPage`

`CPrintDialog::GetPortName`

`CPrintDialog::GetPrinterDC`

`CPrintDialog::GetToPage`

`CPrintDialog::m_pd`

`CPrintDialog::PrintAll`

`CPrintDialog::PrintCollate`

`CPrintDialog::PrintRange`

`CPrintDialog::PrintSelection`