manpagez: man pages & more
man XmPrintShell(3)
Home | html | info | man
XmPrintShell(library call)                          XmPrintShell(library call)




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
                 attribute, 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    XmTog-
                       gleB.selectPixmap,  XmPushBG.armPixmap,  XmIconG.*Icon-
                       Mask,         XmMessageBox.symbolPixmap,         XmCon-
                       tainer.*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(library call)

openMotif 2.3.1 - Generated Tue Dec 2 07:54:28 CST 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.