PRINTDLGA 结构 (commdlg.h)
包含 PrintDlg 函数用于初始化 打印对话框的信息。 用户关闭对话框后,系统将使用此结构返回有关用户选择的信息。
语法
typedef struct tagPDA {
DWORD lStructSize;
HWND hwndOwner;
HGLOBAL hDevMode;
HGLOBAL hDevNames;
HDC hDC;
DWORD Flags;
WORD nFromPage;
WORD nToPage;
WORD nMinPage;
WORD nMaxPage;
WORD nCopies;
HINSTANCE hInstance;
LPARAM lCustData;
LPPRINTHOOKPROC lpfnPrintHook;
LPSETUPHOOKPROC lpfnSetupHook;
LPCSTR lpPrintTemplateName;
LPCSTR lpSetupTemplateName;
HGLOBAL hPrintTemplate;
HGLOBAL hSetupTemplate;
} PRINTDLGA, *LPPRINTDLGA;
成员
lStructSize
类型:DWORD
结构大小(以字节为单位)。
hwndOwner
类型:HWND
拥有对话框的窗口的句柄。 此成员可以是任何有效的窗口句柄,如果对话框没有所有者,也可以为 NULL 。
hDevMode
类型: HGLOBAL
包含 DEVMODE 结构的可移动全局内存对象的句柄。 如果 hDevMode 在输入时不为 NULL ,则必须为 DEVMODE 结构分配可移动内存块并初始化其成员。 PrintDlg 函数使用输入数据初始化对话框中的控件。 当 PrintDlg 返回时,DEVMODE 成员指示用户的输入。
如果 hDevMode 在输入时为 NULL,PrintDlg 会为 DEVMODE 结构分配内存,初始化其成员以指示用户的输入,并返回标识它的句柄。
如果指定打印机的设备驱动程序不支持扩展设备模式,则当 PrintDlg 返回时,hDevMode 为 NULL。
如果设备名称 (由 DEVMODE 结构的 dmDeviceName 成员指定的) 未出现在 WIN.INI 的 [devices] 节中,PrintDlg 将返回错误。
有关 hDevMode 和 hDevNames 成员的详细信息,请参阅本主题末尾的“备注”部分。
hDevNames
类型: HGLOBAL
包含 DEVNAMES 结构的可移动全局内存对象的句柄。 如果 hDevNames 在输入时不为 NULL ,则必须为 DEVNAMES 结构分配可移动内存块并初始化其成员。 PrintDlg 函数使用输入数据初始化对话框中的控件。 当 PrintDlg 返回时,DEVNAMES 成员包含用户选择的打印机的信息。 可以使用此信息创建设备上下文或信息上下文。
hDevNames 成员可以为 NULL,在这种情况下,PrintDlg 为 DEVNAMES 结构分配内存,初始化其成员以指示用户的输入,并返回标识它的句柄。
有关 hDevMode 和 hDevNames 成员的详细信息,请参阅本主题末尾的“备注”部分。
hDC
类型: HDC
设备上下文或信息上下文的句柄,具体取决于 Flags 成员是指定 PD_RETURNDC 还是 PC_RETURNIC 标志。 如果两个标志均未指定,则此成员的值未定义。 如果同时指定了两个标志, PD_RETURNDC 具有优先级。
Flags
类型:DWORD
初始化“ 打印 ”对话框。 当对话框返回时,它会设置这些标志以指示用户的输入。 此成员可以是以下一个或多个值。
值 | 含义 |
---|---|
|
默认标志,指示最初选择“ 全部 ”单选按钮。 此标志用作占位符,指示未指定 PD_PAGENUMS 和 PD_SELECTION 标志。 |
|
如果设置了此标志,则选中“整理检查框。
如果在 PrintDlg 函数返回时设置此标志,则应用程序必须模拟多个副本的排序规则。 有关详细信息,请参阅 PD_USEDEVMODECOPIESANDCOLLATE 标志的说明。 请参阅 PD_NOPAGENUMS。 |
|
禁用“打印到文件检查框。 |
|
启用 在 lpfnPrintHook 成员中指定的挂钩过程。 这将启用“ 打印 ”对话框的挂钩过程。 |
|
指示 hInstance 和 lpPrintTemplateName 成员指定默认 打印 对话框模板的替换项。 |
|
指示 hPrintTemplate 成员标识包含预加载对话框模板的数据块。 此模板替换“ 打印 ”对话框的默认模板。 如果指定了此标志,系统将忽略 lpPrintTemplateName 成员。 |
|
启用 在 lpfnSetupHook 成员中指定的挂钩过程。 这将启用“ 打印设置 ”对话框的挂钩过程。 |
|
指示 hInstance 和 lpSetupTemplateName 成员指定默认 打印设置 对话框模板的替换项。 |
|
指示 hSetupTemplate 成员标识包含预加载对话框模板的数据块。 此模板替换“ 打印设置 ”对话框的默认模板。 如果指定了此标志,系统将忽略 lpSetupTemplateName 成员。 |
|
隐藏“打印到文件检查框。 |
|
隐藏和禁用“ 网络 ”按钮。 |
|
禁用 “页面” 单选按钮和关联的编辑控件。 此外,它还会导致“排序检查”框显示在对话框中。 |
|
禁用“ 选择” 单选按钮。 |
|
防止在没有默认打印机时显示警告消息。 |
|
如果设置了此标志,则选择 “页面” 单选按钮。 如果在 PrintDlg 函数返回时设置此标志, 则 nFromPage 和 nToPage 成员指示用户指定的起始页和结束页。 |
|
使系统显示“ 打印设置 ”对话框而不是“ 打印 ”对话框。 |
|
如果设置了此标志,则选中“打印到文件检查框。 如果在 PrintDlg 函数返回时设置此标志,则由 DEVNAMES 结构的 wOutputOffset 成员指示的偏移量包含字符串“FILE:”。 调用 StartDoc 函数以启动打印操作时,请在 DOCINFO 结构的 lpszOutput 成员中指定此“FILE:”字符串。 指定此字符串会导致打印子系统向用户查询输出文件的名称。 |
|
使 PrintDlg 返回与用户在对话框中所做的选择相匹配的设备上下文。 设备上下文在 hDC 中返回。 |
|
如果设置了此标志, PrintDlg 函数不会显示对话框。 相反,它将 hDevNames 和 hDevMode 成员设置为为系统默认打印机初始化的 DEVMODE 和 DEVNAMES 结构的句柄。 hDevNames 和 hDevMode 必须为 NULL,否则 PrintDlg 将返回错误。 |
|
与 PD_RETURNDC 标志类似,只不过此标志返回信息上下文而不是设备上下文。 如果既未指定 PD_RETURNDC ,也未指定 PD_RETURNIC ,则输出中未定义 hDC 。 |
|
如果设置了此标志,则选择 “选择” 单选按钮。 如果 PD_PAGENUMS 和 PD_SELECTION 均未设置,则选择“ 全部 ”单选按钮。 |
|
使对话框显示 “帮助” 按钮。 hwndOwner 成员必须指定窗口,以接收当用户单击“帮助”按钮时对话框发送的 HELPMSGSTRING 注册消息。 |
|
与 PD_USEDEVMODECOPIESANDCOLLATE 相同。 |
|
此标志指示应用程序是否支持多个副本和排序规则。 在输入时设置此标志以指示应用程序不支持多个副本和排序规则。 在这种情况下,PRINTDLG 结构的 nCopies 成员始终返回 1,并且永远不会在 Flags 成员中设置PD_COLLATE。
如果未设置此标志,则应用程序负责打印和整理多个副本。 在这种情况下,PRINTDLG 结构的 nCopies 成员指示用户想要打印的副本数,Flags 成员中的 PD_COLLATE 标志指示用户是否需要排序规则。 无论是否设置此标志,应用程序都可以从 nCopies 和 PD_COLLATE 确定要呈现的副本数以及是否打印这些副本。 如果设置了此标志,并且打印机驱动程序不支持多个副本,则禁用 “复制 ”编辑控件。 同样,如果设置了此标志,并且打印机驱动程序不支持排序规则,则会禁用“排序规则检查”框。 DEVMODE 结构的 dmCopies 和 dmCollate 成员包含打印机驱动程序使用的副本和整理信息。 如果设置了此标志并且打印机驱动程序支持多个副本, 则 dmCopies 成员指示用户请求的份数。 如果设置了此标志并且打印机驱动程序支持排序规则,则 DEVMODE 结构的 dmCollate 成员指示用户是否需要排序规则。 如果未设置此标志, dmCopies 成员始终返回 1,dmCollate 成员始终为零。 Windows 2000/XP/2003 上的已知问题: 如果在调用 PrintDlg 之前未设置此标志, PrintDlg 可能会在返回时交换 nCopies 和 dmCopies 值。 此问题的解决方法是,如果 dmCopies 的值大于 1,请使用 nCopies,以便在 PrintDlg 返回时获取要打印的实际副本数。 |
若要确保 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 和 Windows 7 上,调用 PrintDlg 或 PrintDlgEx 且PD_RETURNDC设置为 TRUE且PD_USEDEVMODECOPIESANDCOLLATE设置为 FALSE 时,PrintDlg 或 PrintDlgEx 函数设置 PRINTDLG 结构的 nCopies 成员中的份数,并设置由 PRINTDLG 结构的 hDC 成员表示的结构中的份数。
调用 GDI 时,必须忽略 nCopies 的值,将该值视为 1,并使用返回的 hDC 以避免打印重复副本。
nFromPage
类型: WORD
起始页编辑控件的初始值。
当 PrintDlg 返回时,nFromPage 是用户指定的起始页。 如果用户单击“确定”按钮时选择了“页面”单选按钮,PrintDlg 将设置PD_PAGENUMS标志,并且不会返回,直到用户输入的起始页值在最小到最大页面范围内。
如果 nFromPage 或 nToPage 的输入值超出最小/最大范围,则仅当指定了 PD_PAGENUMS 标志时,PrintDlg 才返回错误;否则,它将显示对话框,但将范围外值更改为最小值或最大值。
nToPage
类型: WORD
结束页编辑控件的初始值。 当 PrintDlg 返回时,nToPage 是用户指定的结束页。 如果在使用单击“确定”按钮时选择了“页面”单选按钮,PrintDlg 将设置PD_PAGENUMS标志,并且不会返回,直到用户输入的结束页值在最小到最大页面范围内。
nMinPage
类型: WORD
在“ 开始 ”和“ 到 ”页编辑控件中指定的页面范围的最小值。 如果 nMinPage 等于 nMaxPage,则会禁用 “页面” 单选按钮以及起始和结束页面编辑控件。
nMaxPage
类型: WORD
在“ 开始 ”和“ 到 ”页编辑控件中指定的页面范围的最大值。
nCopies
类型: WORD
如果 hDevMode 为 NULL,则为复制编辑控件的初始副本数;否则,DEVMODE 结构的 dmCopies 成员包含初始值。 当 PrintDlg 返回时,nCopies 包含要打印的实际份数。 此值取决于应用程序还是打印机驱动程序负责打印多个副本。 如果在 Flags 成员中设置了PD_USEDEVMODECOPIESANDCOLLATE标志,则 nCopies 在返回时始终为 1,并且打印机驱动程序负责打印多个副本。 如果未设置标志,则应用程序负责打印 nCopies 指定的份数。 有关详细信息,请参阅 PD_USEDEVMODECOPIESANDCOLLATE 标志的说明。
hInstance
类型: HINSTANCE
如果在 Flags 成员中设置了 PD_ENABLEPRINTTEMPLATE 或 PD_ENABLESETUPTEMPLATE 标志,则 hInstance 是包含由 lpPrintTemplateName 或 lpSetupTemplateName 成员命名的对话框模板的应用程序或模块实例的句柄。
lCustData
类型:LPARAM
系统传递给由 lpfnPrintHook 或 lpfnSetupHook 成员标识的挂钩过程的应用程序定义数据。 当系统将 WM_INITDIALOG 消息发送到挂钩过程时,消息的 lParam 参数是指向创建对话框时指定的 PRINTDLG 结构的指针。 挂钩过程可以使用此指针获取 lCustData 值。
lpfnPrintHook
类型: LPPRINTHOOKPROC
指向 PrintHookProc 挂钩过程的指针,该过程可以处理用于“ 打印 ”对话框的消息。 除非在 Flags 成员中设置了PD_ENABLEPRINTHOOK标志,否则将忽略此成员。
lpfnSetupHook
类型: LPSETUPHOOKPROC
指向 SetupHookProc 挂钩过程的指针,该过程可以处理用于 “打印设置 ”对话框的消息。 除非在 Flags 成员中设置了PD_ENABLESETUPHOOK标志,否则将忽略此成员。
lpPrintTemplateName
类型: LPCTSTR
hInstance 成员标识的模块中对话框模板资源的名称。 此模板替换默认的“ 打印 ”对话框模板。 除非在 Flags 成员中设置了 PD_ENABLEPRINTTEMPLATE 标志,否则将忽略此成员。
lpSetupTemplateName
类型: LPCTSTR
hInstance 成员标识的模块中对话框模板资源的名称。 此模板将替换默认的 “打印设置 ”对话框模板。 除非在 Flags 成员中设置了PD_ENABLESETUPTEMPLATE标志,否则将忽略此成员。
hPrintTemplate
类型: HGLOBAL
如果在 Flags 成员中设置了PD_ENABLEPRINTTEMPLATEHANDLE标志,则 hPrintTemplate 是包含对话框模板的内存对象的句柄。 此模板替换默认的“ 打印 ”对话框模板。
hSetupTemplate
类型: HGLOBAL
如果在 Flags 成员中设置了PD_ENABLESETUPTEMPLATEHANDLE标志,则 hSetupTemplate 是包含对话框模板的内存对象的句柄。 此模板替换默认的 “打印设置 ”对话框模板。
注解
如果 hDevMode 和 hDevNames 均为 NULL,PrintDlg 将使用当前默认打印机初始化对话框。 若要初始化其他打印机的对话框,请使用 DEVNAMES 结构的 wDeviceOffset 成员指定打印机的名称。
请注意,DEVMODE 结构的 dmDeviceName 成员还指定打印机名称。 但是, dmDeviceName 限制为 32 个字符, 而 wDeviceOffset 名称则不是。 如果 wDeviceOffset 和 dmDeviceName 名称不同, PrintDlg 将使用 wDeviceOffset 指定的打印机初始化对话框。
如果设置了PD_RETURNDEFAULT标志,并且 hDevMode 和 hDevNames 均为 NULL,PrintDlg 将使用 hDevNames 和 hDevMode 成员返回有关当前默认打印机的信息,而不显示对话框。
注意
commdlg.h 标头将 PRINTDLG 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配,从而导致编译或运行时错误。 有关详细信息,请参阅 函数原型的约定。
要求
最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
标头 | commdlg.h (包括 Windows.h) |
另请参阅
概念性
引用