WinCreateCursor

This function creates or changes a cursor for a specified window.

Syntax

WinCreateCursor(hwnd, lx, ly, lcx, lcy, ulrgf, prclClip)

Parameters

hwnd (HWND) - input

Handle of window in which cursor is displayed.

This must be the handle of a window for which the application can receive input.

lx (LONG) - input

x-position of cursor.

ly (LONG) - input

y-position of cursor.

lcx (LONG) - input

x-size of cursor.

If 0, the system nominal border width (SV_CXBORDER) is used.

lcy (LONG) - input

y-size of cursor.

If 0, the system nominal border height (SV_CYBORDER) is used.

ulrgf (ULONG) - input

Controls the appearance of the cursor.

CURSOR_SOLID - The cursor is solid.

CURSOR_HALFTONE - The cursor is halftone.

CURSOR_FRAME - The cursor is a rectangular frame.

CURSOR_FLASH - The cursor flashes.

CURSOR_SETPOS - Set a new cursor position. lcx and lcy are ignored. Used when a cursor has already been created. In this case, all other appearance flags are ignored.

prclClip (PRECTL) - input

Cursor rectangle.

A rectangle within which the cursor is visible. If the cursor goes outside this rectangle, it is clipped away and is invisible.

The rectangle is specified in window coordinates.

If prclClip is NULL, the drawing of the cursor is clipped to the window rectangle of hwnd.

Note: The cursor is always clipped to the window rectangle, even if part of prclClip is outside it.

The value of each field in this structure must be in the range -32 768 through 32 767. The data type WRECT can also be used, if supported by the language.

Returns

rc (BOOL) - returns

Success indicator.

TRUE - Successful completion

FALSE - Error occurred.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001)

An invalid window handle was specified.

PMERR_INVALID_FLAG (0x1019)

An invalid bit was set for a parameter. Use constants defined by PM for options, and do not set any reserved bits.

Remarks

The cursor is used to indicate the position of text input. It is initially hidden and must be made visible using the WinShowCursor function.

This function destroys any existing cursor, as it is confusing to the user if two cursors are visible at any one time. An application creates and displays a cursor when it has the input focus, or is the active window. Creating a cursor at any other time can stop the cursor from flashing in another window. Similarly, when the application loses the input focus or becomes inactive, it destroys its cursor using the WinDestroyCursor function.

The cursor width is generally specified as 0 (nominal border width is used). This is preferable to a value of 1, for example, as such a fine width is almost invisible on a high-resolution device.

When ulrgf is set to CURSOR_FLASH, TID_CURSOR timer is created.

Example Code

This example creates a cursor of default height and width at (0,200) which will be visible within the entirety of the input window.

#define INCL_WINCURSORS    /* Window Cursor Functions */
#include <os2.h>

BOOL    fSuccess;      /* success indicator           */
HWND    hwnd;          /* cursor display window       */
LONG    lx = 0;        /* cursor x position           */
LONG    ly = 200;      /* cursor y position           */
ULONG   ulrgf;         /* cursor appearance           */

fSuccess = WinCreateCursor(hwnd, lx, ly, 0, 0, ulrgf, NULL);

Related Functions

• WinDestroyCursor
• WinQueryCursorInfo
• WinShowCursor