WinExcludeUpdateRegion

This function subtracts the update region (invalid region) of a window from the clipping region of a presentation space.

Syntax

WinExcludeUpdateRegion(hps, hwnd)

Parameters

hps (HPS) - Input: Presentation-space handle whose clipping region is to be updated.
hwnd (HWND) - Input: Window handle of window whose update region is subtracted.
lComplexity (LONG) - Returns: Complexity value.

Returns

lComplexity (LONG) - returns

Complexity value. This indicates the resulting form of the clipping area. The values and meanings of this parameter are defined in GpiCombineRegion.

RGN_NULL: Null Region
RGN_RECT: Rectangle region
RGN_COMPLEX: Complex region
RGN_ERROR: Error.

Remarks

This function is typically used to prevent drawing into parts of a window that are known to be invalid, as during an incremental update optimization process.

It is the application's responsibility to reset the clipping region when necessary.

Errors

Possible returns from WinGetLastError:

PMERR_INVALID_HWND (0x1001) - An invalid window handle was specified.

Example Code

#define INCL_WINWINDOWMGR /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HPS     hps;          /*  Presentation-space handle whose clipping region is to be updated. */
HWND    hwnd;         /*  Window handle. */
LONG    lComplexity;  /*  Complexity value. */

lComplexity = WinExcludeUpdateRegion(hps,
                hwnd);

This example uses WinExcludeUpdateRegion to prevent drawing into the window's known invalid regions (to optimize updates) by excluding the window's update region from the clipping region of the presentation space. The clipping region will need to be reset later by the application, which can accomplished using GpiIntersectClipRectangle with the rectangle comprising the window as input.

#define INCL_WINWINDOWMGR         /* Window Manager Functions         */
#define INCL_GPIREGIONS           /* Region functions                 */
#include <os2.h>

LONG  lComplexity;           /* clipping complexity/error return     */
HWND    hwnd;                /* parent window                         */
RECTL   rcl;                 /* update region                         */
HPS     hps;                 /* presentation-space handle             */

 case WM_PAINT:
    lComplexity = WinExcludeUpdateRegion(hps, hwnd);

    hps = WinBeginPaint(hwnd,   /* handle of the window             */
                        NULLHANDLE,           /* get a cache presentation space */
                        &rcl);                /* receives update rectangle      */
    WinFillRect(hps, &rcl, CLR_WHITE);
    WinEndPaint(hps);

Related Functions