LoadIconMetric function (commctrl.h)

Article
2023-06-20

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

[in] hinst

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 system icon or a standalone icon file, set this parameter to NULL.

[in] pszName

Type: PCWSTR

A pointer to a null-terminated, Unicode buffer that contains location information about the icon to load.

If hinst is non-NULL, pszName specifies the icon resource either by name or ordinal. This ordinal must be packaged by using the MAKEINTRESOURCE macro.

If hinst is NULL, pszName specifies the identifier (beginning with the IDI_ prefix) of a predefined system icon to load.

[in] lims

Type: int

The desired metric. One of the following values:

Value	Meaning
LIM_SMALL	Corresponds to SM_CXSMICON, the recommended pixel width of a small icon.
LIM_LARGE	Corresponds to SM_CXICON, the default pixel width of an icon.

[out] phico

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 code	Description
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.

If an exact size match is found in the resource, that icon is used.
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.
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

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	commctrl.h
Library	Comctl32.lib
DLL	Comctl32.dll

Share via