Функция 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, имя указывает ресурс изображения в модуле hInst .

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

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

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

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

Prefix Значение
OBM_ Точечные изображения OEM. Используйте макрос MAKEINTRESOURCE для их передачи.
ОИК_ Значки OEM. Используйте макрос 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. Если первым символом строки является знак фунта (#), остальные символы представляют десятичное число, указывающее целочисленный идентификатор ресурса. Например, строка "#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

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

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

Ресурсы