LoadIconMetric, fonction (commctrl.h)

  • Article

Charge une ressource d’icône spécifiée avec une métrique système spécifiée par le client.

Syntaxe

HRESULT LoadIconMetric(
  [in]  HINSTANCE hinst,
  [in]  PCWSTR    pszName,
  [in]  int       lims,
  [out] HICON     *phico
);

Paramètres

[in] hinst

Type : HINSTANCE

Handle pour le module d’un fichier DLL ou exécutable (.exe) qui contient l’icône à charger. Pour plus d’informations, consultez GetModuleHandle.

Pour charger une icône système prédéfinie ou un fichier d’icône autonome, définissez ce paramètre sur NULL.

[in] pszName

Type : PCWSTR

Pointeur vers une mémoire tampon Unicode terminée par un caractère Null qui contient des informations d’emplacement sur l’icône à charger.

Si hinst n’a pas la valeur NULL, pszName spécifie la ressource d’icône par nom ou par ordinal. Cet ordinal doit être empaqueté à l’aide de la macro MAKEINTRESOURCE .

Si hinst a la valeur NULL, pszName spécifie l’identificateur (en commençant par le préfixe IDI_) d’une icône système prédéfinie à charger.

[in] lims

Type : int

Métrique souhaitée. Une des valeurs suivantes :

Value Signification
LIM_SMALL
 Correspond à SM_CXSMICON, la largeur de pixel recommandée d’une petite icône.
LIM_LARGE
 Correspond à SM_CXICON, la largeur de pixel par défaut d’une icône.

[out] phico

Type : HICON*

Lorsque cette fonction retourne, contient un pointeur vers le handle de l’icône chargée.

Valeur retournée

Type : HRESULT

Retourne S_OK en cas de réussite, sinon une erreur, y compris la valeur suivante.

Code de retour Description
E_INVALIDARG
 Le contenu de la mémoire tampon pointée vers pszName ne correspond à aucune des interprétations attendues.

Remarques

LoadIconMetric est similaire à LoadIcon, mais avec la possibilité de spécifier la métrique d’icône. Il est utilisé à la place de LoadIcon lorsque l’application appelante souhaite garantir une icône de haute qualité. Cela est particulièrement utile dans les situations de points élevés par pouce (ppp).

Les icônes sont extraites ou créées comme suit.

  1. Si une correspondance de taille exacte est trouvée dans la ressource, cette icône est utilisée.
  2. Si une correspondance de taille exacte est introuvable et qu’une icône plus grande est disponible, une nouvelle icône est créée en mettant à l’échelle la version plus grande jusqu’à la taille souhaitée.
  3. Si une correspondance de taille exacte est introuvable et qu’aucune icône plus grande n’est disponible, une nouvelle icône est créée en mettant à l’échelle une icône plus petite jusqu’à la taille souhaitée.
Les appels comparatifs sont présentés ici pour LoadIconMetric et LoadIcon. 
NOTIFYICONDATA  nidIconData  = {0};
nidIconData.hIcon = LoadIcon(hInstance, MAKEINTRESOURCE(IDI_ICON));

// Or...

HRESULT hr = LoadIconMetric(hInstance, MAKEINTRESOURCE(IDI_ICON), LIM_SMALL, &nidIconData.hIcon);

L’application est chargée d’appeler DestroyIcon sur l’icône récupérée.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau uniquement]
Plateforme cible Windows
En-tête commctrl.h
Bibliothèque Comctl32.lib
DLL Comctl32.dll