CContainedWindow

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 aboutSee
Creating controlsATL Tutorial
Using windows in ATLATL Window Classes
ATL Object WizardCreating 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


CContainedWindow Class Members

Methods
CContainedWindowConstructor. Initializes data members to specify which message map will process the contained window's messages.
CreateCreates a window.
DefWindowProcProvides default message processing.
RegisterWndSuperclassRegisters the window class of the contained window.
SubclassWindowSubclasses a window.
SwitchMessageMapChanges which message map is used to process the contained window's messages.
UnsubclassWindowRestores a previously subclassed window.
WindowProcProcesses messages sent to the contained window.
Data Members
m_dwMsgMapIDIdentifies which message map will process the contained window's messages.
m_lpszClassNameSpecifies the name of an existing window class on which a new window class will be based.
m_pfnSuperWindowProcPoints to the window class's original window procedure.
m_pObjectPoints to the containing object.

CContainedWindow Overview


Methods


CContainedWindow::CContainedWindow

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


CContainedWindow::Create

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


CContainedWindow::DefWindowProc

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


CContainedWindow::RegisterWndSuperclass

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


CContainedWindow::SubclassWindow

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


CContainedWindow::SwitchMessageMap

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


CContainedWindow::UnsubclassWindow

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


CContainedWindow::WindowProc

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


Data Members


CContainedWindow::m_dwMsgMapID

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


CContainedWindow::m_lpszClassName

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


CContainedWindow::m_pfnSuperWindowProc

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


CContainedWindow::m_pObject

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