訊息對應巨集 (MFC)

發行項
10/12/2023

若要支援訊息對應，MFC 提供下列巨集：

訊息對應宣告和分界巨集

名稱	描述
`DECLARE_MESSAGE_MAP`	宣告的訊息對應會使用類別將訊息與函式對應 (必須在類別宣告中使用)。
`BEGIN_MESSAGE_MAP`	開始進行訊息對應的定義 (必須在類別實作中使用)。
`BEGIN_TEMPLATE_MESSAGE_MAP`	開始在包含單一樣板引數的類別類型上定義訊息對應。
`END_MESSAGE_MAP`	結束訊息對應的定義 (必須在類別實作中使用)。

訊息對應巨集

名稱	描述
`ON_COMMAND`	指出哪些函式會處理指定的命令訊息。
`ON_COMMAND_EX`	指出哪些函式會處理指定的命令訊息。
`ON_CONTROL`	指出哪些函式會處理指定的控制項通知訊息。
`ON_MESSAGE`	指出哪些函式會處理使用者定義的訊息。
`ON_OLECMD`	指出哪些函式會處理來自 DocObject 或其容器的功能表命令。
`ON_REGISTERED_MESSAGE`	指出哪些函式會處理已註冊的使用者定義訊息。
`ON_REGISTERED_THREAD_MESSAGE`	指出當您擁有 `CWinThread` 類別時，哪些函式會處理已註冊的使用者定義訊息。
`ON_THREAD_MESSAGE`	指出當您擁有 `CWinThread` 類別時，哪些函式會處理使用者定義的訊息。
`ON_UPDATE_COMMAND_UI`	指出哪些函式會處理指定的使用者介面更新命令訊息。

訊息對應範圍巨集

名稱	描述
`ON_COMMAND_RANGE`	指出哪些函式會處理巨集的前兩個參數中指定之命令 ID 的範圍。
`ON_UPDATE_COMMAND_UI_RANGE`	指出哪些更新處理常式會處理在巨集前兩個參數中指定之命令 ID 的範圍。
`ON_CONTROL_RANGE`	指出哪些函式會處理來自在巨集的第二和第三個參數中指定之控制項 ID 範圍的通知。第一個參數是控制項通知訊息，例如 `BN_CLICKED` 。

如需訊息對應、訊息對應宣告和分界宏以及訊息對應宏的詳細資訊，請參閱訊息地圖和訊息處理和對應主題。如需訊息對應範圍的詳細資訊，請參閱訊息對應範圍的處理常式。

`BEGIN_MESSAGE_MAP`

開始訊息對應的定義。

語法

BEGIN_MESSAGE_MAP( theClass, baseClass )

參數

theClass
指定訊息對應為的類別名稱。

baseClass
指定的基類 theClass 名稱。

備註

在定義類別成員函式的實作（.cpp）檔案中，使用 BEGIN_MESSAGE_MAP 宏啟動訊息對應，然後為每個訊息處理常式函式新增宏專案，然後使用宏完成訊息對應 END_MESSAGE_MAP 。

如需訊息對應的詳細資訊，請參閱訊息地圖

範例

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

需求

標頭：afxwin.h

`BEGIN_TEMPLATE_MESSAGE_MAP`

開始在包含單一樣板引數的類別類型上定義訊息對應。

語法

BEGIN_TEMPLATE_MESSAGE_MAP( theClass, type_name, baseClass )

參數

theClass
指定訊息對應為的類別名稱。

type_name
為類別指定的樣板參數名稱。

baseClass
指定的基類 theClass 名稱。

備註

這個宏與 BEGIN_MESSAGE_MAP 宏類似，不過，這個宏適用于包含單一樣板引數的類別。

在類別的方法實作區段中，使用 BEGIN_TEMPLATE_MESSAGE_MAP 宏啟動訊息對應;然後針對標準訊息對應新增每個訊息處理常式方法的宏專案。如同宏 BEGIN_MESSAGE_MAP ，請使用 END_MESSAGE_MAP 宏完成範本訊息對應。

