The Print dialog box lets the user select options for a particular print job. For example, the user can specify the printer to use, the range of pages to print, and the number of copies.
Windows NT 5.0 and later: You can use the PrintDlgEx function to display a Print property sheet, which has a General page containing controls similar to the Print dialog box. The property sheet can also have additional application-specific and driver-specific property pages following the General page.
You create and display a Print dialog box by initializing a PRINTDLG structure and passing the structure to the PrintDlg function.
The following illustration shows a typical Print dialog box.
If the user clicks the OK button, PrintDlg returns TRUE and uses the PRINTDLG structure to return information about the user's selections. For example, the hDevMode and hDevNames members typically return global memory handles for DEVMODE and DEVNAMES structures. You can use the information in these structures to create a device context or an information context for the selected printer.
If the user cancels the Print dialog box or an error occurs, PrintDlg returns FALSE. You can determine the cause of an error by using the CommDlgExtendedError function to retrieve the extended error value.
The Print dialog box includes a Print Range group of radio buttons that indicate whether the user wants to print all pages, a range of pages, or only the selected text. Before calling PrintDlg, you can set one of the PD_ALLPAGES, PD_SELECTION, or PD_PAGENUMS flags to indicate which button is initially selected. When PrintDlg returns TRUE, the function sets one of these flags to indicate the user's selections. If PD_PAGENUMS is set, the nFromPage and nToPage members of the PRINTDLG structure contain the starting and ending pages specified by the user. To disable the Pages radio button and its associated From and To edit controls, set the PD_NOPAGENUMS flag. To disable the Selection radio button, set the PD_NOSELECTION flag.
The dialog box includes an edit control in which the user can type the number of copies to print. If the hDevMode member of the PRINTDLG structure is non-NULL, the dmCopies member of the DEVMODE structure specifies the initial value for this edit control. If hDevMode is NULL, the nCopies member of the PRINTDLG structure specifies the initial value. When PrintDlg returns, nCopies typically indicates the number of copies specified by the user. However, if you set the PD_USEDEVMODECOPIESANDCOLLATE flag when you create the dialog box, nCopies is always set to 1 on return and the dmCopies member of DEVMODE indicates the number of copies to print.
The Collate check box indicates whether the user wants to collate the pages if multiple copies are being printed. The PD_COLLATE flag is set if the Collate check box is checked. If your application does not support multiple copies or simulated collation, set the PD_USEDEVMODECOPIESANDCOLLATE flag in the Flags member of the PRINTDLG structure. This disables the Collate check box and the Number of Copies edit control unless the printer driver supports multiple copies and collation.
The Print To File check box indicates whether the user wants to send output to a file rather than to a printer. You can set the PD_PRINTTOFILE flag so the check box is initially checked. To hide the check box, set the PD_HIDEPRINTTOFILE flag. To disable it, set the PD_DISABLEPRINTTOFILE flag. If the user selects the Print To File option, PrintDlg sets the PD_PRINTTOFILE flag and returns "FILE:" at the offset indicated by the wOutputOffset member of the DEVNAMES structure. 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.
By default, the Print dialog box initially displays information about the current default printer. You can direct it to display information for another installed printer by initializing a DEVMODE or DEVNAMES structure and assigning the global memory handle for the structure to the hDevMode or hDevNames member. The device name you specify in the dmDeviceName member of the DEVMODE structure or in the wDriverOffset member of the DEVNAMES structure must identify a printer device that is also listed in the [Devices] section of the WIN.INI file. If the device is not listed, PrintDlg returns an error.
You can direct PrintDlg to create a device context or information context for the printer by setting the PD_RETURNDC or PD_RETURNIC flag in the Flags member of the PRINTDLG structure. The function returns the handle of the device context or information context in the hDC member. If you use the PD_RETURNDC flag, you can use the device context to generate output for the printer.
To retrieve information about the default printer without displaying the Print dialog box, set the PD_RETURNDEFAULT flag. In this case, PrintDlg returns immediately after setting the hDevMode and hDevNames members to handles for structures containing the information.
By default, PrintDlg displays message boxes when errors occur. For example, the function displays an error message if no printers are installed. To prevent the function from displaying these warning messages, set the PD_NOWARNING flag.