CWindowImpl Class
The latest version of this topic can be found at CWindowImpl Class.
Provides methods for creating or subclassing a window.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
template <class T, class TBase = CWindow, class TWinTraits = CControlWinTraits>
class ATL_NO_VTABLE CWindowImpl : public CWindowImplBaseT<TBase, TWinTraits>
Parameters
T
Your new class, derived from CWindowImpl.
TBase
The base class of your class. By default, the base class is CWindow.
TWinTraits
A traits class that defines styles for your window. The default is CControlWinTraits.
Members
Public Methods
| Name | Description |
|---|---|
| CWindowImpl::Create | Creates a window. |
CWindowImplBaseT Methods
| DefWindowProc | Provides default message processing. |
| GetCurrentMessage | Returns the current message. |
| GetWindowProc | Returns the current window procedure. |
| OnFinalMessage | Called after the last message is received (typically WM_NCDESTROY). |
| SubclassWindow | Subclasses a window. |
| UnsubclassWindow | Restores a previously subclassed window. |
Static Methods
| GetWndClassInfo | Returns a static instance of CWndClassInfo, which manages the window class information. |
| WindowProc | Processes messages sent to the window. |
Data Members
| m_pfnSuperWindowProc | Points to the window class's original window procedure. |
Remarks
You can use CWindowImpl to create a window or subclass an existing window. the CWindowImpl window procedure uses a message map to direct messages to the appropriate handlers.
CWindowImpl::Create creates a window based on the window class information that's managed by CWndClassInfo. CWindowImpl contains the DECLARE_WND_CLASS macro, which means CWndClassInfo registers a new window class. If you want to superclass an existing window class, derive your class from CWindowImpl and include the DECLARE_WND_SUPERCLASS macro. In this case, CWndClassInfo registers a window class that's based on an existing class but uses CWindowImpl::WindowProc. For example:
class ATL_NO_VTABLE CMyWindow :
OtherInheritedClasses
public CComControl<CMyWindow>
// CComControl derives from CWindowImpl
{
public:
// 1. The NULL parameter means ATL will generate a
// name for the superclass
// 2. The "EDIT" parameter means the superclass is
// based on the standard Windows Edit box
DECLARE_WND_SUPERCLASS(NULL, _T("EDIT"))
// Remainder of class declaration omitted
Note
Because CWndClassInfo manages the information for just one window class, each window created through an instance of CWindowImpl is based on the same window class.
CWindowImpl also supports window subclassing. The SubclassWindow method attaches an existing window to the CWindowImpl object and changes the window procedure to CWindowImpl::WindowProc. Each instance of CWindowImpl can subclass a different window.
Note
For any given CWindowImpl object, call either Create or SubclassWindow. Don't invoke both methods on the same object.
In addition to CWindowImpl, ATL provides CContainedWindow to create a window that's contained in another object.
The base class destructor (~ CWindowImplRoot) ensures that the window is gone before the object is destroyed.
CWindowImpl derives from CWindowImplBaseT, which derives from CWindowImplRoot, which derives from TBase and CMessageMap.
| For more information about | See |
|---|---|
| Creating controls | ATL Tutorial |
| Using windows in ATL | ATL Window Classes |
| ATL Project Wizard | Creating an ATL Project |
Inheritance Hierarchy
TBase
CWindowImplRoot
CWindowImplBaseT
CWindowImpl
Requirements
Header: atlwin.h
CWindowImpl::Create
Creates a window based on a new window class.
HWND Create(
HWND hWndParent,
_U_RECT rect = NULL,
LPCTSTR szWindowName = NULL,
DWORD dwStyle = 0,
DWORD dwExStyle = 0,
_U_MENUorID MenuOrID = 0U,
LPVOID lpCreateParam = NULL);
Parameters
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. This value is combined with the style provided by the traits class for the window. The default value gives the traits class full control over the style. For a list of possible values, see CreateWindow in the Windows SDK.
dwExStyle
[in] The extended window style. This value is combined with the style provided by the traits class for the window. The default value gives the traits class full control over the 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
Create first registers the window class if it has not yet been registered. The newly created window is automatically attached to the CWindowImpl object.
Note
Do not call Create if you have already called SubclassWindow.
To use a window class that is based on an existing window class, derive your class from CWindowImpl and include the DECLARE_WND_SUPERCLASS macro. The existing window class's window procedure is saved in m_pfnSuperWindowProc. For more information, see the CWindowImpl overview.
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.
CWindowImpl::DefWindowProc
Called by WindowProc to process messages not handled by the message map.
LRESULT DefWindowProc(
UINT uMsg,
WPARAM wParam,
LPARAM lParam);
LRESULT DefWindowProc();
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.
The function with no parameters automatically retrieves the needed parameters from the current message.
CWindowImpl::GetCurrentMessage
Returns the current message, packaged in the MSG structure.
const MSG* GetCurrentMessage();
Return Value
The current message.
CWindowImpl::GetWindowProc
Returns WindowProc, the current window procedure.
virtual WNDPROC GetWindowProc();
Return Value
The current window procedure.
Remarks
Override this method to replace the window procedure with your own.
CWindowImpl::GetWndClassInfo
Called by Create to access the window class information.
static CWndClassInfo& GetWndClassInfo();
Return Value
A static instance of CWndClassInfo.
Remarks
By default, CWindowImpl obtains this method through the DECLARE_WND_CLASS macro, which specifies a new window class.
To superclass an existing window class, derive your class from CWindowImpl and include the DECLARE_WND_SUPERCLASS macro to override GetWndClassInfo. For more information, see the CWindowImpl overview.
Besides using the DECLARE_WND_CLASS and DECLARE_WND_SUPERCLASS macros, you can override GetWndClassInfo with your own implementation.
CWindowImpl::m_pfnSuperWindowProc
Depending on the window, points to one of the following window procedures.
WNDPROC m_pfnSuperWindowProc;
Remarks
| Type of window | Window procedure |
|---|---|
| A window based on a new window class, specified through the DECLARE_WND_CLASS macro. | The DefWindowProc Win32 function. |
| A window based on a window class that modifies an existing class, specified through the DECLARE_WND_SUPERCLASS macro. | The existing window class's window procedure. |
| A subclassed window. | The subclassed window's original window procedure. |
CWindowImpl::DefWindowProc sends message information to the window procedure saved in m_pfnSuperWindowProc.
CWindowImpl::OnFinalMessage
Called after receiving the last message (typically WM_NCDESTROY).
virtual void OnFinalMessage(HWND hWnd);
Parameters
hWnd
[in] A handle to the window being destroyed.
Remarks
The default implementation of OnFinalMessage does nothing, but you can override this function to handle cleanup before destroying a window. If you want to automatically delete your object upon the window destruction, you can call delete this; in this function.
CWindowImpl::SubclassWindow
Subclasses the window identified by hWnd and attaches it to the CWindowImpl 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 CWindowImpl::WindowProc. The original window procedure is saved in m_pfnSuperWindowProc.
Note
Do not call SubclassWindow if you have already called Create.
CWindowImpl::UnsubclassWindow
Detaches the subclassed window from the CWindowImpl object and restores the original window procedure, saved in m_pfnSuperWindowProc.
HWND UnsubclassWindow();
Return Value
The handle to the window previously subclassed.
CWindowImpl::WindowProc
This static function 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 uses the default message map (declared with BEGIN_MSG_MAP) to direct messages to the appropriate handlers. If necessary, WindowProc calls DefWindowProc for additional message processing. If the final message is not handled, WindowProc does the following:
Performs unsubclassing if the window was unsubclassed.
Clears
m_hWnd.Calls OnFinalMessage before the window is destroyed.
You can override WindowProc to provide a different mechanism for handling messages.