Funzione LoadImageA (winuser.h)

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

Sintassi

HANDLE LoadImageA(
  [in, optional] HINSTANCE hInst,
  [in]           LPCSTR    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 file 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 esposta dalla 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 è diverso da NULL e il parametro fuLoad omette LR_LOADFROMFILE, name specifica la risorsa immagine nel modulo hInst .

Se la risorsa immagine deve essere caricata in base al nome del 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 il numero ordinale di 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. Utilizzare la macro MAKEINTRESOURCE per passarli.
OIC_ Icone OEM. Utilizzare la macro MAKEINTRESOURCE per passarli.
OCR_ Cursori OEM. Utilizzare la macro MAKEINTRESOURCE per passarli.
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 name , 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 , name è 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 SM_CXICON o SM_CXCURSOR valore della metrica di sistema per impostare la larghezza. Se questo parametro è zero e non viene usato LR_DEFAULTSIZE , 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 della metrica di sistema SM_CYICON o SM_CYCURSOR per impostare l'altezza. Se questo parametro è zero e non viene usato LR_DEFAULTSIZE , 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 caricare una bitmap senza mapparla ai colori del dispositivo di visualizzazione.
LR_DEFAULTCOLOR
0x00000000
Flag predefinito; non fa nulla. Tutto ciò significa che "non LR_MONOCHROME".
LR_DEFAULTSIZE
0x00000040
Usa la larghezza o l'altezza specificata dai valori delle metriche di sistema per cursori o 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 per nome (icona, cursore o file bitmap).
LR_LOADMAP3DCOLORS
0x00001000
Cerca l'immagine nella tabella dei colori e sostituisce le sfumature di grigio seguenti con il colore 3D corrispondente.
  • Dk Gray, RGB(128,128,128) con COLOR_3DSHADOW
  • Grigio, RGB(192,192,192) con COLOR_3DFACE
  • Lt Grigio, 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 dei colori con il colore della finestra predefinito (COLOR_WINDOW). Tutti i pixel nell'immagine che usano tale voce diventano il colore della finestra predefinito. Questo valore si applica solo alle immagini con tabelle 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 LR_LOADTRANSPARENT che LR_LOADMAP3DCOLORS , LR_LOADTRANSPARENT ha la precedenza. Tuttavia, la voce della tabella dei 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