WinInvalidateRegion

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

Syntax

WinInvalidateRegion(hwnd, hrgn, fIncludeChildren)

Parameters

hwnd (HWND) - Input

Handle of the window whose update region is to be changed. Use HWND_DESKTOP for the entire screen.

hrgn (HRGN) - Input

Handle of the region to be added to the update region. Use NULLHANDLE to invalidate the entire window.

fIncludeChildren (BOOL) - Input

Invalidation scope indicator.

TRUE: Include the descendants of hwnd in the invalid region.
FALSE: Include descendants only if the parent window does not have the WS_CLIPCHILDREN style.

rc (BOOL) - Returns: TRUE for successful completion, FALSE for error.

Returns

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion
FALSE: Error occurred.

Remarks

The update region is a portion of a window that needs to be redrawn because it is considered "invalid" or visually incorrect.

If the window has the CS_SYNCPAINT style, it is redrawn during this function call, and the update region should be NULL upon return.

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

Do not call this function in response to a WM_PAINT message for windows with the CS_SYNCPAINT style. This would lead to an infinite loop of invalidation and paint messages.

Errors

Possible returns from WinGetLastError:

PMERR_INVALID_HWND (0x1001) - An invalid window handle was specified.
PMERR_HRGN_BUSY (0x2034) - An internal region busy error occurred due to concurrent access from different threads.
PMERR_INVALID_FLAG (0x1019) - An invalid flag was set for a parameter. Use defined constants.

Example Code

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

HWND    hwnd;       /* window handle                    */

WinInvalidateRegion(hwnd, NULLHANDLE, 0);

This example invalidates the entire window. To invalidate a subregion, replace NULLHANDLE with a valid region handle.

Related Messages

WM_PAINT

Related Functions