如需實作範本類別之訊息對應的詳細資訊，請參閱如何：建立範本類別的訊息對應。

需求

標頭：afxwin.h

`DECLARE_MESSAGE_MAP`

宣告類別定義訊息對應。程式中的每個 CCmdTarget 衍生類別都必須提供訊息對應來處理訊息。

語法

DECLARE_MESSAGE_MAP( )

備註

在 DECLARE_MESSAGE_MAP 類別宣告結尾使用宏。然後，在定義類別成員函式的 .cpp 檔案中，使用 BEGIN_MESSAGE_MAP 宏、每個訊息處理常式函式的宏專案，以及 END_MESSAGE_MAP 宏。

注意

如果您在之後 DECLARE_MESSAGE_MAP 宣告任何成員，則必須為其指定新的存取類型（ public 、 private 或 protected ）。

如需訊息對應和 DECLARE_MESSAGE_MAP 宏的詳細資訊，請參閱訊息處理和對應主題。

範例

class CMainFrame : public CMDIFrameWnd
{
   DECLARE_MESSAGE_MAP()

   // Remainder of class declaration omitted.

需求

標頭：afxwin.h

`END_MESSAGE_MAP`

結束訊息對應的定義。

語法

END_MESSAGE_MAP( )

備註

如需訊息對應和 END_MESSAGE_MAP 宏的詳細資訊，請參閱訊息處理和對應主題。

需求

標頭：afxwin.h

`ON_COMMAND`

這個宏會將命令訊息對應至成員函式。

語法

ON_COMMAND( commandId, memberFxn )

參數

commandId
命令 ID。

memberFxn
命令對應的訊息處理函式名稱。

備註

它會指出哪個函式會處理來自命令使用者介面物件的命令訊息，例如功能表項目或工具列按鈕。

當命令目標物件收到具有指定識別碼的 Windows WM_COMMAND 訊息時， ON_COMMAND 將會呼叫成員函式 memberFxn 來處理訊息。

使用 ON_COMMAND 將單一命令對應至成員函式。用來 ON_COMMAND_RANGE 將命令識別碼的範圍對應至一個成員函式。只有一個訊息對應專案可以符合指定的命令識別碼。也就是說，您無法將命令對應至多個處理常式。如需詳細資訊和範例，請參閱訊息處理和對應主題。

範例

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

需求

標頭：afxmsg_.h

`ON_COMMAND_EX`

擴充的命令處理常式成員函式。

語法

ON_COMMAND_EX(commandId, memberFxn);

參數

commandId
命令 ID。

memberFxn
命令對應的訊息處理函式名稱。

備註

命令訊息處理常式的擴充形式可供進階使用。宏 ON_COMMAND_EX 會用於這類訊息處理常式，並提供功能的超集合 ON_COMMAND 。擴充的命令處理常式成員函式會採用單一參數、 UINT 包含命令識別碼的，並傳 BOOL 回。傳回值應該是 TRUE 表示已處理命令，否則路由會繼續傳送至其他命令目標物件。

如需詳細資訊，請參閱技術注意事項 [TN006：訊息地圖]tm006-message-maps.md]。

需求

標頭檔： afxmsg_.h

`ON_CONTROL`

指出哪個函式會處理自訂控制項通知訊息。

語法

ON_CONTROL( wNotifyCode, commandId, memberFxn )

參數

wNotifyCode
控制項的通知碼。

commandId
命令 ID。

memberFxn
命令對應的訊息處理函式名稱。

備註

控制項通知訊息是從控制項傳送至其父視窗的通知訊息。

訊息對應中應該只有一個 ON_CONTROL 巨集式，每個控制項通知訊息都必須對應至訊息處理常式函式。

如需詳細資訊和範例，請參閱訊息處理和對應主題。

需求

標頭：afxmsg_.h

`ON_MESSAGE`

