Funzione LoadImageW (winuser.h)

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)

Vedi anche

Informazioni concettuali

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

Altre risorse

Riferimento

Risorse