Message Map Macros (MFC)

Article
08/03/2021

To support message maps, MFC supplies the following macros:

Message-Map Declaration and Demarcation Macros

Name	Description
`DECLARE_MESSAGE_MAP`	Declares that a message map will be used in a class to map messages to functions (must be used in the class declaration).
`BEGIN_MESSAGE_MAP`	Begins the definition of a message map (must be used in the class implementation).
`BEGIN_TEMPLATE_MESSAGE_MAP`	Begins the definition of a message map on a class type containing a single template argument.
`END_MESSAGE_MAP`	Ends the definition of a message map (must be used in the class implementation).

Message-Mapping Macros

Name	Description
`ON_COMMAND`	Indicates which function will handle a specified command message.
`ON_COMMAND_EX`	Indicates which function will handle a specified command message.
`ON_CONTROL`	Indicates which function will handle a specified control-notification message.
`ON_MESSAGE`	Indicates which function will handle a user-defined message.
`ON_OLECMD`	Indicates which function will handle a menu command from a DocObject or its container.
`ON_REGISTERED_MESSAGE`	Indicates which function will handle a registered user-defined message.
`ON_REGISTERED_THREAD_MESSAGE`	Indicates which function will handle a registered user-defined message when you have a `CWinThread` class.
`ON_THREAD_MESSAGE`	Indicates which function will handle a user-defined message when you have a `CWinThread` class.
`ON_UPDATE_COMMAND_UI`	Indicates which function will handle a specified user-interface update command message.

Message-Map Range Macros

Name	Description
`ON_COMMAND_RANGE`	Indicates which function will handle the range of command IDs specified in the first two parameters to the macro.
`ON_UPDATE_COMMAND_UI_RANGE`	Indicates which update handler will handle the range of command IDs specified in the first two parameters to the macro.
`ON_CONTROL_RANGE`	Indicates which function will handle notifications from the range of control IDs specified in the second and third parameters to the macro. The first parameter is a control-notification message, such as `BN_CLICKED`.

For more information on message maps, the message-map declaration and demarcation macros, and the message-mapping macros, see Message Maps and Message Handling and Mapping Topics. For more information about message-map ranges, see Handlers for Message-Map Ranges.

`BEGIN_MESSAGE_MAP`

Begins the definition of your message map.

Syntax

BEGIN_MESSAGE_MAP( theClass, baseClass )

Parameters

theClass
Specifies the name of the class whose message map this is.

baseClass
Specifies the name of the base class of theClass.

Remarks

In the implementation (.cpp) file that defines the member functions for your class, start the message map with the BEGIN_MESSAGE_MAP macro, then add macro entries for each of your message-handler functions, and complete the message map with the END_MESSAGE_MAP macro.

For more information about message maps, see Message Maps

Example

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

Requirements

Header: afxwin.h

`BEGIN_TEMPLATE_MESSAGE_MAP`

Begins the definition of a message map on a class type containing a single template argument.

Syntax

BEGIN_TEMPLATE_MESSAGE_MAP( theClass, type_name, baseClass )

Parameters

theClass
Specifies the name of the class whose message map this is.

type_name
The name of the template parameter specified for the class.

baseClass
Specifies the name of the base class of theClass.

Remarks

This macro is similar to the BEGIN_MESSAGE_MAP macro; however, this macro is intended for classes containing a single template argument.

In the method implementation section of your class, start the message map with the BEGIN_TEMPLATE_MESSAGE_MAP macro; then add macro entries for each of your message-handler methods as you would for a standard message map. As with the BEGIN_MESSAGE_MAP macro, complete the template message map with the END_MESSAGE_MAP macro.

For more information on implementing message maps for template classes, refer to How to: Create a Message Map for a Template Class.

Requirements

Header: afxwin.h

`DECLARE_MESSAGE_MAP`

Declares that the class defines a message map. Each CCmdTarget-derived class in your program must provide a message map to handle messages.

Syntax

DECLARE_MESSAGE_MAP( )

Remarks

Use the DECLARE_MESSAGE_MAP macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the BEGIN_MESSAGE_MAP macro, macro entries for each of your message-handler functions, and the END_MESSAGE_MAP macro.

Note

If you declare any member after DECLARE_MESSAGE_MAP, you must specify a new access type (public, private, or protected) for them.

For more information on message maps and the DECLARE_MESSAGE_MAP macro, see Message Handling and Mapping Topics.

Example

class CMainFrame : public CMDIFrameWnd
{
   DECLARE_MESSAGE_MAP()

