Message Map Macros (ATL)

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at Message Map Macros (ATL).

These macros define message maps and entries.

ALT_MSG_MAPMarks the beginning of an alternate message map.
BEGIN_MSG_MAPMarks the beginning of the default message map.
CHAIN_MSG_MAP_ALTChains to an alternate message map in the base class.
CHAIN_MSG_MAP_ALT_MEMBERChains to an alternate message map in a data member of the class.
CHAIN_MSG_MAPChains to the default message map in the base class.
CHAIN_MSG_MAP_DYNAMICChains to the message map in another class at run time.
CHAIN_MSG_MAP_MEMBERChains to the default message map in a data member of the class.
COMMAND_CODE_HANDLERMaps a WM_COMMAND message to a handler function, based on the notification code.
COMMAND_HANDLERMaps 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_HANDLERMaps a WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator.
COMMAND_RANGE_CODE_HANDLERMaps a WM_COMMAND message to a handler function, based on the notification code and a contiguous range of control identifiers.
COMMAND_RANGE_HANDLERMaps a WM_COMMAND message to a handler function, based on a contiguous range of control identifiers.
DECLARE_EMPTY_MSG_MAPImplements an empty message map.
DEFAULT_REFLECTION_HANDLERProvides a default handler for reflected messages that are not handled otherwise.
END_MSG_MAPMarks the end of a message map.
FORWARD_NOTIFICATIONSForwards notification messages to the parent window.
MESSAGE_HANDLERMaps a Windows message to a handler function.
MESSAGE_RANGE_HANDLERMaps a contiguous range of Windows messages to a handler function.
NOTIFY_CODE_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code.
NOTIFY_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code and the control identifier.
NOTIFY_ID_HANDLERMaps a WM_NOTIFY message to a handler function, based on the control identifier.
NOTIFY_RANGE_CODE_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code and a contiguous range of control identifiers.
NOTIFY_RANGE_HANDLERMaps a WM_NOTIFY message to a handler function, based on a contiguous range of control identifiers.
REFLECT_NOTIFICATIONSReflects notification messages back to the window that sent them.
REFLECTED_COMMAND_CODE_HANDLERMaps a reflected WM_COMMAND message to a handler function, based on the notification code.
REFLECTED_COMMAND_HANDLERMaps 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_HANDLERMaps a reflected WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator.
REFLECTED_COMMAND_RANGE_CODE_HANDLERMaps a reflected WM_COMMAND message to a handler function, based on the notification code and a contiguous range of control identifiers.
REFLECTED_COMMAND_RANGE_HANDLERMaps a reflected WM_COMMAND message to a handler function, based on a contiguous range of control identifiers.
REFLECTED_NOTIFY_CODE_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on the notification code.
REFLECTED_NOTIFY_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on the notification code and the control identifier.
REFLECTED_NOTIFY_ID_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on the control identifier.
REFLECTED_NOTIFY_RANGE_CODE_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on the notification code and a contiguous range of control identifiers.
REFLECTED_NOTIFY_RANGE_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on a contiguous range of control identifiers.

Marks the beginning of an alternate message map.

ALT_MSG_MAP(msgMapID)

Parameters

msgMapID
[in] The message map identifier.

Remarks

ATL identifies each message map by a number. The default message map (declared with the BEGIN_MSG_MAP macro) is identified by 0. An alternate message map is identified by msgMapID.

Message maps are used to process messages sent to a window. For example, CContainedWindow allows you to specify the identifier of a message map in the containing object. CContainedWindow::WindowProc then uses this message map to direct the contained window's messages either to the appropriate handler function or to another message map. For a list of macros that declare handler functions, see BEGIN_MSG_MAP.

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps.

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.

Example

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

Marks the beginning of the default message map.

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.

