CContainedWindowT 类

项目
04/03/2023

此类实现包含在另一个对象中的窗口。

重要

无法在 Windows 运行时中执行的应用程序中使用此类及其成员。

语法

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

参数

TBase
新类的基类。默认基类为 CWindow。

TWinTraits
定义窗口样式的特征类。默认为 CControlWinTraits。

注意

CContainedWindow 是 CContainedWindowT 的专用化。如果你想要更改基类或特征，请直接使用 CContainedWindowT。

成员

公共构造函数

名称	描述
CContainedWindowT::CContainedWindowT	构造函数。初始化数据成员，以指定哪个消息映射将处理包含的窗口的消息。

公共方法

名称	描述
CContainedWindowT::Create	创建一个窗口。
CContainedWindowT::DefWindowProc	提供默认消息处理。
CContainedWindowT::GetCurrentMessage	返回当前消息。
CContainedWindowT::RegisterWndSuperclass	注册包含的窗口的窗口类。
CContainedWindowT::SubclassWindow	对窗口子类化。
CContainedWindowT::SwitchMessageMap	更改用于处理包含的窗口的消息的消息映射。
CContainedWindowT::UnsubclassWindow	还原先前子类化的窗口。
CContainedWindowT::WindowProc	（静态）处理发送到包含的窗口的消息。

公共数据成员

“属性”	描述
CContainedWindowT::m_dwMsgMapID	标识哪个消息映射将处理包含的窗口的消息。
CContainedWindowT::m_lpszClassName	指定新窗口类基于的现有窗口类的名称。
CContainedWindowT::m_pfnSuperWindowProc	指向窗口类的原始窗口过程。
CContainedWindowT::m_pObject	指向包含对象。

注解

CContainedWindowT 实现包含在另一个对象中的窗口。 CContainedWindowT 的窗口过程使用包含对象中的消息映射将消息定向到相应的处理程序。构造 CContainedWindowT 对象时，需指定要使用哪个消息映射。

CContainedWindowT 允许通过超类化现有窗口类来创建新窗口。 Create 方法首先注册一个基于现有类但使用 CContainedWindowT::WindowProc 的窗口类。然后 Create 基于此新窗口类创建一个窗口。 CContainedWindowT 的每个实例可以超类化不同的窗口类。

CContainedWindowT 还支持窗口子类化。 SubclassWindow 方法将现有的窗口附加到 CContainedWindowT 对象并将窗口过程更改为 CContainedWindowT::WindowProc。 CContainedWindowT 的每个实例可以子类化其他窗口。

注意

对于任何给定的 CContainedWindowT 对象，请调用 Create 或 SubclassWindow。不应在同一个对象上调用这两个方法。

在 ATL 项目向导中使用“基于以下条件添加控件”选项时，该向导会自动将 CContainedWindowT 数据成员添加到实现该控件的类。以下示例演示如何声明包含的窗口：

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;
}

有关	请参阅
创建控件	ATL 教程
使用 ATL 中的窗口	ATL 窗口类
ATL 项目向导	创建 ATL 项目
Windows	Windows SDK 中的窗口和后续主题

继承层次结构

TBase

CContainedWindowT

要求

标头：atlwin.h

CContainedWindowT::CContainedWindowT

该构造函数初始化数据成员。

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

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

参数

lpszClassName
[in] 包含的窗口基于的现有窗口类的名称。

pObject
[in] 指向声明消息映射的包含对象的指针。此对象的类必须派生自 CMessageMap。

dwMsgMapID
[in] 标识将处理包含的窗口的消息的消息映射。默认值 0 指定使用 BEGIN_MSG_MAP 声明的默认消息映射。若要使用通过 ALT_MSG_MAP(msgMapID) 声明的备用消息映射，请传递 msgMapID。

备注

如果你想要通过 Create 创建新窗口，则必须为 lpszClassName 参数传递现有窗口类的名称。有关示例，请参阅 CContainedWindow 概述。

有三个构造函数：

具有三个参数的构造函数是通常调用的构造函数。
具有两个参数的构造函数使用 TBase::GetWndClassName 中的类名。
如果你想稍后再提供参数，请使用不带参数的构造函数。稍后调用 Create 时，必须提供窗口类名、消息映射对象和消息映射 ID。

如果通过 SubclassWindow 子类化现有窗口，则不会使用 lpszClassName 值；因此，可为此参数传递 NULL。

CContainedWindowT::Create

调用 RegisterWndSuperclass 以注册基于现有类但使用 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] 包含的窗口基于的现有窗口类的名称。

pObject
[in] 指向声明消息映射的包含对象的指针。此对象的类必须派生自 CMessageMap。

hWndParent
[in] 父窗口或所有者窗口的句柄。

rect
[in] 用于指定窗口位置的 RECT 结构。可以通过指针或引用传递 RECT。

szWindowName
[in] 指定窗口的名称。默认值为 NULL。

dwStyle
[in] 窗口的样式。默认值为 WS_CHILD | WS_VISIBLE。有关可能值的列表，请参阅 Windows SDK 中的 CreateWindow。

dwExStyle
[in] 扩展窗口样式。默认值为 0，即无扩展样式。有关可能值的列表，请参阅 Windows SDK 中的 CreateWindowEx。

MenuOrID
[in] 对于子窗口，值为该窗口的标识符。对于顶级窗口，值为该窗口的菜单句柄。默认值为 0U。

lpCreateParam
[in] 指向窗口创建数据的指针。有关完整说明，请参阅 CreateWindowEx 的最后一个参数的说明。

返回值

如果成功，则返回新建窗口的句柄；否则返回 NULL。

备注

现有窗口类名保存在 m_lpszClassName 中。然后 Create 基于此新类创建一个窗口。新建的窗口会自动附加到 CContainedWindowT 对象。

注意

如果已调用 SubclassWindow，请不要调用 Create。

注意

如果使用 0 作为 MenuOrID 参数的值，则必须将其指定为 0U（默认值）以避免编译器错误。

CContainedWindowT::DefWindowProc

由 WindowProc 调用以处理消息映射未处理的消息。

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

参数

uMsg
[in] 发送到窗口的消息。

wParam
[in] 其他的消息特定信息。

lParam
[in] 其他的消息特定信息。

返回值

消息处理的结果。

备注

默认情况下，DefWindowProc 调用 CallWindowProc Win32 函数以将消息信息发送到 m_pfnSuperWindowProc 中指定的窗口过程。

CContainedWindowT::GetCurrentMessage

返回当前消息 (m_pCurrentMsg)。

const _ATL_MSG* GetCurrentMessage();

返回值

打包在 MSG 结构中的当前消息。

CContainedWindowT::m_dwMsgMapID

保存当前用于包含的窗口的消息映射的标识符。

DWORD m_dwMsgMapID;

备注

必须在包含对象中声明此消息映射。

使用 BEGIN_MSG_MAP 声明的默认消息映射始终由零标识。使用 ALT_MSG_MAP(msgMapID) 声明的备用消息映射由 msgMapID 标识。

m_dwMsgMapID 首先由构造函数初始化，可以通过调用 SwitchMessageMap 对其进行更改。有关示例，请参阅 CContainedWindowT 概述。

CContainedWindowT::m_lpszClassName

指定现有窗口类的名称。

LPTSTR m_lpszClassName;

注解

当你创建窗口时，Create 会注册一个新窗口类，该类基于此现有类但使用 CContainedWindowT::WindowProc。

m_lpszClassName 由构造函数初始化。有关示例，请参阅 CContainedWindowT 概述。

CContainedWindowT::m_pfnSuperWindowProc

如果包含的窗口已子类化，则 m_pfnSuperWindowProc 将指向窗口类的原始窗口过程。

WNDPROC m_pfnSuperWindowProc;

备注

如果包含的窗口已超类化（即它基于修改现有类的窗口类），则 m_pfnSuperWindowProc 将指向现有窗口类的窗口过程。

DefWindowProc 方法将消息信息发送到保存在 m_pfnSuperWindowProc 中的窗口过程。

CContainedWindowT::m_pObject

指向包含 CContainedWindowT 对象的对象。

CMessageMap* m_pObject;

备注

此容器（其类必须派生自 CMessageMap）声明包含的窗口使用的消息映射。

m_pObject 由构造函数初始化。有关示例，请参阅 CContainedWindowT 概述。

CContainedWindowT::RegisterWndSuperclass

由 Create 调用以注册包含的窗口的窗口类。

ATOM RegisterWndSuperClass();

返回值

如果成功，则返回一个用于唯一标识所要注册的窗口类的原子；否则返回零。

备注

此窗口类基于现有类，但使用 CContainedWindowT::WindowProc。现有窗口类的名称和窗口过程分别保存在 m_lpszClassName 和 m_pfnSuperWindowProc 中。

CContainedWindowT::SubclassWindow

子类化 hWnd 标识的窗口并将其附加到 CContainedWindowT 对象。

BOOL SubclassWindow(HWND hWnd);

参数

hWnd
[in] 正在子类化的窗口的句柄。

返回值

如果成功子类化窗口，则返回 TRUE；否则返回 FALSE。

注解

子类化窗口现在使用 CContainedWindowT::WindowProc。原始窗口过程保存在 m_pfnSuperWindowProc 中。

注意

如果已调用 Create，请不要调用 SubclassWindow。

CContainedWindowT::SwitchMessageMap

更改用于处理包含的窗口的消息的消息映射。

void SwitchMessageMap(DWORD dwMsgMapID);

参数

dwMsgMapID
[in] 消息映射标识符。若要使用通过 BEGIN_MSG_MAP 声明的默认消息映射，请传递零。若要使用通过 ALT_MSG_MAP(msgMapID) 声明的备用消息映射，请传递 msgMapID。

注解

必须在包含对象中定义该消息映射。

最初在构造函数中指定消息映射标识符。

CContainedWindowT::UnsubclassWindow

从 CContainedWindowT 对象中分离子类化窗口，并还原保存在 m_pfnSuperWindowProc 中的原始窗口过程。

HWND UnsubclassWindow(BOOL bForce = FALSE);

参数

bForce
[in] 设置为 TRUE 会强制还原原始窗口过程，即使此 CContainedWindowT 对象的窗口过程当前不处于活动状态。如果 bForce 设置为 FALSE，并且此 CContainedWindowT 对象的窗口过程当前不处于活动状态，则不会还原原始窗口过程。

返回值

先前已子类化的窗口的句柄。如果 bForce 设置为 FALSE，并且此 CContainedWindowT 对象的窗口过程当前不处于活动状态，则返回 NULL。

注解

请仅在你想要在销毁窗口之前还原原始窗口过程时才使用此方法。否则，在销毁窗口时，WindowProc 将自动执行此操作。

CContainedWindowT::WindowProc

此静态方法实现窗口过程。

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

参数

hWnd
[in] 窗口的句柄。