LoadImage
[Now
Supported on Windows NT]
The LoadImage
function loads an icon, cursor, or bitmap.
HANDLE LoadImage(
|
HINSTANCE hinst, |
// handle
of the instance that contains 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
Identifies an
instance of the module that contains the image to be loaded. To load an OEM
image, set this parameter to zero.
lpszName
Identifies
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 |
Windows 95:
If the fuLoad parameter includes the LR_LOADFROMFILE value, lpszName
is the name of the file that contains the image.
Windows NT:
LR_LOADFROMFILE is not supported.
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. |
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.
See Also