WinInvalidateRect

This function adds a rectangle to a window's update region.

Syntax

WinInvalidateRect(hwnd, pwrc, fIncludeChildren)

Parameters

hwnd (HWND) - Input: Handle of window whose update region is to be changed. Use HWND_DESKTOP for the whole screen.
pwrc (PRECTL) - Input: Update rectangle. NULL to invalidate the whole window.
fIncludeChildren (BOOL) - Input: Invalidation-scope indicator. TRUE to include descendants, FALSE to include only if parent doesn't have WS_CLIPCHILDREN.
rc (BOOL) - Returns: Success indicator. TRUE for success, FALSE for error.

Returns

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion
FALSE: Error occurred.

Remarks

The update region is a subregion of a window that is deemed "invalid" or incorrect in visual terms and in need of redrawing.

If the window has a CS_SYNCPAINT style, it is redrawn during the processing of this function and the update region should be NULL on return from this function.

If the window has a WS_CLIPCHILDREN style with part of its update region overlapping child windows with a CS_SYNCPAINT style, those children are updated before this function returns.

This function should not be called in response to a WM_PAINT request for windows of style CS_SYNCPAINT. CS_SYNCPAINT means that windows are updated synchronously when invalidated, which generates a WM_PAINT message. Thus, invalidating the window in response to a WM_PAINT message would cause another invalidate, and another WM_PAINT, and so on.

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 to be changed. */
PRECTL    pwrc;       /* Update rectangle. */
BOOL      fIncludeChildren; /* Invalidation-scope indicator. */
BOOL      rc;         /* Success indicator. */

rc = WinInvalidateRect(hwnd, pwrc, fIncludeChildren);

This example gets the dimensions of the window and calls WinInvalidateRect to invalidate the window. The application will be sent a WM_PAINT message with the entire window as the update rectangle.

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

HWND    hwnd;                  /* parent window                         */
RECTL   rcl;                   /* update region                         */

WinQueryWindowRect(hwnd, &rcl);

WinInvalidateRect(hwnd,     /* window to invalidate    */
                &rcl,                      /* invalid rectangle       */
                FALSE);                   /* do not include children */

Related Messages

WM_PAINT

Related Functions