LoadIconMetric-Funktion (commctrl.h)

  • Artikel

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 Symbol 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. Sie wird wie folgt interpretiert:

Wenn hinstNULL ist, kann pszName eine von zwei Dingen angeben.

  1. Der Name einer eigenständigen Symboldatei (.ico).
  2. Der Bezeichner eines vordefinierten zu ladenden Symbols. Diese Bezeichner werden erkannt:
    • IDI_APPLICATION
    • IDI_INFORMATION
    • IDI_ERROR
    • IDI_WARNING
    • IDI_SHIELD
    • IDI_QUESTION

      Um diese Konstanten an die LoadIconMetric-Funktion zu übergeben, verwenden Sie das MAKEINTRESOURCE-Makro . Um beispielsweise das symbol IDI_ERROR zu laden, übergeben Sie MAKEINTRESOURCE(IDI_ERROR) als pszName-Parameter und NULL als hinst-Parameter .

Wenn hinst nicht NULL ist, kann pszName eine von zwei Dingen angeben.

  1. Der Name der Symbolressource, wenn die Symbolressource nach Name aus dem Modul geladen werden soll.
  2. Die Ordnungszahl des Symbols, wenn die Symbolressource von ordinal aus dem Modul geladen werden soll. Diese Ordnungszahl muss mithilfe des MAKEINTRESOURCE-Makros gepackt werden.

[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.

Bemerkungen

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.

  1. Wenn eine genaue Größengleichung in der Ressource gefunden wird, wird dieses Symbol verwendet.
  2. 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.
  3. 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

   
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