Функция LoadImageW (winuser.h)

Статья
07/21/2023

Загружает значок, курсор, анимированный курсор или точечный рисунок.

Синтаксис

HANDLE LoadImageW(
  [in, optional] HINSTANCE hInst,
  [in]           LPCWSTR   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 указывает ресурс image в модуле hInst .

Если ресурс изображения должен быть загружен из модуля по имени, параметр name является указателем на строку, завершающуюся нулевым значением, которая содержит имя ресурса образа.

Если ресурс изображения должен быть загружен по порядковой номеру из модуля, используйте макрос MAKEINTRESOURCE для преобразования порядкового номера изображения в форму, которую можно передать в функцию LoadImage .

Если параметр hInst имеет значение NULL , а параметр fuLoad пропускает значение LR_LOADFROMFILE , имя указывает предопределенное изображение для загрузки.

Предопределенные идентификаторы образов определяются в Winuser.h и имеют следующие префиксы:

Prefix	Значение
OBM_	Точечные изображения oem. Используйте макрос MAKEINTRESOURCE для их передачи.
ОИК_	Значки изготовителя оборудования. Используйте макрос MAKEINTRESOURCE для их передачи.
OCR_	Курсоры OEM. Используйте макрос MAKEINTRESOURCE для их передачи.
IDI_	Стандартные значки
IDC_	Стандартные курсоры

Чтобы передать константы идентификаторов образов OEM в функцию LoadImage , используйте макрос MAKEINTRESOURCE . Например, чтобы загрузить курсор OCR_NORMAL , передайте MAKEINTRESOURCE(OCR_NORMAL) в качестве параметра name , 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

Ширина значка или курсора (в пикселях). Если этот параметр равен нулю и параметр fuLoadLR_DEFAULTSIZE, функция использует значение системной метрики SM_CXICON или SM_CXCURSOR для задания ширины. Если этот параметр равен нулю и LR_DEFAULTSIZE не используется, функция использует фактическую ширину ресурса.

[in] cy

Тип: int

Высота значка или курсора в пикселях. Если этот параметр равен нулю и параметр fuLoadLR_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 задано значение 0, функция использует фактический размер ресурса. Если ресурс содержит несколько изображений, функция использует размер первого изображения.
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 Не используйте этот параметр, если загружается растровое изображение с глубиной цвета больше 8 бит/с.
LR_LOADTRANSPARENT 0x00000020	Извлекает значение цвета первого пикселя на изображении и заменяет соответствующую запись в таблице цветов цветом окна по умолчанию (COLOR_WINDOW). Все пиксели на изображении, в которые используется эта запись, становятся цветом окна по умолчанию. Это значение применяется только к изображениям с соответствующими таблицами цветов. Не используйте этот параметр, если загружается растровое изображение с глубиной цвета больше 8 бит/с. Если 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.

Если первым символом строки является знак фунта (#), остальные символы представляют десятичное число, указывающее целочисленный идентификатор ресурса. Например, строка "No 258" представляет идентификатор 258.

После завершения работы с загруженным растровым рисунком, курсором или значком без указания флага LR_SHARED можно освободить связанную память, вызвав одну из функций в следующей таблице.

Ресурс	Функция release
Bitmap	DeleteObject
Курсор	DestroyCursor
Значок	DestroyIcon

Система автоматически удаляет эти ресурсы, когда процесс, создавший их, завершается; однако вызов соответствующей функции экономит память и уменьшает размер рабочего набора процесса.

Примеры

Пример см. в разделе Использование оконных классов.

Примечание

Заголовок winuser.h определяет LoadImage как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-gui-l1-1-0 (представлено в Windows 8)