Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 in-
       teraction 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 Dt-
       PrintSetupBox widget instance, or if a DtPrintSetupBox widget  instance
       is  unavailable,	DtPrintFillSetupData will provide a new	X printer con-
       nection.

       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 de-
       scription of this process, see the  DtNverifyPrinterProc	 resource  de-
       scription 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:

	  o  The wid parameter should be set to	 the  widget  ID  of  the  Dt-
	     PrintSetupBox   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
	     caller's responsibility to	free the  allocated  memory  locations
	     pointed  to by the	print_data structure by	calling	DtPrintFreeSe-
	     tupData.

	  o  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.

	  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 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.

	  o  The  destination  and dest_info elements of the passed print_data
	     will be set according to the current  state  of  the  passed  Dt-
	     PrintSetupBox.  If	dest_info is set when passed to	DtPrintFillSe-
	     tupData, 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
	     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  Dt-
       PrintSetupBox.  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	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.

	  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 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 Dt-
		 PrintFillSetupData 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 ALSO
       DtPrintCopySetupData(3),	DtPrintSetupBox(3), DtPrintFreeSetupData(3)

					    DtPrintFillSetupData(library call)

NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | RETURN VALUE | ENVIRONMENT VARIABLES | RESOURCES | ACTIONS/MESSAGES | ERRORS/WARNINGS | EXAMPLES | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DtPrintFillSetupData&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help