The PRINTDLG structure contains information that the PrintDlg function uses to initialize the Print common dialog box. After the user closes the dialog box, the system returns information about the user-defined print selections in this structure.
typedef struct tagPD { // pd
DWORD lStructSize;
HWND hwndOwner;
HANDLE hDevMode;
HANDLE hDevNames;
HDC hDC;
DWORD Flags;
WORD nFromPage;
WORD nToPage;
WORD nMinPage;
WORD nMaxPage;
WORD nCopies;
HINSTANCE hInstance;
DWORD lCustData;
LPPRINTHOOKPROC lpfnPrintHook;
LPSETUPHOOKPROC lpfnSetupHook;
LPCTSTR lpPrintTemplateName;
LPCTSTR lpSetupTemplateName;
HANDLE hPrintTemplate;
HANDLE hSetupTemplate;
} PRINTDLG;
If you use the structure to initialize the dialog box controls, you must allocate space for and create the DEVMODE structure. (You should allocate a movable block of memory.)
If you do not use the structure to initialize the dialog box controls, hDevMode may be NULL. In this case, PrintDlg allocates memory for the structure, initializes its members, and returns a handle that identifies it.
If the device driver for the specified printer does not support extended device modes, hDevMode is NULL when PrintDlg returns.
If the device name (specified by the dmDeviceName member of the DEVMODE structure) does not appear in the [devices] section of WIN.INI, PrintDlg returns an error.
Because this structure is a movable global memory object, the value of hDevMode may change during the execution of PrintDlg.
For a discussion of how the system resolves a possible data collision between
values specified by the hDevMode and hDevNames members, see the
following Remarks section.
If you use the structure to initialize the dialog box controls, you must allocate space for and create the DEVNAMES structure. (You should allocate a movable block of global memory.)
If you do not use the structure to initialize the dialog box controls, hDevNames may be NULL. In this case, PrintDlg allocates memory for the structure, initializes its members (by using the printer name specified in the DEVMODE structure), and returns a handle that identifies it. PrintDlg uses the first port name that appears in the [devices] section of WIN.INI when it initializes the members in the DEVNAMES structure. For example, the function uses “LPT1:” as the port name if the following string appears in the [devices] section:
PCL / HP LaserJet=HPPCL,LPT1:,LPT2:
If both hDevMode and hDevNames are NULL, PrintDlg initializes hDevNames using the current default printer.
Because this structure is a movable global memory object, the value of hDevNames may change during the execution of PrintDlg.
For a discussion of how the system resolves a possible data collision between
values specified by hDevNames and hDevMode, see the Remarks
section later in 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 and PD_SELECTION flags are not specified. | |
|
PD_COLLATE | |
|
Places a checkmark in the Collate check box when set on input. When the PrintDlg function returns, this flag indicates that the user selected the Collate option and the printer driver does not support collation. In this case, the application must provide collation. If PrintDlg sets the PD_COLLATE flag on return, the dmCollate member of the DEVMODE structure is undefined. | |
|
PD_DISABLEPRINTTOFILE | |
|
Disables the Print to File check box. | |
|
PD_ENABLEPRINTHOOK | |
|
Enables the hook procedure specified in the lpfnPrintHook member. This enables the hook procedure for the Print dialog box. | |
|
PD_ENABLEPRINTTEMPLATE | |
|
Indicates that the hInstance and lpPrintTemplateName members specify a dialog box template to use in place of the default template for the Print dialog box. | |
|
PD_ENABLEPRINTTEMPLATEHANDLE | |
|
Indicates that the hPrintTemplate member identifies a data block that contains a preloaded dialog box template. The system uses this template in place of the default template for the Print dialog box. The system ignores the lpPrintTemplateName member if this flag is specified. | |
|
PD_ENABLESETUPHOOK | |
|
Enables the hook procedure specified in the lpfnSetupHook member. This enables the hook procedure for the Print Setup dialog box. | |
|
PD_ENABLESETUPTEMPLATE | |
|
Indicates that the hInstance and lpSetupTemplateName members specify a dialog box template to use in place of the default template for the Print Setup dialog box. | |
|
PD_ENABLESETUPTEMPLATEHANDLE | |
|
Indicates that the hSetupTemplate member identifies a data block that contains a preloaded dialog box template. The system uses this template in place of the default template for the Print Setup dialog box. The system ignores the lpSetupTemplateName member if this flag is specified. | |
|
PD_HIDEPRINTTOFILE | |
|
Hides the Print to File check box. | |
|
PD_NONETWORKBUTTON | |
|
Hides and disables the Network 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 there is no default printer. | |
|
PD_PAGENUMS | |
|
Causes the Pages radio button to be in the selected state when the dialog box is created. When PrintDlg returns, this flag is set if the Pages radio button is in the selected state. | |
|
PD_PRINTSETUP | |
|
Causes the system to display the Print Setup dialog box rather than the Print dialog box. | |
|
PD_PRINTTOFILE | |
|
Causes the Print to File check box to be checked when the dialog box is created. When PrintDlg returns, this flag is set if the check box is checked. In this case, 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 PrintDlg to return a device context matching the selections the user made in the dialog box. The device context is returned in hDC. | |
|
PD_RETURNDEFAULT | |
|
The PrintDlg function does not display the dialog box. 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 or hDevMode must be NULL, or PrintDlg returns an error. If the system default printer is supported by an old printer driver (earlier than Windows version 3.0), only hDevNames is returned; hDevMode is NULL. | |
|
PD_RETURNIC | |
|
Similar to the PD_RETURNDC flag, except that 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 | |
|
Causes the Selection radio button to be in the selected state when the dialog box is created. When PrintDlg returns, this flag is specified if the Selection radio button is selected. If neither PD_PAGENUMS nor PD_SELECTION is set, the All radio button is selected. | |
|
PD_SHOWHELP | |
|
Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button. | |
|
PD_USEDEVMODECOPIES | |
|
Same as PD_USEDEVMODECOPIESANDCOLLATE | |
|
PD_USEDEVMODECOPIESANDCOLLATE | |
|
Disables the Copies edit control if the printer driver does not support multiple copies, and disables the Collate checkbox if the printer driver does not support collation. If this flag is not specified, PrintDlg stores the user selections for the Copies and Collate options in the dmCopies and dmCollate members of the DEVMODE structure. | |
|
If this flag isn’t set, the copies and collate information is returned in the DEVMODE structure if the driver supports multiple copies and collation. If the driver doesn’t support multiple copies and collation, the information is returned in the PRINTDLG structure. This means that an application only has to look at nCopies and PD_COLLATE to determine how many copies it needs to render and whether it needs to print them collated. |
There might be data collision between the values specified by hDevNames and hDevMode because the wDeviceOffset member of the DEVNAMES structure is supposed to be identical to the dmDeviceName member of the DEVMODE structure. If it is not, the system resolves the data collision by using the value of wDeviceOffset.
If the user checks the Collate check box in the common Print dialog box, but the printer driver does not support collation, the Flags member of the PRINTDLG structure returned by PrintDlg includes the PD_COLLATE flag. In addition, the dmCollate member of the DEVMODE structure identified by the hDevMode member is set to COLLATE_TRUE. If the PD_COLLATE flag is set, the application must simulate collation.
If the PD_USEDEVMODECOPIESANDCOLLATE flag is set, the Collate check box is grayed out if the printer driver does not support collation. This ensures that the user can only select one copy, and nCopies will be one. If the driver does support multiple copies, dmCopies will contain the number of copies, and nCopies will be one.
On entry to PrintDlg, the nCopies member of the PRINTDLG structure specifies the number of copies if PD_USEDEVMODECOPIESANDCOLLATE is not set. On exit from PrintDlg, nCopies contains the number of copies if the printer driver does not support multiple copies. Otherwise it is set to one. If nCopies is greater than one on exit from PrintDlg, the application must print multiple copies of the document.
CreateDC, CreateIC, PrintDlg, DEVMODE, DEVNAMES, WM_INITDIALOG