[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Programmer's Guide



The Printing APIs

The printing APIs are as follows:

  1. XmPrintSetup

  2. XmPrintShell

  3. XmPrintPopupPDM

  4. XmGetScaledPixMap

  5. XmRedisplayWidget

  6. XmPrintToFile

    This section summarizes the APIs and gives examples of their use.

    XmPrintSetup registers an X Print Server connection with Xt, sets resources appropriately, and creates an XmPrintShell that it returns to the caller. In this example, the print shell is created in the OKcallback of a DtPrintSetupBox:

    void OKCallback(Widget w, XtPointer client_data, XtPointer
    call_data)
    {
        DtPrintSetupCallbackStruct *pbs = call_data;
        static Widget shell;
        static int num;          /* app data to print */
     
        if (!shell) {
          shell =
              XmPrintSetup(widget,
                           XpGetScreenOfContext(pbs->
    print_display,
                                                pbs->
    print_context)
                           "Print", NULL, 0);
          XtAddCallback(p->
    print_shell, XmNpageSetupCallback,
                        PageSetupCB, &num);
          XtAddCallback(p->
    print_shell, XmNpdmNotificationCallback,
                        PdmNotifyCB, &num);
        }
     
        num = 0;
     
        /* check print-to-file & print */
    }

    XmPrintShell encapsulates some of the X Print Service functionalities and provides the framework for the asynchronous printing programming model. Here is an example of a XmNpageSetupCallback:

    void PageSetupCB(Widget w, XtPointer client_data, XtPointer
                     call_data)
    {
       Widget print_shell = widget;
       XmPrintShellCallbackStruct* pr_cbs = call_data;
       int *num = client_data;
       static Widget form, text;
       char buf[10];
     
       /* don't do anything after last page is printed *
       if (pr_cbs->
    last_page) return;
     
       /* create the widgets once */
       if (!form) {
          form = XmCreateForm("form", print_shell, NULL, 0);
          text = XmCreateTextField("text", form, NULL, 0);
       }
     
       /* setup app's data in print text widget */
       sprintf(buf, "%d", *num);
       XmTextSetString(text, buf);
     
       num++
       if (num >
     9) pr_cbs->
    last_page = True;
    }

    XmPrintPopupPDM sends a notification to start a print dialog manager on behalf of the application. An example:

    if (XmPrintPopupPDM(print_shell, top_level) !=
         XmPDM_NOTIFY_SUCCESS)
     {
         /* let user know of problem */
     }

    XmGetScaledPixMap retrieves a Pixmap from an XBM or XPM file and potentially scales it to match the printer resolution. Again, this example is from a XmNpageSetupCallback:

    int *month = client_data;
    static Widget form, label;
    Pixmap pixmap;
    unsigned long fg, bg;
    int depth;
     
    /* create the widgets once */
    if (!form) {
       form = XmCreateForm("form", print_shell, NULL, 0);
       label1 = XmCreateLabel("label", form, NULL, 0);
    }
     
    XtVaGetValues(label, XmNforeground, &fg,
                  XmNbackground, &bg, XmNdepth, &depth);
     
    /* since label is a child of a XmPrintShell, and we have
       specified 0 as the scaling factor, it will be scaled
       appropriately.  Also, the cache will take care of calling
       this more than once */
    pixmap = XmGetScaledPixmap(label,
                               ((*month) ? "month.xpm": "week.xpm"),
                               fg, bg, depth, 0);

    XmRedisplayWidget calls the expose method of a widget in order to draw its content; for example:

    XmTextScroll(text, lines_per_page);
    XmRedisplayWidget(text);

    XmPrintToFile retrieves the data being sent by a Print Server and prints it to a file on the client side. What follows is the remaining part of the OKCallback above:

    int save_data = XPSpool;
     
    if (pbs->
    destination == DtPRINT_TO_FILE)
    save_data = XPGetData;
     
    /* start job must precede XpGetDocumentData in XmPrintToFile */
    XpStartJob(XtDisplay(print_shell), save_data);
     
    /* setup print to file */
    if (pbs->
    destination == DtPRINT_TO_FILE)
    {
       if (!XmPrintToFile(XtDisplay(print_shell),
                          pbs->
    dest_info, FinishPrintToFile, NULL))
          {
            /* output some kind of error message */
           XpCancelJob(XtDisplay(print_shell), True);
     
           /* go back to the event loop as if we had never printed */
              return;
          }
    }

  7. [ Previous | Next | Contents | Glossary | Home | Search ]