Baca dalam bahasa Inggris

Bagikan melalui


Makro Peta Pesan (MFC)

Untuk mendukung peta pesan, MFC menyediakan makro berikut:

Deklarasi Peta Pesan dan Makro Demarkasi

Nama Deskripsi
DECLARE_MESSAGE_MAP Menyatakan bahwa peta pesan akan digunakan di kelas untuk memetakan pesan ke fungsi (harus digunakan dalam deklarasi kelas).
BEGIN_MESSAGE_MAP Memulai definisi peta pesan (harus digunakan dalam implementasi kelas).
BEGIN_TEMPLATE_MESSAGE_MAP Memulai definisi peta pesan pada jenis kelas yang berisi argumen templat tunggal.
END_MESSAGE_MAP Mengakhiri definisi peta pesan (harus digunakan dalam implementasi kelas).

Makro Pemetaan Pesan

Nama Deskripsi
ON_COMMAND Menunjukkan fungsi mana yang akan menangani pesan perintah tertentu.
ON_COMMAND_EX Menunjukkan fungsi mana yang akan menangani pesan perintah tertentu.
ON_CONTROL Menunjukkan fungsi mana yang akan menangani pesan pemberitahuan kontrol tertentu.
ON_MESSAGE Menunjukkan fungsi mana yang akan menangani pesan yang ditentukan pengguna.
ON_OLECMD Menunjukkan fungsi mana yang akan menangani perintah menu dari DocObject atau kontainernya.
ON_REGISTERED_MESSAGE Menunjukkan fungsi mana yang akan menangani pesan terdaftar yang ditentukan pengguna.
ON_REGISTERED_THREAD_MESSAGE Menunjukkan fungsi mana yang akan menangani pesan terdaftar yang ditentukan pengguna saat Anda memiliki CWinThread kelas.
ON_THREAD_MESSAGE Menunjukkan fungsi mana yang akan menangani pesan yang ditentukan pengguna saat Anda memiliki CWinThread kelas.
ON_UPDATE_COMMAND_UI Menunjukkan fungsi mana yang akan menangani pesan perintah pembaruan antarmuka pengguna tertentu.

Makro Rentang Peta Pesan

Nama Deskripsi
ON_COMMAND_RANGE Menunjukkan fungsi mana yang akan menangani rentang ID perintah yang ditentukan dalam dua parameter pertama ke makro.
ON_UPDATE_COMMAND_UI_RANGE Menunjukkan handler pembaruan mana yang akan menangani rentang ID perintah yang ditentukan dalam dua parameter pertama ke makro.
ON_CONTROL_RANGE Menunjukkan fungsi mana yang akan menangani pemberitahuan dari rentang ID kontrol yang ditentukan dalam parameter kedua dan ketiga ke makro. Parameter pertama adalah pesan pemberitahuan kontrol, seperti BN_CLICKED.

Untuk informasi selengkapnya tentang peta pesan, makro deklarasi dan demarkasi peta pesan, dan makro pemetaan pesan, lihat Peta Pesan dan Penanganan Pesan dan Topik Pemetaan. Untuk informasi selengkapnya tentang rentang peta pesan, lihat Penangan untuk Rentang Peta Pesan.

BEGIN_MESSAGE_MAP

Memulai definisi peta pesan Anda.

Sintaks

BEGIN_MESSAGE_MAP( theClass, baseClass )

Parameter

theClass
Menentukan nama kelas yang pesannya memetakan ini.

baseClass
Menentukan nama kelas theClassdasar .

Keterangan

Dalam file implementasi (.cpp) yang menentukan fungsi anggota untuk kelas Anda, mulai peta pesan dengan BEGIN_MESSAGE_MAP makro, lalu tambahkan entri makro untuk setiap fungsi penanganan pesan Anda, dan selesaikan peta pesan dengan END_MESSAGE_MAP makro.

Untuk informasi selengkapnya tentang peta pesan, lihat Peta Pesan

Contoh

BEGIN_MESSAGE_MAP(CMainFrame, CMDIFrameWnd)
   ON_WM_CREATE()