MacroDescription
MESSAGE_HANDLERMaps a Windows message to a handler function.
MESSAGE_RANGE_HANDLERMaps a contiguous range of Windows messages to a handler function.
COMMAND_HANDLERMaps 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_HANDLERMaps a WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator.
COMMAND_CODE_HANDLERMaps a WM_COMMAND message to a handler function, based on the notification code.
COMMAND_RANGE_HANDLERMaps a contiguous range of WM_COMMAND messages to a handler function, based on the identifier of the menu item, control, or accelerator.
NOTIFY_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code and the control identifier.
NOTIFY_ID_HANDLERMaps a WM_NOTIFY message to a handler function, based on the control identifier.
NOTIFY_CODE_HANDLERMaps a WM_NOTIFY message to a handler function, based on the notification code.
NOTIFY_RANGE_HANDLERMaps 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."

MacroDescription
CHAIN_MSG_MAPChains to the default message map in the base class.
CHAIN_MSG_MAP_MEMBERChains to the default message map in a data member of the class.
CHAIN_MSG_MAP_ALTChains to an alternate message map in the base class.
CHAIN_MSG_MAP_ALT_MEMBERChains to an alternate message map in a data member of the class.
CHAIN_MSG_MAP_DYNAMICChains 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.

MacroDescription
REFLECTED_COMMAND_HANDLERMaps 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_HANDLERMaps a reflected WM_COMMAND message to a handler function, based on the identifier of the menu item, control, or accelerator.
REFLECTED_COMMAND_CODE_HANDLERMaps a reflected WM_COMMAND message to a handler function, based on the notification code.
REFLECTED_COMMAND_RANGE_HANDLERMaps a reflected WM_COMMAND message to a handler function, based on a contiguous range of control identifiers.
REFLECTED_COMMAND_RANGE_CODE_HANDLERMaps a reflected WM_COMMAND message to a handler function, based on the notification code and a contiguous range of control identifiers.
REFLECTED_NOTIFY_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on the notification code and the control identifier.
REFLECTED_NOTIFY_ID_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on the control identifier.
REFLECTED_NOTIFY_CODE_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on the notification code.
REFLECTED_NOTIFY_RANGE_HANDLERMaps a reflected WM_NOTIFY message to a handler function, based on a contiguous range of control identifiers.
REFLECTED_NOTIFY_RANGE_CODE_HANDLERMaps 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.

Defines an entry in a message map.

CHAIN_MSG_MAP_ALT(theChainClass, msgMapID)

Parameters

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

msgMapID
[in] The message map identifier.

Remarks

CHAIN_MSG_MAP_ALT directs messages to an alternate message map in a base class. You must have declared this alternate message map with ALT_MSG_MAP(msgMapID). To direct messages to a base class's default message map (declared with BEGIN_MSG_MAP), use CHAIN_MSG_MAP. For an example, see CHAIN_MSG_MAP.

System_CAPS_ICON_note.jpg Note

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

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

Defines an entry in a message map.

CHAIN_MSG_MAP_ALT_MEMBER(theChainMember, msgMapID)

Parameters

theChainMember
[in] The name of the data member containing the message map.

msgMapID
[in] The message map identifier.

Remarks

CHAIN_MSG_MAP_ALT_MEMBER directs messages to an alternate message map in a data member. You must have declared this alternate message map with ALT_MSG_MAP(msgMapID). To direct messages to a data member's default message map (declared with BEGIN_MSG_MAP), use CHAIN_MSG_MAP_MEMBER. For an example, see CHAIN_MSG_MAP_MEMBER.

System_CAPS_ICON_note.jpg Note

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

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

Defines an entry in a message map.

CHAIN_MSG_MAP(theChainClass)

Parameters

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

Remarks

CHAIN_MSG_MAP directs messages to a base class's default message map (declared with BEGIN_MSG_MAP). To direct messages to a base class's alternate message map (declared with ALT_MSG_MAP), use CHAIN_MSG_MAP_ALT.

System_CAPS_ICON_note.jpg Note

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

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

Example

class CMyExtClass : public CMyBaseClass
{
public:
  BEGIN_MSG_MAP(CMyExtClass)
     MESSAGE_HANDLER(WM_PAINT, OnPaint)
     // chain to default message map in CMyBaseClass
     CHAIN_MSG_MAP(CMyBaseClass)
  ALT_MSG_MAP(1)
     // chain to first alternative message map in CMyBaseClass
     CHAIN_MSG_MAP(CMyBaseClass)
  ALT_MSG_MAP(2)
     MESSAGE_HANDLER(WM_CHAR, OnChar)
     // chain to alternate message map in CMyBaseClass
     CHAIN_MSG_MAP_ALT(CMyBaseClass, 1)
  END_MSG_MAP()

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

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

This example illustrates the following:

