IShellItemImageFactory::GetImage-Methode (shobjidl_core.h)

  • Artikel

Ruft eine HBITMAP ab, die ein IShellItem darstellt. Das Standardverhalten besteht darin, eine Miniaturansicht zu laden. Wenn keine Miniaturansicht für das aktuelle IShellItem vorhanden ist, wird ein HBITMAP-Element für das Symbol des Elements abgerufen. Die Miniaturansicht oder das Symbol wird extrahiert, wenn sie derzeit nicht zwischengespeichert ist.

Syntax

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

Parameter

[in] size

Typ: SIZE

Eine -Struktur, die die Größe des zu empfangenden Bilds angibt.

[in] flags

Typ: SIIGBF

Mindestens eines der folgenden Elemente:

SIIGBF_RESIZETOFIT (0x00000000)

Verkleinern Sie die Bitmap nach Bedarf, um sie anzupassen, und behalten Sie dabei das Seitenverhältnis bei.

SIIGBF_BIGGERSIZEOK (0x00000001)

Wird von Anrufern übergeben, wenn sie das zurückgegebene Bild selbst strecken möchten. Wenn der Aufrufer beispielsweise eine Symbolgröße von 80 x 80 übergibt, kann eine Miniaturansicht von 96 x 96 zurückgegeben werden. Diese Aktion kann als Leistungsoptimierung verwendet werden, wenn der Aufrufer erwartet, dass er das Bild strecken muss. Beachten Sie, dass die Shell-Implementierung von IShellItemImageFactory einen GDI-Stretch-Blit ausführt. Wenn der Aufrufer eine Bildstreckung mit höherer Qualität als über diesen Mechanismus erhalten möchte, sollte er dieses Flag übergeben und die Dehnung selbst ausführen.

SIIGBF_MEMORYONLY (0x00000002)

Gibt das Element nur zurück, wenn es sich bereits im Arbeitsspeicher befindet. Greifen Sie nicht auf den Datenträger zu, auch wenn das Element zwischengespeichert ist. Beachten Sie, dass dies nur ein bereits zwischengespeichertes Symbol zurückgibt und auf ein Klassensymbol zurückgreifen kann, wenn ein Element über ein symbol pro instance verfügt, das nicht zwischengespeichert wurde. Zum Abrufen einer Miniaturansicht, auch wenn sie zwischengespeichert ist, muss immer auf den Datenträger zugegriffen werden. Daher sollte GetImage nicht über den UI-Thread aufgerufen werden, ohne SIIGBF_MEMORYONLY zu übergeben.

SIIGBF_ICONONLY (0x00000004)

Gibt nur das Symbol zurück, niemals die Miniaturansicht.

SIIGBF_THUMBNAILONLY (0x00000008)

Gibt nur die Miniaturansicht zurück, niemals das Symbol. Beachten Sie, dass nicht alle Elemente Miniaturansichten aufweisen, sodass SIIGBF_THUMBNAILONLY in diesen Fällen zu fehlern bei der Methode führt.

SIIGBF_INCACHEONLY (0x00000010)

Ermöglicht den Zugriff auf den Datenträger, aber nur, um ein zwischengespeichertes Element abzurufen. Dadurch wird eine zwischengespeicherte Miniaturansicht zurückgegeben, sofern sie verfügbar ist. Wenn keine zwischengespeicherte Miniaturansicht verfügbar ist, wird ein zwischengespeichertes symbol pro instance zurückgegeben, aber keine Miniaturansicht oder ein Symbol extrahiert.

SIIGBF_CROPTOSQUARE (0x00000020)

In Windows 8 eingeführt. Schneiden Sie die Bitmap bei Bedarf auf ein Quadrat zu.

SIIGBF_WIDETHUMBNAILS (0x00000040)

In Windows 8 eingeführt. Strecken und Zuschneiden der Bitmap auf ein Seitenverhältnis von 0,7.

SIIGBF_ICONBACKGROUND (0x00000080)

In Windows 8 eingeführt. Wenn Sie ein Symbol zurückgeben, zeichnen Sie einen Hintergrund mit der registrierten Hintergrundfarbe der zugeordneten App.

SIIGBF_SCALEUP (0x00000100)

In Windows 8 eingeführt. Wenn erforderlich, strecken Sie die Bitmap so, dass die Höhe und Breite der angegebenen Größe entsprechen.

[out] phbm

Typ: HBITMAP*

Zeiger auf einen Wert, der nach erfolgreicher Rückgabe dieser Methode das Handle der abgerufenen Bitmap empfängt. Es liegt in der Verantwortung des Aufrufers, diese abgerufene Ressource über DeleteObject frei zu geben, wenn sie nicht mehr benötigt wird.

Rückgabewert

Typ: HRESULT

Wenn diese Methode erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Die Symbolextraktion kann zeitaufwändig sein. Diese Methode sollte in der Regel nicht von einem UI-Thread aufgerufen werden, um zu vermeiden, dass dieser Thread nicht mehr reagiert. Sie können IShellItemImageFactory::GetImage in einem UI-Thread aufrufen, wenn Sie das flag SIIGBF_INCACHEONLY festlegen. Wenn das Image jedoch nicht im Cache gefunden wird, sollte die aufrufende Anwendung darauf vorbereitet sein, einen Hintergrundthread zu starten, um das Image zu extrahieren. Eine Extraktion sollte niemals in einem UI-Thread erfolgen.

Ein vollständiges Beispiel für die Verwendung dieser Methode finden Sie im Beispiel zur Verwendung von Image Factory .

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile shobjidl_core.h (shobjidl.h einschließen)