WinSetCapture
This function captures all pointing device messages.
Syntax
WinSetCapture(hwndDesktop, hwnd)
Parameters
- hwndDesktop (HWND) - Input
- Desktop-window handle, or HWND_DESKTOP.
- hwnd (HWND) - Input
- Handle of the window that is to receive all pointing device messages. Use NULLHANDLE to release capture, or HWND_THREADCAPTURE to capture to the current thread.
- rc (BOOL) - Returns
- Success indicator. TRUE for success, FALSE for error.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion.
- FALSE
- Error occurred. If the pointing device has already been captured by another thread or window, the call fails.
Remarks
This function assigns the pointing device capture to hwnd.
With the pointing device capture set to a window, all pointing device input is directed to that window, regardless of whether the pointing device pointer is over that window.
When this function (hwndDesktop, NULLHANDLE) is called to release the pointing device capture, a WM_MOUSEMOVE message is posted regardless of whether the pointing device pointer has actually moved. This ensures that the window below the pointing device, at that time, is able to change features, such as the shape of the pointing device pointer.
If this function (hwndDesktop, HWND_THREADCAPTURE) is called, the pointing device is captured to the current thread. Pointing device QMSGs processed in this manner have NULLHANDLE window handles, and the pointing device coordinates are relative to the screen.
This function returns an unlocked window handle.
It must only be called while processing pointing device or keyboard input. A message box or dialog box must not be created while the pointing device is captured.
Errors
Possible returns from WinGetLastError:
- PMERR_INVALID_HWND (0x1001) - An invalid window handle was specified.
Example Code
#define INCL_WININPUT /* Or use INCL_WIN, INCL_PM, */ #include <os2.h> HWND hwndDesktop; /* Desktop-window handle, or HWND_DESKTOP. */ HWND hwnd; /* Handle of the window that is to receive all pointing device messages. */ BOOL rc; /* Success indicator. */ rc = WinSetCapture(hwndDesktop, hwnd);
This example uses the WinSetCapture call to capture the mouse until the button is released. The user has selected a specific object with mouse button 2.
#define INCL_WININPUT
#include <OS2.H>
HWND hwnd;
USHORT msg;
WinSetCapture(hwnd,HWND_DESKTOP);
switch (msg) {
case WM_BUTTON2DOWN:
/*******************************************************************/
/* An object has been picked. Set the mouse capture until */
/* a 'button up' message is detected. */
/*******************************************************************/
if (hwnd != WinQueryFocus(HWND_DESKTOP)){
WinSetFocus(HWND_DESKTOP, hwnd);
}
WinSetCapture(HWND_DESKTOP, hwnd);
break;
}
Related Messages
Related Functions
- WinQueryCapture
- WinSetCapture