DtPrintFillSetupData(library call) DtPrintFillSetupData(library call)
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 acti-
vated the "Print" button. The following conditions apply to this case:
o 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.
o The X printer connection returned is managed by the DtPrintSetupBox. The caller should not destroy the print context, nor close the
print display connection.
o The DtPrintSetupBox widget instance passed via wid does not have to have been managed prior to calling DtPrintFillSetupData.
o 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.
o The destination and dest_info elements of the passed print_data will be set according to the current state of the passed DtPrintSe-
tupBox. 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.
o If a connection cannot be established, the DtPrintSetupBox will automatically be managed, displaying an error message box. After dis-
missing 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 con-
nection established by DtPrintSetupBox, without actually creating a DtPrintSetupBox. The following conditions apply to this case:
o The passed wid must be set to NULL.
o The X printer connection returned is managed by the caller, which means that the caller must destroy the print context (via XpDe-
stroyContext) and close the print display connection (via XCloseDisplay).
o 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.
o The destination and dest_info elements of the passed print_data structure will be ignored by DtPrintFillSetupData.
o 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 infor-
mation. 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.
SEE ALSO
DtPrintCopySetupData(3), DtPrintSetupBox(3), DtPrintFreeSetupData(3)
DtPrintFillSetupData(library call)