pop-up-printer-job-dialog

Arguments: printer-stream &rest restarg

Pops up the print job dialog, where the end user may specify which printer to print on and what style of printing that printer's driver should use. An application should not call this function directly, because Common Graphics calls it internally whenever a printer stream is opened. This page documents the printer-specific arguments that you would pass to open-stream or with-output-to-printer, which Common Graphics will pass along to this function.

The argument values will determine the initially-selected options on the print job dialog, unless :no-dialog-p t is passed to bypass the dialog, in which case the argument values determine the actual print style.

Note that each printer driver supports some subset of these properties, and ignores any specification of the others. When using the print job dialog, a driver will typically suppress the properties that it does not support. But when bypassing the print job dialog by passing :no-dialog-p, it may not be clear which properties are supported, and so it's probably best to pass initargs in this case only for properties such as orientation that are supported by most any printer driver.

The keyword arguments (open-stream initargs) are:

• no-dialog-p: if true, then the print job dialog is not invoked as usual, and the current Windows printer is used with its current settings, except as overridden by other initargs passed here.
• start: the first page to print; see the start-page property.
• end: the last page to print; see the end-page property.
• min-start: the smallest number that the end user is allowed to specify as the start-page on the print job dialog.
• max-end: the largest number that the end user is allowed to specify as the end-page on the print job dialog.
• copies: the number of copies to print; see the driver-copies and user-copies properties.
• collate-p: if true, then the output should be collated; see the driver-collate-p and user-collate-p properties.
• orientation: either :portrait or :landscape; see the orientation property.
• scale: a scaling factor for the printer driver to use; see the scale property.
• filename: may be either nil to print output to a physical printer as usual, or else a pathname or path namestring to print to a file instead. When printing is done to a file, the file will contain printer code such as PCL or PostScript, as written by the driver of the selected printer. When a path is specified, the output will go to the file even if the print-to-file-p argument is nil or if the user unchecks the Print to file check-box on the Print Job dialog; therefore it is probably best to pass either no-dialog-p or hide-print-to-file as true when passing a filename.
• print-to-file-p: if true, then the Print to file check-box on the Print Job dialog will initially be checked; if nil, it will be unchecked. Some printer drivers may not support printing to a file, in which case this check-box will not appear. If filename is nil or unspecified and the user exits the Print Job dialog with the Print to file check-box checked, then the OS will ask for the path to print to, and there is no way for lisp to know what path was specified; therefore, if you need to know what file was created then you should instead pass the desired path as the filename argument, perhaps after calling ask-user-for-new-pathname to ask the user for the path.
• disable-print-to-file: if true, then the option to print to a file will be disabled (grayed) on the print job dialog.
• hide-print-to-file: if true, then the option to print to a file will not appear at all on the print job dialog.
• disable-page-numbers: if true, then the Page Numbers radio button and associated page range fields on the print job dialog will be unavailable (grayed).
• disable-selection: if true, then the Selection radio button on the print job dialog will be unavailable.
• selection-p: if true, then the Selection radio button on the print job dialog will be initially selected, rather than the All Pages radio button.
• disable-copies-and-collate-if-no-driver-support: if true and the printer driver does not support printing multiple copies or collation itself, then the options for multiple copies and collation will be disabled on the print job dialog.
• print-quality: the print quality to use; see the print-quality property.
• paper-size: the paper size to use; see the paper-size property.
• multicolor: whether to print in multicolor or monochrome on a color printer; see the multicolor property.
• no-warning-p: if true, then no warning will appear if there is currently no default printer.
• printer-name: a string indicating the printer on which to print. The string should be equal to one of the values in the list returned by printer-names. This option has an effect only when the no-dialog-p option is true.
• driver-name: a string indicating the printer driver to use. The default is "winspool", which is normally the appropriate value. But if you know the name of an alternate driver that you would like to use, you may specify it here.
• title: a string that serves as a descriptive name for the document being printed, such as "My Primary Report". This name may appear in a system dialog that lists currently queued print jobs, for example. Adobe Distller uses this string as the default filename that it presents to the user for the PDF file that it creates. (This open-stream argument is actually handled in the device-open method for printer streams, but is included here to document all printer initargs together.)
• double-sided: whether to print double-sided or single-sided. If nil (or unspecified), then the printer's default setting will be used. If :no, then printing will be single-sided. If :short-edge-binding, then printing will be double-sided and oriented toward binding (or flipping) the pages along the shorter side of the paper. If :long-edge-binding (or any true value other than the ones mentioned), then printing will be double-sided and oriented toward binding along the longer side of the paper. (Since binding along the longer side is typical, it may be easier to remember to specify t for double-sided.) Note that on the print job dialog for some printer drivers this option is called "Duplex". See double-sided.

See also pop-up-printer-setup-dialog and with-printer.

GTK Note

Printing (hardcopy) is not implemented on the GTK platform at this time. Opening a printer stream will simply invoke the *gtk-compatibility-warning-action*.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.