[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

Use the function InstallClipRegion() to install the region.

    struct Region *InstallClipRegion( struct Layer *layer,
                                      struct Region *region );

This installs a transparent clipping region to a layer.  All subsequent
graphics calls will be clipped to this region.  The region must be removed
with a second call to InstallClipRegion() before removing the layer.

    /*
    ** Sample installation and removal of a clipping region
    */
    register struct Region     *new_region ;
    register struct Region     *old_region ;

    /* If the application owns the layer and has not installed a region,
    ** old_region will return NULL here.
    */
    old_region = InstallClipRegion(win->WLayer, new_region);

    /* draw into the layer or window */

    if (NULL != (old_region = InstallClipRegion(win->WLayer, old_region)))
        {
        /* throw the used region away.  This region could be saved and
        ** used again later, if desired by the application.
        */
        DisposeRegion(new_region) ;
        }


    A Warning About InstallClipRegion().
    ------------------------------------
    The program must not call InstallClipRegion() inside of a
    Begin/EndRefresh() or Begin/EndUpdate() pair.  The following code
    segment shows how to modify the user clipping region when using these
    calls.  See the Autodoc for BeginRefresh() for more details.


    register struct Region     *new_region ;
    register struct Region     *old_region ;

    /* you have to have already setup the new_region and old_region */

    BeginRefresh(window);
    /* draw through the damage list */
    /* into the layer or window */
    EndRefresh(window, FALSE);              /* keep the damage list */

    old_region = InstallClipRegion(win->WLayer, new_region);

    BeginRefresh(window);
    /* draw through the damage list and the new_region */
    /* into the layer or window */
    EndRefresh(window, FALSE);              /* keep the damage list */

    /* put back the old region */
    new_region = InstallClipRegion(win->WLayer, old_region);

    BeginRefresh(window);
    EndRefresh(window, TRUE);               /* remove the damage list */

    old_region = InstallClipRegion(win->WLayer, new_region);

    BeginRefresh(window);
    /* draw through the new_region only into the layer or window */
    EndRefresh(window, FALSE);

    /* finally get rid of the new region, old_region still installed */
    if (NULL != (new_region = InstallClipRegion(win->WLayer, old_region)))
        DisposeRegion(new_region) ;