IShellItemImageFactory ::GetImage, méthode (shobjidl_core.h)

Article
11/20/2024

Obtient un HBITMAP qui représente un IShellItem. Le comportement par défaut consiste à charger une miniature. S’il n’existe aucune miniature pour l'IShellItem actuel , il récupère un HBITMAP pour l’icône de l’élément. La miniature ou l’icône est extraite s’il n’est pas actuellement mis en cache.

Syntaxe

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

Paramètres

[in] size

Type : SIZE

Structure qui spécifie la taille de l’image à recevoir.

[in] flags

Type : SIIGBF

Une ou plusieurs des opérations suivantes :

SIIGBF_RESIZETOFIT (0x00000000)

Réduisez l’image bitmap selon les besoins, en conservant son rapport d’aspect.

SIIGBF_BIGGERSIZEOK (0x00000001)

Transmis par les appelants s’ils veulent étirer l’image retournée eux-mêmes. Par exemple, si l’appelant passe une taille d’icône de 80 x 80, une miniature de 96 x 96 peut être retournée. Cette action peut être utilisée comme optimisation des performances si l’appelant s’attend à ce qu’il ait besoin d’étirer l’image. Notez que l’implémentation shell de IShellItemImageFactory effectue une blit d’étirement GDI. Si l’appelant veut une étendue d’image de meilleure qualité que fournie par le biais de ce mécanisme, il doit passer cet indicateur et effectuer l’étirement eux-mêmes.

SIIGBF_MEMORYONLY (0x00000002)

Retourne l’élément uniquement s’il est déjà en mémoire. N’accédez pas au disque même si l’élément est mis en cache. Notez que cela retourne uniquement une icône déjà mise en cache et peut revenir à une icône par classe si un élément a une icône par instance qui n’a pas été mise en cache. La récupération d’une miniature, même si elle est mise en cache, nécessite toujours l’accès au disque. Par conséquent, GetImage ne doit pas être appelée à partir du thread d’interface utilisateur sans passer SIIGBF_MEMORYONLY.

SIIGBF_ICONONLY (0x00000004)

Retournez uniquement l’icône, jamais la miniature.

SIIGBF_THUMBNAILONLY (0x00000008)

Retournez uniquement la miniature, jamais l’icône. Notez que tous les éléments n’ont pas de miniatures. Par conséquent, SIIGBF_THUMBNAILONLY entraîne l’échec de la méthode dans ces cas.

SIIGBF_INCACHEONLY (0x00000010)

Autorise l’accès au disque, mais uniquement pour récupérer un élément mis en cache. Cette opération renvoie une miniature mise en cache si elle est disponible. Si aucune miniature mise en cache n’est disponible, elle retourne une icône mise en cache par instance, mais n’extrait pas une miniature ou une icône.

SIIGBF_CROPTOSQUARE (0x00000020)

introduit dans Windows 8. Si nécessaire, rognez la bitmap sur un carré.

SIIGBF_WIDETHUMBNAILS (0x00000040)

introduit dans Windows 8. Étirez et rognez la bitmap en un rapport d’aspect de 0,7.

SIIGBF_ICONBACKGROUND (0x00000080)

introduit dans Windows 8. Si vous retournez une icône, peindre un arrière-plan à l’aide de la couleur d’arrière-plan inscrite de l’application associée.

SIIGBF_SCALEUP (0x00000100)

introduit dans Windows 8. Si nécessaire, étirez la bitmap afin que la hauteur et la largeur correspondent à la taille donnée.

[out] phbm

Type : HBITMAP*

Pointeur vers une valeur qui, lorsque cette méthode retourne correctement, reçoit le handle de l’image bitmap récupérée. Il incombe à l’appelant de libérer cette ressource récupérée via DeleteObject lorsqu’il n’est plus nécessaire.

Valeur de retour

Type : HRESULT

Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un HRESULT code d’erreur.

Remarques

L’extraction d’icônes peut prendre du temps. Cette méthode ne doit généralement pas être appelée à partir d’un thread d’interface utilisateur pour éviter que ce thread ne réponde pas. Vous pouvez appeler IShellItemImageFactory ::GetImage sur un thread d’interface utilisateur si vous définissez l’indicateur SIIGBF_INCACHEONLY. Toutefois, si l’image est introuvable dans le cache, l’application appelante doit être prête à lancer un thread d’arrière-plan pour extraire l’image. Une extraction ne doit jamais être effectuée sur un thread d’interface utilisateur.

Consultez l’exemple Using Image Factory pour obtenir un exemple complet de l’utilisation de cette méthode.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	shobjidl_core.h (include Shobjidl.h)

Partager via