CWindowImpl

[Previous] [Next]

You use CWindowImpl to create a new window or to subclass an existing window. You can also create a new window with a window class based on an existing window class, which is known as superclassing. As you can see in the class hierarchy, CWindowImpl inherits functionality from CWindowImplBaseT and CWindowImplRoot. Most of the meat is in these parent classes, but normally you'll instantiate only a CWindowImpl-derived class. CWindowImpl itself implements just one function—Create. CWindowImpl also inherits CMessageMap via CWindowImplRoot. CMessageMap and the message-map macros define a convenient mechanism for mapping messages to functions. We'll look at message maps in detail later in the chapter.

CWindowImpl takes three template parameters. Only the first is required, as shown in the following class definition:

 template <class T, class TBase =     CWindow, class TWinTraits = CControlWinTraits> class ATL_NO_VTABLE CWindowImpl :     public CWindowImplBaseT< TBase, TWinTraits > 

Parameter T is your class, derived from CWindowImpl. TBase is the ultimate base class that contains the m_hWnd data member and all the Win32 API encapsulation. CWindow is typically used for TBase, but you could provide your own CWindow derivative.

Traits

The TWinTraits template parameter defines a class that encapsulates the desired window styles and extended styles. A trait class must implement two static member functions—GetWndStyle and GetWndExStyle—as the ATL CWinTraits class does here:

 template <DWORD t_dwStyle = 0, DWORD t_dwExStyle = 0> class CWinTraits { public:     static DWORD GetWndStyle(DWORD dwStyle)     {         return dwStyle == 0 ? t_dwStyle : dwStyle;     }     static DWORD GetWndExStyle(DWORD dwExStyle)     {         return dwExStyle == 0 ? t_dwExStyle : dwExStyle;     } }; 

CWindowImpl calls the static members of the class specified by the TWinTraits template argument in CWindowImpl::Create to determine the actual window styles. The CWinTraits class uses template parameters to store the window styles you specify. Note that the CWinTraits methods return the template styles only if the caller specifies a 0 value for dwStyle. The result is that any styles you specify to the CWindowImpl::Create method cause CWinTraits styles to be unused. CWinTraits is one of two trait classes ATL provides. The other class is CWinTraitsOR, which adds the template trait styles to any styles you specify in Create. CWinTraitsOR generates a style from your creation styles, template parameter styles, and template trait styles. The template parameter styles t_dwStyle and t_dwExStyle are just like the CWinTraits versions. The CWinTraitsOR class is shown in the following code section:

 template <DWORD t_dwStyle = 0, DWORD t_dwExStyle = 0,     class TWinTraits = CControlWinTraits> class CWinTraitsOR { public:     static DWORD GetWndStyle(DWORD dwStyle)     {         return dwStyle | t_dwStyle |             TWinTraits::GetWndStyle(dwStyle);     }     static DWORD GetWndExStyle(DWORD dwExStyle)     {         return dwExStyle | t_dwExStyle |             TWinTraits::GetWndExStyle(dwExStyle);     } }; 

ATL defines some common variations of the CWinTraits class through the following typedefs:

 typedef CWinTraits<WS_CHILD | WS_VISIBLE | WS_CLIPCHILDREN |     WS_CLIPSIBLINGS, 0> CControlWinTraits; typedef CWinTraits<WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN |     WS_CLIPSIBLINGS, WS_EX_APPWINDOW | WS_EX_WINDOWEDGE>     CFrameWinTraits; typedef CWinTraits<WS_OVERLAPPEDWINDOW | WS_CHILD | WS_VISIBLE |     WS_CLIPCHILDREN | WS_CLIPSIBLINGS, WS_EX_MDICHILD>     CMDIChildWinTraits; typedef CWinTraits<0, 0> CNullTraits; 

You can define your own CWinTraits variations as well, if you prefer.

Implementing a Window with CWindowImpl

To create a window that uses a completely new window class (not a C++ class) or superclasses an existing window class, start by deriving a class from CWindowImpl. The following code section shows how to declare a basic application frame window in ATL:

 class CMainFrame : public CWindowImpl<CMainFrame, CWindow,     CFrameWinTraits>   { public:     CMainFrame();     virtual ~CMainFrame(); DECLARE_WND_CLASS(NULL);     BEGIN_MSG_MAP(CMainFrame) END_MSG_MAP() }; 

The resulting window will have the predefined ATL frame window traits when created, which means it gets the following styles and extended styles:

 WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN | WS_CLIPSIBLINGS,     WS_EX_APPWINDOW | WS_EX_WINDOWEDGE 

The window-class macros and message-map macros complete the minimal implementation. We'll talk about those macros soon.

To create the window, use the CWindowImpl::Create function as shown here:

 CMainFrame mainframe; mainframe.Create(::GetDesktopWindow(),     CWindow::rcDefault,      _T("ATL Scribble"), 0, 0, 0); mainframe.ShowWindow(SW_SHOWNORMAL); 

The Create function takes the handle to the parent window as the first parameter. The second parameter is the initial rectangle. In this case, we're using the default rectangle provided by the static rcDefault data member of the CWindow class. The remaining parameters are the window name, style, extended style, and control ID (or menu handle). As mentioned earlier, if you specify styles in Create, they will override the ones specified in your traits unless you use CWinTraitsOR. In the previous code section, we specified 0 for the styles, so our CFrameWinTraits styles are used.