PRINTDLGEXA 结构 (commdlg.h)

  • 项目

包含 PrintDlgEx 函数用于初始化 Print 属性表的信息。 用户关闭属性表后，系统使用此结构返回有关用户选择的信息。

语法

typedef struct tagPDEXA {
  DWORD            lStructSize;
  HWND             hwndOwner;
  HGLOBAL          hDevMode;
  HGLOBAL          hDevNames;
  HDC              hDC;
  DWORD            Flags;
  DWORD            Flags2;
  DWORD            ExclusionFlags;
  DWORD            nPageRanges;
  DWORD            nMaxPageRanges;
  LPPRINTPAGERANGE lpPageRanges;
  DWORD            nMinPage;
  DWORD            nMaxPage;
  DWORD            nCopies;
  HINSTANCE        hInstance;
  LPCSTR           lpPrintTemplateName;
  LPUNKNOWN        lpCallback;
  DWORD            nPropertyPages;
  HPROPSHEETPAGE   *lphPropertyPages;
  DWORD            nStartPage;
  DWORD            dwResultAction;
} PRINTDLGEXA, *LPPRINTDLGEXA;

成员

lStructSize

类型：DWORD

结构大小（以字节为单位）。

hwndOwner

类型：HWND

拥有属性表的窗口的句柄。 此成员必须是有效的窗口句柄;它不能为 NULL。

hDevMode

类型： HGLOBAL

包含 DEVMODE 结构的可移动全局内存对象的句柄。 如果 hDevMode 在输入时不为 NULL ，则必须为 DEVMODE 结构分配可移动内存块并初始化其成员。 PrintDlgEx 函数使用输入数据初始化属性表中的控件。 PrintDlgEx 返回时，DEVMODE 成员指示用户的输入。

如果 hDevMode 在输入时为 NULL ， PrintDlgEx 会为 DEVMODE 结构分配内存，初始化其成员以指示用户的输入，并返回标识它的句柄。

有关 hDevMode 和 hDevNames 成员的详细信息，请参阅本主题末尾的“备注”部分。

hDevNames

类型： HGLOBAL

包含 DEVNAMES 结构的可移动全局内存对象的句柄。 如果 hDevNames 在输入时不为 NULL ，则必须为 DEVNAMES 结构分配可移动内存块并初始化其成员。 PrintDlgEx 函数使用输入数据初始化属性表中的控件。 PrintDlgEx 返回时，DEVNAMES 成员包含用户选择的打印机的信息。 可以使用此信息来创建设备上下文或信息上下文。

hDevNames 成员可以为 NULL，在这种情况下，PrintDlgEx 为 DEVNAMES 结构分配内存，初始化其成员以指示用户的输入，并返回标识该成员的句柄。

有关 hDevMode 和 hDevNames 成员的详细信息，请参阅本主题末尾的“备注”部分。

hDC

类型： HDC

设备上下文或信息上下文的句柄，具体取决于 Flags 成员是指定 PD_RETURNDC 还是 PC_RETURNIC 标志。 如果未指定这两个标志，则此成员的值未定义。 如果指定了两个标志，则 PD_RETURNDC 具有优先级。 如果 hDC 不为 NULL，则必须在不再需要 GDI 对象后调用 DeleteDC 以释放它;否则，每当调用 PrintDlgw API 时，都会泄漏 GDI 对象。

Flags

类型：DWORD

可用于初始化 Print 属性表的一组位标志。 当 PrintDlgEx 函数返回时，它会设置这些标志来指示用户的输入。 此成员可以是以下一个或多个值。

若要确保 PrintDlg 或 PrintDlgEx 在 DEVMODE 结构的 dmCopies 和 dmCollate 成员中返回正确的值，请将 PD_RETURNDC = TRUE 和 PD_USEDEVMODECOPIESANDCOLLATE = TRUE。 这样做时，PRINTDLG 结构的 nCopies 成员始终为 1，PD_COLLATE始终为 FALSE。

若要确保 PrintDlg 或 PrintDlgEx 在 nCopies 和 PD_COLLATE 中返回正确的值，请将 PD_RETURNDC = TRUE 和 PD_USEDEVMODECOPIESANDCOLLATE = FALSE。 这样做时， dmCopies 始终为 1， dmCollate 始终为 FALSE。

从 Windows Vista 开始，调用 PrintDlg 或 PrintDlgEx 且PD_RETURNDC设置为 TRUEPD_USEDEVMODECOPIESANDCOLLATE设置为 FALSE 时，PrintDlg 或 PrintDlgEx 函数将设置 PRINTDLG 结构的 nCopies 成员中的副本数，并设置由 PRINTDLG 结构的 hDC 成员表示的结构中的副本数。

调用 GDI 时，必须忽略 nCopies 的值，将该值视为 1，并使用返回的 hDC 以避免打印重复副本。

