Message Map Macros

Contributed by shabbir () On 22nd September, 2006

This is an article on Message Map Macros in MFC.

To support message maps, MFC supplies the following macros:

Message-Map Declaration

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).

Example:

Code: CPP

// example for DECLARE_MESSAGE_MAP
class CMyWnd : public CFrameWnd
{
    // Member declarations
    
    DECLARE_MESSAGE_MAP( )
};

BEGIN_MESSAGE_MAP
Begins the definition of a message map (must be used in the class implementation).

Example:

Code: CPP

// example for BEGIN_MESSAGE_MAP
BEGIN_MESSAGE_MAP( CMyWindow, CFrameWnd )
   //{{AFX_MSG_MAP( CMyWindow )
    ON_WM_PAINT()
    ON_COMMAND( IDM_ABOUT, OnAbout )
   //}}AFX_MSG_MAP
END_MESSAGE_MAP( )

END_MESSAGE_MAP
Ends the definition of a message map (must be used in the class implementation).

Message-Mapping Macros

ON_COMMAND
Indicates which function will handle a specified command message.

Example:

Code: CPP

// example for ON_COMMAND
BEGIN_MESSAGE_MAP( CMyDoc, CDocument )
    //{{AFX_MSG_MAP( CMyDoc )
    ON_COMMAND( ID_MYCMD, OnMyCommand )
    // ... More entries to handle additional commands
    //}}AFX_MSG_MAP
END_MESSAGE_MAP( )

ON_CONTROL
Indicates which function will handle a specified control-notification message.

Example:

Code: CPP

// example for ON_CONTROL
BEGIN_MESSAGE_MAP(CMyButton, CButton)
    //{{AFX_MSG_MAP(CMyButton)
    ON_CONTROL(BN_CLICKED, OnClicked)
    // ... More entries to handle additional commands
    //}}AFX_MSG_MAP
END_MESSAGE_MAP()

ON_MESSAGE
Indicates which function will handle a user-defined message.

Example:

Code: CPP

// example for ON_MESSAGE
#define WM_MYMESSAGE (WM_USER + 1)
BEGIN_MESSAGE_MAP( CMyWnd, CMyParentWndClass )
    //{{AFX_MSG_MAP( CMyWnd
    ON_MESSAGE( WM_MYMESSAGE, OnMyMessage )
    // ... Possibly more entries to handle additional messages
    //}}AFX_MSG_MAP
END_MESSAGE_MAP( )

ON_OLECMD
Indicates which function will handle a menu command from a DocObject or its container.

Routes commands through the command dispatch interface IOleCommandTarget. 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.

ON_REGISTERED_MESSAGE
Indicates which function will handle a registered user-defined message.

Example:

Code: CPP

// example for ON_REGISTERED_MESSAGE
const UINT    wm_Find = RegisterWindowMessage( FINDMSGSTRING )
BEGIN_MESSAGE_MAP( CMyWnd, CMyParentWndClass )
    //{{AFX_MSG_MAP( CMyWnd )
    ON_REGISTERED_MESSAGE( wm_Find, OnFind )
    // ... Possibly more entries to handle additional messages
    //}}AFX_MSG_MAP
END_MESSAGE_MAP( )

ON_REGISTERED_THREAD_MESSAGE
Indicates which function will handle a registered user-defined message when you have a CWinThread class.

ON_REGISTERED_THREAD_MESSAGE must be used instead of ON_REGISTERED_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_THREAD_MESSAGE must be used instead of ON_MESSAGE when you have a CWinThread class.

ON_UPDATE_COMMAND_UI
Indicates which function will handle a specified user-interface update command message.

Example :

Code: CPP

// example for ON_UPDATE_COMMAND_UI
BEGIN_MESSAGE_MAP(CMyApp, CWinApp)
    //{{AFX_MSG_MAP(CMyApp)
    ...
    //}}AFX_MSG_MAP
    ON_UPDATE_COMMAND_UI(IDC_CHECK1, OnUpdateCheck1)
END_MESSAGE_MAP( )

Message-Map Range Macros

ON_COMMAND_RANGE
Indicates which function will handle the range of command IDs specified in the first two parameters to the macro.

Example:

Code: CPP

// example for ON_COMMAND_RANGE 
BEGIN_MESSAGE_MAP( CMyDoc, CDocument )
    //{{AFX_MSG_MAP( CMyDoc )
    ...
    //}}AFX_MSG_MAP
    ON_COMMAND_RANGE(ID_MYCMD_ONE, ID_MYCMD_TEN, OnDoSomething)
END_MESSAGE_MAP( )

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.

Example:

Code: CPP

// example for ON_UPDATE_COMMAND_UI_RANGE
BEGIN_MESSAGE_MAP(CMyApp, CWinApp)
    //{{AFX_MSG_MAP(CMyApp)
    ...
    //}}AFX_MSG_MAP
    ON_UPDATE_COMMAND_UI_RANGE(ID_VIEW_ZOOM25, ID_VIEW_ZOOM300, OnZoom)
END_MESSAGE_MAP( )

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.

Example:

Code: CPP

// example for ON_CONTROL_RANGE
BEGIN_MESSAGE_MAP(CMyButton, CButton)
    //{{AFX_MSG_MAP(CMyButton)
    ON_CONTROL_RANGE(BN_CLICKED, IDC_BUTTON1, IDC_BUTTON10, OnButtonClicked)
    // ... More entries to handle additional commands
    //}}AFX_MSG_MAP
END_MESSAGE_MAP()