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 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 WinMaine 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, nome specifica la risorsa immagine nel modulo hInst.

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

Se la risorsa immagine deve essere caricata dal modulo ordinale, 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. 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 degli identificatori di immagine OEM alla funzione LoadImage , usare la macro MAKEINTRESOURCE . Ad esempio, per caricare il cursore OCR_NORMAL, passare 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, nome è il nome del file che contiene la risorsa autonoma (icona, cursore o file bitmap), ad esempio .

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 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 SM_CYICON o SM_CYCURSOR metrica di sistema 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 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 cursori o icone, se i valori cxDesired o i valori cyDesired sono impostati su zero. Se questo flag non viene specificato e cxDesired e cyDesired vengono 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 da nome (icona, cursore o file bitmap).
LR_LOADMAP3DCOLORS 0x00001000	Cerca nella tabella colori l'immagine 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 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 di colore del primo pixel nell'immagine e sostituisce la voce corrispondente nella tabella dei colori con il colore predefinito della finestra (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 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 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 oppure la funzione non riuscirà a caricare la risorsa. Questa funzione trova la prima immagine nella cache con il nome della risorsa richiesto, 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 ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

Se IS_INTRESOURCE( nome) è TRUE, nome specifica l'identificatore intero della risorsa specificata. In caso contrario, è 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 consente di risparmiare memoria e riduce le dimensioni del working set del processo.

Esempi

Per un esempio, vedere Using Window Classes.

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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
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)

Vedere anche

concettuale

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

loadIcon

altre risorse

riferimento

risorse