LoadIconMetric function

Loads a specified icon resource with a client-specified system metric.

Syntax


HRESULT LoadIconMetric(
  _In_   HINSTANCE hinst,
  _In_   PCWSTR pszName,
  _In_   int lims,
  _Out_  HICON *phico
);

Parameters

hinst [in]

Type: HINSTANCE

A handle to the module of either a DLL or executable (.exe) file that contains the icon to be loaded. For more information, see GetModuleHandle.

To load a predefined icon or a standalone icon file, set this parameter to NULL.

pszName [in]

Type: PCWSTR

A pointer to a null-terminated, Unicode buffer that contains location information about the icon to load. It is interpreted as follows:

If hinst is NULL, pszName can specify one of two things.

  1. The identifier of a predefined icon to load. These identifiers are recognized.
    • IDI_APPLICATION
    • IDI_INFORMATION
    • IDI_ERROR
    • IDI_WARNING
    • IDI_SHIELD
    • IDI_QUESTION

    To pass these constants to the LoadIconMetric function, use the MAKEINTRESOURCE macro. For example, to load the IDI_ERROR icon, pass MAKEINTRESOURCE(IDI_ERROR) as the pszName parameter and NULL as the hinst parameter.

  2. The name of a standalone icon (.ico) file.

If hinst is non-null, pszName can specify one of two things.

  1. The name of the icon resource, if the icon resource is to be loaded by name from the module.
  2. The icon ordinal, if the icon resource is to be loaded by ordinal from the module. This ordinal must be packaged by using the MAKEINTRESOURCE macro.
lims [in]

Type: int

The desired metric. One of the following values:

ValueMeaning
LIM_SMALL

Corresponds to SM_CXSMICON, the recommended pixel width of a small icon.

LIM_LARGE

Corresponds toSM_CXICON, the default pixel width of an icon.

 

phico [out]

Type: HICON*

When this function returns, contains a pointer to the handle of the loaded icon.

Return value

Type: HRESULT

Returns S_OK if successful, otherwise an error, including the following value.

Return codeDescription
E_INVALIDARG

The contents of the buffer pointed to by pszName do not fit any of the expected interpretations.

 

Remarks

LoadIconMetric is similar to LoadIcon, but with the capability to specify the icon metric. It is used in place of LoadIcon when the calling application wants to ensure a high quality icon. This is particularly useful in high dots per inch (dpi) situations.

Icons are extracted or created as follows.

  1. If an exact size match is found in the resource, that icon is used.
  2. If an exact size match cannot be found and a larger icon is available, a new icon is created by scaling the larger version down to the desired size.
  3. If an exact size match cannot be found and no larger icon is available, a new icon is created by scaling a smaller icon up to the desired size.

Comparative calls are shown here for LoadIconMetric and LoadIcon.

NOTIFYICONDATA  nidIconData  = {0};
nidIconData.hIcon = LoadIcon(hInstance, MAKEINTRESOURCE(IDI_ICON));

// Or...

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

The application is responsible for calling DestroyIcon on the retrieved icon.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Commctrl.h

Library

Comctl32.lib

DLL

Comctl32.dll

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.