Функция 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
Этот параметр может иметь одно или несколько из следующих значений.
Возвращаемое значение
Тип: 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) |
См. также раздел
Основные понятия
Другие ресурсы
Справочные материалы