  • If a window procedure is using CMyClass's default message map and OnPaint does not handle a message, the message is directed to CMyBaseClass's default message map for processing.

  • If a window procedure is using the first alternate message map in CMyClass, all messages are directed to CMyBaseClass's default message map.

  • If a window procedure is using CMyClass's second alternate message map and OnChar does not handle a message, the message is directed to the specified alternate message map in CMyBaseClass. CMyBaseClass must have declared this message map with ALT_MSG_MAP(1).

Defines an entry in a message map.

CHAIN_MSG_MAP_DYNAMIC(dynaChainID)

Parameters

dynaChainID
[in] The unique identifier for an object's message map.

Remarks

CHAIN_MSG_MAP_DYNAMIC directs messages, at run time, to the default message map in another object. The object and its message map are associated with dynaChainID, which you define through CDynamicChain::SetChainEntry. You must derive your class from CDynamicChain in order to use CHAIN_MSG_MAP_DYNAMIC. For an example, see the CDynamicChain overview.

System_CAPS_ICON_note.jpg Note

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

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

Defines an entry in a message map.

CHAIN_MSG_MAP_MEMBER(theChainMember)

Parameters

theChainMember
[in] The name of the data member containing the message map.

Remarks

CHAIN_MSG_MAP_MEMBER directs messages to a data member's default message map (declared with BEGIN_MSG_MAP). To direct messages to a data member's alternate message map (declared with ALT_MSG_MAP), use CHAIN_MSG_MAP_ALT_MEMBER.

System_CAPS_ICON_note.jpg Note

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

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

Example

class CMyContainerClass : public CWindowImpl<CMyContainerClass>
{
public:
   CMyContainedClass m_obj;

   BEGIN_MSG_MAP(CMyContainerClass)
      MESSAGE_HANDLER(WM_PAINT, OnPaint)
      // chain to default message map of m_obj
      CHAIN_MSG_MAP_MEMBER(m_obj)
   ALT_MSG_MAP(1)
      // chain to default message map of m_obj
      CHAIN_MSG_MAP_MEMBER(m_obj)
   ALT_MSG_MAP(2)
      MESSAGE_HANDLER(WM_CHAR, OnChar)
      // chain to alternate message map of m_obj
      CHAIN_MSG_MAP_ALT_MEMBER(m_obj, 1)
   END_MSG_MAP()

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

This example illustrates the following:

  • If a window procedure is using CMyClass's default message map and OnPaint does not handle a message, the message is directed to m_obj's default message map for processing.

  • If a window procedure is using the first alternate message map in CMyClass, all messages are directed to m_obj's default message map.

