PRINTDLG

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;

HANDLE hInstance;

DWORD lCustData;

LPPRINTHOOKPROC lpfnPrintHook;

LPSETUPHOOKPROC lpfnSetupHook;

LPSTR lpPrintTemplateName;

LPSTR lpSetupTemplateName;

HANDLE hPrintTemplate;

HANDLE hSetupTemplate;

} PRINTDLG;

The PRINTDLG structure contains information that the system uses to initialize the system-defined print dialog boxes. After the user dismisses the dialog box, the system returns information about the user-specified print parameters in this structure.

Fields

lStructSize

Specifies the length of the structure (in bytes).

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or NULL if the dialog box has no owner.

hDevMode

Identifies a movable global memory object that contains a DEVMODE structure. Prior to calling the PrintDlg function, the members in this structure may contain data used to initialize the dialog controls. When the PrintDlg function returns, the members in this structure specify the state of the dialog controls.

If the application uses the structure to initialize the dialog controls, it must allocate space for and create the DEVMODE data structure. (The application should allocate a movable block of memory.)

If the application does not use the structure to initialize the dialog controls, the hDevMode member may be NULL. In this case, the PrintDlg function will allocate memory for the structure, initialize its fields and return a handle which identifies it.

If the device driver for the specified printer does not support extended device modes, the hDevMode member will be NULL when PrintDlg returns.

If the device name (specified by the dmDeviceName field of the DEVMODE structure) does not appear in the [devices] section of WIN.INI, the PrintDlg function will return an error.

Because this structure is a movable global memory object, the value of hDevMode may change during the execution of the PrintDlg function.

hDevNames

Identifies a movable global memory object that contains a DEVNAMES structure. This structure contains three strings which specify the driver name, the printer name, and the output-port name. Prior to calling the PrintDlg function, the members of this structure contain strings used to initialize dialog controls. When the PrintDlg function returns, the members of this structure contain the strings entered by the user. The calling application uses these strings to create a device context or an information context.

If the application uses the structure to initialize the dialog controls, it must allocate space for and create the DEVMODE data structure. (The application should allocate a movable block of global memory.)

If the application does not use the structure to initialize the dialog controls, the hDevNames member may be NULL. In this case, the PrintDlg function will allocate memory for the structure, initialize its fields (using the printer name specified in the DEVMODE data structure) and return a handle which identifies it. The PrintDlg function will use the first port name that appears in the [devices] section of WIN.INI when it initializes the fields in the DEVNAMES structure. For example, if the following string appears in the [devices] section:

PCL / HP LaserJet=HPPCL,LPT1:,LPT2:

the function will use “LPT1:” as the port name.

If both hDevMode and hDevNames fields are NULL, PrintDlg will initialize 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 the PrintDlg function.

hDC

Identifies a device context or information context, depending on whether the Flags member specifies the PD_RETURNDC or the PC_RETURNIC flag. If neither flag is specified, the value of this member undefined. If both flags are specified, BD_RETURNDC has priority.

Flags

Specifies the dialog-box initialization flags. This member may be a combination of the following values:

Value Meaning

