Метод IShellItemImageFactory::GetImage (shobjidl_core.h)

Статья
03/13/2024

Возвращает HBITMAP , представляющий IShellItem. Поведение по умолчанию — загрузка эскиза. Если для текущего элемента IShellItem нет эскиза, он получает HBITMAP для значка элемента. Эскиз или значок извлекаются, если они в настоящее время не кэшируются.

Синтаксис

HRESULT GetImage(
  [in]  SIZE    size,
  [in]  SIIGBF  flags,
  [out] HBITMAP *phbm
);

Параметры

[in] size

Тип: SIZE

Структура, указывающая размер получаемого изображения.

[in] flags

Тип: SIIGBF

Одно или несколько из следующих компонентов:

SIIGBF_RESIZETOFIT (0x00000000)

При необходимости сожмите растровое изображение, сохранив его пропорции.

SIIGBF_BIGGERSIZEOK (0x00000001)

Передается вызывающими абонентами, если они хотят растянуть возвращенное изображение самостоятельно. Например, если вызывающий объект передает значок размером 80x80, можно вернуть эскиз размером 96x96. Это действие можно использовать в качестве оптимизации производительности, если вызывающий объект ожидает, что ей потребуется растянуть изображение. Обратите внимание, что реализация оболочки IShellItemImageFactory выполняет gDI stretch blit. Если вызывающему объекту требуется растягивание изображения более высокого качества, чем предусмотрено с помощью этого механизма, он должен передать этот флаг и выполнить растяжение самостоятельно.

SIIGBF_MEMORYONLY (0x00000002)

Возвращать элемент, только если он уже находится в памяти. Не получайте доступ к диску, даже если элемент кэширован. Обратите внимание, что при этом возвращается только кэшированный значок, и он может вернуться к значку класса, если у элемента есть значок для каждого экземпляра, который не был кэширован. Для получения эскиза, даже если он кэшируется, всегда требуется доступ к диску, поэтому getImage не следует вызывать из потока пользовательского интерфейса без передачи SIIGBF_MEMORYONLY.

SIIGBF_ICONONLY (0x00000004)

Возвращает только значок, а не эскиз.

SIIGBF_THUMBNAILONLY (0x00000008)

Возвращает только эскиз, но не значок. Обратите внимание, что не все элементы имеют эскизы, поэтому SIIGBF_THUMBNAILONLY приведет к сбою метода в таких случаях.

SIIGBF_INCACHEONLY (0x00000010)

Разрешает доступ к диску, но только для извлечения кэшированного элемента. При этом возвращается кэшированный эскиз, если он доступен. Если кэшированный эскиз недоступен, он возвращает кэшированный значок для каждого экземпляра, но не извлекает эскиз или значок.

SIIGBF_CROPTOSQUARE (0x00000020)

Представлено в Windows 8. При необходимости обрежьте растровое изображение до квадрата.

SIIGBF_WIDETHUMBNAILS (0x00000040)

Представлено в Windows 8. Растяжение и обрезка растрового рисунка до пропорций 0,7.

SIIGBF_ICONBACKGROUND (0x00000080)

Представлено в Windows 8. При возврате значка нарисуйте фон, используя зарегистрированный цвет фона связанного приложения.

SIIGBF_SCALEUP (0x00000100)

Представлено в Windows 8. При необходимости растяните растровое изображение так, чтобы высота и ширина соответствовали заданному размеру.

[out] phbm

Тип: HBITMAP*

Указатель на значение, которое при успешном возвращении этого метода получает дескриптор полученного растрового изображения. Вызывающий объект отвечает за освобождение полученного ресурса с помощью DeleteObject , когда он больше не нужен.

Возвращаемое значение

Тип: HRESULT

Если этот метод завершается успешно, он возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Извлечение значков может занять много времени. Как правило, этот метод не следует вызывать из потока пользовательского интерфейса, чтобы избежать того, что поток перестанет отвечать на запросы. IShellItemImageFactory::GetImage можно вызвать в потоке пользовательского интерфейса, если задан флаг SIIGBF_INCACHEONLY. Однако если изображение не найдено в кэше, вызывающее приложение должно быть готово к запуску фонового потока для извлечения изображения. Извлечение никогда не должно выполняться в потоке пользовательского интерфейса.

Полный пример использования этого метода см. в разделе Использование фабрики образов .

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	shobjidl_core.h (включая Shobjidl.h)

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