SetCursor

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function establishes the cursor shape.

HCURSOR
SetCursor(
HCURSOR
hCursor
);

Parameters

hCursor

[in] Handle to the cursor. The cursor must have been created by the CreateCursoror loaded by the LoadCursoror LoadImagefunction. If this parameter is NULL, the cursor is removed from the screen.

The width and height of the cursor must be the values returned by the GetSystemMetricsfunction for SM_CXCURSOR and SM_CYCURSOR.

Return Values

The handle to the previous cursor, if there was one, indicates success. NULL indicates that there was no previous cursor.

Remarks

Use Cursor.lib when targeting a platform that does not support mouse cursors. The only cursor this component supports is the wait cursor. Use the following code to set the wait cursor:

SetCursor(LoadCursor(NULL, IDC_WAIT));

Use Mcursor.lib when targeting a platform that does support mouse cursors. This component does not support color cursors.

If SetCursoris called after CreateCursorcreates a zero dimension cursor, it still shows the old cursor, not the new cursor.

The cursor is set only if the new cursor is different from the previous cursor; otherwise, the function returns immediately.

The cursor is a shared resource. A window should set the cursor shape only when the cursor is in its client area or when the window is capturing mouse input. In systems without a mouse, the window should restore the previous cursor before the cursor leaves the client area or before it relinquishes control to another window.

If your application must set the cursor while it is in a window, make sure the class cursor for the specified window's class is set to NULL. If the class cursor is not NULL, the system restores the class cursor each time the mouse is moved.

The cursor is not shown on the screen if the internal cursor display count is less than zero. This occurs if the application uses the ShowCursorfunction to hide the cursor more times than to show the cursor.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	1.0 and later	Winuser.h		Cursor.lib, Mcursor.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.