class CContainedWindow : public CWindow
CContainedWindow implements a window contained within another object. CContainedWindow's window procedure uses a message map in the containing object to direct messages to the appropriate handlers. When constructing a CContainedWindow object, you specify which message map should be used.
CContainedWindow allows you to create a new window by superclassing an existing window class. The Create method first registers a window class that is based on an existing class but uses CContainedWindow::WindowProc. Create then creates a window based on this new window class. Each instance of CContainedWindow can superclass a different window class.
CContainedWindow also supports window subclassing. The SubclassWindow method attaches an existing window to the CContainedWindow object and changes the window procedure to CContainedWindow::WindowProc. Each instance of CContainedWindow can subclass a different window.
Note For any given CContainedWindow object, call either Create or SubclassWindow. You should not invoke both methods on the same object.
When you use the Add control based on option in the ATL Object Wizard, the wizard will automatically add a CContainedWindow data member to the class implementing the control. The following example is taken from the SUBEDIT sample and shows how the contained window is declared:
class CAtlEdit : ... { public: // Declare a contained window data member CContainedWindow m_EditCtrl;
// Initialize the contained window: // 1. Pass "EDIT" to specify that the contained // window should be based on the standard // Windows Edit box // 2. Pass 'this' pointer to specify that CAtlEdit // contains the message map to be used for the // contained window's message processing // 3. Pass the identifier of the message map. '1' // identifies the alternate message map declared // with ALT_MSG_MAP(1) CAtlEdit() : m_EditCtrl(_T("EDIT"), this, 1) { m_bWindowOnly = TRUE; }
// Declare the default message map, // identified by '0' BEGIN_MSG_MAP(CAtlEdit) ... MESSAGE_HANDLER(WM_CREATE, OnCreate) ... // Declare an alternate message map, // identified by '1' ALT_MSG_MAP(1) MESSAGE_HANDLER(WM_CHAR, OnChar) END_MSG_MAP()
// Define OnCreate handler // When the containing window receives a WM_CREATE // message, create the contained window by calling // CContainedWindow::Create LRESULT OnCreate(UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL& bHandled) { ... m_EditCtrl.Create(m_hWnd, rc, _T("hello"), WS_CHILD | WS_VISIBLE | ES_MULTILINE | ES_AUTOVSCROLL);
return 0; }
...
};
For more information about | See |
Creating controls | ATL Tutorial |
Using windows in ATL | ATL Window Classes |
ATL Object Wizard | Creating an ATL Project |
Windows | "Windows" and subsequent topics in the Win32 SDK |
Subclassing | "Window Procedure Subclassing" in the Win32 SDK |
Superclassing | "Window Procedure Superclassing" in the Win32 SDK |
#include <atlwin.h>
See Also CWindow, CWindowImpl, CMessageMap, BEGIN_MSG_MAP, ALT_MSG_MAP
Methods | |
CContainedWindow | Constructor. Initializes data members to specify which message map will process the contained window's messages. |
Create | Creates a window. |
DefWindowProc | Provides default message processing. |
RegisterWndSuperclass | Registers the window class of the contained window. |
SubclassWindow | Subclasses a window. |
SwitchMessageMap | Changes which message map is used to process the contained window's messages. |
UnsubclassWindow | Restores a previously subclassed window. |
WindowProc | Processes messages sent to the contained window. |
Data Members | |
m_dwMsgMapID | Identifies which message map will process the contained window's messages. |
m_lpszClassName | Specifies the name of an existing window class on which a new window class will be based. |
m_pfnSuperWindowProc | Points to the window class's original window procedure. |
m_pObject | Points to the containing object. |
CContainedWindow( LPTSTR lpszClassName, CMessageMap* pObject, DWORD dwMsgMapID = 0 );
Parameters
lpszClassName [in] The name of an existing window class on which the contained window will be based.
pObject [in] A pointer to the containing object that declares the message map. This object's class must derive from CMessageMap.
dwMsgMapID [in] Identifies the message map that will process the contained window's messages. The default value, 0, specifies the default message map declared with BEGIN_MSG_MAP. To use an alternate message map declared with ALT_MSG_MAP(msgMapID), pass msgMapID.
Remarks
The constructor initializes data members. If you want to create a new window through Create, you must pass the name of an existing window class for the lpszClassName parameter. For an example, see the CContainedWindow overview.
If you subclass an existing window through SubclassWindow, the lpszClassName value will not be used. Therefore, you can pass NULL for this parameter.
CContainedWindow Overview | Class Members
See Also CContainedWindow::m_lpszClassName, CContainedWindow::m_pObject, CContainedWindow::m_pfnSuperWindowProc, CContainedWindow::SwitchMessageMap
HWND Create( HWND hWndParent, RECT& rcPos, LPCTSTR szWindowName = NULL, DWORD dwStyle = WS_CHILD | WS_VISIBLE, DWORD dwExStyle = 0, UINT nID = 0 );
Return Value
If successful, the handle to the newly created window. Otherwise, NULL.
Parameters
hWndParent [in] The handle to the parent or owner window.
rcPos [in] A RECT structure specifying the position of the window.
szWindowName [in] Specifies the name of the window. The default value is NULL.
dwStyle [in] The style of the window. The default value is WS_CHILD | WS_VISIBLE. For a list of possible values, see CreateWindow in the Win32 SDK.
dwExStyle [in] The extended window style. The default value is 0, meaning no extended style. For a list of possible values, see CreateWindowEx in the Win32 SDK.
nID [in] For a child window, the window identifier. For a top-level window, an HWND casted to a UINT. The default value is 0.
Remarks
Calls RegisterWndSuperclass to register a window class that is based on an existing class but uses CContainedWindow::WindowProc. The existing window class name is saved in m_lpszClassName. Create then creates a window based on this new class. The newly created window is automatically attached to the CContainedWindow object.
Note Do not call Create if you have already called SubclassWindow.
CContainedWindow Overview | Class Members
See Also CWindow::m_hWnd
LRESULT DefWindowProc( UINT uMsg, WPARAM wParam, LPARAM lParam );
Return Value
The result of the message processing.
Parameters
uMsg [in] The message sent to the window.
wParam [in] Additional message-specific information.
lParam [in] Additional message-specific information.
Remarks
Called by WindowProc to process messages not handled by the message map. By default, DefWindowProc calls the CallWindowProc Win32 function to send the message information to the window procedure specified in m_pfnSuperWindowProc.
CContainedWindow Overview | Class Members
ATOM RegisterWndSuperClass( );
Return Value
If successful, an atom that uniquely identifies the window class being registered. Otherwise, 0.
Remarks
Called by Create to register the window class of the contained window. This window class is based on an existing class but uses CContainedWindow::WindowProc. The existing window class's name and window procedure are saved in m_lpszClassName and m_pfnSuperWindowProc, respectively.
CContainedWindow Overview | Class Members
See Also CContainedWindow::CContainedWindow
BOOL SubclassWindow( HWND hWnd );
Return Value
TRUE if the window is successfully subclassed; otherwise, FALSE.
Parameters
hWnd [in] The handle to the window being subclassed.
Remarks
Subclasses the window identified by hWnd and attaches it to the CContainedWindow object. The subclassed window now uses CContainedWindow::WindowProc. The original window procedure is saved in m_pfnSuperWindowProc.
Note Do not call SubclassWindow if you have already called Create.
CContainedWindow Overview | Class Members
See Also CContainedWindow::UnsubclassWindow
void SwitchMessageMap( DWORD dwMsgMapID );
Parameters
dwMsgMapID [in] The message map identifier. To use the default message map declared with BEGIN_MSG_MAP, pass 0. To use an alternate message map declared with ALT_MSG_MAP(msgMapID), pass msgMapID.
Remarks
Changes which message map will be used to process the contained window's messages. The message map must be defined in the containing object.
You initially specify the message map identifier in the constructor.
CContainedWindow Overview | Class Members
See Also CContainedWindow::CContainedWindow, CContainedWindow::m_dwMsgMapID
HWND UnsubclassWindow( );
Return Value
The handle to the window previously subclassed.
Remarks
Detaches the subclassed window from the CContainedWindow object and restores the original window procedure, saved in m_pfnSuperWindowProc.
CContainedWindow Overview | Class Members
See Also CContainedWindow::SubclassWindow
static LRESULT CALLBACK WindowProc( HWND hWnd, UINT uMsg, WPARAM wParam, LPARAM lParam );
Return Value
The result of the message processing.
Parameters
hWnd [in] The handle to the window.
uMsg [in] The message sent to the window.
wParam [in] Additional message-specific information.
lParam [in] Additional message-specific information.
Remarks
This static method implements the window procedure. WindowProc directs messages to the message map identified by m_dwMsgMapID. If necessary, WindowProc calls DefWindowProc for additional message processing.
CContainedWindow Overview | Class Members
See Also BEGIN_MSG_MAP, ALT_MSG_MAP
DWORD m_dwMsgMapID;
Remarks
Holds the identifier of the message map currently being used for the contained window. This message map must be declared in the containing object.
The default message map, declared with BEGIN_MSG_MAP, is always identified by 0. An alternate message map, declared with ALT_MSG_MAP(msgMapID), is identified by msgMapID.
m_dwMsgMapID is first initialized by the constructor and can be changed by calling SwitchMessageMap. For an example, see the CContainedWindow overview.
CContainedWindow Overview | Class Members
See Also CContainedWindow::m_pObject
LPTSTR m_lpszClassName;
Remarks
Specifies the name of an existing window class. When you create a window, Create registers a new window class that is based on this existing class but uses CContainedWindow::WindowProc.
m_lpszClassName is initialized by the constructor. For an example, see the CContainedWindow overview.
CContainedWindow Overview | Class Members
WNDPROC m_pfnSuperWindowProc;
Remarks
If the contained window is subclassed, m_pfnSuperWindowProc points to the original window procedure of the window class. If the contained window is superclassed, meaning it is based on a window class that modifies an existing class, m_pfnSuperWindowProc points to the existing window class's window procedure.
DefWindowProc sends message information to the window procedure saved in m_pfnSuperWindowProc.
CContainedWindow Overview | Class Members
See Also CContainedWindow::Create, CContainedWindow::SubclassWindow
CMessageMap* m_pObject;
Remarks
Points to the object containing the CContainedWindow object. This container, whose class must derive from CMessageMap, declares the message map used by the contained window.
m_pObject is initialized by the constructor. For an example, see the CContainedWindow overview.
CContainedWindow Overview | Class Members
See Also CContainedWindow::m_dwMsgMapID