Freigeben über


LoadImageA-Funktion (winuser.h)

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 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 Instanzhandle (HINSTANCE), z. B. das Anwendungsinstanzhandle, das durch den Systemfunktionsaufruf von WinMain verfügbar gemacht wird, und ein Modulhandle (HMODULE) dasselbe sind.

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

[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 Imageressource im hInst-Modul an.

Wenn die Imageressource anhand des Namens aus dem Modul geladen werden soll, ist der Name-Parameter ein Zeiger auf eine Zeichenfolge mit NULL-Beendigung, die den Namen der Imageressource enthält.

Wenn die Bildressource von der Ordnungszahl 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 und den LR_SHARED enthält, gibt der Name das zu ladende vordefinierte Bild 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-Bildbezeichnerkonstanten an die LoadImage-Funktion zu übergeben. Um beispielsweise den OCR_NORMAL Cursor zu laden, übergeben Sie MAKEINTRESOURCE(OCR_NORMAL) als name-Parameter, 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, c:\myicon.icoz. B. .

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

[in] type

Typ: UINT

Der Typ des zu ladenden Bilds.

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 null 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 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-Abschnittsbitmap 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 bedeutet, ist "nicht LR_MONOCHROME".
LR_DEFAULTSIZE
0x00000040
Verwendet die von den Systemmetrikwerten für Cursor oder Symbole angegebene Breite oder Höhe, wenn die werte cxDesired oder cyDesired auf Null 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 Grautöne 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 LR_LOADTRANSPARENT - als auch LR_LOADMAP3DCOLORS-Werte enthält, hat LR_LOADTRANSPARENT Vorrang. Der Farbtabelleneintrag wird jedoch durch COLOR_3DFACE anstelle von 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, wird das Image durch einen zweiten Aufruf von LoadImage für dieselbe Ressource erneut geladen und ein anderes Handle zurückgegeben.

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

Anforderung Wert
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)

Siehe auch

Konzept

CopyImage

GetSystemMetrics

LoadBitmap

LoadCursor

LoadIcon

Andere Ressourcen

Referenz

Ressourcen