Windows support class-CContainedWindowT

Introduction

Hey, Ninjas! In this blog, we will be discussing the Windows support class CContainedWindowT. The CContainedWindowT class is a template class in the Windows API used to create and manage windows contained within another window. It provides a convenient way to create and manage a window that is a child of another window and simplifies the process of handling window messages and events.

In this article, we will learn about the Windows Support Class-CContainedWindowT, its members, constructor, and methods.

CContainedWindowT Class

The CContainedWindowT class is a template class in the Windows API used to create and manage windows contained within another window. This class is part of the WTL (Windows Template Library), a C++ library for developing Windows applications.

It provides a convenient way to create and manage a window that is a child of another window and simplifies the process of handling window messages and events.
It includes various other functionalities, such as automatic cleanup and font management.
This class can be used to create various types of windows, such as buttons, edit controls, and list boxes, and it can be customized to suit the needs of your application.
The CContainedWindowT class is a template class that can be instantiated with different window classes, such as buttons, edit controls, and list boxes.

Overall, CContainedWindowT is a powerful class that can simplify the process of creating and managing windows in a Windows application, and it is widely used in WTL-based projects.

Syntax

Let's see the syntax of the class below.

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

Parameter

The class takes only one parameter, TBase, representing the base class of your new class. The default base class is CWindow.

Members

The CContainedWindowT class has various members that can be used to create and manage windows contained within another window.

There are three types of members, which are discussed below.

Public Constructor

This method has only one type, which is described below.

CContainedWindowT::CContainedWindowT
Specifies which message map will handle the messages from the enclosing window when data members are initialized.

Public Methods

This method has seven types, which are described below.

CContainedWindowT::Create
Creates a host 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::UnsubclassWindow
Restores a previously subclassed window.
CContainedWindowT::WindowProc
Processes messages sent to the contained window.

Public Data Members

This method has four types, which are described below.

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.

Method Name	Description
CContainedWindowT::CContainedWindowT	Specifies which message map will handle the messages from the enclosing window when data members are initialized.
CContainedWindowT::Create	Creates a host 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::UnsubclassWindow	Restores a previously subclassed window.
CContainedWindowT::WindowProc	Processes messages sent to the contained window.
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

A window that is contained within another object is implemented by CContainedWindowT.
The window procedure of CContainedWindowT employs a message map in the contained object to route messages to the proper handlers. Which message map should be utilized is specified when creating a CContainedWindowT object.
By superclassing an existing window class, you can make a new window with CContainedWindowT.
A window class based on an existing class but using CContainedWindowT:: is initially registered by the Create method.
Then, based on this new window class, Create builds a window.
A separate window class can be superclassed by each instance of CContainedWindowT.

Inheritance Hierarchy

The CContainedWindowT class is a template class defined in the Microsoft Active Template Library (ATL). Here's the general inheritance hierarchy of the CAxWindow2T class:

CContainedWindowT:
It is the class that you will use to create a window that hosts an ActiveX control.
TBase:
It is the base class that the window will inherit from. The default value is CWindow, which provides basic implementations for standard window functions such as message handling and window creation.

CContainedWindowT::CContainedWindowT

CContainedWindowT::CContainedWindowT is a constructor for the CContainedWindowT class. It does not have any member variables. It takes a single parameter, the handle of the parent window, that the contained window will be created within.

When the constructor is called, it sets the parent window handle and initializes other member variables to default values. It does not create the contained window itself but instead sets the class ready to make the window when the Create function is called.

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

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

Parameters

lpszClassName
The name of an existing window class will serve as the foundation for the contained window.
pObject
A reference to the object that contains the message map and declares it. The class of this object must descend from CMessageMap.

Remarks

The lpszClassName option must contain the name of an existing window class if you want to create a new window using Create.

CContainedWindowT::Create

