`CPrintDialog` 类

项目
10/12/2023

封装由 Windows 公共对话框提供的打印服务。

语法

class CPrintDialog : public CCommonDialog

成员

公共构造函数

名称	描述
`CPrintDialog::CPrintDialog`	构造 `CPrintDialog` 对象。

公共方法

名称	描述
`CPrintDialog::CreatePrinterDC`	在不显示“打印”对话框的情况下创建打印机设备上下文。
`CPrintDialog::DoModal`	显示对话框并允许用户做出选择。
`CPrintDialog::GetCopies`	检索请求的份数。
`CPrintDialog::GetDefaults`	在不显示对话框的情况下检索设备默认值。
`CPrintDialog::GetDeviceName`	检索当前所选打印机设备的名称。
`CPrintDialog::GetDevMode`	检索 `DEVMODE` 结构。
`CPrintDialog::GetDriverName`	检索当前所选打印机驱动程序的名称。
`CPrintDialog::GetFromPage`	检索打印范围的起始页面。
`CPrintDialog::GetPortName`	检索当前所选打印机端口的名称。
`CPrintDialog::GetPrinterDC`	检索打印机设备上下文的句柄。
`CPrintDialog::GetToPage`	检索打印范围的结束页面。
`CPrintDialog::PrintAll`	确定是否打印文档的所有页面。
`CPrintDialog::PrintCollate`	确定是否请求了已整理的副本。
`CPrintDialog::PrintRange`	确定是否只打印指定范围的页面。
`CPrintDialog::PrintSelection`	确定是否只打印当前所选项。

公共数据成员

“属性”	描述
`CPrintDialog::m_pd`	用于自定义 `CPrintDialog` 对象的结构。

备注

通用打印对话框提供了一种以符合 Windows 标准的方式实现“打印”和“打印设置”对话框的简单方式。

注意

CPrintDialogEx 类封装由 Windows 打印属性表提供的服务。有关详细信息，请参阅 CPrintDialogEx 概述。

CPrintDialog 的功能已由 CPageSetupDialog 的功能所取代，后者提供一个用于打印设置和页面设置的通用对话框。

你可以依赖框架来为应用程序处理打印过程的许多方面。在这种情况下，框架会自动显示用于打印的 Windows 通用对话框。你还可以让框架为应用程序处理打印，但使用自己的打印对话框来替代通用的“打印”对话框。有关使用框架处理打印任务的详细信息，请参阅打印一文。

如果你希望应用程序在没有框架参与的情况下处理打印，可以结合提供的构造函数“按原样”使用 CPrintDialog 类，或者可以从 CPrintDialog 派生自己的对话框类并编写一个构造函数来满足需求。在任一情况下，这些对话框的行为类似于标准 MFC 对话框，因为这些对话框派生自 CCommonDialog 类。

若要使用 CPrintDialog 对象，请先使用 CPrintDialog 构造函数创建该对象。在构造完对话框后，可以设置或修改 m_pd 结构中的任何值来初始化对话框的控件的值。 m_pd 结构的类型为 PRINTDLG。有关此结构的详细信息，请参阅 Windows SDK。

如果你未在 hDevMode 和 hDevNames 成员的 m_pd 中提供自己的句柄，请确保在处理完对话框后为这些句柄调用 Windows 函数 GlobalFree。使用框架的由 CWinApp::OnFilePrintSetup 提供的“打印设置”实现时，不必释放这些句柄。这些句柄由 CWinApp 维护并在 CWinApp 的析构函数中释放。只有在单独使用 CPrintDialog 时才需要释放这些句柄。

初始化对话框控件后，调用 DoModal 成员函数以显示对话框，并允许用户选择打印选项。 DoModal 返回用户选择的是“确定”(IDOK) 还是“取消”(IDCANCEL) 按钮。

如果 DoModal 返回 IDOK，则你可以使用 CPrintDialog 的成员函数之一来检索用户输入的信息。

CPrintDialog::GetDefaults 成员函数可用于在不显示对话框的情况下检索当前打印机默认值。此成员函数不需要用户交互。

可以使用 Windows CommDlgExtendedError 函数来确定对话框初始化期间是否发生了错误，并了解有关错误的详细信息。有关此函数的详细信息，请参阅 Windows SDK。

CPrintDialog 依赖于 Windows 3.1 和更高版本随附的 COMMDLG.DLL 文件。

若要自定义对话框，请从 CPrintDialog 派生类，提供自定义对话框模板，并添加消息映射以处理来自扩展控件的通知消息。任何未处理的消息应传递给基类。不需要自定义挂钩函数。

若要根据对话框是“打印”还是“打印设置”来以不同方式处理同一消息，必须为每个对话框派生一个类。此外，必须重写 Windows AttachOnSetup 函数，在“打印”对话框中选择了“打印设置”按钮时，该函数将处理新对话框的创建。

