Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function loads an icon, 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.

lpszName

[in] Pointer to a null-terminated string that contains the name of the image resource in the hinstmodule that identifies the image to load.

uType

[in] Specifies the type of image to be loaded. This parameter can be one of the following values.

Value Description

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, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width. If uTypeis IMAGE_BITMAP, this parameter must be zero.

cyDesired

[in] Specifies the height, in pixels, of the icon or cursor. If this parameter is zero, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height. If uTypeis IMAGE_BITMAP, this parameter must be zero.

fuLoad

[in] Set to zero.

Windows Embedded CE behaves as though the LR_DEFAULTCOLOR and LR_DEFAULTSIZE values are set. LR_DEFAULTCOLOR means not monochrome. LR_DEFAULTSIZE means that the system uses the width or height specified by the system metric values for cursors or icons if the cxDesiredor cyDesiredvalues are set to zero. If the resource contains multiple images, the function uses the size of the first image.

Return Value

The handle of the newly loaded image indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

When you are finished using a bitmap, cursor, or icon you loaded, 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 working set of the process.

If you are targeting a platform that does not support mouse cursors, you cannot specify the SM_CXCURSOR and SM_CYCURSOR values in the cxDesiredand cyDesiredparameters, and you cannot specify IMAGE_CURSOR for the uTypeparameter.

You typically use LoadImageto load icons, cursors, and bitmaps from a standard resource (.rc) file. It is also possible, however, to store these resources in a common DLL file. To obtain a handle to a resource stored in a DLL, call the LoadLibraryExfunction with the dwFlagsparameter set to LOAD_LIBRARY_AS_DATAFILE. You can then pass the resulting handle to LoadImage.

Bitmaps returned from LoadImageare not writable. All calls to write to a bitmap returned by the LoadImagefunction will fail.

Requirements

Header winuser.h
Library Loadimg.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also