View source for 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==
<PRE> #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); </PRE>

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).
<PRE> #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);} </PRE>

==Related Functions==
* [[WinBeginPaint]]
* [[WinEnableWindowUpdate]]
* [[WinEndPaint]]
* [[WinExcludeUpdateRegion]]
* [[WinGetClipPS]]
* [[WinGetPS]]
* [[WinGetScreenPS]]
* [[WinInvalidateRect]]
* [[WinInvalidateRegion]]
* [[WinIsWindowShowing]]
* [[WinIsWindowVisible]]
* [[WinLockVisRegions]]
* [[WinOpenWindowDC]]
* [[WinQueryUpdateRect]]
* [[WinQueryUpdateRegion]]
* [[WinRealizePalette]]
* [[WinReleasePS]]
* [[WinShowWindow]]
* [[WinUpdateWindow]]
* [[WinValidateRect]]

[[Category:Win]]