XmPrintShell

a shell widget class used for printing in Motif

Format

#include <Xm/Print.h>
Boolean
XmIsPrintShellWidget

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

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:

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:

    ! 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)

    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)