Share via

CContainedWindowT Class

  • Article

 

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 CContainedWindowT Class.

This class implements a window contained within another object.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

template <class TBase = CWindow, class TWinTraits = CControlWinTraits>  
class CContainedWindowT : public TBase

Parameters

TBase
The base class of your new class. The default base class is CWindow.

TWinTraits
A traits class that defines styles for your window. The default is CControlWinTraits.

Note

CContainedWindow is a specialization of CContainedWindowT. If you want to change the base class or traits, use CContainedWindowT directly.

Members

Public Constructors

Name Description
CContainedWindowT::CContainedWindowT Constructor. Initializes data members to specify which message map will process the contained window's messages.

Public Methods

Name Description
CContainedWindowT::Create Creates a window.
CContainedWindowT::DefWindowProc Provides default message processing.
CContainedWindowT::GetCurrentMessage Returns the current message.
CContainedWindowT::RegisterWndSuperclass Registers the window class of the contained window.
CContainedWindowT::SubclassWindow Subclasses a window.
CContainedWindowT::SwitchMessageMap Changes which message map is used to process the contained window's messages.
CContainedWindowT::UnsubclassWindow Restores a previously subclassed window.
CContainedWindowT::WindowProc (Static) Processes messages sent to the contained window.

Public Data Members

Name Description
CContainedWindowT::m_dwMsgMapID Identifies which message map will process the contained window's messages.
CContainedWindowT::m_lpszClassName Specifies the name of an existing window class on which a new window class will be based.
CContainedWindowT::m_pfnSuperWindowProc Points to the window class's original window procedure.
CContainedWindowT::m_pObject Points to the containing object.

Remarks

CContainedWindowT implements a window contained within another object. CContainedWindowT's window procedure uses a message map in the containing object to direct messages to the appropriate handlers. When constructing a CContainedWindowT object, you specify which message map should be used.

CContainedWindowT 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 CContainedWindowT::WindowProc. Create then creates a window based on this new window class. Each instance of CContainedWindowT can superclass a different window class.

CContainedWindowT also supports window subclassing. The SubclassWindow method attaches an existing window to the CContainedWindowT object and changes the window procedure to CContainedWindowT::WindowProc. Each instance of CContainedWindowT can subclass a different window.

Note

For any given CContainedWindowT 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 Project Wizard, the wizard will automatically add a CContainedWindowT data member to the class implementing the control. The following example shows how the contained window is declared:

public:
   // Declare a contained window data member
   CContainedWindow m_ctlEdit;

   // 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_ctlEdit(_T("Edit"), this, 1)
   {
      m_bWindowOnly = TRUE;
   }

// Declare the default message map, identified by '0'
BEGIN_MSG_MAP(CAtlEdit)
   MESSAGE_HANDLER(WM_CREATE, OnCreate)
   MESSAGE_HANDLER(WM_SETFOCUS, OnSetFocus)
   CHAIN_MSG_MAP(CComControl<CAtlEdit>)