PD_COLLATE Causes the Collate checkbox to be in the checked state when the dialog box is created. When the PrintDlg function returns, this flag indicates the state in which the user left the Collate checkbox.
PD_ENABLEPRINTHOOK Enables the hook function specified in the lpfnPrintHook member of this structure.
PD_ENABLEPRINTTEMPLATE Causes the system to create the dialog box using the dialog template identified by the hInstance and lpPrintTemplateName members.
PD_ENABLEPRINTTEMPLATEHANDLE Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpPrintTemplateName member if this flag is specified.
PD_ENABLESETUPHOOK Enables the hook function specified in the lpfnSetupHook member of this structure.
PD_ENABLESETUPTEMPLATE Causes the system to create the dialog box using the dialog template identified by the hInstance and lpSetupTemplateName members.
PD_ENABLESETUPTEMPLATEHANDLE Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpSetupTemplateName member if this flag is specified.
PD_MODIFYDM Specifies that the printer driver should accept the changes specified by the user in the setup dialog. (If this flag is not set, the specified changes will not be made.)
PD_NOPAGENUMS Disables the Pages radio button and the associated edit control.
PD_NOSELECTION Disables the Selection radio button.
PD_PAGENUMS Causes the Pages radio button to be in the selected state when the dialog box is created. When the PrintDlg function returns, this flag is set if the Pages radion 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 in the checked state when the dialog box is created. When the PrintDlg function returns, the pOutput member of the DEVNAMES structure will point to the “FILE:” string.
PD_RETURNDC Causes the PrintDlg function to return a device context matching the selections that the user made in the dialog box. The device context is returned in the hDC member.
PD_RETURNDEFAULT Causes the PrintDlg function to return DEVMODE and DEVNAME structures that are initialized for the system default printer. It does this without displaying a dialog box. It is assumed that both the hDevNames and the hDevMode members are NULL; otherwise, the function returns an error. If the system default printer is supported by an old printer driver (pre-3.0), only the hDevNames member will be returned—the hDevMode member will be 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 are specified, the hDC parameter is undefined on output.
PD_SELECTION Causes the Selection radio button to be in the selected state when the dialog box is created. When the PrintDlg function returns, this flag is set if the Selection radio button is in the selected state. If neither PD_PAGENUMS nor PD_SELECTION are specified, the All radio button is in the selected state.
PD_SHOWHELP Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified.
PD_USEDEVMODECOPIES If a printer driver does not support multiple copies, setting this flag disables the Copies edit control; if a driver does support multiple copies, setting this flag indicates that the PrintDlg function should store the requested number of copies in the dmCopies member of the DEVMODE data structure and store the value 1 in the nCopies member of the PRINTDLG data structure.
  If this flag is not set, the PrintDlg structure will store the value 1 in the dmCopies member of the DEVMODE structure and store the requested number of copies in the nCopies member of the PRINTDLG data structure.

nFromPage

Specifies the initial value for the starting page edit control. When the PrintDlg function returns, this member specifies the page at which to begin printing. This value is only valid if the PD_PAGENUMS flag is specified.

nToPage

Specifies the initial value for the ending page edit control. When the PrintDlg function returns, this member specifies the last page to print. This value is only valid if the PD_PAGENUMS flag is specified.

nMinPage

Specifies the minimum value for the range of pages specified in the From and To page edit controls.

nMaxPage

Specifies the maximum value for the range of pages specified in the From and To page edit controls.

nCopies

Prior to calling the PrintDlg function, this member contains a value used to initialize the Copies edit control if the hDevMode member is NULL; otherwise, the dmCopies field of the DEVMODE data structure contains the value used to initialize this control

Upon returning from the PrintDlg function the value specified by this member depends on the printer-driver version. For pre-3.0 printer drivers, this member specifies the number of copies requested by the user in the dialog's Copies edit control. For 3.0 and later printer drivers this member specifies the number of copies requested by the user if the PD_USEDEVMODECOPIES flag was not set; otherwise, this member specifies the value 1 and the actual requested copy count appears in the DEVMODE data structure.

hInstance

Identifies a data block that contains pre-loaded dialog template specified by the lpstrTemplateName member. This member is only used if the Flags member specifies the PD_ENABLEPRINTTEMPLATE or PD_ENABLESETUPTEMPLATE flags; otherwise, this member is ignored.

lCustData

Specifies application-defined data that the system passes to the hook function identified by the lpfnHook member. The system passes the data in the lParam field of the WM_INITDIALOG message.

lpfnPrintHook

Exported function to hook dialog messages if the application decides to alter the print dialog. This field is ignored unless the PD_ENABLEPRINTHOOK flag is specified in the Flags member.

lpfnSetupHook

Exported function to hook dialog messages if the application decides to alter the print setup dialog. This field is ignored unless the PD_ENABLESETUPHOOK flag is specified in the Flags member.

lpPrintTemplateName

Points to a hook function that processes messages intended for the dialog box. An application must specify the PD_ENABLEPRINTTEMPLATE or PD_ENABLEPRINTERTEMPLATEHANDLE constants in the Flags member to enable the function; otherwise, the system ignores this structure member. The hook function should return FALSE to pass a message on to the standard dialog procedure, or TRUE to discard the message.

lpSetupTemplateName

Points to a hook function that processes messages intended for the dialog box. An application must specify the PD_ENABLESETUPTEMPLATE or PD_ENABLESETUPTEMPLATEHANDLE constants in the Flags member to enable the function; otherwise, the system ignores this structure member. The hook function should return FALSE to pass a message on to the standard dialog procedure, or TRUE to discard the message.

hPrintTemplate

Identifies the handle to the global memory object which contains the pre-loaded dialog template to be used instead of the default print dialog.

hSetupTemplate

Identifies the handle to the global memory object which contains the pre-loaded dialog template to be used instead of the default setup dialog.

See Also

CreateDC, CreateIC, PrintDlg DEVMODE DEVNAMES