CContainedWindowT::Create is a member function of the CContainedWindowT class, a template class that provides a way to create a window contained within another window, rather than being a top-level window. Here's a simplified version of what the Create function might look like:

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
The name of an existing window class that will serve as the foundation for the contained window.
pObject
a reference to the object that contains the message map and declares it.
dwMsgMapID
The message map that will handle the messages for the confined window is identified by dwMsgMapID.
hWndParent
The handle to the parent or owner window is hWndParent.
Rect
A RECT structure defining the window's location. Either a pointer or a reference can be used to transmit the RECT.
szWindowName
Specifies the name of the window. The default value is NULL.
dwStyle
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
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
For a child window, the window identifier. For a top-level window, a menu handle for the window. The default value is 0U.
lpCreateParam
A pointer to window-creation data. For a full description, see the description for the final

Return Values

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

Remarks

The value of m lpszClassName stores the current window class name. A window based on this new class is then created by Create. The CContainedWindowT object receives the newly formed window by default.

CContainedWindowT::DefWindowProc

CContainedWindowT::DefWindowProc is a member function of the CContainedWindowT class, a template class that provides a way to create a window contained within another window, rather than being a top-level window.

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

Parameters

uMsg
The message sent to the window.
wParam
Additional message-specific information.
lParam
Additional message-specific information.

Return Values

A message's processing outcome.

Remarks

To deliver the message information to the window procedure mentioned in m pfnSuperWindowProc, DefWindowProc by default calls the CallWindowProc Win32 function.

CContainedWindowT::GetCurrentMessage

CContainedWindowT::GetCurrentMessage is a member function of the CContainedWindowT class, a template class that provides a way to create a window contained within another window, rather than being a top-level window.

Here's an example of how GetCurrentMessage might be used in a message-handling function:

const _ATL_MSG* GetCurrentMessage();

The getCurrentMessage function takes no parameter; it retrieves the current message from the thread's message queue. It is a helper function and can be replaced with::GetMessage(&msg, NULL, 0, 0) in the message handling function.

Return Value

The most recent message, presented in an MSG format.

CContainedWindowT::RegisterWndSuperclass

CContainedWindowT::RegisterWndSuperclass is a function in the CContainedWindowT template class in the Microsoft Foundation Class (MFC) library for C++. It is used to register a window class for a contained window, a window created and managed by a parent window. The function takes several parameters, including the class name, the window procedure, and the style of the window. Once the class is registered, it can be used to create instances of the contained window.

ATOM RegisterWndSuperClass();

Return Value

If the registration is successful, an atom that specifically identifies the window class will be returned; if not, zero.

Remarks

This window class uses CContainedWindowT::WindowProc but is based on an existing class. The window procedure and the name of the current window class are recorded in the variables m pfnSuperWindowProc and m lpszClassName, respectively.

CContainedWindowT::SubclassWindow

This function is used to subclass a window and is typically used to add custom functionality to a pre-existing window class. The function takes a single argument, the handle of the window to be subclassed, and returns a boolean value indicating whether the operation was successful.

Here is an example usage of this function:

BOOL SubclassWindow(HWND hWnd);

Parameters

hWnd
The handle to the window being subclassed.

Return Value

If the window is successfully subclassed, return TRUE; otherwise, return FALSE.

Remarks

The subclassed window now uses CContainedWindowT::WindowProc. In m pfnSuperWindowProc, the original window procedure is stored.

CContainedWindowT::UnsubclassWindow

This function is used to unsubclass a window that was previously subclassed using the CContainedWindowT::SubclassWindow function. This function removes the custom functionality added to the window by the subclassing operation and restores the original window procedure of the window. It typically takes no argument and returns a boolean value indicating whether the operation was successful.

Here is an example usage of this function:

HWND UnsubclassWindow(BOOL bForce = FALSE);

Parameters

bForce
If the window process for this CContainedWindowT object is not currently active, force its restoration by setting it to TRUE.

Return Value

the window's handle from its previous subclass. Returns NULL if bForce is set to FALSE and this CContainedWindowT object's window function is not currently active.

Remarks

