Funzione LoadImageW (winuser.h)

Articolo
03/04/2024

Carica un'icona, un cursore, un cursore animato o una bitmap.

Sintassi

HANDLE LoadImageW(
  [in, optional] HINSTANCE hInst,
  [in]           LPCWSTR   name,
  [in]           UINT      type,
  [in]           int       cx,
  [in]           int       cy,
  [in]           UINT      fuLoad
);

Parametri

[in, optional] hInst

Tipo: HINSTANCE

Handle per il modulo di una DLL o di un eseguibile (.exe) che contiene l'immagine da caricare. Per altre informazioni, vedere GetModuleHandle. Si noti che a partire da Windows a 32 bit, un handle di istanza (HINSTANCE), ad esempio l'istanza dell'applicazione gestita da chiamata di funzione di sistema di WinMain e un handle di modulo (HMODULE) sono la stessa cosa.

Per caricare un'immagine predefinita o una risorsa autonoma (icona, cursore o file bitmap), impostare questo parametro su NULL.

[in] name

Tipo: LPCTSTR

Immagine da caricare.

Se il parametro hInst non è NULL e il parametro fuLoad omette LR_LOADFROMFILE, il nome specifica la risorsa immagine nel modulo hInst .

Se la risorsa immagine deve essere caricata per nome dal modulo, il parametro name è un puntatore a una stringa con terminazione null contenente il nome della risorsa immagine.

Se la risorsa immagine deve essere caricata da ordinale dal modulo, usare la macro MAKEINTRESOURCE per convertire l'ordinale dell'immagine in un modulo che può essere passato alla funzione LoadImage .

Se il parametro hInst è NULL e il parametro fuLoad omette il valore LR_LOADFROMFILE e include il LR_SHARED, il nome specifica l'immagine predefinita da caricare.

Gli identificatori di immagine predefiniti sono definiti in Winuser.h e hanno i prefissi seguenti:

Prefisso	Significato
OBM_	Bitmap OEM. Usare la macro MAKEINTRESOURCE per passare questi elementi.
OIC_	Icone OEM. Usare la macro MAKEINTRESOURCE per passare questi elementi.
OCR_	Cursori OEM. Usare la macro MAKEINTRESOURCE per passare questi elementi.
IDI_	Icone standard
IDC_	Cursori standard

Per passare costanti di identificatori di immagine OEM alla funzione LoadImage , usare la macro MAKEINTRESOURCE . Ad esempio, per caricare il cursore OCR_NORMAL , passare MAKEINTRESOURCE(OCR_NORMAL) come parametro nome , NULL come parametro hInst e LR_SHARED come uno dei flag al parametro fuLoad .

Se il parametro hInst è NULL e il parametro fuLoad include il valore LR_LOADFROMFILE , il nome è il nome del file che contiene la risorsa autonoma (icona, cursore o file bitmap), ad esempio c:\myicon.ico.

Per altre informazioni, vedere la sezione Osservazioni di seguito.

[in] type

Tipo: UINT

Tipo di immagine da caricare.

Questo parametro può essere uno dei valori seguenti:

Valore	Significato
IMAGE_BITMAP	Carica una bitmap.
IMAGE_CURSOR	Carica un cursore.
IMAGE_ICON	Carica un'icona.

[in] cx

Tipo: int

Larghezza, in pixel, dell'icona o del cursore. Se questo parametro è zero e il parametro fuLoad è LR_DEFAULTSIZE, la funzione usa il valore di SM_CXICON o SM_CXCURSOR metrica di sistema per impostare la larghezza. Se questo parametro è zero e LR_DEFAULTSIZE non viene usato, la funzione usa la larghezza effettiva della risorsa.

[in] cy

Tipo: int

Altezza, in pixel, dell'icona o del cursore. Se questo parametro è zero e il parametro fuLoad è LR_DEFAULTSIZE, la funzione usa il valore di SM_CYICON o SM_CYCURSOR metrica di sistema per impostare l'altezza. Se questo parametro è zero e LR_DEFAULTSIZE non viene usato, la funzione usa l'altezza effettiva della risorsa.

[in] fuLoad

