Fungsi MessageBoxW (winuser.h)

Artikel
06/08/2023

Menampilkan kotak dialog modal yang berisi ikon sistem, sekumpulan tombol, dan pesan khusus aplikasi singkat, seperti informasi status atau kesalahan. Kotak pesan mengembalikan nilai bilangan bulat yang menunjukkan tombol mana yang diklik pengguna.

Sintaks

int MessageBoxW(
  [in, optional] HWND    hWnd,
  [in, optional] LPCWSTR lpText,
  [in, optional] LPCWSTR lpCaption,
  [in]           UINT    uType
);

Parameter

[in, optional] hWnd

Jenis: HWND

Handel ke jendela pemilik kotak pesan yang akan dibuat. Jika parameter ini NULL, kotak pesan tidak memiliki jendela pemilik.

[in, optional] lpText

Jenis: LPCTSTR

Pesan yang akan ditampilkan. Jika string terdiri dari lebih dari satu baris, Anda dapat memisahkan garis menggunakan karakter pengembalian pengangkutan dan/atau linefeed di antara setiap baris.

[in, optional] lpCaption

Jenis: LPCTSTR

Judul kotak dialog. Jika parameter ini NULL, judul defaultnya adalah Kesalahan.

[in] uType

Jenis: UINT

Konten dan perilaku kotak dialog. Parameter ini bisa menjadi kombinasi bendera dari grup bendera berikut.

Untuk menunjukkan tombol yang ditampilkan dalam kotak pesan, tentukan salah satu nilai berikut ini.

Nilai	Makna
MB_ABORTRETRYIGNORE 0x00000002L	Kotak pesan berisi tiga tombol dorong: Batalkan, Coba Lagi, dan Abaikan.
MB_CANCELTRYCONTINUE 0x00000006L	Kotak pesan berisi tiga tombol dorong: Batal, Coba Lagi, Lanjutkan. Gunakan tipe kotak pesan ini alih-alih MB_ABORTRETRYIGNORE.
MB_HELP 0x00004000L	Menambahkan tombol Bantuan ke kotak pesan. Saat pengguna mengklik tombol Bantuan atau menekan F1, sistem mengirim pesan WM_HELP kepada pemilik.
MB_OK 0x00000000L	Kotak pesan berisi satu tombol pendorongan: OK. Ini adalah default.
MB_OKCANCEL 0x00000001L	Kotak pesan berisi dua tombol dorong: OK dan Batal.
MB_RETRYCANCEL 0x00000005L	Kotak pesan berisi dua tombol pendorongan: Coba Lagi dan Batalkan.
MB_YESNO 0x00000004L	Kotak pesan berisi dua tombol dorong: Ya dan Tidak.
MB_YESNOCANCEL 0x00000003L	Kotak pesan berisi tiga tombol dorong: Ya, Tidak, dan Batal.

Untuk menampilkan ikon dalam kotak pesan, tentukan salah satu nilai berikut ini.

Nilai	Makna
MB_ICONEXCLAMATION 0x00000030L	Ikon tanda seru muncul di kotak pesan.
MB_ICONWARNING 0x00000030L	Ikon tanda seru muncul di kotak pesan.
MB_ICONINFORMATION 0x00000040L	Ikon yang terdiri dari huruf kecil i dalam lingkaran muncul di kotak pesan.
MB_ICONASTERISK 0x00000040L	Ikon yang terdiri dari huruf kecil i dalam lingkaran muncul di kotak pesan.
MB_ICONQUESTION 0x00000020L	Ikon tanda tanya muncul di kotak pesan. Ikon pesan tanda tanya tidak lagi direkomendasikan karena tidak secara jelas mewakili jenis pesan tertentu dan karena pembuatan frasa pesan sebagai pertanyaan dapat berlaku untuk jenis pesan apa pun. Selain itu, pengguna dapat membingungkan tanda tanya simbol pesan dengan informasi Bantuan. Oleh karena itu, jangan gunakan simbol pesan tanda tanya ini dalam kotak pesan Anda. Sistem terus mendukung penyertaannya hanya untuk kompatibilitas mundur.
MB_ICONSTOP 0x00000010L	Ikon stop-sign muncul di kotak pesan.
MB_ICONERROR 0x00000010L	Ikon stop-sign muncul di kotak pesan.
MB_ICONHAND 0x00000010L	Ikon stop-sign muncul di kotak pesan.

Untuk menunjukkan tombol default, tentukan salah satu nilai berikut.

Nilai	Makna
MB_DEFBUTTON1 0x00000000L	Tombol pertama adalah tombol default. MB_DEFBUTTON1 adalah default kecuali MB_DEFBUTTON2, MB_DEFBUTTON3, atau MB_DEFBUTTON4 ditentukan.
MB_DEFBUTTON2 0x00000100L	Tombol kedua adalah tombol default.
MB_DEFBUTTON3 0x00000200L	Tombol ketiga adalah tombol default.
MB_DEFBUTTON4 0x00000300L	Tombol keempat adalah tombol default.

