Fungsi LoadImageW (winuser.h)

Artikel
01/27/2024

Memuat ikon, kursor, kursor animasi, atau bitmap.

Sintaks

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

Jenis: HINSTANCE

Handel ke modul DLL atau executable (.exe) yang berisi gambar yang akan dimuat. Untuk informasi selengkapnya, lihat GetModuleHandle. Perhatikan bahwa pada Windows 32-bit, handel instans (HINSTANCE), seperti handel instans aplikasi yang diekspos oleh panggilan fungsi sistem WinMain, dan handel modul (HMODULE) adalah hal yang sama.

Untuk memuat gambar yang telah ditentukan sebelumnya atau sumber daya mandiri (ikon, kursor, atau file bitmap), atur parameter ini ke NULL.

[in] name

Jenis: LPCTSTR

Gambar yang akan dimuat.

Jika parameter hInstnon-NULL dan parameter fuLoad menghilangkan LR_LOADFROMFILE, nama menentukan sumber daya gambar dalam modul hInst .

Jika sumber daya gambar akan dimuat berdasarkan nama dari modul, parameter nama adalah penunjuk ke string yang dihentikan null yang berisi nama sumber daya gambar.

Jika sumber daya gambar akan dimuat dengan ordinal dari modul, gunakan makro MAKEINTRESOURCE untuk mengonversi ordinal gambar menjadi formulir yang dapat diteruskan ke fungsi LoadImage .

Jika parameter hInst adalah NULL dan parameter fuLoad menghilangkan nilai LR_LOADFROMFILE , nama menentukan gambar yang telah ditentukan untuk dimuat.

Pengidentifikasi gambar yang telah ditentukan sebelumnya didefinisikan dalam Winuser.h dan memiliki awalan berikut:

Prefiks	Makna
OBM_	Bitmap OEM. Gunakan makro MAKEINTRESOURCE untuk meneruskan ini.
OKI_	Ikon OEM. Gunakan makro MAKEINTRESOURCE untuk meneruskan ini.
OCR_	Kursor OEM. Gunakan makro MAKEINTRESOURCE untuk meneruskan ini.
IDI_	Ikon standar
IDC_	Kursor standar

Untuk meneruskan konstanta pengidentifikasi gambar OEM ke fungsi LoadImage , gunakan makro MAKEINTRESOURCE . Misalnya, untuk memuat kursor OCR_NORMAL , teruskan MAKEINTRESOURCE(OCR_NORMAL) sebagai parameter nama , NULL sebagai parameter hInst , dan LR_SHARED sebagai salah satu bendera ke parameter fuLoad .

Jika parameter hInst adalah NULL dan parameter fuLoad menyertakan nilai LR_LOADFROMFILE , nama adalah nama file yang berisi sumber daya mandiri (ikon, kursor, atau file bitmap), - misalnya, c:\myicon.ico.

Untuk informasi selengkapnya, lihat bagian Keterangan di bawah ini.

[in] type

Jenis: UINT

Jenis gambar yang akan dimuat.

Parameter ini bisa menjadi salah satu nilai berikut:

Nilai	Makna
IMAGE_BITMAP	Memuat bitmap.
IMAGE_CURSOR	Memuat kursor.
IMAGE_ICON	Memuat ikon.

[in] cx

Jenis: int

Lebar, dalam piksel, ikon atau kursor. Jika parameter ini nol dan parameter fuLoadLR_DEFAULTSIZE, fungsi menggunakan nilai metrik sistem SM_CXICON atau SM_CXCURSOR untuk mengatur lebar. Jika parameter ini nol dan LR_DEFAULTSIZE tidak digunakan, fungsi menggunakan lebar sumber daya aktual.

[in] cy

Jenis: int

Tinggi, dalam piksel, ikon atau kursor. Jika parameter ini nol dan parameter fuLoadLR_DEFAULTSIZE, fungsi menggunakan nilai metrik sistem SM_CYICON atau SM_CYCURSOR untuk mengatur tinggi. Jika parameter ini nol dan LR_DEFAULTSIZE tidak digunakan, fungsi menggunakan tinggi sumber daya aktual.

[in] fuLoad

