LoadImageA 函数（winuser.h）

项目
11/20/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，则名称指定 hInst 模块中的图像资源。

如果要从模块中按名称加载映像资源，则名称参数是指向包含图像资源名称的以 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 游标，请将 MAKEINTRESOURCE(OCR_NORMAL) 作为名称参数传递，NULL 作为 hInst 参数传递，并将 LR_SHARED 作为标志之一传递给 fuLoad 参数。

如果 hInst 参数 NULL，并且 fuLoad 参数包含 LR_LOADFROMFILE 值，则名称是包含独立资源（图标、游标或位图文件）的文件的名称，例如 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 Gray，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，则名称指定给定资源的整数标识符。否则，它是指向以 null 结尾的字符串的指针。如果字符串的第一个字符是磅号（#），则剩余字符表示一个指定资源的整数标识符的十进制数。例如，字符串“#258”表示标识符 258。

使用完未指定 LR_SHARED 标志的位图、光标或图标后，可以通过调用下表中的某个函数来释放其关联内存。

资源	Release 函数
位图	DeleteObject
光标	DestroyCursor
图标	DestroyIcon

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

例子

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

注意

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

要求

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