指出哪些函式會處理使用者定義的訊息。

語法

ON_MESSAGE( message, memberFxn )

參數

message
訊息 ID。

memberFxn
訊息對應的訊息處理常式函式名稱。

函式的類型必須是 afx_msg LRESULT (CWnd::*)(WPARAM, LPARAM) 。

備註

使用者定義的訊息是任何不是標準 Windows WM_MESSAGE 訊息的訊息。選取訊息識別碼時，您必須使用（0x0400）範圍內的 WM_USER 值來0x7FFF或 WM_APP （0x8000）來0xBFFF。如需有關訊息識別碼的詳細資訊，請參閱 WM_APP 。

訊息對應中應該只有一個 ON_MESSAGE 巨集式，每個使用者定義訊息都必須對應至訊息處理常式函式。

注意

除了使用者定義的訊息之外， ON_MESSAGE 還處理較不常見的 Windows 訊息。如需詳細資訊，請參閱訊息地圖。

如需詳細資訊和範例，請參閱訊息處理和對應主題和使用者定義處理常式

範例

#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;
}

需求

標頭：afxmsg_.h

`ON_OLECMD`

透過命令分派介面 IOleCommandTarget 路由命令。

語法

ON_OLECMD( pguid, olecmdid, commandId )

參數

pguid
命令所屬命令群組的識別碼。用於 NULL 標準群組。

olecmdid
OLE 命令的識別碼。

commandId
發出命令之資源或物件的功能表識別碼、工具列識別碼、按鈕識別碼或其他識別碼。

備註

IOleCommandTarget 允許容器接收源自 DocObject 使用者介面的命令，並允許容器將相同的命令傳送至 DocObject，例如 [檔案] 功能表上的 [新增]、[開啟]、[SaveAs] 和 [列印]、[複製]、[貼上]、[復原] 等命令。

IOleCommandTarget 比 OLE Automation 的 IDispatch 更簡單。 IOleCommandTarget 完全依賴一組很少有引數的標準命令，而且不會涉及任何類型資訊（命令引數的型別安全性也會降低）。如果您需要使用引數來分派命令，請使用 COleServerDoc::OnExecOleCmd 。

MFC IOleCommandTarget 已在下列宏中實作標準功能表命令：

ON_OLECMD_CLEARSELECTION( )

分派 [編輯清除] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_CLEARSELECTION, ID_EDIT_CLEAR)

ON_OLECMD_COPY( )

分派 [編輯複製] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_COPY, ID_EDIT_COPY)

ON_OLECMD_CUT( )

分派 [編輯剪下] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_CUT, ID_EDIT_CUT)

ON_OLECMD_NEW( )

分派 [檔案新] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_NEW, ID_FILE_NEW)

ON_OLECMD_OPEN( )

分派 [檔案開啟] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_OPEN, ID_FILE_OPEN)

ON_OLECMD_PAGESETUP( )

分派 [檔案頁面設定] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_PAGESETUP, ID_FILE_PAGE_SETUP)

ON_OLECMD_PASTE( )

分派 [編輯貼上] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_PASTE, ID_EDIT_PASTE)

ON_OLECMD_PASTESPECIAL( )

分派 [編輯貼上特殊] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_PASTESPECIAL, ID_EDIT_PASTE_SPECIAL)

ON_OLECMD_PRINT( )

分派 [檔案列印] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)

ON_OLECMD_PRINTPREVIEW( )

分派 [檔案預覽列印] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_PRINTPREVIEW, ID_FILE_PRINT_PREVIEW)

ON_OLECMD_REDO( )

分派 Edit Redo 命令。實作為：

ON_OLECMD(NULL, OLECMDID_REDO, ID_EDIT_REDO)

ON_OLECMD_SAVE( )

分派 [檔案儲存] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_SAVE, ID_FILE_SAVE)

ON_OLECMD_SAVE_AS( )

分派 [檔案另存新檔] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_SAVEAS, ID_FILE_SAVE_AS)