END_MESSAGE_MAP()

Persyaratan

Header: afxwin.h

BEGIN_TEMPLATE_MESSAGE_MAP

Memulai definisi peta pesan pada jenis kelas yang berisi argumen templat tunggal.

Sintaks

BEGIN_TEMPLATE_MESSAGE_MAP( theClass, type_name, baseClass )

Parameter

theClass
Menentukan nama kelas yang pesannya memetakan ini.

type_name
Nama parameter templat yang ditentukan untuk kelas .

baseClass
Menentukan nama kelas theClassdasar .

Keterangan

Makro ini mirip BEGIN_MESSAGE_MAP dengan makro; namun, makro ini ditujukan untuk kelas yang berisi argumen templat tunggal.

Di bagian implementasi metode kelas Anda, mulai peta pesan dengan BEGIN_TEMPLATE_MESSAGE_MAP makro; lalu tambahkan entri makro untuk setiap metode penanganan pesan seperti yang Anda lakukan untuk peta pesan standar. Seperti halnya BEGIN_MESSAGE_MAP makro, selesaikan peta pesan templat dengan END_MESSAGE_MAP makro.

Untuk informasi selengkapnya tentang menerapkan peta pesan untuk kelas templat, lihat Cara: Membuat Peta Pesan untuk Kelas Templat.

Persyaratan

Header: afxwin.h

DECLARE_MESSAGE_MAP

Menyatakan bahwa kelas mendefinisikan peta pesan. Setiap CCmdTargetkelas -turunan dalam program Anda harus menyediakan peta pesan untuk menangani pesan.

Sintaks

DECLARE_MESSAGE_MAP( )

Keterangan

DECLARE_MESSAGE_MAP Gunakan makro di akhir deklarasi kelas Anda. Kemudian, dalam file .cpp yang menentukan fungsi anggota untuk kelas, gunakan BEGIN_MESSAGE_MAP makro, entri makro untuk setiap fungsi pengelola pesan Anda, dan END_MESSAGE_MAP makro.

Catatan

Jika Anda mendeklarasikan anggota DECLARE_MESSAGE_MAPsetelah , Anda harus menentukan jenis akses baru (public, private, atau protected) untuk mereka.

Untuk informasi selengkapnya tentang peta pesan dan DECLARE_MESSAGE_MAP makro, lihat Topik Penanganan dan Pemetaan Pesan.

Contoh

class CMainFrame : public CMDIFrameWnd
{
   DECLARE_MESSAGE_MAP()

   // Remainder of class declaration omitted.

Persyaratan

Header: afxwin.h

END_MESSAGE_MAP

Mengakhiri definisi peta pesan Anda.

Sintaks

END_MESSAGE_MAP( )

Keterangan

Untuk informasi selengkapnya tentang peta pesan dan END_MESSAGE_MAP makro, lihat Topik Penanganan dan Pemetaan Pesan.

Persyaratan

Header: afxwin.h

ON_COMMAND

Makro ini memetakan pesan perintah ke fungsi anggota.

Sintaks

ON_COMMAND( commandId, memberFxn )

Parameter

commandId
ID perintah.

memberFxn
Nama fungsi message-handler tempat perintah dipetakan.

Keterangan

Ini menunjukkan fungsi mana yang akan menangani pesan perintah dari objek antarmuka pengguna perintah seperti item menu atau tombol toolbar.

Ketika objek target perintah menerima pesan Windows WM_COMMAND dengan ID yang ditentukan, ON_COMMAND akan memanggil fungsi memberFxn anggota untuk menangani pesan.

Gunakan ON_COMMAND untuk memetakan satu perintah ke fungsi anggota. Gunakan ON_COMMAND_RANGE untuk memetakan rentang ID perintah ke satu fungsi anggota. Hanya satu entri peta pesan yang dapat mencocokkan ID perintah tertentu. Artinya, Anda tidak dapat memetakan perintah ke lebih dari satu handler. Untuk informasi dan contoh selengkapnya, lihat Topik Penanganan dan Pemetaan Pesan.

Contoh

BEGIN_MESSAGE_MAP(CMFCListViewDoc, CDocument)
   ON_COMMAND(ID_MYCOMMAND, &CMFCListViewDoc::OnMycommand)
END_MESSAGE_MAP()

Persyaratan

Header: afxmsg_.h

ON_COMMAND_EX

Fungsi anggota handler perintah yang diperluas.

Sintaks

ON_COMMAND_EX(commandId, memberFxn);

Parameter

commandId
ID perintah.

memberFxn
Nama fungsi message-handler tempat perintah dipetakan.

Keterangan

Bentuk penangan pesan perintah yang diperluas tersedia untuk penggunaan tingkat lanjut. ON_COMMAND_EX Makro digunakan untuk penanganan pesan tersebut, dan menyediakan superset ON_COMMAND fungsionalitas. Fungsi anggota handler perintah yang diperluas mengambil satu parameter, yang UINT berisi ID perintah, dan mengembalikan BOOL. Nilai pengembalian harus TRUE menunjukkan bahwa perintah telah ditangani; jika tidak, perutean akan berlanjut ke objek target perintah lainnya.

Untuk informasi selengkapnya, lihat Catatan Teknis [TN006: Peta Pesan]tm006-message-maps.md).