   // Remainder of class declaration omitted.

Requirements

Header: afxwin.h

`END_MESSAGE_MAP`

Ends the definition of your message map.

Syntax

END_MESSAGE_MAP( )

Remarks

For more information on message maps and the END_MESSAGE_MAP macro, see Message Handling and Mapping Topics.

Requirements

Header: afxwin.h

`ON_COMMAND`

This macro maps a command message to a member function.

Syntax

ON_COMMAND( commandId, memberFxn )

Parameters

commandId
The command ID.

memberFxn
The name of the message-handler function to which the command is mapped.

Remarks

It indicates which function will handle a command message from a command user-interface object such as a menu item or toolbar button.

When a command-target object receives a Windows WM_COMMAND message with the specified ID, ON_COMMAND will call the member function memberFxn to handle the message.

Use ON_COMMAND to map a single command to a member function. Use ON_COMMAND_RANGE to map a range of command IDs to one member function. Only one message-map entry can match a given command ID. That is, you can't map a command to more than one handler. For more information and examples, see Message Handling and Mapping Topics.

Example

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

Requirements

Header: afxmsg_.h

`ON_COMMAND_EX`

Extended command-handler member function.

Syntax

ON_COMMAND_EX(commandId, memberFxn);

Parameters

commandId
The command ID.

memberFxn
The name of the message-handler function to which the command is mapped.

Remarks

An extended form of command message handlers is available for advanced uses. The ON_COMMAND_EX macro is used for such message handlers, and it provides a superset of the ON_COMMAND functionality. Extended command-handler member functions take a single parameter, a UINT containing the command ID, and return a BOOL. The return value should be TRUE to indicate that the command has been handled; otherwise routing will continue to other command target objects.

For more information, see Technical Note [TN006: Message Maps]tm006-message-maps.md).

Requirements

Header file: afxmsg_.h

`ON_CONTROL`

Indicates which function will handle a custom-control notification message.

Syntax

ON_CONTROL( wNotifyCode, commandId, memberFxn )

Parameters

wNotifyCode
The notification code of the control.

commandId
The command ID.

memberFxn
The name of the message-handler function to which the command is mapped.

Remarks

Control notification messages are those sent from a control to its parent window.

There should be exactly one ON_CONTROL macro statement in your message map for every control notification message that must be mapped to a message-handler function.

For more information and examples, see Message Handling and Mapping Topics.

Requirements

Header: afxmsg_.h

`ON_MESSAGE`

Indicates which function will handle a user-defined message.

Syntax

ON_MESSAGE( message, memberFxn )

Parameters

message
The message ID.

memberFxn
The name of the message-handler function to which the message is mapped.

The type of the function must be afx_msg LRESULT (CWnd::*)(WPARAM, LPARAM).

Remarks

User-defined messages are any messages that are not standard Windows WM_MESSAGE messages. When selecting a message ID, you must use values within the range of WM_USER (0x0400) to 0x7FFF or WM_APP (0x8000) to 0xBFFF. For more information regarding message IDs, see WM_APP.

There should be exactly one ON_MESSAGE macro statement in your message map for every user-defined message that must be mapped to a message-handler function.

Note

In addition to user-defined messages, ON_MESSAGE handles less common Windows messages. For more information, see Message Maps.

For more information and examples, see Message Handling and Mapping Topics and User-Defined Handlers

Example

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

Requirements

Header: afxmsg_.h

`ON_OLECMD`

Routes commands through the command dispatch interface IOleCommandTarget.

Syntax

ON_OLECMD( pguid, olecmdid, commandId )

Parameters

pguid
Identifier of the command group to which the command belongs. Use NULL for the standard group.

olecmdid
The identifier of the OLE command.

commandId
The menu ID, toolbar ID, button ID, or other ID of the resource or object issuing the command.

Remarks

IOleCommandTarget allows a container to receive commands that originate in a DocObject's user interface, and allows the container to send the same commands (such as New, Open, SaveAs, and Print on the File menu; and Copy, Paste, Undo, and so forth on the Edit menu) to a DocObject.

IOleCommandTarget is simpler than OLE Automation's IDispatch. IOleCommandTarget relies entirely on a standard set of commands that rarely have arguments, and no type information is involved (type safety is diminished for command arguments as well). If you do need to dispatch commands with arguments, use COleServerDoc::OnExecOleCmd.

The IOleCommandTarget standard menu commands have been implemented by MFC in the following macros:

ON_OLECMD_CLEARSELECTION( )

Dispatches the Edit Clear command. Implemented as:

ON_OLECMD(NULL, OLECMDID_CLEARSELECTION, ID_EDIT_CLEAR)

