BEGIN_MSG_MAP

Article
12/01/2015

Marks the beginning of the default message map.

Syntax

BEGIN_MSG_MAP( theClass )

Parameters

theClass
[in] The name of the class containing the message map.

Remarks

CWindowImpl::WindowProc uses the default message map to process messages sent to the window. The message map directs messages either to the appropriate handler function or to another message map.

The following macros map a message to a handler function. This function must be defined in theClass.

Macro	Description
MESSAGE_HANDLER	Maps a Windows message to a handler function.
MESSAGE_RANGE_HANDLER	Maps a contiguous range of Windows messages to a handler function.
COMMAND_HANDLER	Maps a WM_COMMAND message to a handler function, based on the notification code and the identifier of the menu item, control, or accelerator.
COMMAND_ID_HANDLER	Maps a WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator.
COMMAND_CODE_HANDLER	Maps a WM_COMMAND message to a handler function, based on the notification code.
COMMAND_RANGE_HANDLER	Maps a contiguous range of WM_COMMAND messages to a handler function, based on the identifier of the menu item, control, or accelerator.
NOTIFY_HANDLER	Maps a WM_NOTIFY message to a handler function, based on the notification code and the control identifier.
NOTIFY_ID_HANDLER	Maps a WM_NOTIFY message to a handler function, based on the control identifier.
NOTIFY_CODE_HANDLER	Maps a WM_NOTIFY message to a handler function, based on the notification code.
NOTIFY_RANGE_HANDLER	Maps a contiguous range of WM_NOTIFY messages to a handler function, based on the control identifier.

The following macros direct messages to another message map. This process is called "chaining."

Macro	Description
CHAIN_MSG_MAP	Chains to the default message map in the base class.
CHAIN_MSG_MAP_MEMBER	Chains to the default message map in a data member of the class.
CHAIN_MSG_MAP_ALT	Chains to an alternate message map in the base class.
CHAIN_MSG_MAP_ALT_MEMBER	Chains to an alternate message map in a data member of the class.
CHAIN_MSG_MAP_DYNAMIC	Chains to the default message map in another class at run time.

The following macros direct "reflected" messages from the parent window. For example, a control normally sends notification messages to its parent window for processing, but the parent window can reflect the message back to the control.

Macro	Description
REFLECTED_COMMAND_HANDLER	Maps a reflected WM_COMMAND message to a handler function, based on the notification code and the identifier of the menu item, control, or accelerator.
REFLECTED_COMMAND_ID_HANDLER	Maps a reflected WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator.
REFLECTED_COMMAND_CODE_HANDLER	Maps a reflected WM_COMMAND message to a handler function, based on the notification code.
REFLECTED_COMMAND_RANGE_HANDLER	Maps a reflected WM_COMMAND message to a handler function, based on a contiguous range of control identifiers.
REFLECTED_COMMAND_RANGE_CODE_HANDLER	Maps a reflected WM_COMMAND message to a handler function, based on the notification code and a contiguous range of control identifiers.
REFLECTED_NOTIFY_HANDLER	Maps a reflected WM_NOTIFY message to a handler function, based on the notification code and the control identifier.
REFLECTED_NOTIFY_ID_HANDLER	Maps a reflected WM_NOTIFY message to a handler function, based on the control identifier.
REFLECTED_NOTIFY_CODE_HANDLER	Maps a reflected WM_NOTIFY message to a handler function, based on the notification code.
REFLECTED_NOTIFY_RANGE_HANDLER	Maps a reflected WM_NOTIFY message to a handler function, based on a contiguous range of control identifiers.
REFLECTED_NOTIFY_RANGE_CODE_HANDLER	Maps a reflected WM_NOTIFY message to a handler function, based on the notification code and a contiguous range of control identifiers.

Example

class CMyExtWindow : public CMyBaseWindow
{
public:
   BEGIN_MSG_MAP(CMyExtWindow)
      MESSAGE_HANDLER(WM_PAINT, OnPaint)
      MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus)
      CHAIN_MSG_MAP(CMyBaseWindow)
   END_MSG_MAP()

   LRESULT OnPaint(UINT /*nMsg*/, WPARAM /*wParam*/, LPARAM /*lParam*/, 
      BOOL& /*bHandled*/)
   {
      return 0;   
   }

   LRESULT OnSetFocus(UINT /*nMsg*/, WPARAM /*wParam*/, LPARAM /*lParam*/, 
      BOOL& /*bHandled*/) 
   {
      return 0;   
   }
};

When a CMyExtWindow object receives a WM_PAINT message, the message is directed to CMyExtWindow::OnPaint for the actual processing. If OnPaint indicates the message requires further processing, the message will then be directed to the default message map in CMyBaseWindow.

In addition to the default message map, you can define an alternate message map with ALT_MSG_MAP. Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps. The following example shows the default message map and one alternate message map, each containing one handler function:

BEGIN_MSG_MAP(CMyOneAltClass)
   MESSAGE_HANDLER(WM_PAINT, OnPaint)
ALT_MSG_MAP(1)
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus)
END_MSG_MAP()

The next example shows two alternate message maps. The default message map is empty.

BEGIN_MSG_MAP(CMyClass)
ALT_MSG_MAP(1)
   MESSAGE_HANDLER(WM_PAINT, OnPaint)
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus)
ALT_MSG_MAP(2)
   MESSAGE_HANDLER(WM_CREATE, OnCreate)
END_MSG_MAP()

The END_MSG_MAP macro marks the end of the message map. Note that there is always exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

For more information about using message maps in ATL, see Message Maps.

Requirements

Header: atlwin.h

Share via