Persyaratan

File header: afxmsg_.h

ON_CONTROL

Menunjukkan fungsi mana yang akan menangani pesan pemberitahuan kontrol kustom.

Sintaks

ON_CONTROL( wNotifyCode, commandId, memberFxn )

Parameter

wNotifyCode
Kode pemberitahuan kontrol.

commandId
ID perintah.

memberFxn
Nama fungsi message-handler tempat perintah dipetakan.

Keterangan

Pesan pemberitahuan kontrol adalah pesan yang dikirim dari kontrol ke jendela induknya.

Harus ada tepat satu ON_CONTROL pernyataan makro di peta pesan Anda untuk setiap pesan pemberitahuan kontrol yang harus dipetakan ke fungsi penanganan pesan.

Untuk informasi dan contoh selengkapnya, lihat Topik Penanganan dan Pemetaan Pesan.

Persyaratan

Header: afxmsg_.h

ON_MESSAGE

Menunjukkan fungsi mana yang akan menangani pesan yang ditentukan pengguna.

Sintaks

ON_MESSAGE( message, memberFxn )

Parameter

message
ID pesan.

memberFxn
Nama fungsi message-handler tempat pesan dipetakan.

Jenis fungsi harus afx_msg LRESULT (CWnd::*)(WPARAM, LPARAM).

Keterangan

Pesan yang ditentukan pengguna adalah pesan apa pun yang bukan merupakan pesan Windows WM_MESSAGE standar. Saat memilih ID pesan, Anda harus menggunakan nilai dalam rentang WM_USER (0x0400) untuk 0x7FFF atau WM_APP (0x8000) untuk 0xBFFF. Untuk informasi selengkapnya mengenai ID pesan, lihat WM_APP.

Harus ada tepat satu ON_MESSAGE pernyataan makro di peta pesan Anda untuk setiap pesan yang ditentukan pengguna yang harus dipetakan ke fungsi penanganan pesan.

Catatan

Selain pesan yang ditentukan pengguna, ON_MESSAGE menangani pesan Windows yang kurang umum. Untuk informasi selengkapnya, lihat Peta Pesan.

Untuk informasi dan contoh selengkapnya, lihat Topik Penanganan dan Pemetaan Pesan dan Penangan yang Ditentukan Pengguna

Contoh

#define WM_MYMESSAGE (WM_USER + 100)

BEGIN_MESSAGE_MAP(CMyWnd2, CWnd)
   ON_MESSAGE(WM_MYMESSAGE, OnMyMessage)
END_MESSAGE_MAP()

// inside the class declaration
afx_msg LRESULT OnMyMessage(WPARAM wParam, LPARAM lParam);

