LoadImage

The LoadImage function loads an icon, cursor, or bitmap.

HANDLE LoadImage(
  HINSTANCE hinst,   // handle of the instance containing the image
  LPCTSTR lpszName,  // name or identifier of image
  UINT uType,        // type of image
  int cxDesired,     // desired width
  int cyDesired,     // desired height
  UINT fuLoad        // load flags
);

Parameters

hinst

Handle to an instance of the module that contains the image to be loaded. To load an OEM image, set this parameter to zero.

lpszName

Handle to the image to load.

If the hinst parameter is non-NULL and the fuLoad parameter does not include LR_LOADFROMFILE, lpszName is a pointer to a null-terminated string that contains the name of the image resource in the hinst module.

If hinst is NULL and LR_LOADFROMFILE is not specified, the low-order word of this parameter must be the identifier of the OEM image to load. The OEM image identifiers are defined in WINUSER.H and have the following prefixes:

Prefix Meaning

OBM_ OEM bitmaps

OIC_ OEM icons

OCR_ OEM cursors

Prefix	Meaning
OBM_	OEM bitmaps
OIC_	OEM icons
OCR_	OEM cursors

If the fuLoad parameter includes the LR_LOADFROMFILE value, lpszName is the name of the file that contains the image.

uType

Specifies the type of image to be loaded. This parameter can be one of the following values:

Value	Meaning
IMAGE_BITMAP	Loads a bitmap.
IMAGE_CURSOR	Loads a cursor.
IMAGE_ICON	Loads an icon.

cxDesired

Specifies 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.

cyDesired

Specifies 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.

fuLoad

Specifies a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	The default flag; it does nothing. All it means is "not LR_MONOCHROME".
LR_CREATEDIBSECTION	When the uType parameter specifies IMAGE_BITMAP, causes the function to return a DIB section bitmap rather than a compatible bitmap. This flag is useful for loading a bitmap without mapping it to the colors of the display device.
LR_DEFAULTSIZE	Uses the width or height specified by the system metric values for cursors or icons, if the cxDesired or cyDesired values are set to zero. If this flag is not specified and cxDesired and cyDesired are set to zero, the function uses the actual resource size. If the resource contains multiple images, the function uses the size of the first image.
LR_LOADFROMFILE	Loads the image from the file specified by the lpszName parameter. If this flag is not specified, lpszName is the name of the resource.
LR_LOADMAP3DCOLORS	Searches the color table for the image and replaces the following shades of gray with the corresponding 3D color:

	Color	Replaced with
	Dk Gray, RGB(128,128,128)	COLOR_3DSHADOW
	Gray, RGB(192,192,192)	COLOR_3DFACE
	Lt Gray, RGB(223,223,223)	COLOR_3DLIGHT

LR_LOADTRANSPARENT	Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (COLOR_WINDOW). All pixels in the image that use that entry become the default window color. This value applies only to images that have corresponding color tables. If fuLoad includes both the LR_LOADTRANSPARENT and LR_LOADMAP3DCOLORS values, LRLOADTRANSPARENT takes precedence. However, the color table entry is replaced with COLOR_3DFACE rather than COLOR_WINDOW.
LR_MONOCHROME	Loads the image in black and white.
LR_SHARED	Shares the image handle if the image is loaded multiple times. If LR_SHARED is not set, a second call to LoadImage for the same resource will load the image again and return a different handle. Do not use LR_SHARED for images that have non-standard sizes, that may change after loading, or that are loaded from a file. Windows 95 and Windows 98: The function finds the first image with the requested resource name in the cache, regardless of the size requested.
LR_VGACOLOR	Uses true VGA colors.

Return Values

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

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

Resource	Release function
Bitmap	DeleteObject
Cursor	DestroyCursor
Icon	DestroyIcon

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.

Windows CE: The cxDesired and cyDesired parameters must be zero for IMAGE_BITMAP.

Windows CE does not support stretching and shrinking of icons.

The fuLoad parameter must be zero (==LR_DEFAULTCOLOR).

If you are targeting a platform that does not support mouse cursors, you cannot specify the SM_CXCURSOR and SM_CYCURSOR values in the cxDesired and cyDesired parameters, and you cannot specify IMAGE_CURSOR for the uType parameter.

If you are targeting a platform that supports mouse cursors, you can specify SM_CXCURSOR and SM_CYCURSOR in the cxDesired and cyDesired parameters, and IMAGE_CURSOR in the uType parameter.

QuickInfo

  Windows NT: Requires version 4.0 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Requires version 1.0 or later.
  Header: Declared in winuser.h.
  Import Library: Use user32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

LoadImage

Parameters

Return Values

Remarks

QuickInfo

See Also