ON_OLECMD_COPY( )

Dispatches the Edit Copy command. Implemented as:

ON_OLECMD(NULL, OLECMDID_COPY, ID_EDIT_COPY)

ON_OLECMD_CUT( )

Dispatches the Edit Cut command. Implemented as:

ON_OLECMD(NULL, OLECMDID_CUT, ID_EDIT_CUT)

ON_OLECMD_NEW( )

Dispatches the File New command. Implemented as:

ON_OLECMD(NULL, OLECMDID_NEW, ID_FILE_NEW)

ON_OLECMD_OPEN( )

Dispatches the File Open command. Implemented as:

ON_OLECMD(NULL, OLECMDID_OPEN, ID_FILE_OPEN)

ON_OLECMD_PAGESETUP( )

Dispatches the File Page Setup command. Implemented as:

ON_OLECMD(NULL, OLECMDID_PAGESETUP, ID_FILE_PAGE_SETUP)

ON_OLECMD_PASTE( )

Dispatches the Edit Paste command. Implemented as:

ON_OLECMD(NULL, OLECMDID_PASTE, ID_EDIT_PASTE)

ON_OLECMD_PASTESPECIAL( )

Dispatches the Edit Paste Special command. Implemented as:

ON_OLECMD(NULL, OLECMDID_PASTESPECIAL, ID_EDIT_PASTE_SPECIAL)

ON_OLECMD_PRINT( )

Dispatches the File Print command. Implemented as:

ON_OLECMD(NULL, OLECMDID_PRINT, ID_FILE_PRINT)

ON_OLECMD_PRINTPREVIEW( )

Dispatches the File Print Preview command. Implemented as:

ON_OLECMD(NULL, OLECMDID_PRINTPREVIEW, ID_FILE_PRINT_PREVIEW)

ON_OLECMD_REDO( )

Dispatches the Edit Redo command. Implemented as:

ON_OLECMD(NULL, OLECMDID_REDO, ID_EDIT_REDO)

ON_OLECMD_SAVE( )

Dispatches the File Save command. Implemented as:

ON_OLECMD(NULL, OLECMDID_SAVE, ID_FILE_SAVE)

ON_OLECMD_SAVE_AS( )

Dispatches the File Save As command. Implemented as:

ON_OLECMD(NULL, OLECMDID_SAVEAS, ID_FILE_SAVE_AS)

ON_OLECMD_SAVE_COPY_AS( )

Dispatches the File Save Copy As command. Implemented as:

ON_OLECMD(NULL, OLECMDID_SAVECOPYAS, ID_FILE_SAVE_COPY_AS)

ON_OLECMD_SELECTALL( )

Dispatches the Edit Select All command. Implemented as:

ON_OLECMD(NULL, OLECMDID_SELECTALL, ID_EDIT_SELECT_ALL)

ON_OLECMD_UNDO( )

Dispatches the Edit Undo command. Implemented as:

ON_OLECMD(NULL, OLECMDID_UNDO, ID_EDIT_UNDO)

Requirements

Header: afxdocob.h

`ON_REGISTERED_MESSAGE`

The Windows RegisterWindowMessage function is used to define a new window message that is guaranteed to be unique throughout the system.

Syntax

ON_REGISTERED_MESSAGE( nMessageVariable, memberFxn )

Parameters

nMessageVariable
The registered window-message ID variable.

memberFxn
The name of the message-handler function to which the message is mapped.

Remarks

This macro indicates which function will handle the registered message.

For more information and examples, see Message Handling and Mapping Topics.

Example

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

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

Requirements

Header: afxmsg_.h

`ON_REGISTERED_THREAD_MESSAGE`

Indicates which function will handle the message registered by the Windows RegisterWindowMessage function.

Syntax

ON_REGISTERED_THREAD_MESSAGE(nMessageVariable, memberFxn )

Parameters

nMessageVariable
The registered window-message ID variable.

memberFxn
The name of the CWinThread-message-handler function to which the message is mapped.

Remarks

RegisterWindowMessage is used to define a new window message that is guaranteed to be unique throughout the system. ON_REGISTERED_THREAD_MESSAGE must be used instead of ON_REGISTERED_MESSAGE when you have a CWinThread class.

Requirements

Header: afxmsg_.h

`ON_THREAD_MESSAGE`

Indicates which function will handle a user-defined message.

Syntax

ON_THREAD_MESSAGE( message, memberFxn )

Parameters

message
The message ID.

memberFxn
The name of the CWinThread-message-handler function to which the message is mapped.

Remarks

