LoadImageA-Funktion (winuser.h)

Artikel
01/27/2024

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

Syntax

HANDLE LoadImageA(
  [in, optional] HINSTANCE hInst,
  [in]           LPCSTR    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 einer ausführbaren Datei (.exe), die das zu ladende Image enthält. Weitere Informationen finden Sie unter GetModuleHandle. Beachten Sie, dass ab 32-Bit-Windows ein instance Handle (HINSTANCE) wie die Anwendung instance Handle, die durch den Systemfunktionsaufruf von WinMain verfügbar gemacht wird, und ein Modulhandle (HMODULE) dasselbe sind.

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 nicht NULL ist und der fuLoad-ParameterLR_LOADFROMFILE auslässt, gibt name die Bildressource im hInst-Modul an.

Wenn die Imageressource nach Name aus dem Modul geladen werden soll, ist der Name-Parameter ein Zeiger auf eine null-beendete Zeichenfolge, die den Namen der Imageressource enthält.

Wenn die Bildressource von ordinal aus dem Modul geladen werden soll, verwenden Sie das MAKEINTRESOURCE-Makro , um die Ordnungszahl des Bilds in ein Formular zu konvertieren, das an die LoadImage-Funktion übergeben werden kann.

Wenn der hInst-ParameterNULL ist und der fuLoad-Parameter den LR_LOADFROMFILE-Wert auslässt, gibt der Name das vordefinierte zu ladende Image an.

Die vordefinierten Bildbezeichner sind in Winuser.h definiert 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-Imagebezeichnerkonstanten an die LoadImage-Funktion zu übergeben. Um beispielsweise den OCR_NORMAL Cursor zu laden, übergeben Sie MAKEINTRESOURCE(OCR_NORMAL) als Namensparameter , NULL 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 name der Name der Datei, die die eigenständige Ressource (Symbol, Cursor oder Bitmapdatei) enthält, z. B c:\myicon.ico. .

Weitere Informationen finden Sie weiter unten im Abschnitt Hinweise.

[in] type

Typ: UINT

Der Typ des zu ladenden Images.

Dieser Parameter kann einer der folgenden Werte sein:

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 0 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 oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
LR_CREATEDIBSECTION 0x00002000	Wenn der uType-ParameterIMAGE_BITMAP angibt, gibt die Funktion anstelle einer kompatiblen Bitmap eine DIB-Abschnittsbitbitbit zurück. Dieses Flag ist nützlich, um eine Bitmap zu laden, ohne sie den Farben des Anzeigegeräts zuzuordnen.
LR_DEFAULTCOLOR 0x00000000	Das Standardflag; es tut nichts. Alles, was es bedeutet, ist "nicht LR_MONOCHROME".
LR_DEFAULTSIZE 0x00000040	Verwendet die Breite oder Höhe, die durch die Systemmetrikwerte für Cursor oder Symbole angegeben wird, wenn die Werte cxDesired oder cyDesired auf 0 festgelegt sind. Wenn dieses Flag nicht angegeben ist und cxDesired und cyDesired auf Null festgelegt sind, 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 durch den Namen angegebenen Datei (Symbol, Cursor oder Bitmapdatei).
LR_LOADMAP3DCOLORS 0x00001000	Durchsucht die Farbtabelle für das 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 bpp 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 im Bild, die diesen Eintrag verwenden, werden zur Standardfarbe des Fensters. 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 bpp 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	Gibt das Imagehandle weiter, wenn das Image mehrmals geladen wird. Wenn LR_SHARED nicht festgelegt ist, lädt ein zweiter Aufruf von LoadImage für dieselbe Ressource das Image erneut und gibt ein anderes Handle zurück. Wenn Sie dieses Flag 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 die aus einer Datei geladen werden. Beim Laden eines Systemsymbols oder Cursors müssen Sie LR_SHARED verwenden, sonst kann die Funktion die Ressource nicht laden. Diese Funktion findet das erste Image 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 bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn IS_INTRESOURCE(name) true ist, gibt name den ganzzahligen Bezeichner der angegebenen Ressource an. Andernfalls handelt es sich um einen Zeiger auf eine NULL-Zeichenfolge. Wenn das erste Zeichen der Zeichenfolge ein Pfundzeichen (#) ist, stellen die restlichen Zeichen eine Dezimalzahl dar, die den ganzzahligen Bezeichner der Ressource angibt. Die Zeichenfolge "#258" stellt beispielsweise den Bezeichner 258 dar.

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

Resource	Release-Funktion
Bitmap	DeleteObject
Cursor	DestroyCursor
Symbol	DestroyIcon

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

Beispiele

Ein Beispiel finden Sie unter Verwenden von Fensterklassen.

Hinweis

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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (einschließlich Windows.h)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-gui-l1-1-0 (eingeführt in Windows 8)