DtPrintFillSetupData(library call) DtPrintFillSetupData(library call)
NAME [Toc] [Back]
DtPrintFillSetupData - obtains X printer connection information
SYNOPSIS [Toc] [Back]
#include <Print.h>
XtEnum DtPrintFillSetupData(
Widget wid,
DtPrintSetupData* print_data);
DESCRIPTION [Toc] [Back]
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
- 1 - Formatted: January 24, 2005
DtPrintFillSetupData(library call) DtPrintFillSetupData(library call)
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
- 2 - Formatted: January 24, 2005
DtPrintFillSetupData(library call) DtPrintFillSetupData(library call)
DtPrintFreeSetupData.
ARGUMENTS [Toc] [Back]
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 [Toc] [Back]
DtPRINT_SUCCESS
The X printer connection was successfully obtained.
DtPRINT_INVALID_DISPLAY [Toc] [Back]
The indicated X print server could not be found.
DtPRINT_NOT_XP_DISPLAY [Toc] [Back]
The indicated X server does not support the X Printing
Extension.
DtPRINT_NO_PRINTER [Toc] [Back]
The indicated printer could not be found on the X print
server, or a default printer could not be determined.
DtPRINT_BAD_PARM [Toc] [Back]
The value passed for print_data is NULL, or the value of the
DtNprintSetupMode resource for wid is not DtPRINT_SETUP_XP.
ENVIRONMENT VARIABLES [Toc] [Back]
None.
RESOURCES [Toc] [Back]
None.
ACTIONS/MESSAGES
None.
ERRORS/WARNINGS
None.
EXAMPLES [Toc] [Back]
None.
FILES [Toc] [Back]
None.
SEE ALSO [Toc] [Back]
- 3 - Formatted: January 24, 2005
DtPrintFillSetupData(library call) DtPrintFillSetupData(library call)
DtPrintCopySetupData(3), DtPrintSetupBox(3), DtPrintFreeSetupData(3)
- 4 - Formatted: January 24, 2005 [ Back ] |
