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

FreeBSD Manual Pages

  
 
  

home | help
XmPrintShell(3)		   Library Functions Manual	       XmPrintShell(3)

NAME
       XmPrintShell -- a shell widget class used for printing in Motif

SYNOPSIS
       #include	<Xm/Print.h>
       Boolean XmIsPrintShell(
       Widget);

DESCRIPTION
       The  XmPrintShell  provides the Motif application programmer with an Xt
       widget oriented API to some of the X Print resources and	a callback  to
       drive the pagination.

       The  XmPrintShell  provides  a simple callback to handle	the pagination
       logic, and a set	of resources to	get and	set common printer attributes.

       If not created on an XPrint connection, XmPrintShell behaves as a regu-
       lar applicationShell.

       The XmPrintShell	also initializes the Xp	extension event	handling mech-
       anism, by registering an	extension selector  that  calls	 XpSelectInput
       and  event  dispatcher  for print and attributes	Xp events, so applica-
       tions can use XtInsertEventTypeHandler to register  their  own  handler
       with the	Xp events.

   Arguments
       No  XmCreate function is	provided, since	this is	a toplevel shell, most
       likely created thru some	Xt shell creation routine or XmPrintSetup.

   Classes
       XmPrintShell is a subclass of ApplicationShell; it  inherits  behavior,
       resources  and  traits from all its superclasses.  The class pointer is
       XmPrintShellWidgetClass.

   New Resources
					XmPrintShell Resource Set
       Name			    Class			 Type		  Default   Access
       XmNstartJobCallback	    XmCCallback			 XtCallbackList	  NULL	    CSG
       XmNendJobCallback	    XmCCallback			 XtCallbackList	  NULL	    CSG
       XmNpageSetupCallback	    XmCCallback			 XtCallbackList	  NULL	    CSG
       XmNminX			    XmCMinX			 Dimension	  dynamic   G
       XmNminY			    XmCMinY			 Dimension	  dynamic   G
       XmNmaxX			    XmCMaxX			 Dimension	  dynamic   G
       XmNmaxY			    XmCMaxY			 Dimension	  dynamic   G
       XmNdefaultPixmapResolution   XmCDefaultPixmapResolution	 unsigned short	  100	    CSG
       XmNpdmNotificationCallback   XmCCallback			 XtCallbackList	  NULL	    CSG

       XmNstartJobCallback
		 Specifies the callback	driving	the  beginning	of  rendering.
		 It  is	 safe for an application to start rendering after this
		 callback has been activated.  XpStartJob must	be  called  to
		 trigger this callback.

       XmNendJobCallback
		 Specifies  the	callback driving the end of rendering.	Notify
		 the client that all rendering has been	processed (whether  on
		 print-to-file	or  regular spool).  XpEndJob is called	by the
		 print shell to	trigger	this callback.

       XmNpageSetupCallback
		 Specifies the callback	driving	the page layout.  It  is  safe
		 for  an app to	start rendering	from this callback even	if the
		 XmNstartJobCallback is	not used.

       XmNminX,	XmNminY, XmNmaxX, XmNmaxY
		 Specify the imageable area of the page	in the	current	 print
		 context.  XmPrintShell	 also  maintains  a proper size	at all
		 times by updating its own widget dimension whenever an	attri-
		 bute, such as resolution or orientation, changes. It is sized
		 in its	Initialize routine so that the application can rely on
		 a proper size before the first	StartPage call is issued.

       XmNdefaultPixmapResolution
		 Indicates  the	 resolution in dpi (dot	per inch) of the image
		 files read and	converted by Motif for the widget  descendants
		 of  this shell. It is used to determine a scaling ratio to be
		 applied to pixmap created thru	regular	pixmap/icon conversion
		 of the	following Widget resources:

		    o  XmLabel.label*Pixmap, XmIconG.*IconPixmap XmToggleB.se-
		       lectPixmap,   XmPushBG.armPixmap,    XmIconG.*IconMask,
		       XmMessageBox.symbolPixmap,    XmContainer.*StatePixmap,
		       ...

		    o  Leaving out the pixmap resources	being used for	tiling
		       (XmNhighlightPixmap, XmNtopShadowPixmap,	XmNbottomShad-
		       owPixmap, XmNbackgroundPixmap, ...)

       XmNpdmNotificationCallback
		 A callback notifying the application about the	status of  the
		 PDM  (see  XmPrintPopupPDM).  A XmPrintShellCallbackStruct is
		 used, with reason:

		    o  XmCR_PDM_NONE: no PDM available on this display for the
		       named selection (provided in detail)

		    o  XmCR_PDM_START_VXAUTH  :	 the  PDM is not authorized to
		       connect to the video display.

		    o  XmCR_PDM_START_PXAUTH : the PDM is  not	authorized  to
		       connect to the print display.

		    o  XmCR_PDM_UP : the PDM is	up and running

		    o  XmCR_PDM_OK : the PDM has exited	with OK	status

		    o  XmCR_PDM_CANCEL : the PDM has exited with CANCEL

		    o  XmCR_PDM_START_ERROR : the PDM cannot start due to some
		       error (usually logged)

		    o  XmCR_PDM_EXIT_ERROR : the PDM has exited	with an	error

   Callback Information
       The XmNstartJobCallback,	 XmNendJobCallback,  XmNpageSetupCallback  and
       XmNpdmNotificationCallback  operate  on	a  XmPrintShellCallbackStruct,
       which is	defined	as follow:

       typedef struct
       {
	   int	   reason;  /* XmCR_START_JOB, XmCR_END_JOB,
			       XmCR_PAGE_SETUP,	XmCR_PDM_* */
	   XEvent  *event;
	   XPContext print_context;
	   Boolean last_page; /* in_out	*/
	   XtPointer detail;
       } XmPrintShellCallbackStruct;

   Additional Behavior
       The  last_page  field  is  only	 meaningful   when   the   reason   is
       XmCR_PAGE_SETUP.

       The  page  setup	 callback is called with last_page False to notify the
       application that	it has to get its internal layout state	ready for  the
       next  page.  Typically, a widget	based application will change the con-
       tent of a Label showing the page	number,	or scroll the content  of  the
       Text widget.

       When  the  application  has  processed its last page, it	should set the
       last_page field in the callback struct to True. The  callback  will  be
       called a	last time after	that with last_page False to notify the	appli-
       cation that it can safely clean-up its internal	state  (e.g.,  destroy
       widgets).

       No drawing should occur from within the callback	function in the	appli-
       cation, this is an Exposure event-driven	programming model  where  wid-
       gets render themselves from their expose	methods.

       The  print shell	calls XpStartPage after	the pageSetupCallback returns,
       and XpEndPage upon reception of StartPageNotify.

