LoadCursorA function (winuser.h)

Article
06/20/2023

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

Share via