Tipo: UINT

Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
LR_CREATEDIBSECTION 0x00002000	Quando il parametro uType specifica IMAGE_BITMAP, la funzione restituisce una bitmap di sezione DIB anziché una bitmap compatibile. Questo flag è utile per il caricamento di una bitmap senza eseguire il mapping ai colori del dispositivo di visualizzazione.
LR_DEFAULTCOLOR 0x00000000	Flag predefinito; non fa niente. Tutto ciò significa che "non LR_MONOCHROME".
LR_DEFAULTSIZE 0x00000040	Usa la larghezza o l'altezza specificata dai valori delle metriche di sistema per i cursori o le icone, se i valori cxDesired o cyDesired sono impostati su zero. Se questo flag non è specificato e cxDesired e cyDesired sono impostati su zero, la funzione usa le dimensioni effettive della risorsa. Se la risorsa contiene più immagini, la funzione usa le dimensioni della prima immagine.
LR_LOADFROMFILE 0x00000010	Carica l'immagine autonoma dal file specificato dal nome (icona, cursore o file bitmap).
LR_LOADMAP3DCOLORS 0x00001000	Cerca la tabella colori per l'immagine e sostituisce le sfumature seguenti di grigio con il colore 3D corrispondente. Dk Grigio, RGB(128,128,128) con COLOR_3DSHADOW Grigio, RGB(192.192.192) con COLOR_3DFACE Lt Gray, RGB(223,223,223) con COLOR_3DLIGHT Non usare questa opzione se si carica una bitmap con una profondità di colore maggiore di 8bpp.
LR_LOADTRANSPARENT 0x00000020	Recupera il valore del colore del primo pixel nell'immagine e sostituisce la voce corrispondente nella tabella colori con il colore della finestra predefinito (COLOR_WINDOW). Tutti i pixel nell'immagine che usano tale voce diventano il colore predefinito della finestra. Questo valore si applica solo alle immagini con tabelle di colori corrispondenti. Non usare questa opzione se si carica una bitmap con una profondità di colore maggiore di 8bpp. Se fuLoad include sia i valori di LR_LOADTRANSPARENT che di LR_LOADMAP3DCOLORS , LR_LOADTRANSPARENT ha la precedenza. Tuttavia, la voce della tabella colori viene sostituita con COLOR_3DFACE anziché COLOR_WINDOW.
LR_MONOCHROME 0x00000001	Carica l'immagine in bianco e nero.
LR_SHARED 0x00008000	Condivide l'handle dell'immagine se l'immagine viene caricata più volte. Se LR_SHARED non è impostato, una seconda chiamata a LoadImage per la stessa risorsa caricherà nuovamente l'immagine e restituirà un handle diverso. Quando si usa questo flag, il sistema eliminerà la risorsa quando non è più necessaria. Non usare LR_SHARED per le immagini con dimensioni non standard, che possono cambiare dopo il caricamento o caricate da un file. Quando si carica un'icona di sistema o un cursore, è necessario usare LR_SHARED o la funzione non riuscirà a caricare la risorsa. Questa funzione trova la prima immagine nella cache con il nome della risorsa richiesta, indipendentemente dalle dimensioni richieste.
LR_VGACOLOR 0x00000080	Utilizza i colori VGA reali.

Valore restituito

Tipo: HANDLE

Se la funzione ha esito positivo, il valore restituito è l'handle dell'immagine appena caricata.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Se IS_INTRESOURCE(name) è TRUE, name specifica l'identificatore intero della risorsa specificata. In caso contrario, si tratta di un puntatore a una stringa con terminazione Null.

Se il primo carattere della stringa è un segno di cancelletto (#), i caratteri rimanenti rappresentano un numero decimale che specifica l'identificatore intero della risorsa. Ad esempio, la stringa "#258" rappresenta l'identificatore 258.

Al termine dell'uso di una bitmap, di un cursore o di un'icona caricata senza specificare il flag di LR_SHARED , è possibile rilasciare la memoria associata chiamando una delle funzioni nella tabella seguente.

Risorsa	Funzione Release
Bitmap	DeleteObject
Cursore	DestroyCursor
Icona	DestroyIcon

Il sistema elimina automaticamente queste risorse quando il processo che li ha creati termina; Tuttavia, la chiamata alla funzione appropriata salva la memoria e riduce le dimensioni del working set del processo.

Esempio

Per un esempio, vedere Uso delle classi finestra.

Nota

L'intestazione winuser.h definisce LoadImage come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-gui-l1-1-0 (introdotto in Windows 8)