WinValidateRect

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

Syntax

WinValidateRect(hwnd, prclRect, 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).

prclRect (PRECTL) - Input

Rectangle to be subtracted from the window's update region.

Note: The value of each field in this structure must be in the range -32 768 through 32 767. The data type WRECT may also be used, if supported by the language.

fIncludeClippedChildren (BOOL) - Input

Validation-scope indicator.

TRUE Include descendants of hwnd in the valid rectangle

FALSE Include descendants of hwnd in the valid rectangle, 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.

This function 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_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. */
PRECTL    prclRect;                 /*  Rectangle to be subtracted from the window's update region. */
BOOL      fIncludeClippedChildren;  /*  Validation-scope indicator. */
BOOL      rc;                       /*  Success indicator. */

rc = WinValidateRect(hwnd, prclRect, fIncludeClippedChildren);

The window needs painting. This is done asynchronously on the drawing thread. The window update region is copied into a local region and passed to the drawing thread. The window must be validated now (to prevent further unnecessary paint messages).

 
#define INCL_WINWINDOWMGR
#include <OS2.H>
HRGN hrgnUpdate;
HPS hps;
HWND hwnd;
/* Window needs paint           */
        case WM_PAINT:

/* assume we stop any asynchronous drawing.  */
/* by posting a message to the asynchronous  */
/* drawing thread.                           */

hrgnUpdate=(HRGN)GpiCreateRegion(hps,    /* Create empty region  */
                             0L,
                             (PRECTL)NULL);

WinQueryUpdateRegion(hwnd,             /* Save the window update */
                     hrgnUpdate);      /* region.                */

WinValidateRect(hwnd,                  /* Validate window now to */
               (PRECTL)NULL,           /*   stop more paint msgs */
                 TRUE);

/* assume a message is posted to the drawing thread, passing */
/* the update region: (MPARAM)hgrnUpdate.                    */

   mr = (MRESULT) 0L;             /*  Message processed          */
   break;                         /*       End window painting   */

Related Functions