Untuk menunjukkan modalitas kotak dialog, tentukan salah satu nilai berikut.

Nilai	Makna
MB_APPLMODAL 0x00000000L	Pengguna harus merespons kotak pesan sebelum melanjutkan pekerjaan di jendela yang diidentifikasi oleh parameter hWnd . Namun, pengguna dapat berpindah ke jendela utas lain dan bekerja di jendela tersebut. Tergantung pada hierarki jendela dalam aplikasi, pengguna mungkin dapat berpindah ke jendela lain dalam utas. Semua jendela anak dari induk kotak pesan secara otomatis dinonaktifkan, tetapi jendela pop-up tidak. MB_APPLMODAL adalah default jika tidak ada MB_SYSTEMMODAL atau MB_TASKMODAL yang ditentukan.
MB_SYSTEMMODAL 0x00001000L	Sama seperti MB_APPLMODAL kecuali bahwa kotak pesan memiliki gaya WS_EX_TOPMOST . Gunakan kotak pesan modal sistem untuk memberi tahu pengguna tentang kesalahan serius dan berpotensi merusak yang memerlukan perhatian segera (misalnya, kehabisan memori). Bendera ini tidak berpengaruh pada kemampuan pengguna untuk berinteraksi dengan jendela selain yang terkait dengan hWnd.
MB_TASKMODAL 0x00002000L	Sama seperti MB_APPLMODAL kecuali bahwa semua jendela tingkat atas milik utas saat ini dinonaktifkan jika parameter hWndadalah NULL. Gunakan bendera ini ketika aplikasi atau pustaka panggilan tidak memiliki handel jendela yang tersedia tetapi masih perlu mencegah input ke jendela lain di utas panggilan tanpa menangguhkan utas lain.

Nilai

Makna

MB_APPLMODAL
0x00000000L

Pengguna harus merespons kotak pesan sebelum melanjutkan pekerjaan di jendela yang diidentifikasi oleh parameter hWnd . Namun, pengguna dapat berpindah ke jendela utas lain dan bekerja di jendela tersebut.

Tergantung pada hierarki jendela dalam aplikasi, pengguna mungkin dapat berpindah ke jendela lain dalam utas. Semua jendela anak dari induk kotak pesan secara otomatis dinonaktifkan, tetapi jendela pop-up tidak.

MB_APPLMODAL adalah default jika tidak ada MB_SYSTEMMODAL atau MB_TASKMODAL yang ditentukan.

MB_SYSTEMMODAL
0x00001000L

Sama seperti MB_APPLMODAL kecuali bahwa kotak pesan memiliki gaya WS_EX_TOPMOST . Gunakan kotak pesan modal sistem untuk memberi tahu pengguna tentang kesalahan serius dan berpotensi merusak yang memerlukan perhatian segera (misalnya, kehabisan memori). Bendera ini tidak berpengaruh pada kemampuan pengguna untuk berinteraksi dengan jendela selain yang terkait dengan hWnd.

MB_TASKMODAL
0x00002000L

Sama seperti MB_APPLMODAL kecuali bahwa semua jendela tingkat atas milik utas saat ini dinonaktifkan jika parameter hWndadalah NULL. Gunakan bendera ini ketika aplikasi atau pustaka panggilan tidak memiliki handel jendela yang tersedia tetapi masih perlu mencegah input ke jendela lain di utas panggilan tanpa menangguhkan utas lain.

Untuk menentukan opsi lain, gunakan satu atau beberapa nilai berikut.

Nilai	Makna
MB_DEFAULT_DESKTOP_ONLY 0x00020000L	Sama seperti desktop stasiun jendela interaktif. Untuk informasi selengkapnya, lihat Window Stations. Jika desktop input saat ini bukan desktop default, MessageBox tidak kembali hingga pengguna beralih ke desktop default.
MB_RIGHT 0x00080000L	Teks dibenarkan kanan.
MB_RTLREADING 0x00100000L	Menampilkan pesan dan caption teks menggunakan urutan pembacaan kanan-ke-kiri pada sistem Ibrani dan Arab.
MB_SETFOREGROUND 0x00010000L	Kotak pesan menjadi jendela latar depan. Secara internal, sistem memanggil fungsi SetForegroundWindow untuk kotak pesan.
MB_TOPMOST 0x00040000L	Kotak pesan dibuat dengan gaya jendela WS_EX_TOPMOST .
MB_SERVICE_NOTIFICATION 0x00200000L	Pemanggil adalah layanan yang memberi tahu pengguna tentang suatu peristiwa. Fungsi ini menampilkan kotak pesan pada desktop aktif saat ini, meskipun tidak ada pengguna yang masuk ke komputer. Layanan Terminal: Jika utas panggilan memiliki token peniruan, fungsi mengarahkan kotak pesan ke sesi yang ditentukan dalam token peniruan. Jika bendera ini diatur, parameter hWnd harus NULL. Ini agar kotak pesan dapat muncul di desktop selain desktop yang sesuai dengan hWnd. Untuk informasi tentang pertimbangan keamanan sehubungan dengan penggunaan bendera ini, lihat Layanan Interaktif. Secara khusus, ketahuilah bahwa bendera ini dapat menghasilkan konten interaktif pada desktop terkunci dan karenanya harus digunakan hanya untuk serangkaian skenario yang sangat terbatas, seperti kelelahan sumber daya.

