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

Статья
11/20/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. Если вызывающий объект хочет более высокого качества растяжения изображения, чем предоставленный через этот механизм, он должен передать этот флаг и выполнить растяжение самостоятельно.

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 [только классические приложения]
целевая платформа	Виндоус
заголовка	shobjidl_core.h (include Shobjidl.h)

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