WinValidateRegion

This function subtracts a region from the update region of an asynchronous paint window, marking that part of the window as visually valid.

Syntax

WinValidateRegion(hwnd, hrgn, fIncludeClippedChildren)

Parameters

hwnd (HWND) - Input

Handle of window whose update region is changed.

If this parameter is HWND_DESKTOP or a desktop window handle, the function applies to the whole screen (or desktop).

hrgn (HRGN) - Input

Handle of subtracted region.

This is the region that is subtracted from the window's update region.

fIncludeClippedChildren (BOOL) - Input

Validation-scope indicator.

TRUE Include descendants of hwnd in the valid region

FALSE Include descendants of hwnd in the valid region, only if parent is not WS_CLIPCHILDREN.

Returns

rc (BOOL) - Returns

Success indicator.

TRUE Successful completion

FALSE Error occurred.

Remarks

The call is not used for CS_SYNCPAINT windows.

The call has no effect on the window if any part of the window has been made invalid since the last call to WinBeginPaint, WinQueryUpdateRect, or WinQueryUpdateRegion.

Errors

Possible returns from WinGetLastError:

• PMERR_INVALID_HWND (0x1001) An invalid window handle was specified.
• PMERR_HRGN_BUSY (0x2034) An internal region busy error was detected. The region was locked by one thread during an attempt to access it from another thread.
• PMERR_INVALID_FLAG (0x1019) An invalid bit was set for a parameter. Use constants defined by PM for options, and do not set any reserved bits.

Example Code

 #define INCL_WINWINDOWMGR /* Or use INCL_WIN, INCL_PM, */ #include <os2.h> HWND hwnd; /* Handle of window whose update region is changed. */ HRGN hrgn; /* Handle of subtracted region. */ BOOL fIncludeClippedChildren; /* Validation-scope indicator. */ BOOL rc; /* Success indicator. */ rc = WinValidateRegion(hwnd, hrgn, fIncludeClippedChildren); 

This example shows how an application can incrementally repaint an asynchronous-paint window one area at a time. While a window is invalid (has a non-null update region), WM_PAINT messages are returned by WinGetMsg. The application uses WinQueryUpdateRegion to obtain a region that requires repainting, and WinValidateRegion to validate the region (reset the update region to null).

 #define INCL_WINWINDOWMGR #define INCL_GPIREGIONS #include <OS2.H> HRGN hrgnUpdt, sRgnType; HPS hpsPaint; HWND hwnd; /* Window needs paint */ case WM_PAINT: /* assume we stop any asynchronous drawing. */ /* by posting a message to the asynchronous */ /* drawing thread. */ hrgnUpdt = (HRGN)GpiCreateRegion(hpsPaint, (ULONG)0, (PRECTL)NULL); sRgnType = (HRGN)WinQueryUpdateRegion(hwnd, hrgnUpdt); /* if the region is not null and the call is not in error, */ /* validate the region. */ if ((sRgnType != NULL) && (sRgnType != RGN_ERROR)) { WinValidateRegion(hwnd, hrgnUpdt, FALSE); /* here we would send the update region handle to an asynchronous drawing thread. We have already validated the region, so no more WM_PAINT messages will be sent due to this region. */ } else { GpiDestroyRegion(hpsPaint, hrgnUpdt);} 

Related Functions

• WinBeginPaint
• WinEnableWindowUpdate
• WinEndPaint
• WinExcludeUpdateRegion
• WinGetClipPS
• WinGetPS
• WinGetScreenPS
• WinInvalidateRect
• WinInvalidateRegion
• WinIsWindowShowing
• WinIsWindowVisible
• WinLockVisRegions
• WinOpenWindowDC
• WinQueryUpdateRect
• WinQueryUpdateRegion
• WinRealizePalette
• WinReleasePS
• WinShowWindow
• WinUpdateWindow
• WinValidateRect