LoadImageA, fonction (winuser.h)

Article
02/01/2024

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 pour le module d’une DLL ou d’un exécutable (.exe) qui contient l’image à charger. Pour plus d’informations, consultez GetModuleHandle. Notez qu’à 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 la même chose.

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, name spécifie la ressource d’image dans le module hInst .

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

Si la ressource 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 a la valeur 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.
OCI_	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 MAKEINTRESOURCE(OCR_NORMAL) comme paramètre name , NULL comme paramètre hInst et LR_SHARED comme l’un des indicateurs au paramètre fuLoad .

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

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 de ressource réelle.

[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 prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
LR_CREATEDIBSECTION 0x00002000	Lorsque le paramètre uType spécifie IMAGE_BITMAP, la fonction retourne 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 ; il ne fait rien. Tout ce que cela signifie est « pas LR_MONOCHROME ».
LR_DEFAULTSIZE 0x00000040	Utilise la largeur ou la hauteur spécifiées par les valeurs de métriques 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 de ressource réelle. 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 son nom (icône, curseur ou fichier bitmap).
LR_LOADMAP3DCOLORS 0x00001000	Recherche l’image dans la table de couleurs et remplace les nuances de gris suivantes par la couleur 3D correspondante. Dk Gray, RVB(128,128,128) avec COLOR_3DSHADOW Gris, RVB(192,192,192) avec COLOR_3DFACE Lt Gray, RVB(223,223,223) avec COLOR_3DLIGHT N’utilisez pas cette option si vous chargez une bitmap dont la profondeur de couleur est supérieure à 8 bpp.
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 dont la profondeur de couleur est supérieure à 8 bpp. 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 sinon la fonction ne parvient pas à charger la ressource. Cette fonction recherche la première image du cache avec le nom de ressource demandé, quelle que soit la taille demandée.
LR_VGACOLOR 0x00000080	Utilise de vraies couleurs VGA.

Valeur retournée

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étaillées sur l’erreur, appelez GetLastError.

Remarques

Si IS_INTRESOURCE(name) a la valeur TRUE, name 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 en 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 LR_SHARED , vous pouvez libérer la mémoire associée en appelant l’une des fonctions du tableau suivant.

Ressource	Fonction Release
Bitmap	DeleteObject
Curseur	DestroyCursor
Icône	DestroyIcon

Le système supprime automatiquement ces ressources lorsque le processus qui les a créées se termine ; toutefois, l’appel de la fonction appropriée permet d’économiser de la mémoire et de réduire la taille de l’ensemble de travail du processus.

Exemples

Pour obtenir un exemple, consultez Utilisation de classes de fenêtre.

Notes

L’en-tête winuser.h définit LoadImage comme un 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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winuser.h (inclure Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll
Ensemble d’API	ext-ms-win-ntuser-gui-l1-1-0 (introduit dans Windows 8)