值 含义
PD_ALLPAGES
0x00000000
 默认标志，指示最初选择了“ 所有” 单选按钮。 此标志用作占位符，指示未指定 PD_PAGENUMS、 PD_SELECTION和 PD_CURRENTPAGE 标志。
PD_COLLATE
0x00000010
 如果设置了此标志，则选中“整理检查框。

如果在 PrintDlgEx 函数返回时设置此标志，则应用程序必须模拟多个副本的排序规则。 有关详细信息，请参阅 PD_USEDEVMODECOPIESANDCOLLATE 标志的说明。

请参阅 PD_NOPAGENUMS。
PD_CURRENTPAGE
0x00400000
 如果设置了此标志，则会选择 “当前页” 单选按钮。 如果未设置 任何PD_PAGENUMS、 PD_SELECTION或 PD_CURRENTPAGE 标志，则选择 “全部 ”单选按钮。
PD_DISABLEPRINTTOFILE
0x00080000
 禁用“打印到文件检查框。
PD_ENABLEPRINTTEMPLATE
0x00004000
 指示 hInstance 和 lpPrintTemplateName 成员指定“ 常规 ”页下半部分中默认对话框模板的替换项。 默认模板包含类似于“ 打印 ”对话框的控件。 系统使用指定的模板创建一个窗口，该窗口是 “常规 ”页的子级。
PD_ENABLEPRINTTEMPLATEHANDLE
0x00010000
 指示 hInstance 成员标识包含预加载对话框模板的数据块。 此模板替换“ 常规 ”页面下半部分中的默认对话框模板。 系统使用指定的模板创建一个窗口，该窗口是 “常规 ”页的子级。 如果指定了此标志，系统将忽略 lpPrintTemplateName 成员。
PD_EXCLUSIONFLAGS
0x01000000
 指示 ExclusionFlags 成员标识要从打印机驱动程序属性页中排除的项目。 如果未设置此标志，则默认情况下将从打印机驱动程序属性页中排除项目。 排除项可防止在 “常规 ”页、任何应用程序指定的页面和打印机驱动程序页之间重复项。
PD_HIDEPRINTTOFILE
0x00100000
 隐藏“打印到文件检查框。
PD_NOCURRENTPAGE
0x00800000
 禁用 “当前页” 单选按钮。
PD_NOPAGENUMS
0x00000008
 禁用 “页面” 单选按钮和关联的编辑控件。 此外，它还会导致“整理检查”框显示在对话框中。
PD_NOSELECTION
0x00000004
 禁用“ 选择” 单选按钮。
PD_NOWARNING
0x00000080
 防止在发生错误时显示警告消息。
PD_PAGENUMS
0x00000002
 如果设置了此标志，则选择 “页面” 单选按钮。 如果未设置 任何PD_PAGENUMS、 PD_SELECTION或 PD_CURRENTPAGE 标志，则选择 “全部 ”单选按钮。 如果在 PrintDlgEx 函数返回时设置此标志， 则 lpPageRanges 成员指示用户指定的页面范围。
PD_PRINTTOFILE
0x00000020
 如果设置了此标志，则选中“打印到文件检查框。 如果在 PrintDlgEx 返回时设置此标志，则 DEVNAMES 结构的 wOutputOffset 成员指示的偏移量将包含字符串“FILE：”。 调用 StartDoc 函数以启动打印操作时，请在 DOCINFO 结构的 lpszOutput 成员中指定此“FILE：”字符串。 指定此字符串会导致打印子系统向用户查询输出文件的名称。
PD_RETURNDC
0x00000100
 使 PrintDlgEx 返回与用户在属性表中所做的选择匹配的设备上下文。 设备上下文在 hDC 中返回。
PD_RETURNDEFAULT
0x00000400
 如果设置了此标志， PrintDlgEx 函数不会显示属性表。 而是将 hDevNames 和 hDevMode 成员设置为为系统默认打印机初始化的 DEVNAMES 和 DEVMODE 结构句柄。 hDevNames 和 hDevMode 都必须为 NULL，否则 PrintDlgEx 将返回错误。
PD_RETURNIC
0x00000200
 与 PD_RETURNDC 标志类似，但此标志返回信息上下文而不是设备上下文。 如果既未指定 PD_RETURNDC ，也未指定 PD_RETURNIC ，则输出上未定义 hDC 。
PD_SELECTION
0x00000001
 如果设置了此标志，则选择 “选择” 单选按钮。 如果未设置 任何PD_PAGENUMS、 PD_SELECTION或 PD_CURRENTPAGE 标志，则选择 “全部 ”单选按钮。
PD_USEDEVMODECOPIES
0x00040000
 与 PD_USEDEVMODECOPIESANDCOLLATE 相同。
