LoadCursorA function (winuser.h)

Loads the specified cursor resource from the executable (.EXE) file associated with an application instance.

Note

This function has been superseded by the LoadImage function (with LR_DEFAULTSIZE and LR_SHARED flags set).

Syntax

HCURSOR LoadCursorA(
  [in, optional] HINSTANCE hInstance,
  [in]           LPCSTR    lpCursorName
);

Parameters

[in, optional] hInstance

Type: HINSTANCE

A handle to the module of either a DLL or executable (.exe) file that contains the cursor to be loaded. For more information, see GetModuleHandle.

To load a predefined system cursor, set this parameter to NULL.

[in] lpCursorName

Type: LPCTSTR

If hInstance is non-NULL, lpCursorName specifies the cursor resource either by name or ordinal. This ordinal must be packaged by using the MAKEINTRESOURCE macro.

If hInstance is NULL, lpCursorName specifies the identifier (beginning with the IDC_ prefix) of a predefined system cursor to load.

Return value

Type: HCURSOR

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

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

Remarks

The LoadCursor function loads the cursor resource only if it has not been loaded; otherwise, it retrieves the handle to the existing resource. This function returns a valid cursor handle only if the lpCursorName parameter is a pointer to a cursor resource. If lpCursorName is a pointer to any type of resource other than a cursor (such as an icon), the return value is not NULL, even though it is not a valid cursor handle.

The LoadCursor function searches the cursor resource most appropriate for the cursor for the current display device. The cursor resource can be a color or monochrome bitmap.

DPI Virtualization

This API does not participate in DPI virtualization. The output returned is not affected by the DPI of the calling thread.

Examples

For an example, see Creating a Cursor.

Note

The winuser.h header defines LoadCursor as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

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

Conceptual

Cursors

LoadImage

MAKEINTRESOURCE

IS_INTRESOURCE

Reference

SetCursor

SetCursorPos

ShowCursor