Metodo IShellItemImageFactory::GetImage (shobjidl_core.h)

Ottiene un oggetto HBITMAP che rappresenta un oggetto IShellItem. Il comportamento predefinito consiste nel caricare un'anteprima. Se non è presente alcuna anteprima per l'oggetto IShellItem corrente, recupera un oggetto HBITMAP per l'icona dell'elemento. L'anteprima o l'icona viene estratta se non è attualmente memorizzata nella cache.

Sintassi

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

Parametri

[in] size

Tipo: SIZE

Struttura che specifica le dimensioni dell'immagine da ricevere.

[in] flags

Tipo: SIIGBF

Almeno uno tra i seguenti:

SIIGBF_RESIZETOFIT (0x00000000)

Compattare la bitmap in base alle esigenze, mantenendo le proporzioni.

SIIGBF_BIGGERSIZEOK (0x00000001)

Passato dai chiamanti se vogliono estendere l'immagine restituita. Ad esempio, se il chiamante passa una dimensione dell'icona pari a 80x80, potrebbe essere restituita un'anteprima di 96x96. Questa azione può essere usata come ottimizzazione delle prestazioni se il chiamante prevede che dovrà estendere l'immagine. Si noti che l'implementazione shell di IShellItemImageFactory esegue un'estensione GDI blit. Se il chiamante vuole un'immagine di qualità superiore rispetto a quella fornita tramite tale meccanismo, deve passare questo flag ed eseguire l'estensione stessa.

SIIGBF_MEMORYONLY (0x00000002)

Restituisce l'elemento solo se è già in memoria. Non accedere al disco anche se l'elemento è memorizzato nella cache. Si noti che restituisce solo un'icona già memorizzata nella cache e può eseguire il fallback a un'icona per classe se un elemento ha un'icona per istanza che non è stata memorizzata nella cache. Il recupero di un'anteprima, anche se memorizzata nella cache, richiede sempre l'accesso al disco, quindi GetImage non deve essere chiamato dal thread dell'interfaccia utente senza passare SIIGBF_MEMORYONLY.

SIIGBF_ICONONLY (0x00000004)

Restituisce solo l'icona, mai l'anteprima.

SIIGBF_THUMBNAILONLY (0x00000008)

Restituisce solo l'anteprima, mai l'icona. Si noti che non tutti gli elementi hanno anteprime, quindi SIIGBF_THUMBNAILONLY causerà l'esito negativo del metodo in questi casi.

SIIGBF_INCACHEONLY (0x00000010)

Consente l'accesso al disco, ma solo per recuperare un elemento memorizzato nella cache. Verrà restituita un'anteprima memorizzata nella cache, se disponibile. Se non è disponibile alcuna anteprima memorizzata nella cache, restituisce un'icona memorizzata nella cache per istanza ma non estrae un'anteprima o un'icona.

SIIGBF_CROPTOSQUARE (0x00000020)

Introdotto in Windows 8. Se necessario, ritagliare la bitmap in un quadrato.

SIIGBF_WIDETHUMBNAILS (0x00000040)

Introdotto in Windows 8. Estendere e ritagliare la bitmap in proporzioni di 0,7.

SIIGBF_ICONBACKGROUND (0x00000080)

Introdotto in Windows 8. Se restituisce un'icona, disegna uno sfondo usando il colore di sfondo registrato dell'app associata.

SIIGBF_SCALEUP (0x00000100)

Introdotto in Windows 8. Se necessario, estendere la bitmap in modo che l'altezza e la larghezza siano adatte alle dimensioni specificate.

[out] phbm

Tipo: HBITMAP*

Puntatore a un valore che, quando questo metodo viene restituito correttamente, riceve l'handle della bitmap recuperata. È responsabilità del chiamante liberare questa risorsa recuperata tramite DeleteObject quando non è più necessaria.

Valore restituito

Tipo: HRESULT

Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

L'estrazione delle icone può richiedere molto tempo. Questo metodo in genere non deve essere chiamato da un thread dell'interfaccia utente per evitare di causare la mancata risposta del thread. È possibile chiamare IShellItemImageFactory::GetImage in un thread dell'interfaccia utente se si imposta il flag SIIGBF_INCACHEONLY . Tuttavia, se l'immagine non viene trovata nella cache, l'applicazione chiamante deve essere preparata per avviare un thread di sfondo per estrarre l'immagine. Un'estrazione non deve mai essere eseguita su un thread dell'interfaccia utente.

Per un esempio completo di come usare questo metodo, vedere l'esempio Using Image Factory (Uso di Image Factory ).

Requisiti