LoadImageA function (winuser.h)

Loads an icon, cursor, animated cursor, or bitmap.

Syntax

HANDLE LoadImageA(
  [in, optional] HINSTANCE hInst,
  [in]           LPCSTR    name,
  [in]           UINT      type,
  [in]           int       cx,
  [in]           int       cy,
  [in]           UINT      fuLoad
);

Parameters

[in, optional] hInst

Type: HINSTANCE

A handle to the module of either a DLL or executable (.exe) that contains the image to be loaded. For more information, see GetModuleHandle. Note that as of 32-bit Windows, an instance handle (HINSTANCE), such as the application instance handle exposed by system function call of WinMain, and a module handle (HMODULE) are the same thing.

To load a predefined image or a standalone resource (icon, cursor, or bitmap file), set this parameter to NULL.

[in] name

Type: LPCTSTR

The image to be loaded.

If the hInst parameter is non-NULL and the fuLoad parameter omits LR_LOADFROMFILE, name specifies the image resource in the hInst module.

If the image resource is to be loaded by name from the module, the name parameter is a pointer to a null-terminated string that contains the name of the image resource.

If the image resource is to be loaded by ordinal from the module, use the MAKEINTRESOURCE macro to convert the image ordinal into a form that can be passed to the LoadImage function.

If the hInst parameter is NULL and the fuLoad parameter omits the LR_LOADFROMFILE value and includes the LR_SHARED, the name specifies the predefined image to load.

The predefined image identifiers are defined in Winuser.h and have the following prefixes:

To pass OEM image identifiers constants to the LoadImage function, use the MAKEINTRESOURCE macro. For example, to load the OCR_NORMAL cursor, pass MAKEINTRESOURCE(OCR_NORMAL) as the name parameter, NULL as the hInst parameter, and LR_SHARED as one of the flags to the fuLoad parameter.

If the hInst parameter is NULL and the fuLoad parameter includes the LR_LOADFROMFILE value, name is the name of the file that contains the standalone resource (icon, cursor, or bitmap file), - for example, c:\myicon.ico.

For more information, see the Remarks section below.

[in] type

Type: UINT

The type of image to be loaded.

This parameter can be one of the following values:

[in] cx

Type: int

The width, in pixels, of the icon or cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource width.

[in] cy

Type: int

The height, in pixels, of the icon or cursor. If this parameter is zero and the fuLoad parameter is LR_DEFAULTSIZE, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height. If this parameter is zero and LR_DEFAULTSIZE is not used, the function uses the actual resource height.

[in] fuLoad

Type: UINT

This parameter can be one or more of the following values.

Return value

Type: HANDLE

If the function succeeds, the return value is the handle of the newly loaded image.

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

Remarks

If IS_INTRESOURCE(name) is TRUE, then name specifies the integer identifier of the given resource. Otherwise, it is a pointer to a null-terminated string. If the first character of the string is a pound sign (#), then the remaining characters represent a decimal number that specifies the integer identifier of the resource. For example, the string "#258" represents the identifier 258.

When you are finished using a bitmap, cursor, or icon you loaded without specifying the LR_SHARED flag, you can release its associated memory by calling one of the functions in the following table.

The system automatically deletes these resources when the process that created them terminates; however, calling the appropriate function saves memory and decreases the size of the process's working set.

Examples

For an example, see Using Window Classes.

Requirements

See also

Conceptual

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

Other Resources

Reference

Resources