ON_OLECMD_SAVE_COPY_AS( )

分派 [檔案另存新檔] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_SAVECOPYAS, ID_FILE_SAVE_COPY_AS)

ON_OLECMD_SELECTALL( )

分派 [編輯全選] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_SELECTALL, ID_EDIT_SELECT_ALL)

ON_OLECMD_UNDO( )

分派 [編輯復原] 命令。實作為：

ON_OLECMD(NULL, OLECMDID_UNDO, ID_EDIT_UNDO)

需求

標頭：afxdocob.h

`ON_REGISTERED_MESSAGE`

Windows RegisterWindowMessage 函式可用來定義保證在整個系統中是唯一的新視窗訊息。

語法

ON_REGISTERED_MESSAGE( nMessageVariable, memberFxn )

參數

nMessageVariable
已註冊的視窗訊息識別碼變數。

memberFxn
訊息對應的訊息處理常式函式名稱。

備註

這個宏會指出哪個函式會處理已註冊的訊息。

如需詳細資訊和範例，請參閱訊息處理和對應主題。

範例

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

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

需求

標頭：afxmsg_.h

`ON_REGISTERED_THREAD_MESSAGE`

指出哪個函式會處理 Windows RegisterWindowMessage 函式所註冊的訊息。

語法

ON_REGISTERED_THREAD_MESSAGE(nMessageVariable, memberFxn )

參數

nMessageVariable
已註冊的視窗訊息識別碼變數。

memberFxn
訊息對應的 -message-handler 函式名稱 CWinThread 。

備註

RegisterWindowMessage 用來定義保證在整個系統中是唯一的新視窗訊息。 ON_REGISTERED_THREAD_MESSAGE 您必須使用，而不是 ON_REGISTERED_MESSAGE 當您有類別 CWinThread 時。

需求

標頭：afxmsg_.h

`ON_THREAD_MESSAGE`

指出哪些函式會處理使用者定義的訊息。

語法

ON_THREAD_MESSAGE( message, memberFxn )

參數

message
訊息 ID。

memberFxn
訊息對應的 -message-handler 函式名稱 CWinThread 。

備註

ON_THREAD_MESSAGE 您必須使用，而不是 ON_MESSAGE 當您有類別 CWinThread 時。使用者定義的訊息是任何不是標準 Windows WM_MESSAGE 訊息的訊息。訊息對應中應該只有一個 ON_THREAD_MESSAGE 巨集式，每個使用者定義訊息都必須對應至訊息處理常式函式。

需求

標頭：afxole.h

`ON_UPDATE_COMMAND_UI`

此宏指出哪個函式會處理使用者介面更新命令訊息。

語法

ON_UPDATE_COMMAND_UI( messageId, memberFxn )

參數

messageId
訊息 ID。

memberFxn
訊息對應的訊息處理常式函式名稱。

備註

訊息對應中應該只有一個 ON_UPDATE_COMMAND_UI 巨集式，每個使用者介面更新命令都必須對應至訊息處理常式函式。

如需詳細資訊和範例，請參閱訊息處理和對應主題。

需求

標頭：afxole.h

`ON_COMMAND_RANGE`

使用此宏將連續的命令識別碼範圍對應至單一訊息處理常式函式。

語法

ON_COMMAND_RANGE( id1, id2, memberFxn )

參數

id1
連續命令識別碼範圍開頭的命令識別碼。

id2
連續命令識別碼範圍結尾的命令識別碼。

memberFxn
命令所對應的訊息處理常式函式名稱。

備註

識別碼的範圍以開頭 id1 ，並以結尾 id2 。

用來 ON_COMMAND_RANGE 將命令識別碼的範圍對應至一個成員函式。使用 ON_COMMAND 將單一命令對應至成員函式。只有一個訊息對應專案可以符合指定的命令識別碼。也就是說，您無法將命令對應至多個處理常式。如需對應訊息範圍的詳細資訊，請參閱訊息對應範圍的處理常式。

