DtPrintFillSetupData(library call) DtPrintFillSetupData(library call)
NAMEDtPrintFillSetupData — 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 veri‐
fied, 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 DtPrintSetupCallback‐
Struct passed as call data to the DtNprintCallback list. The only
exception is that when using DtPrintFillSetupData it is the call‐
er's responsibility to free the allocated memory locations
pointed to by the print_data structure by calling DtPrintFreeSe‐
tupData.
· The X printer connection returned is managed by the DtPrintSetup‐
Box. 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 indi‐
cated 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 DtPrint‐
FillSetupData, DtPrintFillSetupData will free the memory by call‐
ing 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 connec‐
tion 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 XpDe‐
stroyContext) and close the print display connection (via
XCloseDisplay).
· If printer_name is set to NULL, DtPrintFillSetupData will deter‐
mine a default printer, using the same procedure as DtPrintSetup‐
Box, 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 DtPrintFreeSetup‐
Data.
ARGUMENTS
wid The widget ID of a DtPrintSetupBox or NULL, if no DtPrintSe‐
tupBox is available.
print_data
A pointer to an existing DtPrintSetupData structure that
DtPrintFillSetupData will update with valid X printer connec‐
tion 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 Exten‐
sion.
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 ALSODtPrintCopySetupData(3), DtPrintSetupBox(3), DtPrintFreeSetupData(3)
DtPrintFillSetupData(library call)