Mengembalikan nilai

Jenis: int

Jika kotak pesan memiliki tombol Batal , fungsi mengembalikan nilai IDCANCEL jika tombol ESC ditekan atau tombol Batal dipilih. Jika kotak pesan tidak memiliki tombol Batal , menekan ESC tidak akan berpengaruh - kecuali ada tombol MB_OK. Jika tombol MB_OK ditampilkan dan pengguna menekan ESC, nilai yang dikembalikan adalah IDOK.

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

Jika fungsi berhasil, nilai yang dikembalikan adalah salah satu nilai item menu berikut.

Mengembalikan kode/nilai	Deskripsi
IDABORT 3	Tombol Batalkan dipilih.
IDCANCEL 2	Tombol Batal dipilih.
IDCONTINUE 11	Tombol Lanjutkan dipilih.
IDIGNORE 5	Tombol Abaikan dipilih.
IDNO 7	Tombol Tidak dipilih.
IDOK 1	Tombol OK dipilih.
IDRETRY 4	Tombol Coba Lagi dipilih.
IDTRYAGAIN 10	Tombol Coba Lagi dipilih.
IDYES 6	Tombol Ya dipilih.

Keterangan

Ikon sistem berikut dapat digunakan dalam kotak pesan dengan mengatur parameter uType ke nilai bendera yang sesuai.

Ikon	Nilai bendera
	MB_ICONHAND, MB_ICONSTOP, atau MB_ICONERROR
	MB_ICONQUESTION
	MB_ICONEXCLAMATION atau MB_ICONWARNING
	MB_ICONASTERISK atau MB_ICONINFORMATION

Menambahkan dua tanda kanan-ke-kiri (RLM), diwakili oleh karakter pemformatan Unicode U+200F, di awal string tampilan MessageBox ditafsirkan oleh mesin penyajian MessageBox sehingga menyebabkan urutan pembacaan MessageBox dirender sebagai kanan-ke-kiri (RTL).

Ketika Anda menggunakan kotak pesan modal sistem untuk menunjukkan bahwa sistem kehabisan memori, string yang ditunjukkan oleh parameter lpText dan lpCaption tidak boleh diambil dari file sumber daya karena upaya untuk memuat sumber daya mungkin gagal.

Jika Anda membuat kotak pesan saat kotak dialog ada, gunakan handel ke kotak dialog sebagai parameter hWnd . Parameter hWnd tidak boleh mengidentifikasi jendela anak, seperti kontrol dalam kotak dialog.

Contoh

Dalam contoh berikut, aplikasi menampilkan kotak pesan yang meminta tindakan kepada pengguna setelah kondisi kesalahan terjadi. Kotak pesan menampilkan pesan yang menjelaskan kondisi kesalahan dan cara mengatasinya. Gaya MB_CANCELTRYCONTINUE mengarahkan MessageBox untuk menyediakan tiga tombol yang dapat dipilih pengguna untuk melanjutkan. Gaya MB_DEFBUTTON2 mengatur fokus default pada tombol kedua kotak pesan, dalam hal ini, tombol Coba Lagi .

int DisplayResourceNAMessageBox()
{
    int msgboxID = MessageBox(
        NULL,
        (LPCWSTR)L"Resource not available\nDo you want to try again?",
        (LPCWSTR)L"Account Details",
        MB_ICONWARNING | MB_CANCELTRYCONTINUE | MB_DEFBUTTON2
    );

    switch (msgboxID)
    {
    case IDCANCEL:
        // TODO: add code
        break;
    case IDTRYAGAIN:
        // TODO: add code
        break;
    case IDCONTINUE:
        // TODO: add code
        break;
    }

    return msgboxID;
}

Gambar berikut menunjukkan output dari contoh kode sebelumnya:

Untuk contoh kotak pesan lain, lihat Menampilkan Kotak Pesan.

Catatan

Header winuser.h mendefinisikan MessageBox 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


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-dialogbox-l1-1-0 (diperkenalkan dalam Windows 8)