有关如何使用 CPrintDialog 的详细信息，请参阅通用对话框类。

继承层次结构

CPrintDialog

要求

标头：afxdlgs.h

`CPrintDialog::CPrintDialog`

构造 Windows“打印”或“打印设置”对话框对象。

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

参数

bPrintSetupOnly
指定是要显示标准 Windows“打印”对话框还是“打印设置”对话框。将此参数设置为 TRUE 会显示标准 Windows“打印设置”对话框。将其设置为 FALSE 会显示 Windows“打印”对话框。如果 bPrintSetupOnly 为 FALSE，则“打印设置”选项按钮仍会显示在“打印”对话框中。

dwFlags
可以使用一个或多个标志来自定义对话框的设置，并使用按位“或”运算符组合这些设置。例如，PD_ALLPAGES 标志将默认打印范围设置为文档的所有页面。有关这些标志的详细信息，请参阅 Windows SDK 中的 PRINTDLG 结构。

pParentWnd
指向对话框的父窗口或所有者窗口的指针。

备注

此成员函数只构造对象。使用 DoModal 成员函数显示对话框。

请注意，在 bPrintSetupOnly 设置为 FALSE 的情况下调用构造函数时，会自动使用 PD_RETURNDC 标志。调用 DoModal、GetDefaults 或 GetPrinterDC 后，将在 m_pd.hDC 中返回打印机 DC。必须由 CPrintDialog 的调用方通过 DeleteDC 调用来释放此 DC。

示例

// 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`

从 DEVMODE 和 DEVNAMES 结构创建打印机设备上下文 (DC)。

HDC CreatePrinterDC();

返回值

新建的打印机设备上下文的句柄。

备注

此 DC 假定为当前打印机 DC，先前获取的任何其他打印机 DC 必须由用户删除。可以调用此函数并使用生成的 DC，而无需显示“打印”对话框。

示例

// 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`

显示 Windows 通用打印对话框并允许用户选择各种打印选项，例如份数、页面范围以及是否应整理页面。

virtual INT_PTR DoModal();

返回值

IDOK 或 IDCANCEL。如果返回 IDCANCEL，则调用 Windows CommDlgExtendedError 函数以确定是否发生了错误。

IDOK 和 IDCANCEL 是常量，指示用户选择的是“确定”按钮还是“取消”按钮。

注解

如果要通过设置 m_pd 结构的成员来初始化各种打印对话框选项，则应在调用 DoModal 之前但在构造对话框对象之后执行此操作。

在调用 DoModal 之后，可以调用其他成员函数来检索用户在对话框中输入的设置或信息。

示例

请参阅 CPrintDialog::CreatePrinterDC 的示例。

`CPrintDialog::GetCopies`

检索请求的份数。

int GetCopies() const;

返回值

请求的份数。

备注

调用 DoModal 后可以调用此函数来检索请求的份数。

示例

请参阅 CPrintDialog::PrintCollate 的示例。

`CPrintDialog::GetDefaults`

在不显示对话框的情况下检索默认打印机的设备默认值。

BOOL GetDefaults();

返回值

如果该函数成功，则为非零；否则为 0。

注解

检索到的值将放在 m_pd 结构中。

在某些情况下，调用此函数会在 bPrintSetupOnly 设置为 FALSE 的情况下调用 CPrintDialog 的构造函数。在这种情况下，会自动分配打印机 DC、hDevNames 和 hDevMode（位于 m_pd 数据成员中的两个句柄）。

如果在 bPrintSetupOnly 设置为 FALSE 的情况下调用 CPrintDialog 的构造函数，则此函数不仅会将 m_pd.hDevNames 和 m_pd.hDevMode 中的 hDevNames 和 hDevMode 返回给调用方，而且还会在 m_pd.hDC 中返回打印机 DC。处理完 CPrintDialog 对象后，调用方需负责删除打印机 DC 并在句柄上调用 Windows GlobalFree 函数。

示例

此代码片段获取默认打印机的设备上下文，并向用户报告打印机的分辨率（每英寸点数）。（打印机功能的此属性通常称为 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`

检索当前所选打印机设备的名称。

CString GetDeviceName() const;

返回值

当前所选打印机的名称。

注解

在调用 DoModal 后可以调用此函数来检索当前所选打印机的名称，或者在调用 GetDefaults 后调用此函数来检索默认打印机的当前设备默认值。将指向由 GetDeviceName 返回的 CString 对象的指针用作 CDC::CreateDC 调用中的 lpszDeviceName 值。

示例

此代码片段演示用户的默认打印机名称及其连接到的端口，以及打印机使用的后台处理程序名称。例如，该代码可能会显示一个消息框，其中指出“Your default printer is HP LaserJet IIIP on \\server\share using winspool.”。

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`