PD_USEDEVMODECOPIESANDCOLLATE
0x00040000
 此标志指示应用程序是否支持多个副本和排序规则。 在输入上设置此标志以指示应用程序不支持多个副本和排序规则。 在这种情况下，PRINTDLGEX 结构的 nCopies 成员始终返回 1，并且永远不会在 Flags 成员中设置PD_COLLATE。

如果未设置此标志，则应用程序负责打印和整理多个副本。 在这种情况下，PRINTDLGEX 结构的 nCopies 成员指示用户想要打印的副本数，Flags 成员中的 PD_COLLATE 标志指示用户是否需要排序规则。

无论是否设置此标志，应用程序都可以从 nCopies 和 PD_COLLATE 要呈现的副本数以及是否打印整理的副本。

如果设置了此标志，并且打印机驱动程序不支持多个副本，则会禁用 “副本编辑” 控件。 同样，如果设置了此标志并且打印机驱动程序不支持排序规则，则会禁用“整理检查”框。

DEVMODE 结构的 dmCopies 和 dmCollate 成员包含打印机驱动程序使用的副本和整理信息。 如果设置了此标志，并且打印机驱动程序支持多个副本， 则 dmCopies 成员指示用户请求的份数。 如果设置了此标志并且打印机驱动程序支持排序规则，则 DEVMODE 结构的 dmCollate 成员指示用户是否需要排序规则。 如果未设置此标志， 则 dmCopies 成员始终返回 1， dmCollate 成员始终为零。

在 Windows Vista 之前的 Windows 版本中，如果调用应用程序未设置此标志，并且 DEVMODE 结构的 dmCopies 成员大于 1，请使用该值作为副本数;否则，请使用 PRINTDLGEX 结构的 nCopies 成员的值。
PD_USELARGETEMPLATE
0x10000000
 强制属性表对 “常规 ”页使用大型模板。 较大的模板为为 “常规 ”页面下半部分指定自定义模板的应用程序提供了更多空间。

Flags2

类型：DWORD

ExclusionFlags

类型：DWORD

一组位标志，可以从 Print 属性表中的打印机驱动程序属性页中排除项。 仅当在 Flags 成员中设置了PD_EXCLUSIONFLAGS标志时，才使用此值。 仅当要排除的项将包含在 “常规 ”页或 “打印 ”属性表的应用程序定义的页面上时，才应使用排除标志。 此成员可以指定以下标志。

PD_EXCL_COPIESANDCOLLATE

从打印属性表中的打印机驱动程序属性页中排除“复制”和“整理”控件。 当应用程序使用由 Print 属性表的“常规”页的下半部分提供的默认“副本”和“排序规则”控件时，应始终设置此标志。

nPageRanges

类型：DWORD

输入时，将此成员设置为 lpPageRanges 数组中指定的初始页范围数。 当 PrintDlgEx 函数返回时，nPageRanges 指示存储在 lpPageRanges 数组中的用户指定的页面范围的数目。 如果指定 了PD_NOPAGENUMS 标志，则此值无效。

nMaxPageRanges

类型：DWORD

lpPageRanges 缓冲区的大小（以数组元素为单位）。 此值指示可存储在数组中的页范围的最大数目。 如果指定 了PD_NOPAGENUMS 标志，则此值无效。 如果未指定 PD_NOPAGENUMS 标志，则此值必须大于零。

lpPageRanges

类型： LPPRINTPAGERANGE

指向包含 PRINTPAGERANGE 结构数组的缓冲区的指针。 输入时，数组包含要显示在 Pages 编辑控件中的初始 页面 范围。 当 PrintDlgEx 函数返回时，数组包含用户指定的页面范围。 如果指定 了PD_NOPAGENUMS 标志，则此值无效。 如果未指定 PD_NOPAGENUMS 标志， 则 lpPageRanges 必须为非 NULL。

nMinPage

类型：DWORD

页面 编辑控件 中指定的页面范围的最小值。 如果指定 了PD_NOPAGENUMS 标志，则此值无效。

nMaxPage

类型：DWORD

页面 编辑控件 中指定的页面范围的最大值。 如果指定 了PD_NOPAGENUMS 标志，则此值无效。

nCopies

类型：DWORD

如果 hDevMode 为 NULL，则包含副本编辑控件的初始副本数;否则，DEVMODE 结构的 dmCopies 成员包含初始值。 当 PrintDlgEx 返回时，nCopies 包含应用程序必须打印的实际副本数。 此值取决于应用程序还是打印机驱动程序负责打印多个副本。 如果在 Flags 成员中设置了PD_USEDEVMODECOPIESANDCOLLATE标志，则 nCopies 在返回时始终为 1，并且打印机驱动程序负责打印多个副本。 如果未设置标志，则应用程序负责打印 nCopies 指定的副本数。 有关详细信息，请参阅 PD_USEDEVMODECOPIESANDCOLLATE 标志的说明。