訊息對應範圍沒有自動支援，因此您必須自行放置宏。

範例

// 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);
}

需求

標頭：afxmsg_.h

`ON_UPDATE_COMMAND_UI_RANGE`

地圖單一更新訊息處理常式函式的連續命令識別碼範圍。

語法

ON_UPDATE_COMMAND_UI_RANGE( id1, id2, memberFxn )

參數

id1
連續命令識別碼範圍開頭的命令識別碼。

id2
連續命令識別碼範圍結尾的命令識別碼。

memberFxn
命令所對應的更新訊息處理常式函式名稱。

備註

更新訊息處理常式會更新與命令相關聯的功能表項目和工具列按鈕的狀態。識別碼的範圍以開頭 id1 ，並以結尾 id2 。

訊息對應範圍沒有自動支援，因此您必須自行放置宏。

需求

標頭：afxmsg_.h

`ON_CONTROL_RANGE`

使用此宏，將連續的控制識別碼範圍對應至指定 Windows 通知訊息的單一訊息處理常式函式，例如 BN_CLICKED 。

語法

ON_CONTROL_RANGE( wNotifyCode, id1, id2, memberFxn )

參數

wNotifyCode
處理常式所回應的通知程式碼。

id1
連續控制項識別碼範圍開頭的命令識別碼。

id2
連續控制項識別碼範圍結尾的命令識別碼。

memberFxn
控制項所對應的訊息處理常式函式名稱。

備註

識別碼的範圍以開頭 id1 ，並以結尾 id2 。針對來自任何對應控制項的指定通知呼叫處理常式。

訊息對應範圍沒有自動支援，因此您必須自行放置宏。

如需實作控制項識別碼範圍之處理常式函式的詳細資訊，請參閱 Message-Map Range 的處理常式。

需求

標頭：afxmsg_.h

另請參閱

ON_COMMAND
TN006：訊息對應
 COleCmdUI 類
 COleServerDoc::OnExecOleCmd
RegisterWindowMessage
使用者定義的處理常式
 CCmdUI 類

共用方式為

訊息對應巨集 (MFC)

訊息對應宣告和分界巨集

訊息對應巨集

訊息對應範圍巨集

BEGIN_MESSAGE_MAP

語法

參數

備註

範例

需求

BEGIN_TEMPLATE_MESSAGE_MAP

語法

參數

備註

需求

DECLARE_MESSAGE_MAP

語法

備註

範例

需求

END_MESSAGE_MAP

語法

備註

需求

ON_COMMAND

語法

參數

備註

範例

需求

ON_COMMAND_EX

語法

參數

備註

需求

ON_CONTROL

語法

參數

備註

需求

ON_MESSAGE

語法

參數

備註

範例

需求

ON_OLECMD

語法

參數

備註

需求

ON_REGISTERED_MESSAGE

語法

參數

備註

範例

需求

ON_REGISTERED_THREAD_MESSAGE

語法

參數

備註

需求

ON_THREAD_MESSAGE

語法

參數

備註

需求

ON_UPDATE_COMMAND_UI

語法

參數

備註

需求

ON_COMMAND_RANGE

語法

參數

備註

範例

需求

ON_UPDATE_COMMAND_UI_RANGE

`BEGIN_MESSAGE_MAP`

`BEGIN_TEMPLATE_MESSAGE_MAP`

`DECLARE_MESSAGE_MAP`

`END_MESSAGE_MAP`

`ON_COMMAND`

`ON_COMMAND_EX`

`ON_CONTROL`

`ON_MESSAGE`

`ON_OLECMD`

`ON_REGISTERED_MESSAGE`

`ON_REGISTERED_THREAD_MESSAGE`

`ON_THREAD_MESSAGE`

`ON_UPDATE_COMMAND_UI`

`ON_COMMAND_RANGE`

`ON_UPDATE_COMMAND_UI_RANGE`

`ON_CONTROL_RANGE`