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)