LoadIconMetric-Funktion (commctrl.h)

Artikel
02/26/2024

Lädt eine angegebene Symbolressource mit einer vom Client angegebenen Systemmetrik.

Syntax

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

Parameter

[in] hinst

Typ: HINSTANCE

Ein Handle für das Modul einer DLL- oder einer ausführbaren Datei (.exe), die das zu ladende Symbol enthält. Weitere Informationen finden Sie unter GetModuleHandle.

Um ein vordefiniertes Systemsymbol oder eine eigenständige Symboldatei zu laden, legen Sie diesen Parameter auf NULL fest.

[in] pszName

Typ: PCWSTR

Ein Zeiger auf einen Mit Null beendeten Unicode-Puffer, der Standortinformationen zum zu ladenden Symbol enthält.

Wenn "hinst " nicht NULL ist, gibt pszName die Symbolressource entweder nach Name oder Ordnungszahl an. Diese Ordnungszahl muss mithilfe des MAKEINTRESOURCE-Makros gepackt werden.

Wenn hinstNULL ist, gibt pszName den Bezeichner (beginnend mit dem präfix IDI_) eines vordefinierten Systemsymbols an, das geladen werden soll.

[in] lims

Typ: int

Die gewünschte Metrik. Einer der folgenden Werte:

Wert	Bedeutung
LIM_SMALL	Entspricht SM_CXSMICON, der empfohlenen Pixelbreite eines kleinen Symbols.
LIM_LARGE	Entspricht SM_CXICON, der Standardpixelbreite eines Symbols.

[out] phico

Typ: HICON*

Wenn diese Funktion zurückgibt, enthält einen Zeiger auf das Handle des geladenen Symbols.

Rückgabewert

Typ: HRESULT

Gibt bei erfolgreicher Ausführung S_OK zurück, andernfalls ein Fehler, einschließlich des folgenden Werts.

Rückgabecode	Beschreibung
E_INVALIDARG	Der Inhalt des Puffers, auf den von pszName verwiesen wird, entspricht keiner der erwarteten Interpretationen.

Hinweise

LoadIconMetric ähnelt LoadIcon, verfügt jedoch über die Möglichkeit, die Symbolmetrik anzugeben. Es wird anstelle von LoadIcon verwendet, wenn die aufrufende Anwendung ein hochwertiges Symbol sicherstellen möchte. Dies ist besonders nützlich in Situationen mit hohen Dpi-Werten (Dots per Inch).

Symbole werden wie folgt extrahiert oder erstellt.

Wenn eine genaue Größengleichung in der Ressource gefunden wird, wird dieses Symbol verwendet.
Wenn eine genaue Größenabgleichung nicht gefunden werden kann und ein größeres Symbol verfügbar ist, wird ein neues Symbol erstellt, indem die größere Version auf die gewünschte Größe herunterskaliert wird.
Wenn eine genaue Größeneinstimmung nicht gefunden werden kann und kein größeres Symbol verfügbar ist, wird ein neues Symbol erstellt, indem ein kleineres Symbol auf die gewünschte Größe skaliert wird.

Hier werden vergleichende Aufrufe für LoadIconMetric und LoadIcon angezeigt.

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

// Or...

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

Die Anwendung ist für den Aufruf von DestroyIcon auf dem abgerufenen Symbol verantwortlich.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	commctrl.h
Bibliothek	Comctl32.lib
DLL	Comctl32.dll

Freigeben über