LoadImageA, fonction (winuser.h)

Charge une icône, un curseur, un curseur animé ou une bitmap.

Syntaxe

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

Paramètres

[in, optional] hInst

Type : HINSTANCE

Handle vers le module d’une DLL ou d’un exécutable (.exe) qui contient l’image à charger. Pour plus d’informations, consultez GetModuleHandle. Notez que, à partir de Windows 32 bits, un handle d’instance (HINSTANCE), tel que le handle d’instance d’application exposé par l’appel de fonction système de WinMain, et un handle de module (HMODULE) sont identiques.

Pour charger une image prédéfinie ou une ressource autonome (icône, curseur ou fichier bitmap), définissez ce paramètre sur NULL.

[in] name

Type : LPCTSTR

Image à charger.

Si le paramètre hInst n’est pas NULL et que le paramètre fuLoad omet LR_LOADFROMFILE, nom spécifie la ressource d’image dans le module hInst.

Si la ressource d’image doit être chargée par nom à partir du module, le nom paramètre est un pointeur vers une chaîne terminée par null qui contient le nom de la ressource d’image.

Si la ressource d’image doit être chargée par ordinal à partir du module, utilisez la macro MAKEINTRESOURCE pour convertir l’ordinal d’image en un formulaire qui peut être transmis à la fonction LoadImage .

Si le paramètre hInst est NULL et que le paramètre fuLoad omet la valeur LR_LOADFROMFILE et inclut la LR_SHARED, le nom spécifie l’image prédéfinie à charger.

Les identificateurs d’image prédéfinis sont définis dans Winuser.h et ont les préfixes suivants :

Préfixe	Signification
OBM_	Bitmaps OEM. Utilisez la macro MAKEINTRESOURCE pour les transmettre.
OIC_	Icônes OEM. Utilisez la macro MAKEINTRESOURCE pour les transmettre.
OCR_	Curseurs OEM. Utilisez la macro MAKEINTRESOURCE pour les transmettre.
IDI_	icônes standard
IDC_	curseurs Standard

Pour passer des constantes d’identificateurs d’image OEM à la fonction LoadImage , utilisez la macro MAKEINTRESOURCE . Par exemple, pour charger le curseur OCR_NORMAL, passez en tant que paramètre nom de , NULL en tant que paramètre hInst et LR_SHARED comme l’un des indicateurs au paramètre fuLoad.

Si le paramètre hInst est NULL et que le paramètre fuLoad inclut la valeur LR_LOADFROMFILE, nom est le nom du fichier qui contient la ressource autonome (icône, curseur ou fichier bitmap), par exemple .

Pour plus d’informations, consultez la section Remarques ci-dessous.

[in] type

Type : uiNT

Type d’image à charger.

Ce paramètre peut être l’une des valeurs suivantes :

Valeur	Signification
IMAGE_BITMAP	Charge une bitmap.
IMAGE_CURSOR	Charge un curseur.
IMAGE_ICON	Charge une icône.

[in] cx

Type : int

Largeur, en pixels, de l’icône ou du curseur. Si ce paramètre est égal à zéro et que le paramètre fuLoad est LR_DEFAULTSIZE, la fonction utilise la valeur de métrique système SM_CXICON ou SM_CXCURSOR pour définir la largeur. Si ce paramètre est égal à zéro et que LR_DEFAULTSIZE n’est pas utilisé, la fonction utilise la largeur réelle des ressources.

[in] cy

Type : int

Hauteur, en pixels, de l’icône ou du curseur. Si ce paramètre est égal à zéro et que le paramètre fuLoad est LR_DEFAULTSIZE, la fonction utilise la valeur de métrique système SM_CYICON ou SM_CYCURSOR pour définir la hauteur. Si ce paramètre est égal à zéro et que LR_DEFAULTSIZE n’est pas utilisé, la fonction utilise la hauteur de ressource réelle.

[in] fuLoad

Type : uiNT

Ce paramètre peut être une ou plusieurs des valeurs suivantes.