Jenis: UINT

Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
LR_CREATEDIBSECTION 0x00002000	Ketika parameter uType menentukan IMAGE_BITMAP, menyebabkan fungsi mengembalikan bitmap bagian DIB daripada bitmap yang kompatibel. Bendera ini berguna untuk memuat bitmap tanpa memetakannya ke warna perangkat tampilan.
LR_DEFAULTCOLOR 0x00000000	Bendera default; itu tidak melakukan apa-apa. Semua itu berarti "tidak LR_MONOCHROME".
LR_DEFAULTSIZE 0x00000040	Menggunakan lebar atau tinggi yang ditentukan oleh nilai metrik sistem untuk kursor atau ikon, jika nilai cxDesired atau cyDesired diatur ke nol. Jika bendera ini tidak ditentukan dan cxDesired dan cyDesired diatur ke nol, fungsi menggunakan ukuran sumber daya aktual. Jika sumber daya berisi beberapa gambar, fungsi menggunakan ukuran gambar pertama.
LR_LOADFROMFILE 0x00000010	Memuat gambar mandiri dari file yang ditentukan berdasarkan nama (ikon, kursor, atau file bitmap).
LR_LOADMAP3DCOLORS 0x00001000	Mencari tabel warna untuk gambar dan mengganti nuansa abu-abu berikut dengan warna 3-D yang sesuai. Dk Gray, RGB(128,128,128) dengan COLOR_3DSHADOW Abu-abu, RGB(192.192.192) dengan COLOR_3DFACE Lt Gray, RGB(223.223.223) dengan COLOR_3DLIGHT Jangan gunakan opsi ini jika Anda memuat bitmap dengan kedalaman warna yang lebih besar dari 8bpp.
LR_LOADTRANSPARENT 0x00000020	Mengambil nilai warna piksel pertama dalam gambar dan mengganti entri terkait dalam tabel warna dengan warna jendela default (COLOR_WINDOW). Semua piksel dalam gambar yang menggunakan entri tersebut menjadi warna jendela default. Nilai ini hanya berlaku untuk gambar yang memiliki tabel warna terkait. Jangan gunakan opsi ini jika Anda memuat bitmap dengan kedalaman warna yang lebih besar dari 8bpp. Jika fuLoad menyertakan nilai LR_LOADTRANSPARENT dan LR_LOADMAP3DCOLORS , LR_LOADTRANSPARENT diutamakan. Namun, entri tabel warna diganti dengan COLOR_3DFACE daripada COLOR_WINDOW.
LR_MONOCHROME 0x00000001	Memuat gambar dalam warna hitam dan putih.
LR_SHARED 0x00008000	Berbagi handel gambar jika gambar dimuat beberapa kali. Jika LR_SHARED tidak diatur, panggilan kedua ke LoadImage untuk sumber daya yang sama akan memuat gambar lagi dan mengembalikan handel yang berbeda. Ketika Anda menggunakan bendera ini, sistem akan menghancurkan sumber daya ketika tidak lagi diperlukan. Jangan gunakan LR_SHARED untuk gambar yang memiliki ukuran non-standar, yang dapat berubah setelah dimuat, atau yang dimuat dari file. Saat memuat ikon sistem atau kursor, Anda harus menggunakan LR_SHARED atau fungsi akan gagal memuat sumber daya. Fungsi ini menemukan gambar pertama dalam cache dengan nama sumber daya yang diminta, terlepas dari ukuran yang diminta.
LR_VGACOLOR 0x00000080	Menggunakan warna VGA yang benar.

Mengembalikan nilai

Jenis: HANDEL

Jika fungsi berhasil, nilai yang dikembalikan adalah handel dari gambar yang baru dimuat.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Jika IS_INTRESOURCE(nama) TRUE, maka nama menentukan pengidentifikasi bilangan bulat dari sumber daya yang diberikan. Jika tidak, ini adalah penunjuk ke string yang dihentikan null.

Jika karakter pertama dari string adalah tanda paund (#), maka karakter yang tersisa mewakili angka desimal yang menentukan pengidentifikasi bilangan bulat sumber daya. Misalnya, string "#258" mewakili pengidentifikasi 258.

Setelah selesai menggunakan bitmap, kursor, atau ikon yang Anda muat tanpa menentukan bendera LR_SHARED , Anda dapat melepaskan memori terkait dengan memanggil salah satu fungsi dalam tabel berikut.

Sumber daya	Fungsi rilis
Bitmap	DeleteObject
Kursor	DestroyCursor
Ikon	DestroyIcon

Sistem secara otomatis menghapus sumber daya ini ketika proses yang membuatnya berakhir; namun, memanggil fungsi yang sesuai akan menghemat memori dan mengurangi ukuran rangkaian kerja proses.

Contoh

Misalnya, lihat Menggunakan Kelas Jendela.

Catatan

Header winuser.h mendefinisikan LoadImage sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-ntuser-gui-l1-1-0 (diperkenalkan dalam Windows 8)