Tribblix: manual page: XmPrintShell.3

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

The XmPrintShell also initializes the Xp extension event handling
mechanism, by registering an extension selector that calls
XpSelectInput and event dispatcher for print and attributes Xp
events, so applications 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
XmToggleB.selectPixmap, XmPushBG.armPixmap,
XmIconG.*IconMask, XmMessageBox.symbolPixmap,
XmContainer.*StatePixmap, ...

+o Leaving out the pixmap resources being used for
tiling (XmNhighlightPixmap, XmNtopShadowPixmap,
XmNbottomShadowPixmap, 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
content 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
application that it can safely clean-up its internal state (e.g.,
destroy widgets).

No drawing should occur from within the callback function in the
application, this is an Exposure event-driven programming model where
widgets 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
resolution 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).