hInstance

类型： HINSTANCE

如果在 Flags 成员中设置了PD_ENABLEPRINTTEMPLATE标志，则 hInstance 是包含由 lpPrintTemplateName 成员命名的对话框模板的应用程序或模块实例的句柄。 如果在 Flags 成员中设置了PD_ENABLEPRINTTEMPLATEHANDLE标志，则 hInstance 是包含对话框模板的内存对象的句柄。 如果未在 Flags 成员中设置这两个模板标志， 则 hInstance 应为 NULL。

lpPrintTemplateName

类型： LPCTSTR

hInstance 成员标识的模块中对话框模板资源的名称。 此模板替换“ 常规 ”页面下半部分中的默认对话框模板。 默认模板包含类似于“ 打印 ”对话框的控件。 除非在 Flags 成员中设置了PD_ENABLEPRINTTEMPLATE标志，否则将忽略此成员。

lpCallback

类型： LPUNKNOWN

指向应用程序定义的回调对象的指针。

对象应包含 IPrintDialogCallback 类，用于在 “常规 ”页的下半部分接收子对话框的消息。

回调对象还应包含 IObjectWithSite 类，以接收指向 IPrintDialogServices 接口的 指针。 PrintDlgEx 函数在回调对象上调用 IUnknown：：QueryInterface，以便IID_IPrintDialogCallback和IID_IObjectWithSite确定支持哪些接口。

如果不想检索任何回调信息，请将 lpCallback 设置为 NULL。

nPropertyPages

类型：DWORD

lphPropertyPages 数组中的属性页句柄数。

lphPropertyPages

类型： HPROPSHEETPAGE*

包含要添加到 Print 属性表的属性页句柄数组。 其他属性页遵循 “常规 ”页。 使用 CreatePropertySheetPage 函数创建这些附加页面。 当 PrintDlgEx 函数返回时，lphPropertyPages 数组中的所有 HPROPSHEETPAGE 句柄都已被销毁。 如果 nPropertyPages 为零， 则 lphPropertyPages 应为 NULL。

nStartPage

类型：DWORD

最初显示的属性页。 若要显示“ 常规 ”页， 请指定START_PAGE_GENERAL。 否则，请在 lphPropertyPages 成员中指定的数组中指定属性页的从零开始的索引。 为保持一致，建议始终在“ 常规 ”页上启动属性表。

dwResultAction

类型：DWORD

输入时，将此成员设置为零。 如果 PrintDlgEx 函数返回S_OK， 则 dwResultAction 包含对话框的结果。 如果 PrintDlgEx 返回错误，则应忽略此成员。 dwResultAction 成员可以是以下值之一。

PD_RESULT_APPLY

用户单击了“ 应用 ”按钮，随后又单击了“ 取消 ”按钮。 这表示用户想要应用在属性表中所做的更改，但尚不想打印。 PRINTDLGEX 结构包含用户单击“应用”按钮时指定的信息。

PD_RESULT_CANCEL

用户单击了“ 取消 ”按钮。 PRINTDLGEX 结构中的信息保持不变。

PD_RESULT_PRINT

用户单击了“ 打印 ”按钮。 PRINTDLGEX 结构包含用户指定的信息。

注解

如果 hDevMode 和 hDevNames 均为 NULL， PrintDlgEx 将使用当前默认打印机初始化属性表。 若要初始化其他打印机的属性表，请使用 DEVNAMES 结构的 wDeviceOffset 成员指定打印机的名称。

请注意，DEVMODE 结构的 dmDeviceName 成员还指定打印机名称。 但是， dmDeviceName 限制为 32 个字符，而 wDeviceOffset 名称则不是。 如果 wDeviceOffset 和 dmDeviceName 名称不同， PrintDlgEx 将使用 wDeviceOffset 指定的打印机初始化属性表。

如果设置了PD_RETURNDEFAULT标志，并且 hDevMode 和 hDevNames 均为 NULL， PrintDlgEx 将使用 hDevNames 和 hDevMode 成员返回有关当前默认打印机的信息，而不显示对话框。

在执行 PrintDlgEx 期间，在 PRINTDLGEX 结构中指定的 DEVMODE 和 DEVNAMES 结构可能并不总是包含当前数据。 因此，应用程序特定的属性页以及初始页的 IPrintDialogCallback 例程应使用 IPrintDialogServices 接口来检索有关当前打印机状态的信息。

注意

commdlg.h 标头将 PRINTDLGEX 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

   
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
标头 commdlg.h (包括 Windows.h)

另请参阅

通用对话框库

概念性

DEVMODE

DEVNAMES

IPrintDialogCallback

IPrintDialogServices

PrintDlgEx

引用