Adding a Rectangular Area to a Clip Region

Some applications might need to increase the size of a clip region. For example, a user might request that a desktop publishing application extend a column of text on a page.

To add a rectangular area to a clip region, follow these steps:

• Determine the dimensions (in device coordinates) of the rectangular area to add to the current clip region.

• Release the current clip region using GpiSetClipRegion. GpiCombineRegion cannot combine regions if either of the regions is a clip region.

• Call GpiCreateRegion and pass it the dimensions of the rectangle that you defined in Step 1. This creates a second region that you can combine with the first.

• Call GpiCreateRegion again and create a third region that will be the final destination region.

• Call GpiCombineRegion to create a region that combines the original region and the region you created in Step 2. It is not essential to create a third region because GpiCombineRegion can use one of the 2 source regions being combined for a target region.

• Call GpiSetClipRegion and pass it the handle returned by GpiCombineRegion.

The following figure illustrates these steps.

#define INCL_GPIREGIONS#include <os2.h>
void fncCLIP04(void){
    HPS   hps;
    RECTL rcl1, rcl2, rcl3;
    HRGN  hrgn1, hrgn2, hrgn3;

    hrgn1 = GpiCreateRegion(hps, sizeof(rcl1) / sizeof(RECTL), &rcl1);
    GpiSetClipRegion(hps, hrgn1, NULL);       /* Creates first clipping region */
        .
        .  /* Compute coordinates of second region here.                       */
        .
    GpiSetClipRegion(hps, NULLHANDLE, NULL);  /* Releases first clipping region*/
    hrgn2 = GpiCreateRegion(hps, sizeof(rcl2) / Sizeof(RECTL), &rcl2);
    hrgn3 = GpiCreateRegion(hps, sizeof(rcl3) / Sizeof(RECTL), &rcl3);
    GpiCombineRegion(hps, hrgn3, hrgn1, hrgn2, CRGN_OR);
    GpiSetClipRegion(hps, hrgn3, NULL);       /* Creates second clipping region*/
} /* fncCLIP04 */