LRESULT CMyWnd2::OnMyMessage(WPARAM wParam, LPARAM lParam)
{
   UNREFERENCED_PARAMETER(wParam);
   UNREFERENCED_PARAMETER(lParam);

   // Handle message here.

   return 0;
}

Persyaratan

Header: afxmsg_.h

ON_OLECMD

Merutekan perintah melalui antarmuka IOleCommandTargetpengiriman perintah .

Sintaks

ON_OLECMD( pguid, olecmdid, commandId )

Parameter

pguid
Pengidentifikasi grup perintah tempat perintah berada. Gunakan NULL untuk grup standar.

olecmdid
Pengidentifikasi perintah OLE.

commandId
ID menu, ID toolbar, ID tombol, atau ID sumber daya atau objek lain yang mengeluarkan perintah.

Keterangan

IOleCommandTarget memungkinkan kontainer untuk menerima perintah yang berasal dari antarmuka pengguna DocObject, dan memungkinkan kontainer untuk mengirim perintah yang sama (seperti Baru, Buka, Simpan, dan Cetak pada menu File; dan Salin, Tempel, Batalkan, dan sebagainya pada menu Edit) ke DocObject.

IOleCommandTarget lebih sederhana daripada OLE Automation IDispatch. IOleCommandTarget sepenuhnya bergantung pada sekumpulan perintah standar yang jarang memiliki argumen, dan tidak ada informasi jenis yang terlibat (keamanan jenis juga berkurang untuk argumen perintah). Jika Anda perlu mengirimkan perintah dengan argumen, gunakan COleServerDoc::OnExecOleCmd.

IOleCommandTarget Perintah menu standar telah diimplementasikan oleh MFC dalam makro berikut:

ON_OLECMD_CLEARSELECTION( )

Mengirimkan perintah Edit Hapus. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_CLEARSELECTION, ID_EDIT_CLEAR)

ON_OLECMD_COPY( )

Mengirimkan perintah Edit Salin. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_COPY, ID_EDIT_COPY)

ON_OLECMD_CUT( )

Mengirimkan perintah Edit Potong. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_CUT, ID_EDIT_CUT)

ON_OLECMD_NEW( )

Mengirimkan perintah File Baru. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_NEW, ID_FILE_NEW)

ON_OLECMD_OPEN( )

Mengirimkan perintah Buka File. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_OPEN, ID_FILE_OPEN)

ON_OLECMD_PAGESETUP( )

Mengirimkan perintah Penyetelan Halaman File. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_PAGESETUP, ID_FILE_PAGE_SETUP)

ON_OLECMD_PASTE( )

Mengirimkan perintah Edit Tempel. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_PASTE, ID_EDIT_PASTE)

ON_OLECMD_PASTESPECIAL( )

Mengirimkan perintah Edit Tempel Spesial. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_PASTESPECIAL, ID_EDIT_PASTE_SPECIAL)

ON_OLECMD_PRINT( )

Mengirimkan perintah Cetak File. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)

ON_OLECMD_PRINTPREVIEW( )

Mengirimkan perintah Pratinjau Cetak File. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_PRINTPREVIEW, ID_FILE_PRINT_PREVIEW)

ON_OLECMD_REDO( )

Mengirimkan perintah Edit Ulang. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_REDO, ID_EDIT_REDO)

ON_OLECMD_SAVE( )

Mengirimkan perintah Simpan File. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_SAVE, ID_FILE_SAVE)

ON_OLECMD_SAVE_AS( )

Mengirimkan perintah Simpan Sebagai File. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_SAVEAS, ID_FILE_SAVE_AS)

ON_OLECMD_SAVE_COPY_AS( )

Mengirimkan perintah Simpan File Salin Sebagai. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_SAVECOPYAS, ID_FILE_SAVE_COPY_AS)

ON_OLECMD_SELECTALL( )

Mengirimkan perintah Edit Pilih Semua. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_SELECTALL, ID_EDIT_SELECT_ALL)

ON_OLECMD_UNDO( )

Mengirimkan perintah Edit Batalkan. Diimplementasikan sebagai:

