# CDE Printing Widgets and APIs

CDE 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.

## 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.

## 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.

### Dt Print 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.

### Dt Print Dialog Manager

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.

## Help for CDE Printing Widgets

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 `XmNhelpCallback`s 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.