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 ==
+This function adjusts the pointer display level to show or hide a pointer.
-; WinShowPointer(desktopHndl, flagShow) : Show or hide the pointer.
-=== Parameters ===
+== Syntax ==
-; desktopHndl - [[OS2_API:DataType:HWND|HWND]] - input : [[OS2_API:Constant:HWND_DESKTOP|HWND_DESKTOP]] or any other value - the desktop handle.
-; flagShow - [[OS2_API:DataType:BOOL|BOOL]] - input :
-* [[OS2 API:Constant:TRUE|TRUE]] - decrement the hide count.
-* [[OS2 API:Constant:FALSE|FALSE]] - increment the hide count.
-=== Constants ===
+ WinShowPointer(hwndDeskTop, fShow);
-=== Returns ===
+== Parameters ==
-Returns [[OS2_API:DataType:BOOL|BOOL]]:
+;''hwndDeskTop'' ([[HWND]]) - input: Desktop-window handle.
-* [[OS2 API:Constant:TRUE|TRUE]] Successful
+:HWND_DESKTOP: The desktop-window handle.
-* [[OS2 API:Constant:FALSE|FALSE]] Unsuccessful
+:Other: The specified desktop-window handle.
-[[OS2 API:WinGetLastError|WinGetLastError]] possible returns:
+;''fShow'' ([[BOOL]]) - input: Level-update indicator.
-* [[OS2 API:PMI:error#PMERR_INVALID_HWND|PMERR_INVALID_HWND]]
+:TRUE: Decrement pointer display level by one. (The pointer level is not decremented to a negative value.)
+:FALSE: Increment pointer display level by one.
-=== Module ===
+== Returns ==
+;''rc'' ([[BOOL]]) - returns: Display-level-updated indicator.
+:TRUE: Pointer display level successfully updated.
+:FALSE: Pointer display level not successfully updated.
-=== Define (C/C++) ===
+== Errors ==
-INCL_WINPOINTERS or INCL_PM or INCL_WIN
+Possible returns from [[WinGetLastError]]
+;PMERR_INVALID_HWND (0x1001)
+:An invalid window handle was specified.
-=== Export name/Ordinal ===
+== 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.
-=== Calling conversion ===
+== Example Code ==
-[[Cdecl32]]
+Declaration:
+<PRE>
+#define INCL_WINPOINTERS /* Or use INCL_WIN, INCL_PM */
+#include <os2.h>
-=== Example Code ===
+HWND     hwndDeskTop;  /* Desktop-window handle. */
- [[OS2 API:DataType:HWND|HWND]] desktopHndl;
+BOOL     fShow;        /* Level-update indicator. */
-  [[OS2 API:DataType:BOOL|BOOL]] flagShow;
+BOOL     rc;           /* Display-level-updated indicator. */
- [[OS2 API:DataType:BOOL|BOOL]] rc;
- ...
- rc = WinShowPointer(desktopHndl, flagShow);
- ...
-=== Related Functions ===
+rc = WinShowPointer(hwndDeskTop, fShow);
-[[OS2 API:WinCreatePointer|WinCreatePointer]] [[OS2_API:WinCreatePointerIndirect|WinCreatePointerIndirect]] [[OS2_API:WinDestroyPointer|WinDestroyPointer]]
+</PRE>
-[[OS2_API:WinDrawPointer|WinDrawPointer]]
+This example obtains the pointer handle from the desktop window handle and hides the pointer.
-[[OS2_API:WinLoadPointer|WinLoadPointer]]
+<pre>
-[[OS2_API:WinQueryPointer|WinQueryPointer]]
+#define INCL_WINPOINTERS
-[[OS2_API:WinQueryPointerInfo|WinQueryPointerInfo]]
+#define INCL_WINDESKTOP
-[[OS2_API:WinQueryPointerPos|WinQueryPointerPos]]
+#include <os2.h>
-[[OS2_API:WinQuerySysPointer|WinQuerySysPointer]]
-[[OS2_API:WinQuerySysPointerData|WinQuerySysPointerData]]
-[[OS2_API:WinSetPointer|WinSetPointer]]
-[[OS2_API:WinSetPointerPos|WinSetPointerPos]]
-[[OS2_API:WinSetSysPointerData|WinSetSysPointerData]]
-=== Notes ===
+HPOINTER hpointer;
-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 [[OS2_API:WinQuerySysValue|WinQuerySysValue]] specifying the [[OS2_API:Constant:SV#SV_POINTERLEVEL|SV_POINTERLEVEL]] option.
+HWND hwnd;
-=== OS Version Introduced ===
+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]]