// 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*/)
   {
      RECT rc;
      GetWindowRect(&rc);
      rc.right -= rc.left;
      rc.bottom -= rc.top;
      rc.top = rc.left = 0;
      m_ctlEdit.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 Project Wizard Creating an ATL Project
Windows Windows and subsequent topics in the Windows SDK

Inheritance Hierarchy

TBase

CContainedWindowT

Requirements

Header: atlwin.h

CContainedWindowT::CContainedWindowT

The constructor initializes data members.

CContainedWindowT(
    LPTSTR lpszClassName,
    CMessageMap* pObject,
    DWORD dwMsgMapID = 0);

CContainedWindowT(
    CMessageMap* pObject,
    DWORD dwMsgMapID = 0)
    CContainedWindowT();

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

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.

There are three constructors:

  • The constructor with three arguments is the one typically called.

  • The constructor with two arguments uses the class name from TBase::GetWndClassName.

  • The constructor with no arguments is used if you want to supply the arguments later. You must supply the window class name, message map object, and message map ID when you later call Create.

If you subclass an existing window through SubclassWindow, the lpszClassName value will not be used; therefore, you can pass NULL for this parameter.

CContainedWindowT::Create

Calls RegisterWndSuperclass to register a window class that is based on an existing class but uses CContainedWindowT::WindowProc.

HWND Create(  
    HWND hWndParent,
    _U_RECT rect,
    LPCTSTR szWindowName = NULL,
    DWORD dwStyle = 0,
    DWORD dwExStyle = 0,
    _U_MENUorID MenuOrID = 0U,
    LPVOID lpCreateParam = NULL);

HWND Create(
    CMessageMap* pObject,
    DWORD dwMsgMapID,
    HWND hWndParent,
    _U_RECT rect,
    LPCTSTR szWindowName = NULL,
    DWORD dwStyle = 0,
    DWORD dwExStyle = 0,
    _U_MENUorID MenuOrID = 0U,
    LPVOID lpCreateParam = NULL);

HWND Create(
    LPCTSTR lpszClassName,
    CMessageMap* pObject,
    DWORD dwMsgMapID,
    HWND hWndParent,
    _U_RECT rect,
    LPCTSTR szWindowName = NULL,
    DWORD dwStyle = 0,
    DWORD dwExStyle = 0,
    _U_MENUorID MenuOrID = 0U,
    LPVOID lpCreateParam = NULL);

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.

hWndParent
[in] The handle to the parent or owner window.

rect
[in] A RECT structure specifying the position of the window. The RECT can be passed by pointer or by reference.

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 Windows 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 Windows SDK.

MenuOrID
[in] For a child window, the window identifier. For a top-level window, a menu handle for the window. The default value is 0U.

lpCreateParam
[in] A pointer to window-creation data. For a full description, see the description for the final parameter to CreateWindowEx.

Return Value

If successful, the handle to the newly created window; otherwise, NULL.

Remarks

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 CContainedWindowT object.

Note

Do not call Create if you have already called SubclassWindow.

Note

If 0 is used as the value for the MenuOrID parameter, it must be specified as 0U (the default value) to avoid a compiler error.

CContainedWindowT::DefWindowProc

Called by WindowProc to process messages not handled by the message map.

LRESULT DefWindowProc()
LRESULT DefWindowProc(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam);

Parameters

uMsg
[in] The message sent to the window.

wParam
[in] Additional message-specific information.

lParam
[in] Additional message-specific information.

Return Value

The result of the message processing.

Remarks

By default, DefWindowProc calls the CallWindowProc Win32 function to send the message information to the window procedure specified in m_pfnSuperWindowProc.

CContainedWindowT::GetCurrentMessage

Returns the current message ( m_pCurrentMsg).

const _ATL_MSG* GetCurrentMessage();

Return Value

The current message, packaged in the MSG structure.

CContainedWindowT::m_dwMsgMapID

Holds the identifier of the message map currently being used for the contained window.

DWORD m_dwMsgMapID;

Remarks

This message map must be declared in the containing object.

The default message map, declared with BEGIN_MSG_MAP, is always identified by zero. 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 CContainedWindowT Overview.

CContainedWindowT::m_lpszClassName

Specifies the name of an existing window class.

LPTSTR m_lpszClassName;

Remarks

When you create a window, Create registers a new window class that is based on this existing class but uses CContainedWindowT::WindowProc.

m_lpszClassName is initialized by the constructor. For an example, see the CContainedWindowT overview.

CContainedWindowT::m_pfnSuperWindowProc

If the contained window is subclassed, m_pfnSuperWindowProc points to the original window procedure of the window class.

WNDPROC m_pfnSuperWindowProc;

Remarks

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.

The DefWindowProc method sends message information to the window procedure saved in m_pfnSuperWindowProc.

CContainedWindowT::m_pObject

Points to the object containing the CContainedWindowT object.

CMessageMap* m_pObject;

Remarks

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 CContainedWindowT overview.

CContainedWindowT::RegisterWndSuperclass

Called by Create to register the window class of the contained window.

ATOM RegisterWndSuperClass();

Return Value

If successful, an atom that uniquely identifies the window class being registered; otherwise, zero.

Remarks

This window class is based on an existing class but uses CContainedWindowT::WindowProc. The existing window class's name and window procedure are saved in m_lpszClassName and m_pfnSuperWindowProc, respectively.

CContainedWindowT::SubclassWindow

Subclasses the window identified by hWnd and attaches it to the CContainedWindowT object.

BOOL SubclassWindow(HWND hWnd);

Parameters

hWnd
[in] The handle to the window being subclassed.

Return Value

TRUE if the window is successfully subclassed; otherwise, FALSE.

Remarks

The subclassed window now uses CContainedWindowT::WindowProc. The original window procedure is saved in m_pfnSuperWindowProc.

Note

Do not call SubclassWindow if you have already called Create.

CContainedWindowT::SwitchMessageMap

Changes which message map will be used to process the contained window's messages.

void SwitchMessageMap(DWORD dwMsgMapID);

Parameters

dwMsgMapID
[in] The message map identifier. To use the default message map declared with BEGIN_MSG_MAP, pass zero. To use an alternate message map declared with ALT_MSG_MAP(msgMapID), pass msgMapID.

Remarks

The message map must be defined in the containing object.

You initially specify the message map identifier in the constructor.

CContainedWindowT::UnsubclassWindow

Detaches the subclassed window from the CContainedWindowT object and restores the original window procedure, saved in m_pfnSuperWindowProc.

HWND UnsubclassWindow(BOOL bForce = FALSE);

Parameters

bForce
[in] Set to TRUE to force the original window procedure to be restored even if the window procedure for this CContainedWindowT object is not currently active. If bForce is set to FALSE and the window procedure for this CContainedWindowT object is not currently active, the original window procedure will not be restored.

Return Value

The handle to the window previously subclassed. If bForce is set to FALSE and the window procedure for this CContainedWindowT object is not currently active, returns NULL.

Remarks

Use this method only if you want to restore the original window procedure before the window is destroyed. Otherwise, WindowProc will automatically do this when the window is destroyed.

CContainedWindowT::WindowProc

This static method implements the window procedure.

static LRESULT CALLBACK WindowProc(  
    HWND hWnd,
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam);

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.

Return Value

The result of the message processing.

Remarks

WindowProc directs messages to the message map identified by m_dwMsgMapID. If necessary, WindowProc calls DefWindowProc for additional message processing.

See Also

CWindow Class
CWindowImpl Class
CMessageMap Class
BEGIN_MSG_MAP
ALT_MSG_MAP
Class Overview