Edit

Message Map Macros (ATL)

  • Article

These macros define message maps and entries.

Name Description
ALT_MSG_MAP Marks the beginning of an alternate message map.
BEGIN_MSG_MAP Marks the beginning of the default message map.
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 Chains to the default message map in the base class.
CHAIN_MSG_MAP_DYNAMIC Chains to the message map in another class at run time.
CHAIN_MSG_MAP_MEMBER Chains to the default message map in a data member of the class.
COMMAND_CODE_HANDLER Maps a WM_COMMAND message to a handler function, based on the notification code.
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_RANGE_CODE_HANDLER Maps a WM_COMMAND message to a handler function, based on the notification code and a contiguous range of control identifiers.
COMMAND_RANGE_HANDLER Maps a WM_COMMAND message to a handler function, based on a contiguous range of control identifiers.
DECLARE_EMPTY_MSG_MAP Implements an empty message map.
DEFAULT_REFLECTION_HANDLER Provides a default handler for reflected messages that are not handled otherwise.
END_MSG_MAP Marks the end of a message map.
FORWARD_NOTIFICATIONS Forwards notification messages to the parent window.
MESSAGE_HANDLER Maps a Windows message to a handler function.
MESSAGE_RANGE_HANDLER Maps a contiguous range of Windows messages to a handler function.
NOTIFY_CODE_HANDLER Maps a WM_NOTIFY message to a handler function, based on the notification code.
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_RANGE_CODE_HANDLER Maps a WM_NOTIFY message to a handler function, based on the notification code and a contiguous range of control identifiers.
NOTIFY_RANGE_HANDLER Maps a WM_NOTIFY message to a handler function, based on a contiguous range of control identifiers.
REFLECT_NOTIFICATIONS Reflects notification messages back to the window that sent them.
REFLECTED_COMMAND_CODE_HANDLER Maps a reflected WM_COMMAND message to a handler function, based on the notification code.
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_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_COMMAND_RANGE_HANDLER Maps a reflected WM_COMMAND message to a handler function, based on a contiguous range of control identifiers.
REFLECTED_NOTIFY_CODE_HANDLER Maps a reflected WM_NOTIFY message to a handler function, based on the notification code.
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_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.
REFLECTED_NOTIFY_RANGE_HANDLER Maps a reflected WM_NOTIFY message to a handler function, based on a contiguous range of control identifiers.

Requirements

Header: atlwin.h

ALT_MSG_MAP

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

Requirements

Header: atlwin.h

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

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

CHAIN_MSG_MAP_ALT

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.

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.

Requirements

Header: atlwin.h

CHAIN_MSG_MAP_ALT_MEMBER

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.

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.

Requirements

Header: atlwin.h

CHAIN_MSG_MAP

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.

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

Requirements

Header: atlwin.h

CHAIN_MSG_MAP_DYNAMIC

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.

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.

Requirements

Header: atlwin.h

CHAIN_MSG_MAP_MEMBER

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.

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

Requirements

Header: atlwin.h

COMMAND_CODE_HANDLER

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.

Requirements

Header: atlwin.h

COMMAND_HANDLER

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.

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.

Requirements

Header: atlwin.h

COMMAND_ID_HANDLER

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.

Requirements

Header: atlwin.h

COMMAND_RANGE_CODE_HANDLER

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.

Requirements

Header: atlwin.h

COMMAND_RANGE_HANDLER

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.

Requirements

Header: atlwin.h

DECLARE_EMPTY_MSG_MAP

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

DEFAULT_REFLECTION_HANDLER

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

Requirements

Header: atlwin.h

END_MSG_MAP

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

Requirements

Header: atlwin.h

FORWARD_NOTIFICATIONS

Forwards notification messages to the parent window.

FORWARD_NOTIFICATIONS()

Remarks

Specify this macro as part of your message map.

Requirements

Header: atlwin.h

MESSAGE_HANDLER

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.

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

Requirements

Header: atlwin.h

MESSAGE_RANGE_HANDLER

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.

Requirements

Header: atlwin.h

NOTIFY_CODE_HANDLER

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.

Requirements

Header: atlwin.h

NOTIFY_HANDLER

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.

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

Requirements

Header: atlwin.h

NOTIFY_ID_HANDLER

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.

Requirements

Header: atlwin.h

NOTIFY_RANGE_CODE_HANDLER

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.

Requirements

Header: atlwin.h

NOTIFY_RANGE_HANDLER

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.

Requirements

Header: atlwin.h

REFLECT_NOTIFICATIONS

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.

Requirements

Header: atlwin.h

REFLECTED_COMMAND_CODE_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_COMMAND_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_COMMAND_ID_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_COMMAND_RANGE_CODE_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_COMMAND_RANGE_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_NOTIFY_CODE_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_NOTIFY_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_NOTIFY_ID_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_NOTIFY_RANGE_CODE_HANDLER

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.

Requirements

Header: atlwin.h

REFLECTED_NOTIFY_RANGE_HANDLER

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.

See also

Macros