CDynamicChain Class
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 CDynamicChain Class.
This class provides methods supporting the dynamic chaining of message maps.
重要
This class and its members cannot be used in applications that execute in the Windows Runtime.
class CDynamicChain
Name | Description |
---|---|
CDynamicChain::CDynamicChain | The constructor. |
CDynamicChain::~CDynamicChain | The destructor. |
Name | Description |
---|---|
CDynamicChain::CallChain | Directs a Windows message to another object's message map. |
CDynamicChain::RemoveChainEntry | Removes a message map entry from the collection. |
CDynamicChain::SetChainEntry | Adds a message map entry to the collection or modifies an existing entry. |
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:
Derive your class from
CDynamicChain
. In the message map, specify the CHAIN_MSG_MAP_DYNAMIC macro to chain to another object's default message map.Derive every class you want to chain to from CMessageMap.
CMessageMap
allows an object to expose its message maps to other objects.Call
CDynamicChain::SetChainEntry
to identify which object and which message map you want to chain to.
For example, suppose your class is defined as follows:
class CMyChainWnd : public CWindowImpl<CMyChainWnd>,
public CDynamicChain
{
public:
CMyChainWnd() {}
BEGIN_MSG_MAP(CMyChainWnd)
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 /*nMsg*/, WPARAM /*wParam*/, LPARAM /*lParam*/,
BOOL& /*bHandled*/)
{
// Do some painting code
return 0;
}
LRESULT OnSetFocus(UINT /*uMsg*/, WPARAM /*wParam*/, LPARAM /*lParam*/,
BOOL& /*bHandled*/)
{
return 0;
}
};
The client then calls CMyWindow::SetChainEntry
:
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."
Header: atlwin.h
Directs the Windows message to another object's message map.
BOOL CallChain(
DWORD dwChainID,
HWND hWnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam,
LRESULT& lResult);
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.
TRUE if the message is fully processed; otherwise, FALSE.
For the window procedure to invoke CallChain
, you must specify the CHAIN_MSG_MAP_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.
The constructor.
CDynamicChain();
The destructor.
~CDynamicChain();
Frees all allocated resources.
Removes the specified message map from the collection.
BOOL RemoveChainEntry(DWORD dwChainID);
dwChainID
[in] The unique identifier associated with the chained object and its message map. You originally define this value through a call to SetChainEntry.
TRUE if the message map is successfully removed from the collection. Otherwise, FALSE.
Adds the specified message map to the collection.
BOOL SetChainEntry(
DWORD dwChainID,
CMessageMap* pObject,
DWORD dwMsgMapID = 0);
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
.
TRUE if the message map is successfully added to the collection. Otherwise, FALSE.
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.