WinShowPointer: Difference between revisions

Latest revision as of 16:37, 15 May 2025

This function adjusts the pointer display level to show or hide a pointer.

Syntax

WinShowPointer(hwndDeskTop, fShow);

Parameters

hwndDeskTop (HWND) - input: Desktop-window handle.; HWND_DESKTOP: The desktop-window handle.; Other: The specified desktop-window handle.

fShow (BOOL) - input: Level-update indicator.; TRUE: Decrement pointer display level by one. (The pointer level is not decremented to a negative value.); FALSE: Increment pointer display level by one.

Returns

rc (BOOL) - returns: Display-level-updated indicator.; TRUE: Pointer display level successfully updated.; FALSE: Pointer display level not successfully updated.

Errors

Possible returns from WinGetLastError

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

Remarks

The pointer display level determines whether the pointer is shown. If it is zero, the pointer is visible, but if it is greater than zero, the pointer is not visible. The initial setting of the pointer display level is dependent on the capabilities of the device. If a pointing device exists, the initial setting of the pointer display level is zero, otherwise it is one. The existing pointer display level can be obtained by using the WinQuerySysValue function with iSysValue set to SV_POINTERLEVEL.

Example Code

Declaration:

#define INCL_WINPOINTERS /* Or use INCL_WIN, INCL_PM */
#include <os2.h>

HWND     hwndDeskTop;  /* Desktop-window handle. */
BOOL     fShow;        /* Level-update indicator. */
BOOL     rc;           /* Display-level-updated indicator. */

rc = WinShowPointer(hwndDeskTop, fShow);

This example obtains the pointer handle from the desktop window handle and hides the pointer.

#define INCL_WINPOINTERS
#define INCL_WINDESKTOP
#include <os2.h>

HPOINTER hpointer;
HWND hwnd;

hpointer = WinQueryPointer(HWND_DESKTOP);
WinShowPointer(hwnd, FALSE);

Related Functions

@@ Line 1: / Line 1: @@
-; WinShowPointer(desktopHndl, flagShow) : Show or hide the pointer.
+This function adjusts the pointer display level to show or hide a pointer.
-=== Parameters ===
+== Syntax ==
-;desktopHndl - [[HWND]] - input : [[HWND_DESKTOP]] or any other value - the desktop handle.
-;flagShow - [[BOOL]] - input :
-* [[TRUE]] - decrement the hide count.
-* [[FALSE]] - increment the hide count.
-=== Returns ===
+ WinShowPointer(hwndDeskTop, fShow);
-Returns [[BOOL]]:
-* [[TRUE]] Successful
-* [[FALSE]] Unsuccessful
-[[WinGetLastError]] possible returns:
+== Parameters ==
-* [[PM Error Codes#PMERR_INVALID_HWND|PMERR_INVALID_HWND]]
+;''hwndDeskTop'' ([[HWND]]) - input: Desktop-window handle.
+:HWND_DESKTOP: The desktop-window handle.
+:Other: The specified desktop-window handle.
-=== Define (C/C++) ===
+;''fShow'' ([[BOOL]]) - input: Level-update indicator.
-INCL_WINPOINTERS or INCL_PM or INCL_WIN
+:TRUE: Decrement pointer display level by one. (The pointer level is not decremented to a negative value.)
+:FALSE: Increment pointer display level by one.
-=== Calling Convention ===
+== Returns ==
-[[Cdecl32]]
+;''rc'' ([[BOOL]]) - returns: Display-level-updated indicator.
+:TRUE: Pointer display level successfully updated.
+:FALSE: Pointer display level not successfully updated.
-=== Example Code ===
+== Errors ==
- HWND desktopHndl;
+Possible returns from [[WinGetLastError]]
- BOOL flagShow;
+;PMERR_INVALID_HWND (0x1001)
- BOOL rc;
+:An invalid window handle was specified.
- ...
- rc = WinShowPointer(desktopHndl, flagShow);
- ...
-=== Related Functions ===
+== Remarks ==
-*WinCreatePointer
+The pointer display level determines whether the pointer is shown. If it is zero, the pointer is visible, but if it is greater than zero, the pointer is not visible. The initial setting of the pointer display level is dependent on the capabilities of the device. If a pointing device exists, the initial setting of the pointer display level is zero, otherwise it is one. The existing pointer display level can be obtained by using the [[WinQuerySysValue]] function with ''iSysValue'' set to SV_POINTERLEVEL.
-*WinCreatePointerIndirect
-*WinDestroyPointer
-*WinDrawPointer
-*WinLoadPointer
-*WinQueryPointer
-*WinQueryPointerInfo
-*WinQueryPointerPos
-*WinQuerySysPointer
-*WinQuerySysPointerData
-*WinSetPointer
-*[[WinSetPointerPos]]
-*WinSetSysPointerData
-=== Notes ===
+== Example Code ==
-The pointer display level dictates the display of the pointer.  The hide count needs to be zero for the pointer to display.  At boot, if a pointing device exists, the pointer display level is set to zero; if a pointing device isn't detected, the pointer display level is set to one.  To get the value of the pointing device call the '''WinQuerySysValue''' specifying the SV_POINTERLEVEL option.
+Declaration:
+<PRE>
+#define INCL_WINPOINTERS /* Or use INCL_WIN, INCL_PM */
+#include <os2.h>
+HWND     hwndDeskTop;  /* Desktop-window handle. */
+BOOL     fShow;        /* Level-update indicator. */
+BOOL     rc;           /* Display-level-updated indicator. */
+rc = WinShowPointer(hwndDeskTop, fShow);
+</PRE>
+This example obtains the pointer handle from the desktop window handle and hides the pointer.
+<pre>
+#define INCL_WINPOINTERS
+#define INCL_WINDESKTOP
+#include <os2.h>
+HPOINTER hpointer;
+HWND hwnd;
+hpointer = WinQueryPointer(HWND_DESKTOP);
+WinShowPointer(hwnd, FALSE);
+</pre>
+== Related Functions ==
+* [[WinCreatePointer]]
+* [[WinCreatePointerIndirect]]
+* [[WinDestroyPointer]]
+* [[WinDrawPointer]]
+* [[WinLoadPointer]]
+* [[WinQueryPointer]]
+* [[WinQueryPointerInfo]]
+* [[WinQueryPointerPos]]
+* [[WinQuerySysPointer]]
+* [[WinQuerySysPointerData]]
+* [[WinSetPointer]]
+* [[WinSetPointerPos]]
+* [[WinSetSysPointerData]]
 [[Category:Win]]