<!-- $XConsortium: RedWidg.sgm /main/9 1996/09/08 20:56:20 rws $ -->
<!-- (c) Copyright 1996 Digital Equipment Corporation. -->
<!-- (c) Copyright 1996 Hewlett-Packard Company. -->
<!-- (c) Copyright 1996 International Business Machines Corp. -->
<!-- (c) Copyright 1996 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1996 Novell, Inc. -->
<!-- (c) Copyright 1996 FUJITSU LIMITED. -->
<!-- (c) Copyright 1996 Hitachi. -->
<RefEntry Id="CDEMOT.XmRedisplayWidget">
<RefMeta>
<RefEntryTitle>XmRedisplayWidget</RefEntryTitle>
<ManVolNum>library call</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Function>XmRedisplayWidget</Function></RefName>
<RefPurpose>
Synchronously activates the <literal>expose</literal> method of a widget to draw its content
</RefPurpose>
</RefNameDiv>
<RefSynopsisDiv>
<FuncSynopsis Remap="ANSI">
<FuncSynopsisInfo>#include &lt;Xm/Xm.h>
</FuncSynopsisInfo>
<FuncDef>void<Function>XmRedisplayWidget</Function></FuncDef>
<ParamDef>Widget<Parameter>widget</parameter></paramdef>
</FuncSynopsis>
</RefSynopsisDiv>
<refsect1><title>DESCRIPTION</title>
<para>This function is a convenience routine that hides the
details of the Xt internals to the application programmer by calling the
<literal>expose</literal>
method of the given widget with a well formed
<literal>Expose</literal>
event and
<literal>Region</literal>
corresponding to the total area of the widget. If the widget doesn't have an
<literal>Expose</literal>
method, the function does nothing.
</para>
<para>This is primarily used in the context of X Printing if the
programming model chosen by the application is <emphasis>synchronous</emphasis>;
that is, it doesn't rely of X Print events for the driving of
page layout but wants to completely control the sequence of rendering requests.
</para>
<para><function>XmRedisplayWidget</function>
doesn't clear the widget window prior to calling the
<literal>expose</literal>
method, since this is handled by calls to
<function>XpStartPage</function>
.
</para>
<variablelist>
<VarListEntry><term><Symbol Role="Variable">widget</Symbol></term>
<ListItem>
<para>The widget to redisplay.
</para>
</ListItem>
</VarListEntry>
</variablelist>
</refsect1>
<refsect1><title>RETURN VALUE</title>
<para>None.
</para>
</refsect1>
<refsect1><title>ERRORS/WARNINGS</title>
<para>Not applicable
</para>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<para>In the following, a simple application wants to
print the content of a multi-page text widget (similar to
<literal>dtpad</literal>).
</para>
<programlisting>
PrintOKCallback(print_dialog...)
/*-------------*/
{
    pshell = XmPrintSetup (print_dialog, pbs->print_screen,
                                   "Print", NULL, 0);

    XpStartJob(XtDisplay(pshell), XPSpool);

    /**** here I realize the shell, get its size, create my widget
     hierarchy: a bulletin board, and then a text widget,
     that I stuff with the video text widget buffer */

    /* get the total number of pages to print */
    XtVaGetValues(ptext, XmNrows, &amp;prows,
                         XmNtotalLines, n_lines, NULL);
    n_pages = n_lines / prows;

    /***** now print the pages in a loop */

    for (cur_page=0; cur_page != n_pages; cur_page++) {

               XpStartPage(XtDisplay(pshell), XtWindow(pshell), False);
               XmRedisplayWidget(ptext);  /* do the drawing */
               XpEndPage(XtDisplay(pshell));

        XmTextScroll(ptext, prows);  /* get ready for next page */
    }

    /***** I'm done */
    XpEndJob(XtDisplay(pshell));

}
</programlisting>
<para>Of course, one could change the above code to include it in a
<function>fork()</function>
branch so that the main program is not blocked while
printing is going on. Another way to achieve a
"print-in-the-background" effect is to use an Xt workproc. Using the
same sample application, that gives us:
</para>
<programlisting>
Boolean
PrintOnePageWP(XtPointer npages) /* workproc */
/*-------------*/
{
    static int cur_page = 0;
    cur_page++;

    XpStartPage(XtDisplay(pshell), XtWindow(pshell), False);
    XmRedisplayWidget(ptext);  /* do the drawing */
    XpEndPage(XtDisplay(pshell));

    XmTextScroll(ptext, prows);  /*  get ready for next page */

    if (cur_page == n_pages) { /***** I'm done */
        XpEndJob(XtDisplay(pshell));

        XtDestroyWidget(pshell);
        XtCloseDisplay(XtDisplay(pshell));
    }

    return (cur_page == n_pages);
}

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 bulletin 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 above example */

    /***** print the pages in the background */
    XtAppAddWorkProc(app_context, PrintOnePageWP, n_pages);
}
</programlisting>
</refsect1>
<refsect1><title>SEE ALSO</title>
<para>&cdeman.XmPrintSetup;,
&cdeman.XmPrintShell;
</para>
</refsect1>
</refentry>
