IShellItemImageFactory::GetImage-Methode (shobjidl_core.h)

Artikel
11/20/2024

Ruft eine HBITMAP-, die ein IShellItem-darstellt. Das Standardverhalten besteht darin, eine Miniaturansicht zu laden. Wenn für das aktuelle IShellItem-keine Miniaturansicht vorhanden ist, wird ein HBITMAP- 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: GRÖßE

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

[in] flags

Typ: SIIGBF-

Eine oder mehrere der folgenden Optionen:

SIIGBF_RESIZETOFIT (0x00000000)

Verkleinern Sie die Bitmap nach Bedarf, um das Seitenverhältnis beizubehalten.

SIIGBF_BIGGERSIZEOK (0x00000001)

Wird von Anrufern übergeben, wenn sie das zurückgegebene Bild selbst strecken möchten. Wenn der Anrufer beispielsweise eine Symbolgröße von 80x80 übergibt, kann eine Miniaturansicht von 96 x 96 zurückgegeben werden. Diese Aktion kann als Leistungsoptimierung verwendet werden, wenn der Aufrufer erwartet, dass das Bild gestreckt werden muss. Beachten Sie, dass die Shell-Implementierung von IShellItemImageFactory eine GDI-Stretch-Blit ausführt. Wenn der Anrufer eine höhere Bildqualität als über diesen Mechanismus bereitgestellt hat, sollten sie dieses Flag übergeben und die Streckung 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 ein Symbol pro Instanz aufweist, das nicht zwischengespeichert wurde. Wenn Sie eine Miniaturansicht abrufen, 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_MEMORYONLYzu ü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. Daher führt SIIGBF_THUMBNAILONLY dazu, dass die Methode in diesen Fällen fehlschlägt.

SIIGBF_INCACHEONLY (0x00000010)

Ermöglicht den Zugriff auf den Datenträger, aber nur das Abrufen eines zwischengespeicherten Elements. Dies gibt eine zwischengespeicherte Miniaturansicht zurück, wenn sie verfügbar ist. Wenn keine zwischengespeicherte Miniaturansicht verfügbar ist, wird ein zwischengespeichertes Symbol pro Instanz zurückgegeben, aber keine Miniaturansicht oder ein Symbol extrahiert.

SIIGBF_CROPTOSQUARE (0x00000020)

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

SIIGBF_WIDETHUMBNAILS (0x00000040)

in Windows 8eingeführt. Ziehen Sie die Bitmap, und schneiden Sie sie auf ein Seitenverhältnis von 0,7 zu.

SIIGBF_ICONBACKGROUND (0x00000080)

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

SIIGBF_SCALEUP (0x00000100)

in Windows 8eingeführt. Dehnen Sie bei Bedarf die Bitmap so, dass die Höhe und Breite der angegebenen Größe entsprechen.

[out] phbm

Typ: HBITMAP*

Zeiger auf einen Wert, der, wenn diese Methode erfolgreich zurückgegeben wird, 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_OKzurückgegeben. Andernfalls wird ein HRESULT- Fehlercode zurückgegeben.

Bemerkungen

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 SIIGBF_INCACHEONLY Flag festlegen. Wenn das Bild jedoch nicht im Cache gefunden wird, sollte die aufrufende Anwendung bereit sein, einen Hintergrundthread zu starten, um das Bild zu extrahieren. Eine Extraktion sollte nie in einem UI-Thread erfolgen.

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

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	shobjidl_core.h (include Shobjidl.h)

Freigeben über