Valeur	Signification
LR_CREATEDIBSECTION 0x00002000	Lorsque le paramètre uType spécifie IMAGE_BITMAP, la fonction renvoie une bitmap de section DIB plutôt qu’une bitmap compatible. Cet indicateur est utile pour charger une bitmap sans la mapper aux couleurs de l’appareil d’affichage.
LR_DEFAULTCOLOR 0x00000000	Indicateur par défaut ; ça ne fait rien. Tout cela signifie qu’il ne s’agit pas de « pas LR_MONOCHROME».
LR_DEFAULTSIZE 0x00000040	Utilise la largeur ou la hauteur spécifiées par les valeurs de métrique système pour les curseurs ou les icônes, si les valeurs cxDesired ou cyDesired sont définies sur zéro. Si cet indicateur n’est pas spécifié et que cxDesired et cyDesired sont définis sur zéro, la fonction utilise la taille réelle de la ressource. Si la ressource contient plusieurs images, la fonction utilise la taille de la première image.
LR_LOADFROMFILE 0x00000010	Charge l’image autonome à partir du fichier spécifié par nom (icône, curseur ou fichier bitmap).
LR_LOADMAP3DCOLORS 0x00001000	Recherche la table de couleurs pour l’image et remplace les nuances de gris suivantes par la couleur 3D correspondante. Dk Gray, RGB(128,128,128) avec COLOR_3DSHADOW Gris, RVB(192,192,192) avec COLOR_3DFACE Lt Gray, RGB(223,223,223) avec COLOR_3DLIGHT N’utilisez pas cette option si vous chargez une bitmap avec une profondeur de couleur supérieure à 8bpp.
LR_LOADTRANSPARENT 0x00000020	Récupère la valeur de couleur du premier pixel de l’image et remplace l’entrée correspondante dans la table de couleurs par la couleur de fenêtre par défaut (COLOR_WINDOW). Tous les pixels de l’image qui utilisent cette entrée deviennent la couleur de fenêtre par défaut. Cette valeur s’applique uniquement aux images qui ont des tables de couleurs correspondantes. N’utilisez pas cette option si vous chargez une bitmap avec une profondeur de couleur supérieure à 8bpp. Si fuLoad inclut les valeurs LR_LOADTRANSPARENT et LR_LOADMAP3DCOLORS, LR_LOADTRANSPARENT est prioritaire. Toutefois, l’entrée de tableau de couleurs est remplacée par COLOR_3DFACE plutôt que par COLOR_WINDOW.
LR_MONOCHROME 0x00000001	Charge l’image en noir et blanc.
LR_SHARED 0x00008000	Partage le handle d’image si l’image est chargée plusieurs fois. Si LR_SHARED n’est pas défini, un deuxième appel à LoadImage pour la même ressource charge à nouveau l’image et retourne un handle différent. Lorsque vous utilisez cet indicateur, le système détruit la ressource lorsqu’elle n’est plus nécessaire. N’utilisez pas LR_SHARED pour les images qui ont des tailles non standard, qui peuvent changer après le chargement ou qui sont chargées à partir d’un fichier. Lors du chargement d’une icône système ou d’un curseur, vous devez utiliser LR_SHARED ou la fonction ne parvient pas à charger la ressource. Cette fonction recherche la première image dans le cache avec le nom de ressource demandé, quelle que soit la taille demandée.
LR_VGACOLOR 0x00000080	Utilise de vraies couleurs VGA.

Valeur de retour

Type : HANDLE

Si la fonction réussit, la valeur de retour est le handle de l’image nouvellement chargée.

Si la fonction échoue, la valeur de retour est NULL . Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Si IS_INTRESOURCE(nom) est TRUE, nom spécifie l’identificateur entier de la ressource donnée. Sinon, il s’agit d’un pointeur vers une chaîne terminée par null. Si le premier caractère de la chaîne est un signe de livre (#), les caractères restants représentent un nombre décimal qui spécifie l’identificateur entier de la ressource. Par exemple, la chaîne « #258 » représente l’identificateur 258.

Lorsque vous avez terminé d’utiliser une bitmap, un curseur ou une icône que vous avez chargé sans spécifier l’indicateur de LR_SHARED, vous pouvez libérer sa mémoire associée en appelant l’une des fonctions du tableau suivant.

Ressource	Fonction Release
Image matricielle	DeleteObject
Curseur	DestroyCursor
Icône	DestroyIcon

 

Le système supprime automatiquement ces ressources lorsque le processus qui les a créés se termine ; Toutefois, l’appel de la fonction appropriée enregistre la mémoire et diminue la taille du jeu de travail du processus.

Exemples

Pour obtenir un exemple, consultez Using Window Classes.

Note

L’en-tête winuser.h définit LoadImage comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winuser.h (include Windows.h)
bibliothèque	User32.lib
DLL	User32.dll
ensemble d’API	ext-ms-win-ntuser-gui-l1-1-0 (introduit dans Windows 8)

Voir aussi

conceptuelle

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

loadIcon

autres ressources

de référence

Ressources