訊息對應巨集 (MFC)

發行項
08/04/2024

若要支援訊息對應，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`