  • If a window procedure is using CMyClass's second alternate message map and OnChar does not handle a message, the message is directed to the specified alternate message map of m_obj. Class CMyContainedClass must have declared this message map with ALT_MSG_MAP(1).

Similar to COMMAND_HANDLER, but maps a WM_COMMAND message based only on the notification code.

COMMAND_CODE_HANDLER(code, func)

Parameters

code
[in] The notification code.

func
[in] The name of the message-handler function.

Defines an entry in a message map.

COMMAND_HANDLER(id, code, func)

Parameters

id
[in] The identifier of the menu item, control, or accelerator.

code
[in] The notification code.

func
[in] The name of the message-handler function.

Remarks

COMMAND_HANDLER maps a WM_COMMAND message to the specified handler function, based on the notification code and the control identifier. For example:

class ATL_NO_VTABLE CPolyProp :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CPolyProp, &CLSID_PolyProp>,
   public IPropertyPageImpl<CPolyProp>,
   public CDialogImpl<CPolyProp>
{
public:
BEGIN_COM_MAP(CPolyProp)
   COM_INTERFACE_ENTRY(IPropertyPage)
END_COM_MAP()

BEGIN_MSG_MAP(CPolyProp)
   COMMAND_HANDLER(IDC_SIDES, EN_CHANGE, OnEnChangeSides)
   CHAIN_MSG_MAP(IPropertyPageImpl<CPolyProp>)
END_MSG_MAP()

   // When a CPolyProp object receives a WM_COMMAND message identified 
   // by IDC_SIDES and EN_CHANGE, the message is directed to 
   // CPolyProp::OnEnChangeSides for the actual processing.
   LRESULT OnEnChangeSides(WORD /*wNotifyCode*/, WORD /*wID*/, HWND /*hWndCtl*/, 
      BOOL& /*bHandled*/);

Any function specified in a COMMAND_HANDLER macro must be defined as follows:

LRESULT CommandHandler(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL& bHandled);

The message map sets bHandled to TRUE before CommandHandler is called. If CommandHandler does not fully handle the message, it should set bHandled to FALSE to indicate the message needs further processing.

System_CAPS_ICON_note.jpg Note

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

In addition to COMMAND_HANDLER, you can use MESSAGE_HANDLER to map a WM_COMMAND message without regard to an identifier or code. In this case, MESSAGE_HANDLER(WM_COMMAND, OnHandlerFunction) will direct all WM_COMMAND messages to OnHandlerFunction.

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

Similar to COMMAND_HANDLER, but maps a WM_COMMAND message based only on the identifier of the menu item, control, or accelerator.

COMMAND_ID_HANDLER(id, func)

Parameters

id
[in] The identifier of the menu item, control, or accelerator sending the message.

func
[in] The name of the message-handler function.

Similar to COMMAND_RANGE_HANDLER, but maps WM_COMMAND messages with a specific notification code from a range of controls to a single handler function.

COMMAND_RANGE_CODE_HANDLER(idFirst, idLast, code, func)

Parameters

idFirst
[in] Marks the beginning of a contiguous range of control identifiers.

idLast
[in] Marks the end of a contiguous range of control identifiers.

code
[in] The notification code.

func
[in] The name of the message-handler function.

Remarks

This range is based on the identifier of the menu item, control, or accelerator sending the message.

Similar to COMMAND_HANDLER, but maps WM_COMMAND messages from a range of controls to a single handler function.

COMMAND_RANGE_HANDLER( idFirst, idLast, func)

Parameters

idFirst
[in] Marks the beginning of a contiguous range of control identifiers.

idLast
[in] Marks the end of a contiguous range of control identifiers.

func
[in] The name of the message-handler function.

Remarks

This range is based on the identifier of the menu item, control, or accelerator sending the message.

Declares an empty message map.

DECLARE_EMPTY_MSG_MAP()

Remarks

DECLARE_EMPTY_MSG_MAP is a convenience macro that calls the macros BEGIN_MSG_MAP and END_MSG_MAP to create an empty message map:

   BEGIN_MSG_MAP(CExample)
   END_MSG_MAP()

Provides a default handler for the child window (control) that will receive reflected messages; the handler will properly pass unhandled messages to DefWindowProc.

DEFAULT_REFLECTION_HANDLER()

Marks the end of a message map.

END_MSG_MAP()

Remarks

Always use the BEGIN_MSG_MAP macro to mark the beginning of a message map. Use ALT_MSG_MAP to declare subsequent alternate message maps.

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.

Example

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

Forwards notification messages to the parent window.

FORWARD_NOTIFICATIONS()

Remarks

Specify this macro as part of your message map.

Defines an entry in a message map.

MESSAGE_HANDLER(Â
    msg, Â
    func Â)

Parameters

msg
[in] The Windows message.

func
[in] The name of the message-handler function.

Remarks

MESSAGE_HANDLER maps a Windows message to the specified handler function.

Any function specified in a MESSAGE_HANDLER macro must be defined as follows:

LRESULT MessageHandler(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled);

The message map sets bHandled to TRUE before MessageHandler is called. If MessageHandler does not fully handle the message, it should set bHandled to FALSE to indicate the message needs further processing.

System_CAPS_ICON_note.jpg Note

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

In addition to MESSAGE_HANDLER, you can use COMMAND_HANDLER and NOTIFY_HANDLER to map WM_COMMAND and WM_NOTIFY messages, respectively.

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

Example

class CMyBaseWindow : public CWindowImpl<CMyBaseWindow>
{
public:
   BEGIN_MSG_MAP(CMyBaseWindow)
      MESSAGE_HANDLER(WM_CREATE, OnCreate)
   END_MSG_MAP()

   // When a CMyBaseWindow object receives a WM_CREATE message, the message
   // is directed to CMyBaseWindow::OnCreate for the actual processing.
   LRESULT OnCreate(UINT /*nMsg*/, WPARAM /*wParam*/, LPARAM /*lParam*/, 
      BOOL& /*bHandled*/)
   {
      return 0;   
   }
};

Similar to MESSAGE_HANDLER, but maps a range of Windows messages to a single handler function.

MESSAGE_RANGE_HANDLER(Â
    msgFirst, Â
    msgLast, Â
    func Â)

Parameters

msgFirst
[in] Marks the beginning of a contiguous range of messages.

msgLast
[in] Marks the end of a contiguous range of messages.

func
[in] The name of the message-handler function.

Similar to NOTIFY_HANDLER, but maps a WM_NOTIFY message based only on the notification code.

NOTIFY_CODE_HANDLER(Â
    cd, Â
    func Â)

Parameters

cd
[in] The notification code.

func
[in] The name of the message-handler function.

Defines an entry in a message map.

NOTIFY_HANDLER(Â
    id, Â
    cd, Â
    func Â)

Parameters

id
[in] The identifier of the control sending the message.

cd
[in] The notification code.

func
[in] The name of the message-handler function.

Remarks

NOTIFY_HANDLER maps a WM_NOTIFY message to the specified handler function, based on the notification code and the control identifier.

Any function specified in a NOTIFY_HANDLER macro must be defined as follows:

LRESULT NotifyHandler(int idCtrl, LPNMHDR pnmh, BOOL& bHandled);

The message map sets bHandled to TRUE before NotifyHandler is called. If NotifyHandler does not fully handle the message, it should set bHandled to FALSE to indicate the message needs further processing.

System_CAPS_ICON_note.jpg Note

Always begin a message map with BEGIN_MSG_MAP. You can then declare subsequent alternate message maps with ALT_MSG_MAP. The END_MSG_MAP macro marks the end of the message map. Every message map must have exactly one instance of BEGIN_MSG_MAP and END_MSG_MAP.

In addition to NOTIFY_HANDLER, you can use MESSAGE_HANDLER to map a WM_NOTIFY message without regard to an identifier or code. In this case, MESSAGE_HANDLER(WM_NOTIFY, OnHandlerFunction) will direct all WM_NOTIFY messages to OnHandlerFunction.

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

Example

class CMyDialog2 : public CDialogImpl<CMyDialog2>
{
public:
   enum { IDD = IDD_MYDLG };

   BEGIN_MSG_MAP(CMyDialog2)
      NOTIFY_HANDLER(IDC_TREE1, NM_CLICK, OnNMClickTree1)
   END_MSG_MAP()

public:
   // When a CMyDialog2 object receives a WM_NOTIFY message 
   // identified by IDC_TREE1 and NM_CLICK, the message is 
   // directed to CMyDialog2::OnNMClickTree1 for the actual
   // processing.
   LRESULT OnNMClickTree1(int /*idCtrl*/, LPNMHDR pNMHDR, BOOL& /*bHandled*/);
};

Similar to NOTIFY_HANDLER, but maps a WM_NOTIFY message based only on the control identifier.

NOTIFY_ID_HANDLER(Â
    id, Â
    func Â)

Parameters

id
[in] The identifier of the control sending the message.

func
[in] The name of the message-handler function.

Similar to NOTIFY_RANGE_HANDLER, but maps WM_NOTIFY messages with a specific notification code from a range of controls to a single handler function.

NOTIFY_RANGE_CODE_HANDLER(Â
    idFirst, Â
    idLast, Â
    cd, Â
    func Â)

Parameters

idFirst
[in] Marks the beginning of a contiguous range of control identifiers.

idLast
[in] Marks the end of a contiguous range of control identifiers.

cd
[in] The notification code.

func
[in] The name of the message-handler function.

Remarks

This range is based on the identifier of the control sending the message.

Similar to NOTIFY_HANDLER, but maps WM_NOTIFY messages from a range of controls to a single handler function.

NOTIFY_RANGE_HANDLER(Â
    idFirst, Â
    idLast, Â
    func Â)

Parameters

idFirst
[in] Marks the beginning of a contiguous range of control identifiers.

idLast
[in] Marks the end of a contiguous range of control identifiers.

func
[in] The name of the message-handler function.

Remarks

This range is based on the identifier of the control sending the message.

Reflects notification messages back to the child window (control) that sent them.

REFLECT_NOTIFICATIONS()

Remarks

Specify this macro as part of the parent window's message map.

Similar to COMMAND_CODE_HANDLER, but maps commands reflected from the parent window.

REFLECTED_COMMAND_CODE_HANDLER(Â
    code, Â
    func Â)

Parameters

code
[in] The notification code.

func
[in] The name of the message-handler function.

Similar to COMMAND_HANDLER, but maps commands reflected from the parent window.

REFLECTED_COMMAND_HANDLER(Â
    id, Â
    code, Â
    func Â)

Parameters

id
[in] The identifier of the menu item, control, or accelerator.

code
[in] The notification code.

func
[in] The name of the message-handler function.

Similar to COMMAND_ID_HANDLER, but maps commands reflected from the parent window.

REFLECTED_COMMAND_ID_HANDLER(Â
    id, Â
    func Â)

Parameters

id
[in] The identifier of the menu item, control, or accelerator.

func
[in] The name of the message-handler function.

Similar to COMMAND_RANGE_CODE_HANDLER, but maps commands reflected from the parent window.

REFLECTED_COMMAND_RANGE_CODE_HANDLER(Â
    idFirst, Â
    idLast, Â
    code, Â
    func Â)

Parameters

idFirst
[in] Marks the beginning of a contiguous range of control identifiers.

idLast
[in] Marks the end of a contiguous range of control identifiers.

code
[in] The notification code.

func
[in] The name of the message-handler function.

Similar to COMMAND_RANGE_HANDLER, but maps commands reflected from the parent window.

REFLECTED_COMMAND_RANGE_HANDLER(Â
    idFirst, Â
    idLast, Â
    func Â)

Parameters

idFirst
[in] Marks the beginning of a contiguous range of control identifiers.

idLast
[in] Marks the end of a contiguous range of control identifiers.

func
[in] The name of the message-handler function.

Similar to NOTIFY_CODE_HANDLER, but maps notifications reflected from the parent window.

REFLECTED_NOTIFY_CODE_HANDLER_EX(Â
    cd, Â
    func Â)

Parameters

cd
[in] The notification code.

func
[in] The name of the message-handler function.

Similar to NOTIFY_HANDLER, but maps notifications reflected from the parent window.

REFLECTED_NOTIFY_HANDLER(Â
    id, Â
    cd, Â
    func Â)

Parameters

id
[in] The identifier of the menu item, control, or accelerator.

cd
[in] The notification code.

func
[in] The name of the message-handler function.

Similar to NOTIFY_ID_HANDLER, but maps notifications reflected from the parent window.

REFLECTED_NOTIFY_ID_HANDLER(Â
    id, Â
    func Â)

Parameters

id
[in] The identifier of the menu item, control, or accelerator.

func
[in] The name of the message-handler function.

Similar to NOTIFY_RANGE_CODE_HANDLER, but maps notifications reflected from the parent window.

REFLECTED_NOTIFY_RANGE_CODE_HANDLER(
idFirst,Â
    idLast, Â
    cd, Â
    func)

Parameters

idFirst
[in] Marks the beginning of a contiguous range of control identifiers.

idLast
[in] Marks the end of a contiguous range of control identifiers.

cd
[in] The notification code.

func
[in] The name of the message-handler function.

Similar to NOTIFY_RANGE_HANDLER, but maps notifications reflected from the parent window.

REFLECTED_NOTIFY_RANGE_HANDLER(Â
    idFirst, Â
    idLast, Â
    func Â)

Parameters

idFirst
[in] Marks the beginning of a contiguous range of control identifiers.

idLast
[in] Marks the end of a contiguous range of control identifiers.

func
[in] The name of the message-handler function.

Macros

Show: