CContainedWindowT 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 CContainedWindowT Class.
This class implements a window contained within another object.
重要
This class and its members cannot be used in applications that execute in the Windows Runtime.
template <class TBase = CWindow, class TWinTraits = CControlWinTraits>
class CContainedWindowT : public TBase
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
.
注意
CContainedWindow is a specialization of CContainedWindowT
. If you want to change the base class or traits, use CContainedWindowT
directly.
Name | Description |
---|---|
CContainedWindowT::CContainedWindowT | Constructor. Initializes data members to specify which message map will process the contained window's messages. |
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. |
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. |
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.
注意
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 |
TBase
CContainedWindowT
Header: atlwin.h
The constructor initializes data members.
CContainedWindowT(
LPTSTR lpszClassName,
CMessageMap* pObject,
DWORD dwMsgMapID = 0);
CContainedWindowT(
CMessageMap* pObject,
DWORD dwMsgMapID = 0)
CContainedWindowT();
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
.
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.
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);
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.
If successful, the handle to the newly created window; otherwise, NULL.
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.
注意
Do not call Create if you have already called SubclassWindow.
注意
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.
Called by WindowProc to process messages not handled by the message map.
LRESULT DefWindowProc()
LRESULT DefWindowProc(
UINT uMsg,
WPARAM wParam,
LPARAM lParam);
uMsg
[in] The message sent to the window.
wParam
[in] Additional message-specific information.
lParam
[in] Additional message-specific information.
The result of the message processing.
By default, DefWindowProc
calls the CallWindowProc Win32 function to send the message information to the window procedure specified in m_pfnSuperWindowProc.
Returns the current message ( m_pCurrentMsg).
const _ATL_MSG* GetCurrentMessage();
The current message, packaged in the MSG
structure.
Holds the identifier of the message map currently being used for the contained window.
DWORD m_dwMsgMapID;
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.
Specifies the name of an existing window class.
LPTSTR m_lpszClassName;
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.
If the contained window is subclassed, m_pfnSuperWindowProc
points to the original window procedure of the window class.
WNDPROC m_pfnSuperWindowProc;
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
.
Points to the object containing the CContainedWindowT
object.
CMessageMap* m_pObject;
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.
Called by Create to register the window class of the contained window.
ATOM RegisterWndSuperClass();
If successful, an atom that uniquely identifies the window class being registered; otherwise, zero.
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.
Subclasses the window identified by hWnd
and attaches it to the CContainedWindowT
object.
BOOL SubclassWindow(HWND hWnd);
hWnd
[in] The handle to the window being subclassed.
TRUE if the window is successfully subclassed; otherwise, FALSE.
The subclassed window now uses CContainedWindowT::WindowProc. The original window procedure is saved in m_pfnSuperWindowProc.
注意
Do not call SubclassWindow
if you have already called Create.
Changes which message map will be used to process the contained window's messages.
void SwitchMessageMap(DWORD dwMsgMapID);
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
.
The message map must be defined in the containing object.
You initially specify the message map identifier in the constructor.
Detaches the subclassed window from the CContainedWindowT
object and restores the original window procedure, saved in m_pfnSuperWindowProc.
HWND UnsubclassWindow(BOOL bForce = FALSE);
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.
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.
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.
This static method implements the window procedure.
static LRESULT CALLBACK WindowProc(
HWND hWnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam);
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.
The result of the message processing.
WindowProc
directs messages to the message map identified by m_dwMsgMapID. If necessary, WindowProc
calls DefWindowProc for additional message processing.
CWindow Class
CWindowImpl Class
CMessageMap Class
BEGIN_MSG_MAP
ALT_MSG_MAP
Class Overview