ON_THREAD_MESSAGE must be used instead of ON_MESSAGE when you have a CWinThread class. User-defined messages are any messages that are not standard Windows WM_MESSAGE messages. There should be exactly one ON_THREAD_MESSAGE macro statement in your message map for every user-defined message that must be mapped to a message-handler function.

Requirements

Header: afxole.h

`ON_UPDATE_COMMAND_UI`

This macro indicates which function will handle a user-interface update command message.

Syntax

ON_UPDATE_COMMAND_UI( messageId, memberFxn )

Parameters

messageId
The message ID.

memberFxn
The name of the message-handler function to which the message is mapped.

Remarks

There should be exactly one ON_UPDATE_COMMAND_UI macro statement in your message map for every user-interface update command that must be mapped to a message-handler function.

For more information and examples, see Message Handling and Mapping Topics.

Requirements

Header: afxole.h

`ON_COMMAND_RANGE`

Use this macro to map a contiguous range of command IDs to a single message handler function.

Syntax

ON_COMMAND_RANGE( id1, id2, memberFxn )

Parameters

id1
Command ID at the beginning of a contiguous range of command IDs.

id2
Command ID at the end of a contiguous range of command IDs.

memberFxn
The name of the message-handler function to which the commands are mapped.

Remarks

The range of IDs starts with id1 and ends with id2.

Use ON_COMMAND_RANGE to map a range of command IDs to one member function. Use ON_COMMAND to map a single command to a member function. Only one message-map entry can match a given command ID. That is, you can't map a command to more than one handler. For more information on mapping message ranges, see Handlers for Message-Map Ranges.

There is no automatic support for message map ranges, so you must place the macro yourself.

Example

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

Requirements

Header: afxmsg_.h

`ON_UPDATE_COMMAND_UI_RANGE`

Maps a contiguous range of command IDs to a single update message handler function.

Syntax

ON_UPDATE_COMMAND_UI_RANGE( id1, id2, memberFxn )

Parameters

id1
Command ID at the beginning of a contiguous range of command IDs.

id2
Command ID at the end of a contiguous range of command IDs.

memberFxn
The name of the update message-handler function to which the commands are mapped.

Remarks

Update message handlers update the state of menu items and toolbar buttons associated with the command. The range of IDs starts with id1 and ends with id2.

There is no automatic support for message map ranges, so you must place the macro yourself.

Requirements

Header: afxmsg_.h

`ON_CONTROL_RANGE`

Use this macro to map a contiguous range of control IDs to a single message handler function for a specified Windows notification message, such as BN_CLICKED.

Syntax

ON_CONTROL_RANGE( wNotifyCode, id1, id2, memberFxn )

Parameters

wNotifyCode
The notification code to which your handler is responding.

id1
Command ID at the beginning of a contiguous range of control IDs.

id2
Command ID at the end of a contiguous range of control IDs.

memberFxn
The name of the message-handler function to which the controls are mapped.

Remarks

The range of IDs starts with id1 and ends with id2. The handler is called for the specified notification coming from any of the mapped controls.

There is no automatic support for message map ranges, so you must place the macro yourself.

For more information on implementing handler functions for a range of control IDs, refer to Handlers for Message-Map Ranges.

Requirements

Header: afxmsg_.h

Share via

Message Map Macros (MFC)

Message-Map Declaration and Demarcation Macros

Message-Mapping Macros

Message-Map Range Macros

BEGIN_MESSAGE_MAP

Syntax

Parameters

Remarks

Example

Requirements

BEGIN_TEMPLATE_MESSAGE_MAP

Syntax

Parameters

Remarks

Requirements

DECLARE_MESSAGE_MAP

Syntax

Remarks

Example

Requirements

END_MESSAGE_MAP

Syntax

Remarks

Requirements

ON_COMMAND

Syntax

Parameters

Remarks

Example

Requirements

ON_COMMAND_EX

Syntax

Parameters

Remarks

Requirements

ON_CONTROL

Syntax

Parameters

Remarks

Requirements

ON_MESSAGE

Syntax

Parameters

Remarks

Example

Requirements

ON_OLECMD

Syntax

Parameters

Remarks

Requirements

ON_REGISTERED_MESSAGE

Syntax

Parameters

Remarks

Example

Requirements

ON_REGISTERED_THREAD_MESSAGE

Syntax

Parameters

Remarks

Requirements

ON_THREAD_MESSAGE

Syntax

Parameters

Remarks

Requirements

ON_UPDATE_COMMAND_UI

Syntax

Parameters

Remarks

Requirements

ON_COMMAND_RANGE

Syntax

Parameters

Remarks

Example

Requirements

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`