ON_OLECMD(NULL, OLECMDID_UNDO, ID_EDIT_UNDO)

Persyaratan

Header: afxdocob.h

ON_REGISTERED_MESSAGE

Fungsi Windows RegisterWindowMessage digunakan untuk menentukan pesan jendela baru yang dijamin unik di seluruh sistem.

Sintaks

ON_REGISTERED_MESSAGE( nMessageVariable, memberFxn )

Parameter

nMessageVariable
Variabel ID pesan jendela terdaftar.

memberFxn
Nama fungsi message-handler tempat pesan dipetakan.

Keterangan

Makro ini menunjukkan fungsi mana yang akan menangani pesan terdaftar.

Untuk informasi dan contoh selengkapnya, lihat Topik Penanganan dan Pemetaan Pesan.

Contoh

static UINT NEAR WM_FIND = RegisterWindowMessage(_T("COMMDLG_FIND"));

BEGIN_MESSAGE_MAP(CMyWnd3, CWnd)
   ON_REGISTERED_MESSAGE(WM_FIND, OnFind)
END_MESSAGE_MAP()

Persyaratan

Header: afxmsg_.h

ON_REGISTERED_THREAD_MESSAGE

Menunjukkan fungsi mana yang akan menangani pesan yang didaftarkan oleh fungsi Windows RegisterWindowMessage .

Sintaks

ON_REGISTERED_THREAD_MESSAGE(nMessageVariable, memberFxn )

Parameter

nMessageVariable
Variabel ID pesan jendela terdaftar.

memberFxn
Nama CWinThreadfungsi -message-handler tempat pesan dipetakan.

Keterangan

RegisterWindowMessage digunakan untuk menentukan pesan jendela baru yang dijamin unik di seluruh sistem. ON_REGISTERED_THREAD_MESSAGE harus digunakan alih-alih ON_REGISTERED_MESSAGE ketika Anda memiliki CWinThread kelas.

Persyaratan

Header: afxmsg_.h

ON_THREAD_MESSAGE

Menunjukkan fungsi mana yang akan menangani pesan yang ditentukan pengguna.

Sintaks

ON_THREAD_MESSAGE( message, memberFxn )

Parameter

message
ID pesan.

memberFxn
Nama CWinThreadfungsi -message-handler tempat pesan dipetakan.

Keterangan

ON_THREAD_MESSAGE harus digunakan alih-alih ON_MESSAGE ketika Anda memiliki CWinThread kelas. Pesan yang ditentukan pengguna adalah pesan apa pun yang bukan merupakan pesan Windows WM_MESSAGE standar. Harus ada tepat satu ON_THREAD_MESSAGE pernyataan makro di peta pesan Anda untuk setiap pesan yang ditentukan pengguna yang harus dipetakan ke fungsi penanganan pesan.

Persyaratan

Header: afxole.h

ON_UPDATE_COMMAND_UI

Makro ini menunjukkan fungsi mana yang akan menangani pesan perintah pembaruan antarmuka pengguna.

Sintaks

ON_UPDATE_COMMAND_UI( messageId, memberFxn )

Parameter

messageId
ID pesan.

memberFxn
Nama fungsi message-handler tempat pesan dipetakan.

Keterangan

Harus ada tepat satu ON_UPDATE_COMMAND_UI pernyataan makro di peta pesan Anda untuk setiap perintah pembaruan antarmuka pengguna yang harus dipetakan ke fungsi penanganan pesan.

Untuk informasi dan contoh selengkapnya, lihat Topik Penanganan dan Pemetaan Pesan.

Persyaratan

Header: afxole.h

ON_COMMAND_RANGE

Gunakan makro ini untuk memetakan rentang ID perintah yang bersebelahan ke satu fungsi handler pesan.

Sintaks

ON_COMMAND_RANGE( id1, id2, memberFxn )

Parameter

id1
ID perintah di awal rentang ID perintah yang bersebelahan.

id2
ID perintah di akhir rentang ID perintah yang bersebelahan.

memberFxn
Nama fungsi message-handler tempat perintah dipetakan.

Keterangan

