LoadImageW-Funktion (winuser.h)

Lädt ein Symbol, einen Cursor, einen animierten Cursor oder eine Bitmap.

Syntax

HANDLE LoadImageW(
  [in, optional] HINSTANCE hInst,
  [in]           LPCWSTR   name,
  [in]           UINT      type,
  [in]           int       cx,
  [in]           int       cy,
  [in]           UINT      fuLoad
);

Parameter

[in, optional] hInst

Typ: HINSTANCE-

Ein Handle für das Modul einer DLL oder ausführbaren Datei (.exe), die das zu ladende Bild enthält. Weitere Informationen finden Sie unter GetModuleHandle. Beachten Sie, dass ab 32-Bit-Windows Ein Instanzhandle (HINSTANCE), z. B. das Anwendungsinstanzhandle, das vom Systemfunktionsaufruf von WinMain verfügbar gemacht wird, und ein Modulhandle (HMODULE) sind identisch.

Um ein vordefiniertes Bild oder eine eigenständige Ressource (Symbol-, Cursor- oder Bitmapdatei) zu laden, legen Sie diesen Parameter auf NULL fest.

[in] name

Typ: LPCTSTR-

Das zu ladende Bild.

Wenn der hInst-Parameter ungleich NULL ist und der fuLoad-ParameterLR_LOADFROMFILE ausgelassen, gibt der Name die Bildressource im hInst-Modul an.

Wenn die Bildressource anhand des Namens aus dem Modul geladen werden soll, ist der Nameparameter ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Namen der Bildressource enthält.

Wenn die Bildressource vom Modul geladen werden soll, verwenden Sie das MAKEINTRESOURCE-Makro , um das Bild-Ordinal in ein Formular zu konvertieren, das an die LoadImage-Funktion übergeben werden kann.

Wenn der parameter hInstNULL ist und der fuLoad-Parameter den LR_LOADFROMFILE Wert ausgelassen und den LR_SHARED enthält, gibt der Name das zu ladende vordefinierte Bild an.

Die vordefinierten Bildbezeichner sind definiert Winuser.h und weisen die folgenden Präfixe auf:

Präfix Bedeutung
OBM_ OEM-Bitmaps. Verwenden Sie das MAKEINTRESOURCE-Makro , um diese zu übergeben.
OIC_ OEM-Symbole. Verwenden Sie das MAKEINTRESOURCE-Makro , um diese zu übergeben.
OCR_ OEM-Cursor. Verwenden Sie das MAKEINTRESOURCE-Makro , um diese zu übergeben.
IDI_ Standardsymbole
IDC_ Standardcursor

Verwenden Sie das MAKEINTRESOURCE-Makro, um OEM-Bildbezeichner konstanten an die LoadImage-Funktion zu übergeben. Um z. B. den OCR_NORMAL Cursor zu laden, übergeben Sie MAKEINTRESOURCE(OCR_NORMAL) als NamensparameterNULL als hInst-Parameter und LR_SHARED als eines der Flags an den FuLoad-Parameter .

Wenn der hInst-ParameterNULL ist und der FuLoad-Parameter den LR_LOADFROMFILE Wert enthält, ist der Name der Datei, die die eigenständige Ressource (Symbol, Cursor oder Bitmapdatei) enthält , c:\myicon.icoz. B. . .

Weitere Informationen finden Sie im Abschnitt "Hinweise" weiter unten.

[in] type

Typ: UINT

Der Typ des zu ladenden Bilds.

Dieser Parameter kann einen der folgenden -Werte aufweisen:

Wert Bedeutung
IMAGE_BITMAP Lädt eine Bitmap.
IMAGE_CURSOR Lädt einen Cursor.
IMAGE_ICON Lädt ein Symbol.

[in] cx

Typ: int

Die Breite des Symbols oder Cursors in Pixel. Wenn dieser Parameter null ist und der FuLoad-ParameterLR_DEFAULTSIZE ist, verwendet die Funktion den SM_CXICON oder SM_CXCURSOR Systemmetrikwert, um die Breite festzulegen. Wenn dieser Parameter null ist und LR_DEFAULTSIZE nicht verwendet wird, verwendet die Funktion die tatsächliche Ressourcenbreite.

[in] cy

Typ: int

Die Höhe des Symbols oder Cursors in Pixel. Wenn dieser Parameter null ist und der FuLoad-ParameterLR_DEFAULTSIZE ist, verwendet die Funktion den SM_CYICON - oder SM_CYCURSOR Systemmetrikwert, um die Höhe festzulegen. Wenn dieser Parameter null ist und LR_DEFAULTSIZE nicht verwendet wird, verwendet die Funktion die tatsächliche Ressourcenhöhe.

[in] fuLoad

Typ: UINT

Dieser Parameter kann einen der folgenden Werte annehmen.

Wert Bedeutung
LR_CREATEDIBSECTION
0x00002000
 Wenn der uType-ParameterIMAGE_BITMAP angibt, gibt die Funktion anstelle einer kompatiblen Bitmap eine DIB-Abschnittsbitmap zurück. Dieses Kennzeichen ist nützlich, um eine Bitmap zu laden, ohne sie den Farben des Anzeigegeräts zuzuordnen.
LR_DEFAULTCOLOR
0x00000000
 Die Standardkennzeichnung; es tut nichts. Alles, was bedeutet, ist "nicht LR_MONOCHROME".
