printinggeneral informationCDE users typically print files through a series of dialogs, the first one being initiated by selecting (for example) the pulldown menu for printing a file. This chapter documents a set of dialogs provided by CDEnext for use primarily by applications that perform X printing: The initial print dialog is provided as the DtPrintSetupBox widget. This consists of the set of generic print options, a possible application-specific set of print options, and a set of command buttons at the bottom to start or cancel the print operation, bring up the Print Dialog Manager (PDM), or bring up a help dialog. The DtPrinterSelectionDialog is for selecting X Printers and is accessible through the DtPrintSetupBox widget. A dialog for obtaining additional printer information, the DtPrinterInfoDialog, is accessible through either the DtPrintSetupBox or the DtPrinterSelectionDialog. There is also a file selection dialog (accessible through DtPrintSetupBox) that enables users to select files to be printed. All of these sub-dialogs are considered part of the DtPrintSetupBox widget, and as such, there is no external API for them. Although DtPrintSetupBox is designed primarily for X printing, it is also designed for use as a general application print dialog for use in any CDEnext application that provides printing. DtPrintSetupBox is also designed to allow simple integration with the Print Dialog Manager, which provides additional printer and spooler specific X printing setup dialogs. The remaining sections of this chapter document the DtPrint convenience functions, the DtPrint Dialog Manager, and how to integrate help with the printing widgets. printingdtprint functions dtprint functions This section summarizes DtPrint functions. Sample code illustrating their use can be found in the /proj/cde/examples/dtprint directory. DtPrintSetupBox DtPrintSetupBox is a widget that is typically the initial window used to set various options prior to printing from an application. This widget is primarily designed for use by applications that utilize the X Print Service. However, the widget interface is also designed to be flexible enough for use by applications employing other printing methods. DtCreatePrintSetupBox DtCreatePrintSetupBox is a convenience function that creates an unmanaged instance of a DtPrintSetupBox widget, and returns its widget ID. DtCreatePrintSetupDialog DtCreatePrintSetupDialog is a convenience function that creates an instance of a dialog containing a DtPrintSetupBox widget, and returns the DtPrintSetupBox widget ID. DtPrintFillSetupData DtPrintFillSetupData is used to obtain an X printer connection in order to initiate an X printing job in situations other than direct interaction with a DtPrintSetupBox (for example, a "quick print" button on a toolbar). This printer connection information can be obtained from an existing DtPrintSetupBox widget instance, or if a DtPrintSetupBox widget instance is unavailable, DtPrintFillSetupData will provide a new X printer connection. DtPrintCopySetupData DtPrintCopySetupData is used to copy a DtPrintSetupData structure. An element in the target is updated only if different from the corresponding element in the source. For elements that point to allocated memory, DtPrintCopySetupData allocates new memory for those elements updated in target. Existing elements in target are freed. All elements in a DtPrintSetupData structure can be freed by calling DtPrintFreeSetupData. DtPrintFreeSetupData Free the memory pointed to by DtPrintSetupData structure elements. DtPrintResetConnection DtPrintResetConnection is a convenience function provided by the DtPrintSetupBox widget that allows applications to direct the widget to stop managing the X print server connection. A mode parameter is included in order to direct the widget to close the print connection or simply to relinquish control of the connection without closing it. DtPrintResetConnection is intended to be used by applications that fork a child process to perform the print rendering operation. Immediately after the fork is performed, the parent process closes its X print server connection and retains its connection to the video X server. The forked child, on the other hand, closes its video X server connection and performs the rendering operation on the X print server connection. DtPrintSetupProc DtPrintSetupProc is a type definition for procedure resources of the DtPrintSetupBox widget. DtPrinterSelectionDialog The DtPrinterSelectionDialog enables the user to select an X printer from a complete list of printers for the client server (provided the server supports the Xp extension), plus each server indicated by either the XpServerList resource or the XPSERVERLIST environment variable. The user typically selects one of the printers and chooses the "OK" button to return the selected printer to the caller. printingprint dialog manager Print Dialog Manager A Print Dialog Manager (PDM) is a process separate from the X Print Server and X Printing Application that provides printer-specific and spooler-specific setup GUIs. An application could choose to understand and display such GUIs itself, but is advised to offload the task to a PDM so that new printers and spoolers can be supported by providing new PDMs, rather than requiring changes to all applications. This section describes the CDEnext implementation of a PDM that uses the PDM Selection Protocol. The CDEnext implementation involves a Print Dialog Manager Daemon (PDMD) executable (dtpdmd) that is initially engaged by the protocol. It then determines which PDM is needed and starts it on behalf of the application. Within CDEnext, the executable dtpdm is the general purpose PDM that the dtpdmd can start. Printer vendors can choose to introduce new GUIs by one of the following techniques: Developing their own PDM implementation that conforms to the PDM Selection Protocol. Develop a PDM that can be started by the dtpdmd; this is the recommended technique. Possibly integrate new shared or dynamic libraries into the dtpdmd. This technique is vendor-dependent. The dtpdm executable implements a reasonably general-purpose print dialog manager capable of providing dialogs suitable for a number of different printers, but is specifically tuned to the needs of the two reference printers, the PCL based HP DeskJet 1600C, and the Postscript based Sun SPARCprinter 2. The dtpdm uses the attributes of the particular printer to provide a limited amount of automatic configuration of the options displayed in its printer setup dialog. The dtpdm's job setup dialog is designed for use with the lp spooler. The dtpdmd executable implements a PDM startup mechanism. This two-layer mechanism means that the PDM Selection Protocol, PDM selection and startup, and security concerns can be dealt with by the dtpdmd, and that resulting PDMs called by the dtpdmd are left with the minimal and simple task of displaying GUIs. printingdtprint dialog manager daemon dtpdmd The dtpdmd is a long-lived daemon process that receives client requests for a PDM, uses some lookup rules, and then starts an appropriate PDM to service the request. When the PDM finishes, control is returned to the dtpdmd, and the dtpdmd in turn responds to the client with final status. The dtpdmd uses the PDMD/PDM Protocol to communicate with the PDM. Communication "to" the PDM is done via a standardized command line. Communication "from" the PDM is done via standardized exit codes. printingdtprint dialog manager dtpdm The dialog manager is a process separate from the print server. It provides the printer-specific GUIs on behalf of a printing application At an application's request, dtpdm posts to the user's display a set of printer-specific dialogs enabling the user to set printer specific and job specific options. Though the setup dialog appears to be part of the application, it is actually managed by the dtpdm program on behalf of the application. It is capable of providing dialogs in all locales for which there are applicable message catalogs. dtpdm presents a dialog containing an XmNotebook widget. This notebook widget contains two tabs: one for the Printer Setup Box and one for the Job Setup Box. Each of these boxes provide controls that allow for configuration of various printing options. The dtpdm dialog also contains three pushbuttons labelled: "OK", "Cancel", and "Help". When the "OK" button is activated, the dialog is dismissed and the newly configured printing options are set in the current print context (via XpSetAttributes). When the "Cancel" button is activated, the dialog is dismissed and no changes are made to the print context. printingintegrating help The DtPrintSetupBox widget provides built-in support for its sub-dialogs. That is, when the user clicks on the Help button in one of these sub-dialogs, a help dialog is displayed containing the relevant help text. The help volume and location IDs used for this purpose are as follows: Printer Info — HelpVolume = LibDtPrint, LocationId = PrinterInfo Printer Selection — HelpVolume = LibDtPrint, LocationId = SelectPrinter File Selection — HelpVolume = LibDtPrint, LocationId = SelectFile For the main dialog, however, no help dialog is automatically displayed when the user presses the Help button. However, the DtPrintSetupBox does provides the hooks that enable the application writer to easily supply help for both the generic and the application-specific portions. These hooks include: A "public" DtPrintSetupBox help volume with one or more location IDs for the generic printing options. An activation callback installed on the DtPrintSetupBox Help button that ensures that any XmNhelpCallbacks installed on the DtPrintSetupBox by the application are called. In order to integrate help for the DtPrintSetupBox into an application, you must: Supply a help volume containing help for the relevant topics. Note that if there are no application-specific printing options, the public help volume supplied with the DtPrintSetupBox will suffice. Otherwise, the authors of the application's help volume will need to supply internal links to the DtPrintSetupBox volume. For example, the help volume for a calendar manager might look something like this: Calendar Print Setup Dialog Box ------------------------------- some graphic Report Type Choose to print Day View, Week View, Month View, or Year View, plus Appointment List or To Do List. From/To The dates for which you want to print calendar data. With the From and To SpinBox, you can select ... See Also: * Generic Print options link1 * To Print Your Appointment List link2 * To Print Your To Do List link3 where link1 is a link to the "public" DtPrintSetupBox help volume. Define a set of location IDs to mark the locations in the application's help volume pertaining to printing. It is up the application to determine how "fine grained" to make the IDs (for example, one for the entire print setup dialog, or one for every print option in the print setup dialog, or some other organization). The more "fine grained" the location IDs, the more specific the help that is displayed when supporting a help system that allows users to select the item for which they want help. Define a callback that is added to the XmNhelpCallback resource of the DtPrintSetupBox. This callback would display a DtHelpDialogWidget or DtHelpQuickDialogWidget setting the DtNhelpVolume and DtNlocationId resources appropriately.