ERRORS/WARNINGS
       XmPrintShell can	generate the following warnings:

	  o  Not connected to a	valid X	Print Server: behavior undefined.

	  o  Attempt to	set an invalid resolution on a printer:	%s

	  o  Attempt to	set an invalid orientation on a	printer: %s

RETURN VALUE
       Not applicable

EXAMPLES
       PrintOnePageCB(Widget pshell, XtPointer npages,
       /*----------*/ XmPrintSetPageCBStruct psp)
       {
	   static int cur_page = 0;
	   cur_page++;

	   if (! psp->last_page
	       && curPage > 1) /* no need to scroll for	the first page */
	   {

	       XmTextScroll(ptext, prows);  /* get ready for next page */

	   } else {    /**** I'm done */

	      XtDestroyWidget(pshell);
	      XtCloseDisplay(XtDisplay(pshell));
	   }

	   if (cur_page	== (int) n_pages) psp->last_page = True;
       }

       PrintOKCallback(...)
       /*-------------*/
       {
	   pshell = XmPrintSetup (widget, pbs->print_screen,
					  "Print", NULL, 0);

	   XpStartJob(XtDisplay(pshell), XPSpool);

	   /**** here I	get the	size of	the shell, create my widget
		 hierarchy: a bulleting	board, and then	a text widget,
		 that I	stuff with the video text widget buffer	*/

	   /* get the total number of pages to print */
	   /* same code	as previous example to get n_pages */

	   /****  set up my print callback */
	   XtAddCallback(pshell,  XmNpageSetUpCallback,
				  PrintOnePageCB, n_pages);
       }

       Examples	of XmNdefaultPixmapResolution usage:

	  o  An	application reuses the same image  sources  it	uses  for  the
	     video  interface,	in  XBM,  XPM,	PNG  ot	JPEG, to layout	on its
	     printed pages. In this case, scaling is seamless.

	   ! icon.xpm is 30x30 pixels
	   app*dialog.pushb.labelPixmap:icon.xpm
	   ! print is 400dpi
	   app.print*form.lab.labelPixmap:icon.xpm
	   ! 120x120 pixels on the paper (auto scaling)

	  o  An	application provides a new set of image	 files,	 for  a	 given
	     printer  resolution  (say 300). It	doesn't	want automatic scaling
	     by	the toolkit for	that resolution, it  wants  scaling  based  on
	     these  300dpi  images for higher resolution. It creates its print
	     shell inside using	the name "printHiRes" and adds	the  following
	     in	its resource file:

	   app.printHiRes.defaultPixmapResolution:300
	   ! icon300.xpm is 120x120 pixels
	   app.printHiRes*form.lab.labelPixmap:icon300.xpm
	   ! 120x120 pixels on the paper (no scaling)

       This  way  a  printer resolution	of 600 will result in a	scale of a 300
       dpi image by 2 (dpi=600 divided by base=300), while a  printer  resolu-
       tion  of	 150 (using default print shell	name "print") will use the 100
       dpi icon	scaled by 1.5 (dpi=150 divided by default base=100).

SEE ALSO
       XmPrintSetup(3),	XmRedisplayWidget(3), XmPrintToFile(3),	 XmPrintPopup-
       PDM(3)

							       XmPrintShell(3)

NAME | SYNOPSIS | DESCRIPTION | ERRORS/WARNINGS | RETURN VALUE | EXAMPLES | SEE ALSO

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

home | help