The LoadImage function loads an icon, cursor, animated cursor, or bitmap.
Syntax
HANDLE LoadImage( HINSTANCE hinst,
LPCTSTR lpszName,
UINT uType,
int cxDesired,
int cyDesired,
UINT fuLoad
);
Parameters
hinst
[in] 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
[in]
Specifies the image to load. If the hinst parameter is non-NULL and the fuLoad parameter omits LR_LOADFROMFILE, lpszName specifies the image resource in the hinst module. If the image resource is to be loaded by name, the lpszName 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, 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, the lpszName specifies the OEM image to load. The OEM image identifiers are defined in Winuser.h and have the following prefixes.
OBM_ OEM bitmaps
OIC_ OEM icons
OCR_ OEM cursors
To pass these constants to the LoadImage function, use the MAKEINTRESOURCE macro. For example, to load the OCR_NORMAL cursor, pass MAKEINTRESOURCE(OCR_NORMAL) as the lpszName parameter and NULL as the hinst parameter.
If the fuLoad parameter includes the LR_LOADFROMFILE value, lpszName is the name of the file that contains the image.
uType
[in] Specifies the type of image to be loaded. This parameter can be one of the following values.
IMAGE_BITMAP
Loads a bitmap.
IMAGE_CURSOR
Loads a cursor.
IMAGE_ICON
Loads an icon.
cxDesired
[in] 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
[in] 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
[in] This parameter can be one or more of the following values.
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 3-D 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
Do not use this option if you are loading a bitmap with a color depth greater than 8bpp.
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.
Do not use this option if you are loading a bitmap with a color depth greater than 8bpp.
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.
When you use this flag, the system will destroy the resource when it is no longer needed.
Do not use LR_SHARED for images that have non-standard sizes, that may change after loading, or that are loaded from a file.
When loading a system icon or cursor, you must use LR_SHARED or the function will fail to load the resource.
Windows 95/98/Me: 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 Value
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 .
Remarks
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.
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 95/98/Me: LoadImageW is supported by the Microsoft® Layer for Unicode (MSLU). To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.
Example
For an example, see Using Window Classes.
Function Information
Header Declared in Winuser.h, include Windows.h
Import library User32.lib
Minimum operating systems Windows 95, Windows NT 4.0
Unicode Implemented as Unicode and ANSI versions on Windows NT, Windows 2000, Windows XP
