[This is preliminary documentation and subject to change.]
The PRINTDLGEX structure contains information that the PrintDlgEx function uses to initialize the Print property sheet. After the user closes the property sheet, the system uses this structure to return information about the user's selections.
typedef struct tagPDEX {
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;
LPCTSTR lpPrintTemplateName;
LPUNKNOWN lpCallback;
DWORD nPropertyPages;
HPROPSHEETPAGE *lphPropertyPages;
DWORD nStartPage;
DWORD dwResultAction;
} PRINTDLGEX, *LPPRINTDLGEX;
If hDevMode is NULL on input, PrintDlgEx allocates memory for the DEVMODE structure, initializes its members to indicate the user's input, and returns a handle that identifies it.
For more information about the hDevMode and hDevNames members, see the Remarks section at the end of this topic.
The hDevNames member can be NULL, in which case, PrintDlgEx allocates memory for the DEVNAMES structure, initializes its members to indicate the user's input, and returns a handle that identifies it.
For more information about the hDevMode and hDevNames members, see the Remarks section at the end of this topic.
| PD_ALLPAGES | |
| The default flag that indicates that the All radio button is initially selected. This flag is used as a placeholder to indicate that the PD_PAGENUMS, PD_SELECTION, and PD_CURRENTPAGE flags are not specified. | |
| PD_COLLATE | |
| If this flag is set, the Collate check box is checked. If this flag is set when the PrintDlgEx function returns, the application must simulate collation of multiple copies. For more information, see the description of the PD_USEDEVMODECOPIESANDCOLLATE flag. |
|
| PD_CURRENTPAGE | |
| If this flag is set, the Current Page radio button is selected. If none of the PD_PAGENUMS, PD_SELECTION, or PD_CURRENTPAGE flags is set, the All radio button is selected. | |
| PD_DISABLEPRINTTOFILE | |
| Disables the Print to File check box. | |
| PD_ENABLEPRINTTEMPLATE | |
| Indicates that the hInstance and lpPrintTemplateName members specify a replacement for the default dialog box template in the lower portion of the General page. The default template contains controls similar to those of the Print dialog box. The system uses the specified template to create a window that is a child of the General page. | |
| PD_ENABLEPRINTTEMPLATEHANDLE | |
| Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. This template replaces the default dialog box template in the lower portion of the General page. The system uses the specified template to create a window that is a child of the General page. The system ignores the lpPrintTemplateName member if this flag is specified. | |
| PD_EXCLUSIONFLAGS | |
| Indicates that the ExclusionFlags member identifies items to be excluded from the printer driver property pages. If this flag is not set, items will be excluded by default from the printer driver property pages. The exclusions prevent the duplication of items among the General page, any application-specified pages, and the printer driver pages. | |
| PD_HIDEPRINTTOFILE | |
| Hides the Print to File check box. | |
| PD_NOCURRENTPAGE | |
| Disables the Current Page radio button. | |
| PD_NOPAGENUMS | |
| Disables the Pages radio button and the associated edit controls. | |
| PD_NOSELECTION | |
| Disables the Selection radio button. | |
| PD_NOWARNING | |
| Prevents the warning message from being displayed when an error occurs. | |
| PD_PAGENUMS | |
| If this flag is set, the Pages radio button is selected. If none of the PD_PAGENUMS, PD_SELECTION, or PD_CURRENTPAGE flags is set, the All radio button is selected. If this flag is set when the PrintDlgEx function returns, the lpPageRanges member indicates the page ranges specified by the user. |
|
| PD_PRINTTOFILE | |
| If this flag is set, the Print to File check box is selected. If this flag is set when PrintDlgEx returns, the offset indicated by the wOutputOffset member of the DEVNAMES structure contains the string "FILE:". When you call the StartDoc function to start the printing operation, specify this "FILE:" string in the lpszOutput member of the DOCINFO structure. Specifying this string causes the print subsystem to query the user for the name of the output file. |
|
| PD_RETURNDC | |
| Causes PrintDlgEx to return a device context matching the selections the user made in the property sheet. The device context is returned in hDC. | |
| PD_RETURNDEFAULT | |
| If this flag is set, the PrintDlgEx function does not display the property sheet. Instead, it sets the hDevNames and hDevMode members to handles to DEVMODE and DEVNAMES structures that are initialized for the system default printer. Both hDevNames and hDevMode must be NULL, or PrintDlgEx returns an error. | |
| PD_RETURNIC | |
| Similar to the PD_RETURNDC flag, except this flag returns an information context rather than a device context. If neither PD_RETURNDC nor PD_RETURNIC is specified, hDC is undefined on output. | |
| PD_SELECTION | |
| If this flag is set, the Selection radio button is selected. If none of the PD_PAGENUMS, PD_SELECTION, or PD_CURRENTPAGE flags is set, the All radio button is selected. |
|
| PD_USEDEVMODECOPIES | |
| Same as PD_USEDEVMODECOPIESANDCOLLATE | |
| PD_USEDEVMODECOPIESANDCOLLATE | |
| This flag indicates whether your application supports multiple copies and collation. Set this flag on input to indicate that your application does not support multiple copies and collation. In this case, the nCopies member of the PRINTDLGEX structure always returns 1, and PD_COLLATE is never set in the Flags member. If this flag is not set, the application is responsible for printing and collating multiple copies. In this case, the nCopies member of the PRINTDLGEX structure indicates the number of copies the user wants to print, and the PD_COLLATE flag in the Flags member indicates whether the user wants collation. Regardless of whether this flag is set, an application can determine from nCopies and PD_COLLATE how many copies to render and whether to print them collated. If this flag is set and the printer driver does not support multiple copies, the Copies edit control is disabled. Similarly, if this flag is set and the printer driver does not support collation, the Collate checkbox is disabled. The dmCopies and dmCollate members of the DEVMODE structure contain the copies and collate information used by the printer driver. If this flag is set and the printer driver supports multiple copies, the dmCopies member indicates the number of copies requested by the user. If this flag is set and the printer driver supports collation, the dmCollate member of the DEVMODE structure indicates whether the user wants collation. If this flag is not set, the dmCopies member always returns 1, and the dmCollate member is always zero. |
|
| PD_EXCL_COPIESANDCOLLATE | |
| Excludes the Copies and Collate controls from the printer driver property pages in a Print property sheet. This flag should always be set when the application uses the default Copies and Collate controls provided by the lower portion of the General page of the Print property sheet. | |
If the PD_NOPAGENUMS flag is specified, this value is not valid. If the PD_NOPAGENUMS flag is not specified, lpPageRanges must be non-NULL.
When PrintDlgEx returns, nCopies contains the actual number of copies the application must print. This value depends on whether the application or the printer driver is responsible for printing multiple copies. If the PD_USEDEVMODECOPIESANDCOLLATE flag is set in the Flags member, nCopies is always 1 on return, and the printer driver is responsible for printing multiple copies. If the flag is not set, the application is responsible for printing the number of copies specified by nCopies. For more information, see the description of the PD_USEDEVMODECOPIESANDCOLLATE flag.
The object should contain the IPrintDialogCallback class to receive messages for the child dialog box in the lower portion of the General page.
The callback object should also contain the IObjectWithSite class to receive a pointer to the IPrintDialogServices interface. The PrintDlgEx function calls QueryInterface on the callback object for both IID_IPrintDialogCallback and IID_IObjectWithSite to determine which interfaces are supported.
If you do not want to retrieve any of the callback information, set lpCallback to NULL.
| Value | Meaning |
|---|---|
| PD_RESULT_APPLY | The user clicked the Apply button and later clicked the Cancel button. This indicates that the user wants to apply the changes made in the property sheet, but does not want to print yet. The PRINTDLGEX structure contains the information specified by the user at the time the Apply button was clicked. |
| PD_RESULT_CANCEL | The user clicked the Cancel button. The information in the PRINTDLGEX structure is unchanged. |
| PD_RESULT_PRINT | The user clicked the Print button. The PRINTDLGEX structure contains the information specified by the user. |
When you call the PrintDlgEx function, be sure that the wDeviceOffset member of the DEVNAMES structure is identical to the dmDeviceName member of the DEVMODE structure. If these members do not specify the same printer, PrintDlgEx initializes the property sheet using the printer specified by the wDeviceOffset member.
Typically, if both hDevMode and hDevNames are NULL, PrintDlgEx initializes the property sheet using the current default printer. However, if the PD_RETURNDEFAULT flag is set and both hDevMode and hDevNames are NULL, PrintDlgEx uses the hDevNames and hDevMode members to return information about the current default printer without displaying the property sheet.
During the execution of PrintDlgEx, the DEVMODE and DEVNAMES structures that you specified in the PRINTDLGEX structure may not always contain current data. For this reason, application-specific property pages as well as IPrintDialogCallback routines for the initial page should use the IPrintDialogServices interface to retrieve information about the state of the current printer.
Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in commdlg.h.
Import Library: Use comdlg32.lib.
Unicode: Defined as Unicode and ANSI structures.
Common Dialog Box Library Overview, Common Dialog Box Structures, CreateDC, CreateIC, CreatePropertySheetPage, DEVMODE, DEVNAMES, IObjectWithSite, IPrintDialogCallback, IPrintDialogServices, PrintDlgEx