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:
- •
- XmLabel.label*Pixmap, XmIconG.*IconPixmap
XmToggleB.selectPixmap, XmPushBG.armPixmap,
XmIconG.*IconMask, XmMessageBox.symbolPixmap,
XmContainer.*StatePixmap, ...
- •
- 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:
- •
- XmCR_PDM_NONE: no PDM available on this display for the named
selection (provided in detail)
- •
- XmCR_PDM_START_VXAUTH : the PDM is not authorized to connect to the
video display.
- •
- XmCR_PDM_START_PXAUTH : the PDM is not authorized to connect to the
print display.
- •
- XmCR_PDM_UP : the PDM is up and running
- •
- XmCR_PDM_OK : the PDM has exited with OK status
- •
- XmCR_PDM_CANCEL : the PDM has exited with CANCEL
- •
- XmCR_PDM_START_ERROR : the PDM cannot start due to some error
(usually logged)
- •
- XmCR_PDM_EXIT_ERROR : the PDM has exited with an error
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:
- •
- Not connected to a valid X Print Server: behavior undefined.
- •
- Attempt to set an invalid resolution on a printer: %s
- •
- 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:
- •
- 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)
- •
- 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).
SEE ALSO¶
XmPrintSetup(3),
XmRedisplayWidget(3),
XmPrintToFile(3),
XmPrintPopupPDM(3)