Rentang ID dimulai dengan id1 dan diakhir dengan id2.

Gunakan ON_COMMAND_RANGE untuk memetakan rentang ID perintah ke satu fungsi anggota. Gunakan ON_COMMAND untuk memetakan satu perintah ke fungsi anggota. Hanya satu entri peta pesan yang dapat mencocokkan ID perintah tertentu. Artinya, Anda tidak dapat memetakan perintah ke lebih dari satu handler. Untuk informasi selengkapnya tentang pemetaan rentang pesan, lihat Penangan untuk Rentang Peta Pesan.

Tidak ada dukungan otomatis untuk rentang peta pesan, jadi Anda harus menempatkan makro sendiri.

Contoh

// The code fragment below shows how to use ON_COMMAND_RANGE macro
// to map a contiguous range of command IDs to a single message
// handler function (i.e. OnRangeCmds() in the sample below). In
// addition, it also shows how to use CheckMenuRadioItem() to check a
// selected menu item and makes it a radio item.

BEGIN_MESSAGE_MAP(CChildFrame, CMDIChildWnd)
   ON_COMMAND_RANGE(ID_COMMAND_RANGECMD1, ID_COMMAND_RANGECMD3, &CChildFrame::OnRangeCmds)
END_MESSAGE_MAP()

void CChildFrame::OnRangeCmds(UINT nID)
{
   CMenu* mmenu = AfxGetMainWnd()->GetMenu();
   CMenu* submenu = mmenu->GetSubMenu(5);
   submenu->CheckMenuRadioItem(ID_COMMAND_RANGECMD1, ID_COMMAND_RANGECMD3,
      nID, MF_BYCOMMAND);
}

Persyaratan

Header: afxmsg_.h

ON_UPDATE_COMMAND_UI_RANGE

Memetakan rentang ID perintah yang bersebelahan ke satu fungsi handler pesan pembaruan.

Sintaks

ON_UPDATE_COMMAND_UI_RANGE( id1, id2, memberFxn )

Parameter

id1
ID perintah di awal rentang ID perintah yang bersebelahan.

id2
ID perintah di akhir rentang ID perintah yang bersebelahan.

memberFxn
Nama fungsi update message-handler tempat perintah dipetakan.

Keterangan

Perbarui penangan pesan memperbarui status item menu dan tombol toolbar yang terkait dengan perintah. Rentang ID dimulai dengan id1 dan diakhir dengan id2.

Tidak ada dukungan otomatis untuk rentang peta pesan, jadi Anda harus menempatkan makro sendiri.

Persyaratan

Header: afxmsg_.h

ON_CONTROL_RANGE

Gunakan makro ini untuk memetakan rentang ID kontrol yang bersebelahan ke fungsi handler pesan tunggal untuk pesan pemberitahuan Windows tertentu, seperti BN_CLICKED.

Sintaks

ON_CONTROL_RANGE( wNotifyCode, id1, id2, memberFxn )

Parameter

wNotifyCode
Kode pemberitahuan yang direspons oleh handler Anda.

id1
ID Perintah di awal rentang ID kontrol yang bersebelahan.

id2
ID perintah di akhir rentang ID kontrol yang bersebelahan.

memberFxn
Nama fungsi message-handler tempat kontrol dipetakan.

Keterangan

Rentang ID dimulai dengan id1 dan diakhir dengan id2. Handler dipanggil untuk pemberitahuan yang ditentukan yang berasal dari salah satu kontrol yang dipetakan.

Tidak ada dukungan otomatis untuk rentang peta pesan, jadi Anda harus menempatkan makro sendiri.

Untuk informasi selengkapnya tentang menerapkan fungsi handler untuk berbagai ID kontrol, lihat Handler untuk Rentang Peta Pesan.

Persyaratan

Header: afxmsg_.h

Lihat juga

ON_COMMAND
TN006: Peta Pesan
COleCmdUI Kelas
COleServerDoc::OnExecOleCmd
RegisterWindowMessage
Handler yang Ditentukan Pengguna
CCmdUI Kelas