LR_DEFAULTSIZE
0x00000040
 Verwendet die durch die Systemmetrikwerte für Cursor oder Symbole angegebene Breite oder Höhe, wenn die Cx - oder Cy-Werte auf Null festgelegt sind. Wenn dieses Flag nicht angegeben ist und cx und cy auf Null festgelegt ist, verwendet die Funktion die tatsächliche Ressourcengröße. Wenn die Ressource mehrere Bilder enthält, verwendet die Funktion die Größe des ersten Bilds.
LR_LOADFROMFILE
0x00000010
 Lädt das eigenständige Bild aus der Durchnamen angegebenen Datei (Symbol, Cursor oder Bitmapdatei).
LR_LOADMAP3DCOLORS
0x00001000
 Sucht die Farbtabelle nach dem Bild und ersetzt die folgenden Graustufen durch die entsprechende 3D-Farbe.
  • Dk Gray, RGB(128,128,128) mit COLOR_3DSHADOW
  • Grau, RGB(192,192,192) mit COLOR_3DFACE
  • Lt Gray, RGB(223,223,223) mit COLOR_3DLIGHT
Verwenden Sie diese Option nicht, wenn Sie eine Bitmap mit einer Farbtiefe von mehr als 8 TB laden.
LR_LOADTRANSPARENT
0x00000020
 Ruft den Farbwert des ersten Pixels im Bild ab und ersetzt den entsprechenden Eintrag in der Farbtabelle durch die Standardfensterfarbe (COLOR_WINDOW). Alle Pixel in dem Bild, das diesen Eintrag verwendet, werden zur Standardfensterfarbe. Dieser Wert gilt nur für Bilder mit entsprechenden Farbtabellen.

Verwenden Sie diese Option nicht, wenn Sie eine Bitmap mit einer Farbtiefe von mehr als 8 TB laden.

Wenn fuLoad sowohl die werte LR_LOADTRANSPARENT als auch LR_LOADMAP3DCOLORS enthält, hat LR_LOADTRANSPARENT Vorrang. Der Farbtabelleneintrag wird jedoch durch COLOR_3DFACE und nicht durch COLOR_WINDOW ersetzt.
LR_MONOCHROME
0x00000001
 Lädt das Bild in Schwarzweiß.
LR_SHARED
0x00008000
 Teilt das Bildhandle, wenn das Bild mehrmals geladen wird. Wenn LR_SHARED nicht festgelegt ist, lädt ein zweiter Aufruf von LoadImage für dieselbe Ressource das Bild erneut und gibt ein anderes Handle zurück.

Wenn Sie dieses Kennzeichen verwenden, zerstört das System die Ressource, wenn sie nicht mehr benötigt wird.

Verwenden Sie LR_SHARED nicht für Bilder mit nicht standardmäßigen Größen, die sich nach dem Laden ändern können oder aus einer Datei geladen werden.

Beim Laden eines Systemsymbols oder Cursors müssen Sie LR_SHARED verwenden, oder die Funktion kann die Ressource nicht laden.

Diese Funktion findet das erste Bild im Cache mit dem angeforderten Ressourcennamen, unabhängig von der angeforderten Größe.
LR_VGACOLOR
0x00000080
 Verwendet echte VGA-Farben.

Rückgabewert

Typ: HANDLE

Wenn die Funktion erfolgreich ist, ist der Rückgabewert das Handle des neu geladenen Images.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen abzurufen.

Bemerkungen

Wenn IS_INTRESOURCE(Name) WAHR ist, gibt der Name den ganzzahligen Bezeichner der angegebenen Ressource an. Andernfalls handelt es sich um einen Zeiger auf eine mit Null beendete Zeichenfolge.

Wenn das erste Zeichen der Zeichenfolge ein Nummernzeichen (#) ist, stellen die verbleibenden Zeichen eine Dezimalzahl dar, die den ganzzahligen Bezeichner der Ressource angibt. Beispielsweise stellt die Zeichenfolge "#258" den Bezeichner 258 dar.

Wenn Sie mit der Verwendung einer Bitmap, eines Cursors oder eines Symbols fertig sind, das Sie geladen haben, ohne das kennzeichen LR_SHARED anzugeben, können Sie den zugeordneten Speicher freigeben, indem Sie eine der Funktionen in der folgenden Tabelle aufrufen.

Resource Release-Funktion
Bitmap DeleteObject
Cursor DestroyCursor
Icon DestroyIcon
 

Das System löscht diese Ressourcen automatisch, wenn der Prozess, der sie erstellt hat, beendet wird; Das Aufrufen der entsprechenden Funktion spart jedoch Speicher und verringert die Größe des Arbeitssatzes des Prozesses.

Beispiele

Ein Beispiel finden Sie unter Verwenden von Fensterklassen.

Note

Der winuser.h-Header definiert LoadImage als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Requirements

Anforderung Wert
Mindestens unterstützter Client Windows 2000 Professional [nur Desktop-Apps]
Mindestanforderungen für unterstützte Server Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Header winuser.h (enthalten Windows.h)
Bibliothek User32.lib
DLL User32.dll
API-Satz ext-ms-win-ntuser-gui-l1-1-0 (eingeführt in Windows 8)

Siehe auch

Konzeptionelle

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

andere Ressourcen

Referenz

Ressourcen

  • Last updated on