WinLockVisRegions

This function locks or unlocks the visible regions of all the windows on the screen, preventing any of the visible regions from changing.

Syntax

WinLockVisRegions(hwndDesktop, fLock)

Parameters

hwndDesktop (HWND) - Input: Desktop-window handle or HWND_DESKTOP.
fLock (BOOL) - Input: Indicates whether to lock or unlock visible regions. TRUE to lock, FALSE to unlock.

Returns

rc (BOOL) - returns

Success indicator.

TRUE: Successful.
FALSE: An error occurred.

Remarks

This function is useful for threads that need to prevent window visible regions from changing during screen operations like copying screen pixels to a memory bitmap.

While visible regions are locked, any other thread attempting to alter them will be blocked. During this lock, no messages should be sent, and no functions that send messages should be called.

Only one thread can lock the visible regions at a time. The same thread can call WinLockVisRegions multiple times; the system maintains a lock count. The count increments on each locking call and decrements on each unlocking call. The visible regions are unlocked only when the count reaches zero.

Note: Locking the visible regions does not prevent painting of a window by another process.

Errors

Possible returns from WinGetLastError:

PMERR_INVALID_HWND (0x1001) - An invalid window handle was specified.

Example Code

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

BOOL    fSuccess;           /* success indicator              */

/* lock visible regions */
fSuccess = WinLockVisRegions(HWND_DESKTOP, TRUE);

/*
 ...
 ... executing screen operation
 ...
 */

/* unlock visible regions */
fSuccess = WinLockVisRegions(HWND_DESKTOP, FALSE);

This example locks the visible regions before a screen operation and unlocks them afterward.

Related Functions