检索 DEVMODE 结构。

LPDEVMODE GetDevMode() const;

返回值

DEVMODE 数据结构，其中包含有关打印驱动程序的设备初始化和环境的信息。必须使用 Windows GlobalUnlock 函数解锁此结构占用的内存，Windows SDK 中对该函数进行了介绍。

注解

在调用 DoModal 或 GetDefaults 后可以调用此函数来检索有关打印设备的信息。

示例

请参阅 CPrintDialog::PrintCollate 的示例。

`CPrintDialog::GetDriverName`

检索当前所选打印机驱动程序的名称。

CString GetDriverName() const;

返回值

指定系统定义的驱动程序名称的 CString。

备注

在调用 DoModal 或 GetDefaults 后可以调用此函数来检索系统定义的打印机设备驱动程序的名称。将指向由 GetDriverName 返回的 CString 对象的指针用作 CDC::CreateDC 调用中的 lpszDriverName 值。

示例

请参阅 CPrintDialog::GetDeviceName 的示例。

`CPrintDialog::GetFromPage`

检索打印范围的起始页面。

int GetFromPage() const;

返回值

要打印的页面范围内的起始页码。

注解

在调用 DoModal 后可以调用此函数来检索要打印的页面范围内的起始页码。

示例

请参阅 CPrintDialog::m_pd 的示例。

`CPrintDialog::GetPortName`

检索当前所选打印机端口的名称。

CString GetPortName() const;

返回值

当前所选打印机端口的名称。

备注

在调用 DoModal 或 GetDefaults 后可以调用此函数来检索当前所选打印机端口的名称。

示例

请参阅 CPrintDialog::GetDeviceName 的示例。

`CPrintDialog::GetPrinterDC`

检索打印机设备上下文的句柄。

HDC GetPrinterDC() const;

返回值

如果成功，则返回打印机设备上下文的句柄；否则返回 NULL。

备注

如果 CPrintDialog 构造函数的 bPrintSetupOnly 参数为 FALSE（指示显示“打印”对话框），则 GetPrinterDC 将返回打印机设备上下文的句柄。使用完设备上下文后，必须调用 Windows DeleteDC 函数将其删除。

示例

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`

检索打印范围的结束页面。

int GetToPage() const;

返回值

要打印的页面范围内的结束页码。

备注

在调用 DoModal 后可以调用此函数来检索要打印的页面范围内的结束页码。

示例

请参阅 CPrintDialog::m_pd 的示例。

`CPrintDialog::m_pd`

一个结构，其成员存储对话框对象的特征。

PRINTDLG& m_pd;

备注

构造 CPrintDialog 对象后，可以在调用 DoModal 成员函数之前使用 m_pd 来设置对话框的各个方面。有关 m_pd 结构的详细信息，请参阅 Windows SDK 中的 PRINTDLG。

如果直接修改 m_pd 数据成员，将会重写任何默认行为。

示例

// 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`

确定是否打印文档的所有页面。

BOOL PrintAll() const;

返回值

如果要打印文档中的所有页面，则返回非零值；否则返回 0。

备注

调用 DoModal 后可以调用此函数来确定是否打印文档中的所有页面。

示例

请参阅 CPrintDialog::m_pd 的示例。

`CPrintDialog::PrintCollate`

确定是否请求了已整理的副本。

BOOL PrintCollate() const;

返回值

如果用户在对话框中选中了整理复选框，则返回非零值；否则返回 0。

备注

在调用 DoModal 后可以调用此函数来确定打印机是否应整理文档的所有打印副本。

示例

// 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`

确定是否只打印指定范围的页面。

BOOL PrintRange() const;

返回值

如果仅打印文档中某个范围内的页面，则返回非零值；否则返回 0。

备注

调用 DoModal 后可以调用此函数来确定是否仅打印文档中某个范围内的页面。

示例

请参阅 CPrintDialog::m_pd 的示例。

`CPrintDialog::PrintSelection`

确定是否只打印当前所选项。

BOOL PrintSelection() const;

返回值

如果仅打印选定项，则返回非零值；否则返回 0。

备注

调用 DoModal 后可以调用此函数来确定是否仅打印当前选定项。

示例

请参阅 CPrintDialog::m_pd 的示例。

另请参阅

MFC 示例 DIBLOOK
CCommonDialog 类
 层次结构图
 CPrintInfo 结构

通过

CPrintDialog 类

语法

成员

公共构造函数

公共方法

公共数据成员

备注

继承层次结构

要求

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

返回值

备注

示例

另请参阅

反馈

其他资源

`CPrintDialog` 类

`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`