Use this technique only if you want to go back to how the window was originally operated before the window is damaged. If not, WindowProc will carry out this action automatically when the window is destroyed.

CContainedWindowT::WindowProc

This function is the window procedure that handles messages sent to the subclassed window. The system calls it when a message is sent to the window.

Here is an example usage of this function:

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

Parameters

hWnd
The handle to the window.
uMsg
The message sent to the window.
wParam
Additional message-specific information.
lParam
Additional message-specific information.

Return Value

The result of the message processing.

Remarks

Messages are routed by WindowProc to the message map designated by m dwMsgMapID. WindowProc will call DefWindowProc if additional message processing is required.

CContainedWindowT::m_dwMsgMapID

This data member holds the identifier of the message map associated with the template class.

Here is an example usage of this function:

DWORD m_dwMsgMapID;

Remarks

The enclosed object must declare this message map.

The BEGIN_MSG_MAP default message map is always designated by zero. MsgMapID is used to identify an alternative message map that was declared with ALT MSG MAP(msgMapID).

CContainedWindowT::m_lpszClassName

It is a null-terminated string that represents the name of the window class associated with the contained window. This name is used to register the class with the operating system and is also used to create windows of that class.

Here is an example usage of this function:

LPTSTR m_lpszClassName;

Remarks

Create registers a new window class that is based on this existing class but utilizes CContainedWindowT::WindowProc when you create a window.

The function Object() { [native code] } initializes m lpszClassName. See the CContainedWindowT overview for an illustration.

CContainedWindowT::m_pfnSuperWindowProc

CContainedWindowT::m_pfnSuperWindowProc is a member variable of the CContainedWindowT class in the ATL (Active Template Library) library in C++. It is a pointer to the original window procedure of the contained window, which is used to handle messages before they are passed to the contained window's message map. This allows for the contained window to intercept and handle messages as desired, while still maintaining the original functionality of the window.

Here is an example usage of this function:

WNDPROC m_pfnSuperWindowProc;

Remarks

m_pfnSuperWindowProc points to the window method of the base window class if the contained window is superclassed, or based on a window class that changes an existing class.

CContainedWindowT::m_pObject

CContainedWindowT::m_pObject is a member variable of the CContainedWindowT class in the ATL (Active Template Library) library in C++. It is a pointer to the object that is associated with the contained window.

It's usually used along with the message map mechanism, where the pointer to the object is passed to the contained window in order to route the Windows messages to the correct class functions. This allows for an object-oriented approach to handling window messages, rather than having to use global functions or a large switch statement to handle messages for a specific window.

Here is an example usage of this function:

CMessageMap* m_pObject;

Remarks

This container declares the message map used by the contained window and whose class must inherit from CMessageMap. The function Object() initializes m_pObject.

Frequently Asked Questions

What is a contained window?

A contained window is a window that is embedded within another window. It is a child window that is not a top-level window.

How do I use CContainedWindowT to create a contained window?

To use CContainedWindowT to create a contained window, you would first need to create a new class that inherits from CContainedWindowT and provides it with the appropriate window class and window style.

How do I handle messages for a contained window created with CContainedWindowT?

To handle messages for a contained window created with CContainedWindowT, you would need to override the WindowProc method in your derived class and provide your own implementation for handling messages.

How do I set the font for a contained window created with CContainedWindowT?

You can set the font for a contained window created with CContainedWindowT by calling the SetFont method and passing in a pointer to a CFont object.

Conclusion

In this blog, we have discussed the Windows support class-CContainedWindowT, along with members of the Windows support class-CContainedWindowT with code.

We hope this blog has helped you enhance your knowledge of the Windows support class-CContainedWindowT.

Check out these useful blogs on windows support classes:

Refer to our guided paths on Coding Ninjas Studio to learn more about DSA, Competitive Programming, JavaScript, System Design, etc. Enroll in our courses and refer to the mock test and problems available, interview puzzles, take a look at the interview experiences, and interview bundle for placement preparations.

Do upvote our blog to help other ninjas grow!

Happy Reading!!‍