CDynamicChain

class CDynamicChain

CDynamicChain manages a collection of message maps, enabling a Windows message to be directed, at run time, to another object's message map.

To add support for dynamic chaining of message maps, do the following:

For example, suppose your class is defined as follows:

class CMyWindow : public CDynamicChain, ... 
{ 
public: 
   ... 
   BEGIN_MSG_MAP(CMyWindow) 
      MESSAGE_HANDLER(WM_PAINT, OnPaint) 
      MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus) 
      // dynamically chain to the default 
      // message map in another object 
      CHAIN_MSG_MAP_DYNAMIC(1313) 
               // '1313' identifies the object 
               // and the message map that will be 
               // chained to. '1313' is defined 
               // through the SetChainEntry method 
   END_MSG_MAP() 
   LRESULT OnPaint(UINT uMsg, WPARAM wParam, 
                   LPARAM lParam, BOOL& bHandled) 
   { ... } 
   LRESULT OnSetFocus(UINT uMsg, WPARAM wParam, 
                   LPARAM lParam, BOOL& bHandled)  
   { ... } 
}; 

The client then calls CMyWindow::SetChainEntry:

// myCtl is a CMyWindow object 
myCtl.SetChainEntry(1313, &chainedObj); 

where chainedObj is the chained object and is an instance of a class derived from CMessageMap. Now, if myCtl receives a message that is not handled by OnPaint or OnSetFocus, the window procedure directs the message to chainedObj's default message map.

For more information about message map chaining, see Message Maps in the article “ATL Window Classes.”

#include <atlwin.h>

See Also CWindowImpl


CDynamicChain Class Members

Methods
CallChainDirects a Windows message to another object's message map.
RemoveChainEntryRemoves a message map entry from the collection.
SetChainEntryAdds a message map entry to the collection or modifies an existing entry.

CDynamicChain Overview


Methods


CDynamicChain::CallChain

BOOL CallChain( DWORD dwChainID, HWND hWnd, UINT uMsg, WPARAM wParam, LPARAM lParam, LRESULT& lResult );

Return Value

TRUE if the message is fully processed; otherwise, FALSE.

Parameters

dwChainID [in] The unique identifier associated with the chained object and its message map.

hWnd [in] The handle to the window receiving the message.

uMsg [in] The message sent to the window.

wParam [in] Additional message-specific information.

lParam [in] Additional message-specific information.

lResult [out] The result of the message processing.

Remarks

Directs the Windows message to another object's message map. In order for the window procedure to invoke CallChain, you must specify the CHAIN_MSG_MAP_DYNAMIC or CHAIN_MSG_MAP_ALT_DYNAMIC macro in your message map. For an example, see the CDynamicChain overview.

CallChain requires a previous call to SetChainEntry to associate the dwChainID value with an object and its message map.

CDynamicChain Overview | Class Members


CDynamicChain::RemoveChainEntry

BOOL RemoveChainEntry( DWORD dwChainID );

Return Value

TRUE if the message map is successfully removed from the collection. Otherwise, FALSE.

Parameters

dwChainID [in] The unique identifier associated with the chained object and its message map. You originally define this value through a call to SetChainEntry.

Remarks

Removes the specified message map from the collection.

CDynamicChain Overview | Class Members


CDynamicChain::SetChainEntry

BOOL SetChainEntry( DWORD dwChainID, CMessageMap* pObject, DWORD dwMsgMapID = 0 );

Return Value

TRUE if the message map is successfully added to the collection. Otherwise, FALSE.

Parameters

dwChainID [in] The unique identifier associated with the chained object and its message map.

pObject [in] A pointer to the chained object declaring the message map. This object must derive from CMessageMap.

dwMsgMapID [in] The identifier of the message map in the chained object. The default value is 0, which identifies the default message map declared with BEGIN_MSG_MAP. To specify an alternate message map declared with ALT_MSG_MAP(msgMapID), pass msgMapID.

Remarks

Adds the specified message map to the collection. If the dwChainID value already exists in the collection, its associated object and message map are replaced by pObject and dwMsgMapID, respectively. Otherwise, a new entry is added.

CDynamicChain Overview | Class Members

See Also CDynamicChain::CallChain, CDynamicChain::RemoveChainEntry, CHAIN_MSG_MAP_DYNAMIC, CHAIN_MSG_MAP_ALT_DYNAMIC