CPrintDialogEx Class
Encapsulates the services provided by the Windows Print property sheet.
Syntax
class CPrintDialogEx : public CCommonDialog
Members
Public Constructors
| Name | Description |
|---|---|
| CPrintDialogEx::CPrintDialogEx | Constructs a CPrintDialogEx object. |
Public Methods
| Name | Description |
|---|---|
| CPrintDialogEx::CreatePrinterDC | Creates a printer device context without displaying the Print dialog box. |
| CPrintDialogEx::DoModal | Displays the dialog box and allows the user to make selections. |
| CPrintDialogEx::GetCopies | Retrieves the number of copies requested. |
| CPrintDialogEx::GetDefaults | Retrieves device defaults without displaying a dialog box. |
| CPrintDialogEx::GetDeviceName | Retrieves the name of the currently selected printer device. |
| CPrintDialogEx::GetDevMode | Retrieves the DEVMODE structure. |
| CPrintDialogEx::GetDriverName | Retrieves the name of the system-defined printer device driver. |
| CPrintDialogEx::GetPortName | Retrieves the name of the currently selected printer port. |
| CPrintDialogEx::GetPrinterDC | Retrieves a handle to the printer device context. |
| CPrintDialogEx::PrintAll | Determines whether to print all pages of the document. |
| CPrintDialogEx::PrintCollate | Determines whether collated copies are requested. |
| CPrintDialogEx::PrintCurrentPage | Determines whether to print the current page of the document. |
| CPrintDialogEx::PrintRange | Determines whether to print only a specified range of pages. |
| CPrintDialogEx::PrintSelection | Determines whether to print only the currently selected items. |
Public Data Members
| Name | Description |
|---|---|
| CPrintDialogEx::m_pdex | A structure used to customize a CPrintDialogEx object. |
Remarks
You can rely on the framework to handle many aspects of the printing process for your application. 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 CPrintDialogEx class "as is" with the constructor provided, or you can derive your own dialog class from CPrintDialogEx 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 CPrintDialogEx object, first create the object using the CPrintDialogEx constructor. Once the dialog box has been constructed, you can set or modify any values in the m_pdex structure to initialize the values of the dialog box's controls. The m_pdex structure is of type PRINTDLGEX. For more information on this structure, see the Windows SDK.
If you do not supply your own handles in m_pdex 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.
After initializing the dialog box controls, call the DoModal member function to display the dialog box and allow the user to select print options. When DoModal returns, you can determine whether the user selected the OK, Apply, or Cancel button.
If the user pressed OK, you can use CPrintDialogEx's member functions to retrieve the information input by the user.
The CPrintDialogEx::GetDefaults member function is useful for retrieving the current printer defaults without displaying a dialog box. This method 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.
For more information on using CPrintDialogEx, see Common Dialog Classes.
Inheritance Hierarchy
IObjectWithSite
IPrintDialogCallback
CPrintDialogEx
Requirements
Header: afxdlgs.h
CPrintDialogEx::CPrintDialogEx
Constructs a Windows Print property sheet.
CPrintDialogEx(
DWORD dwFlags = PD_ALLPAGES | PD_USEDEVMODECOPIES | PD_NOPAGENUMS | PD_HIDEPRINTTOFILE | PD_NOSELECTION | PD_NOCURRENTPAGE,
CWnd* pParentWnd = NULL);
Parameters
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 PRINTDLGEX 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.
CPrintDialogEx::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
The returned DC is also stored in the hDC member of m_pdex.
This DC is assumed to be the current printer DC, and any other previously obtained printer DCs must be deleted. This function can be called, and the resulting DC used, without ever displaying the Print dialog box.
CPrintDialogEx::DoModal
Call this function to display the Windows Print property sheet and allow 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
The INT_PTR return value is actually an HRESULT. See the Return Values section in PrintDlgEx in the Windows SDK.
Remarks
If you want to initialize the various print dialog options by setting members of the m_pdex 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.
If the PD_RETURNDC flag is used when calling DoModal, a printer DC will be returned in the hDC member of m_pdex. This DC must be freed with a call to DeleteDC by the caller of CPrintDialogEx.
CPrintDialogEx::GetCopies
Call this function after calling DoModal to retrieve the number of copies requested.
int GetCopies() const;
Return Value
The number of copies requested.
CPrintDialogEx::GetDefaults
Call this function to retrieve the device defaults of the default printer without displaying a dialog box.
BOOL GetDefaults();
Return Value
TRUE if successful, otherwise FALSE.
Remarks
Creates a printer device context (DC) from the DEVMODE and DEVNAMES structures.
GetDefaults does not display the Print property sheet. Instead, it sets the hDevNames and hDevMode members of m_pdex to handles to the DEVMODE and DEVNAMES structures that are initialized for the system default printer. Both hDevNames and hDevMode must be NULL, or GetDefaults fails.
If the PD_RETURNDC flag is set, this function will not only return hDevNames and hDevMode (located in m_pdex.hDevNames and m_pdex.hDevMode) to the caller, but will also return a printer DC in m_pdex.hDC. It is the responsibility of the caller to delete the printer DC and call the Windows GlobalFree function on the handles when you are finished with the CPrintDialogEx object.
CPrintDialogEx::GetDeviceName
Call this function after calling DoModal to retrieve the name of the currently selected printer, or after calling GetDefaults to retrieve the name of the default printer.
CString GetDeviceName() const;
Return Value
The name of the currently selected printer.
Remarks
Use a pointer to the CString object returned by GetDeviceName as the value of lpszDeviceName in a call to CDC::CreateDC.
CPrintDialogEx::GetDevMode
Call this function after calling DoModal or GetDefaults to retrieve information about the printing device.
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.
CPrintDialogEx::GetDriverName
Call this function after calling DoModal or GetDefaults to retrieve the name of the system-defined printer device driver.
CString GetDriverName() const;
Return Value
A CString specifying the system-defined driver name.
Remarks
Use a pointer to the CString object returned by GetDriverName as the value of lpszDriverName in a call to CDC::CreateDC.
CPrintDialogEx::GetPortName
Call this function after calling DoModal or GetDefaults to retrieve the name of the currently selected printer port.
CString GetPortName() const;
Return Value
The name of the currently selected printer port.
CPrintDialogEx::GetPrinterDC
Returns a handle to the printer device context.
HDC GetPrinterDC() const;
Return Value
A handle to the printer device context.
Remarks
You must call the Windows DeleteDC function to delete the device context when you are done using it.
CPrintDialogEx::m_pdex
A PRINTDLGEX structure whose members store the characteristics of the dialog object.
PRINTDLGEX m_pdex;
Remarks
After constructing a CPrintDialogEx object, you can use m_pdex to set various aspects of the dialog box before calling the DoModal member function. For more information on the m_pdex structure, see PRINTDLGEX in the Windows SDK.
If you modify the m_pdex data member directly, you will override any default behavior.
CPrintDialogEx::PrintAll
Call this function after calling DoModal to determine whether to print all pages in the document.
BOOL PrintAll() const;
Return Value
TRUE if all pages in the document are to be printed; otherwise FALSE.
CPrintDialogEx::PrintCollate
Call this function after calling DoModal to determine whether the printer should collate all printed copies of the document.
BOOL PrintCollate() const;
Return Value
TRUE if the user selects the collate check box in the dialog box; otherwise FALSE.
CPrintDialogEx::PrintCurrentPage
Call this function after calling DoModal to determine whether to print the current page in the document.
BOOL PrintCurrentPage() const;
Return Value
TRUE if Print Current Page is selected in the print dialog; otherwise FALSE.
CPrintDialogEx::PrintRange
Call this function after calling DoModal to determine whether to print only a range of pages in the document.
BOOL PrintRange() const;
Return Value
TRUE if only a range of pages in the document are to be printed; otherwise FALSE.
Remarks
The specified page ranges can be determined from m_pdex (see nPageRanges, nMaxPageRanges, and lpPageRanges in the PRINTDLGEX structure in the Windows SDK).
CPrintDialogEx::PrintSelection
Call this function after calling DoModal to determine whether to print only the currently selected items.
BOOL PrintSelection() const;
Return Value
TRUE if only the selected items are to be printed; otherwise FALSE.