CreateCursor function (winuser.h)

Creates a monochrome cursor having the specified size, bit patterns, and hot spot.

To create a colored cursor at run time you can use the CreateIconIndirect function, which creates a cursor based on the content of an ICONINFO structure.

Syntax

HCURSOR CreateCursor(
  [in, optional] HINSTANCE  hInst,
  [in]           int        xHotSpot,
  [in]           int        yHotSpot,
  [in]           int        nWidth,
  [in]           int        nHeight,
  [in]           const VOID *pvANDPlane,
  [in]           const VOID *pvXORPlane
);

Parameters

[in, optional] hInst

Type: HINSTANCE

A handle to the current instance of the application creating the cursor.

[in] xHotSpot

Type: int

The horizontal position of the cursor's hot spot.

[in] yHotSpot

Type: int

The vertical position of the cursor's hot spot.

[in] nWidth

Type: int

The width of the cursor, in pixels.

[in] nHeight

Type: int

The height of the cursor, in pixels.

[in] pvANDPlane

Type: const VOID*

An array of bytes that contains the bit values for the AND mask of the cursor, as in a monochrome bitmap. See remarks.

[in] pvXORPlane

Type: const VOID*

An array of bytes that contains the bit values for the XOR mask of the cursor, as in a monochrome bitmap. See remarks.

Return value

Type: HCURSOR

If the function succeeds, the return value is a handle to the cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

To determine the nominal size of a cursor, use the GetSystemMetrics function, specifying the SM_CXCURSOR or SM_CYCURSOR value. Also, you can use the DPI-aware version of this API, see (GetSystemMetricsForDpi)(/windows/win32/api/winuser/nf-winuser-getsystemmetricsfordpi). For more information see High DPI Desktop Application Development on Windows.

For more information about pvANDPlane and pvXORPlane parameters see description of lpBits parameter of CreateBitmap function.

CreateCursor applies the following truth table to the AND and XOR bitmasks:

AND bitmask XOR bitmask Display
0 0 Black
0 1 White
1 0 Screen
1 1 Reverse screen

Before closing, an application must call the DestroyCursor function to free any system resources associated with the cursor.

DPI Virtualization

This API does not participate in DPI virtualization. The output returned is in terms of physical coordinates, and is not affected by the DPI of the calling thread. Note that the cursor created may still be scaled to match the DPI of any given window it is drawn into.

Examples

For an example, see Creating a Cursor.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winuser.h (include Windows.h)
Library User32.lib
DLL User32.dll

See also

CreateIcon

CreateIconIndirect

DestroyCursor

GetSystemMetrics

SetCursor

Cursors