PRINTDLG
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;
Members
lStructSize
Specifies the
structure size, in bytes.
hwndOwner
Identifies
the window that owns the dialog box. This member can be any valid window
handle, or it can be NULL if the dialog box has no owner.
hDevMode
Identifies a
movable global memory object that contains a DEVMODE structure. Before a call
to the PrintDlg
function, the structure members may contain data used to initialize the dialog
controls. When PrintDlg returns, the structure members specify the state
of the dialog box controls.
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, PrintDlg11768VZ 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.
hDevNames
Identifies a
movable global memory object that contains a DEVNAMES structure. This structure
contains three strings that specify the driver name, the printer name, and the
output port name. Before the call to PrintDlg11768VZ, the structure members contain strings
used to initialize dialog box controls. When PrintDlg returns, the
structure members contain the strings typed by the user. The calling
application uses these strings to create a device context or an information
context.
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.
hDC
Identifies a
device context or an information context, depending on whether the Flags
member specifies the PD_RETURNDC or PC_RETURNIC flag. If neither flag is
specified, the value of this member is undefined. If both flags are specified,
PD_RETURNDC has priority.
Flags
A set of bit
flags that you can use to initialize the Print common dialog box. When the
dialog box returns, it sets these flags to indicate the user s input. This member can be a combination of the
following flags:
|
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_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 HELPMSGSTRING1N5CG6 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. |
nFromPage
Specifies the
initial value for the starting page edit control. When the PrintDlg function returns, nFromPage
specifies the starting page specified by the user. This value is valid only if
the PD_PAGENUMS flag is specified.
nToPage
Specifies the
initial value for the ending page edit control. When the PrintDlg
function returns, nToPage specifies the ending page specified by the
user. This value is valid only 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
Contains the
initial number of copies for the Copies edit control if hDevMode is
NULL; otherwise, the dmCopies member of the DEVMODE structure contains the
initial value. When PrintDlg returns, this member contains the actual
number of copies to print. If the printer driver does not support multiple
copies, this value may be greater than one and the application must print all
requested copies. If the PD_USEDEVMODECOPIESANDCOLLATE value is set in the Flags
member, nCopies is always set to 1 on return and the dmCopies
member in the DEVMODE receives the actual number of copies to print.
hInstance
If the
PD_ENABLEPRINTTEMPLATE or PD_ENABLESETUPTEMPLATE flag is set in the Flags
member, hInstance is the handle of the application or module instance
that contains the dialog box template named by the lpPrintTemplateName
or lpSetupTemplateName member.
lCustData
Specifies
application-defined data that the system passes to the hook procedure
identified by the lpfnPrintHook or lpfnSetupHook member. When the
system sends the WM_INITDIALOG
message to the hook procedure, the message s lParam
parameter is a pointer to the PRINTDLG structure specified when the
dialog was created. The hook procedure can use this pointer to get the lCustData
value.
lpfnPrintHook
Pointer to a PrintHookProc hook procedure that can
process messages intended for the Print dialog box. This member is ignored
unless the PD_ENABLEPRINTHOOK flag is set in the Flags member.
lpfnSetupHook
Pointer to a SetupHookProc hook procedure that can
process messages intended for the Print Setup dialog box. This member is
ignored unless the PD_ENABLESETUPHOOK flag is set in the Flags member.
lpPrintTemplateName
Pointer to a
null-terminated string that names a dialog box template resource in the module
identified by the hInstance member. This template is substituted for the
standard Print dialog box template. This member is ignored unless the
PD_ENABLEPRINTTEMPLATE flag is set in the Flags member.
lpSetupTemplateName
Pointer to a
null-terminated string that names a dialog box template resource in the module
identified by the hInstance member. This template is substituted for the
standard Print Setup dialog box template. This member is ignored unless the
PD_ENABLESETUPTEMPLATE flag is set in the Flags member.
hPrintTemplate
If the
PD_ENABLEPRINTTEMPLATEHANDLE flag is set in the Flags member, hPrintTemplate
is the handle of a memory object containing a dialog box template. This
template is substituted for the standard Print dialog box template.
hSetupTemplate
If the
PD_ENABLESETUPTEMPLATEHANDLE flag is set in the Flags member, hSetupTemplate
is the handle of a memory object containing a dialog box template. This
template is substituted for the standard Print Setup dialog box template.
Remarks
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.
See Also