Функция LoadImageW (winuser.h)
Загружает значок, курсор, анимированный курсор или точечный рисунок.
Синтаксис
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, имя указывает ресурс изображения в модуле hInst .
Если ресурс образа загружается из модуля по имени, параметр name является указателем на строку с пустым завершением, которая содержит имя ресурса образа.
Если ресурс изображения должен быть загружен порядком из модуля, используйте макрос MAKEINTRESOURCE для преобразования порядкового номера изображения в форму, которую можно передать в функцию LoadImage .
Если параметр hInst имеет значение NULL , а параметр fuLoad пропускает значение LR_LOADFROMFILE и включает LR_SHARED, имя указывает предопределенное изображение для загрузки.
Предопределенные идентификаторы образов определены в 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
Этот параметр может быть одним или несколькими из следующих значений.
Возвращаемое значение
Тип: 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) |
См. также раздел
Основные понятия
Другие ресурсы
Справочные материалы