NAME

DtPrintFillSetupData — obtains X printer connection information

SYNOPSIS

#include &<Print.h>
XtEnum DtPrintFillSetupData(
Widget wid,
DtPrintSetupData* print_data);

DESCRIPTION

The DtPrintFillSetupData function obtains an X printer connection in order to initiate an X printing job in situations other than direct interaction with a DtPrintSetupBox. Examples of such situations include a "quick print" button on a toolbar and "GUI-less" printing. This X 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.

A print job is typically initiated when the user selects the "Print" button from within a DtPrintSetupBox widget instance. Applications may wish to provide additional avenues for the user to initiate a print job, namely a "Quick Print" toolbar button, or a command line parameter to allow "GUI-less" printing, such as from within a desktop action. DtPrintFillSetupData is designed to provide an X printer connection in a manner consistent with DtPrintSetupBox.

For both the "Quick Print" and "GUI-less" cases, the caller may set the printer_name element of the passed print_data in order to specify the destination X printer. DtPrintFillSetupData will treat the passed printer_name as if the user had typed the printer name into the Printer Name text field of the DtPrintSetupBox. The printer_name will be verified, and an X printer connection will be established. The returned printer_name may be a fully qualified version of the passed printer_name as a result of the printer verification process. For a description of this process, see the DtNverifyPrinterProc resource description in DtPrintSetupBox(3). If DtPrintFillSetupData returns a new printer_name, it will free the passed printer_name by calling XtFree.

For the "Quick Print" button case, DtPrintFillSetupData is intended to be used with an existing DtPrintSetupBox instance, so that the "Quick Print" button behaves as if the user had brought up a DtPrintSetupBox, selected a printer as indicated by printer_name, and activated the "Print" button. The following conditions apply to this case:

•: The wid parameter should be set to the widget ID of the DtPrintSetupBox instance. DtPrintFillSetupData will fill the passed print_data structure similarly to how DtPrintSetupBox fills out the print_data element of the DtPrintSetupCallbackStruct passed as call data to the DtNprintCallback list. The only exception is that when using DtPrintFillSetupData it is the caller's responsibility to free the allocated memory locations pointed to by the print_data structure by calling DtPrintFreeSetupData.
•: The X printer connection returned is managed by the DtPrintSetupBox. The caller should not destroy the print context, nor close the print display connection.
•: The DtPrintSetupBox widget instance passed via wid does not have to have been managed prior to calling DtPrintFillSetupData.
•: If the passed printer_name is NULL, the current printer as indicated by the DtNprinterName resource will be used, and returned in printer_name. If the passed printer_name is a different printer than indicated by the current value of the DtNprinterName resource, the resource will be updated.
•: The destination and dest_info elements of the passed print_data will be set according to the current state of the passed DtPrintSetupBox. If dest_info is set when passed to DtPrintFillSetupData, DtPrintFillSetupData will free the memory by calling XtFree if it decides to update If dest_info.
•: If a connection cannot be established, the DtPrintSetupBox will automatically be managed, displaying an error message box. After dismissing the message box, the user can select a new printer and restart the print operation, if desired.

For the "GUI-less" case, DtPrintFillSetupData is intended to provide an X printer connection, in a manner consistent with an X printer connection established by DtPrintSetupBox, without actually creating a DtPrintSetupBox. The following conditions apply to this case:

•: The passed wid must be set to NULL.
•: The X printer connection returned is managed by the caller, which means that the caller must destroy the print context (via XpDestroyContext) and close the print display connection (via XCloseDisplay).
•: If printer_name is set to NULL, DtPrintFillSetupData will determine a default printer, using the same procedure as DtPrintSetupBox, and set the printer_name field to this default printer name upon return.
•: The destination and dest_info elements of the passed print_data structure will be ignored by DtPrintFillSetupData.
•: The caller can free the allocated memory locations pointed to by the returned print_data structure by calling DtPrintFreeSetupData.

ARGUMENTS

wid: The widget ID of a DtPrintSetupBox or NULL, if no DtPrintSetupBox is available.
print_data: A pointer to an existing DtPrintSetupData structure that DtPrintFillSetupData will update with valid X printer connection information. See DtPrintSetupBox(3) for the definition of the DtPrintSetupData structure.

RETURN VALUE

DtPRINT_SUCCESS: The X printer connection was successfully obtained.
DtPRINT_INVALID_DISPLAY: The indicated X print server could not be found.
DtPRINT_NOT_XP_DISPLAY: The indicated X server does not support the X Printing Extension.
DtPRINT_NO_PRINTER: The indicated printer could not be found on the X print server, or a default printer could not be determined.
DtPRINT_BAD_PARM: The value passed for print_data is NULL, or the value of the DtNprintSetupMode resource for wid is not DtPRINT_SETUP_XP.

ENVIRONMENT VARIABLES

None.

RESOURCES

None.

ACTIONS/MESSAGES

None.

ERRORS/WARNINGS

None.

EXAMPLES

None.

FILES

None.