LoadImageA 函数 (winuser.h)

项目
02/01/2024

加载图标、光标、动画光标或位图。

语法

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

参数

[in, optional] hInst

类型： HINSTANCE

包含要加载的图像的 DLL 或可执行文件 (.exe) 的模块的句柄。有关详细信息，请参阅 GetModuleHandle。请注意，从 32 位 Windows 开始，实例句柄 (HINSTANCE) ，例如由 WinMain 的系统函数调用公开的应用程序实例句柄，而模块句柄 (HMODULE) 也是如此。

若要 (图标、光标或位图文件) 加载预定义图像或独立资源，请将此参数设置为 NULL。

[in] name

类型： LPCTSTR

要加载的图像。

如果 hInst 参数为非 NULL 且 fuLoad 参数省略 LR_LOADFROMFILE， 则 name 指定 hInst 模块中的图像资源。

如果要按名称从模块加载图像资源， 则 name 参数是指向包含映像资源名称的以 null 结尾的字符串的指针。

如果要从模块按序号加载图像资源，请使用 MAKEINTRESOURCE 宏将图像序号转换为可传递给 LoadImage 函数的形式。

如果 hInst 参数为 NULL 且 fuLoad 参数省略 LR_LOADFROMFILE 值并包含 LR_SHARED，则名称将指定要加载的预定义图像。

预定义的图像标识符在中 Winuser.h 定义，并具有以下前缀：

前缀	含义
OBM_	OEM 位图。使用 MAKEINTRESOURCE 宏传递这些。
OIC_	OEM 图标。使用 MAKEINTRESOURCE 宏传递这些。
Ocr_	OEM 游标。使用 MAKEINTRESOURCE 宏传递这些。
IDI_	标准图标
Idc_	标准游标

若要将 OEM 图像标识符常量传递给 LoadImage 函数，请使用 MAKEINTRESOURCE 宏。例如，若要加载OCR_NORMAL游标，请将作为 name 参数传递MAKEINTRESOURCE(OCR_NORMAL)，将 NULL 作为 hInst 参数传递，并将LR_SHARED作为标志之一传递给 fuLoad 参数。

如果 hInst 参数为 NULL 且 fuLoad 参数包含LR_LOADFROMFILE值，则 name 是包含独立资源 (图标、光标或位图文件) 的文件的名称，例如。 c:\myicon.ico

有关详细信息，请参阅下面的“备注”部分。

[in] type

类型： UINT

要加载的图像的类型。

此参数可能是以下值之一：

值	含义
IMAGE_BITMAP	加载位图。
IMAGE_CURSOR	加载游标。
IMAGE_ICON	加载图标。

[in] cx

类型： int

图标或光标的宽度（以像素为单位）。如果此参数为零且 fuLoad 参数 为LR_DEFAULTSIZE，则函数使用 SM_CXICON 或 SM_CXCURSOR 系统指标值来设置宽度。如果此参数为零且未使用 LR_DEFAULTSIZE ，则函数使用实际资源宽度。

[in] cy

类型： int

图标或光标的高度（以像素为单位）。如果此参数为零且 fuLoad 参数 为LR_DEFAULTSIZE，则函数使用 SM_CYICON 或 SM_CYCURSOR 系统指标值来设置高度。如果此参数为零且未使用 LR_DEFAULTSIZE ，则函数使用实际资源高度。

[in] fuLoad

类型： UINT

此参数可使用以下一个或多个值。

值	含义
LR_CREATEDIBSECTION 0x00002000	当 uType 参数指定 IMAGE_BITMAP时，会导致函数返回 DIB 节位图而不是兼容的位图。此标志可用于加载位图而不将其映射到显示设备的颜色。
LR_DEFAULTCOLOR 0x00000000	默认标志;它不执行任何工作。它的意思是“不 LR_MONOCHROME”。
LR_DEFAULTSIZE 0x00000040	如果 cxDesired 或 cyDesired 值设置为零，则使用游标或图标的系统指标值指定的宽度或高度。如果未指定此标志，并且 cxDesired 和 cyDesired 设置为零，则函数将使用实际资源大小。如果资源包含多个图像，则函数使用第一个图像的大小。
LR_LOADFROMFILE 0x00000010	从名称 (图标、光标或位图文件指定的文件) 加载独立图像。
LR_LOADMAP3DCOLORS 0x00001000	在颜色表中搜索图像，并将以下灰色底纹替换为相应的三维颜色。 Dk 灰色，RGB (128,128,128) 与 COLOR_3DSHADOW 灰色，RGB (192,192,192) ，带 COLOR_3DFACE Lt Gray，RGB (223,223,223) 与 COLOR_3DLIGHT 如果要加载颜色深度大于 8bpp 的位图，请不要使用此选项。
LR_LOADTRANSPARENT 0x00000020	检索图像中第一个像素的颜色值，并将颜色表中的相应条目替换为默认窗口颜色 (COLOR_WINDOW) 。图像中使用该条目的所有像素都将成为默认的窗口颜色。此值仅适用于具有相应颜色表的图像。如果要加载颜色深度大于 8bpp 的位图，请不要使用此选项。如果 fuLoad 同时包含 LR_LOADTRANSPARENT 值和 LR_LOADMAP3DCOLORS 值， LR_LOADTRANSPARENT 优先。但是，颜色表条目将替换为 COLOR_3DFACE 而不是 COLOR_WINDOW。
LR_MONOCHROME 0x00000001	加载黑白图像。
LR_SHARED 0x00008000	如果多次加载映像，则共享映像句柄。如果未设置 LR_SHARED ，则对同一资源的第二次 LoadImage 调用将再次加载映像并返回不同的句柄。使用此标志时，系统会在不再需要资源时销毁该资源。对于具有非标准大小、加载后可能会更改或从文件加载的图像，请勿使用 LR_SHARED 。加载系统图标或光标时，必须使用 LR_SHARED 否则函数将无法加载资源。无论请求的大小如何，此函数都会查找缓存中具有请求的资源名称的第一个映像。
LR_VGACOLOR 0x00000080	使用真正的 VGA 颜色。

返回值

类型： HANDLE

如果函数成功，则返回值是新加载的图像的句柄。

如果函数失败，则返回值为 NULL。要获得更多的错误信息，请调用 GetLastError。

注解

如果 IS_INTRESOURCE (名称) 为 TRUE，则 name 指定给定资源的整数标识符。否则，它是指向以 null 结尾的字符串的指针。如果字符串的第一个字符是井号 (#) ，则其余字符表示一个指定资源的整数标识符的十进制数。例如，字符串“#258”表示标识符 258。

使用完未指定 LR_SHARED 标志的情况下加载的位图、光标或图标后，可以通过调用下表中的函数之一释放其关联的内存。

资源	Release 函数
Bitmap	DeleteObject
游标	DestroyCursor
图标	DestroyIcon

当创建这些资源的进程终止时，系统会自动删除这些资源;但是，调用相应的函数可节省内存并减小进程的工作集的大小。

示例

有关示例，请参阅使用窗口类。

注意

winuser.h 标头将 LoadImage 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll
API 集	windows 8 中引入的 ext-ms-win-ntuser-gui-l1-1-0 ()