Поделиться через


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

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

Синтаксис

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 указывает ресурс image в модуле hInst .

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

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

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

Предопределенные идентификаторы образов определяются в 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.

Комментарии

Если IS_INTRESOURCE(name) имеет значение TRUE, то name указывает целочисленный идентификатор заданного ресурса. В противном случае это указатель на строку, завершаемую null. Если первым символом строки является знак фунта (#), остальные символы представляют десятичное число, указывающее целочисленный идентификатор ресурса. Например, строка "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)

См. также раздел

Основные понятия

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

Другие ресурсы

Справочные материалы

Ресурсы