TN001: Window Class Registration

This note describes the MFC routines that register the special WNDCLASSes needed by Microsoft Windows. Specific WNDCLASS attributes used by MFC and Windows are discussed.

The Problem

The attributes of a CWnd object, like an HWND in Windows, are stored in two places: the window object and the WNDCLASS. A WNDCLASS is different than a C++ class. The name of the WNDCLASS is passed to general window creation functions such as CWnd::Create and CFrameWnd::Create in the lpszClassName parameter.

This WNDCLASS must be registered via one of four means:

• Implicitly by MFC provided WNDCLASSes

• Implicitly by subclassing a Windows control (or some other control)

• Explicitly by calling the MFC AfxRegisterWndClass or AfxRegisterClass

• Explicitly by calling the Windows routine RegisterClass

WNDCLASSes and MFC

The WNDCLASS structure consists of various fields that describe a window class. Following are the fields and how they are used in an MFC application.

Provided WNDCLASSes

In previous versions of MFC (prior to MFC 4.0), there were a number of predefined Window classes provided. These Window classes are no longer provided by default because of technical problems related to versioning (multiple versions of MFC loaded in one address space) as well as concerns relating to the fact that both MFC applications and OLE Controls may use the MFC DLLs.

The following reference is provided to help migrate code that uses these previously provided WNDCLASSes. Applications should use AfxRegisterWndClass (with the appropriate parameters) in place of these classes.

The following shows the classes and their attributes:

• "AfxWnd" is used for all child windows created with CWnd::Create.

  • class style : CS_DBLCLKS | CS_HREDRAW | CS_VREDRAW

  • no icon

  • arrow cursor

  • no background color

• "AfxFrameOrView" is used for frame windows and views (including stand-alone CFrameWnds and CMDIChildWnds).

  • class style : CS_DBLCLKS | CS_HREDRAW | CS_VREDRAW;

  • icon AFX_IDI_STD_FRAME

  • arrow cursor

  • COLOR_WINDOW background color

• "AfxMDIFrame" is used for the MDI frame window (that is, the parent) created with CMDIFrameWnd::Create.

  • class style : CS_DBLCLKS [ reduces flash during resizing ]

  • icon AFX_IDI_STD_MDIFRAME

  • arrow cursor

  • no background color

• "AfxControlBar" is used for the standard control bar implementation.

  • class style : 0 [ reduces flash during resizing, no double clicks ]

  • no icon

  • arrow cursor

  • gray background color (COLOR_BTNFACE)

If the application provides a resource with the specified resource ID (for example, AFX_IDI_STD_FRAME) ID, MFC will use that resource. Otherwise the default resource is used. For the icon, the standard application icon is used, and for the cursor, the standard arrow cursor is used.

There are two icons that support MDI applications with single document types (one icon for the main application, the other icon for iconic document/MDIChild windows). For multiple document types with different icons, you must register additional WNDCLASSes or use the CFrameWnd::LoadFrame function.

CFrameWnd::LoadFrame will automatically register a WNDCLASS using the standard "AfxFrameOrView" attributes but using the icon ID you specify as the first parameter to LoadFrame.

The values for background color and cursor for the MDIFrameWnd are not used since the client area of the MDIFrameWnd is completely covered by the "MDICLIENT" window. Microsoft does not encourage subclassing the "MDICLIENT" window so use the standard colors and cursor types when possible.

Subclassing Controls

If you subclass or superclass a Windows control (for example, CButton) then your class automatically gets the WNDCLASS attributes provided in the Windows implementation of that control.

The AfxRegisterWndClass Function

MFC provides a helper routine for registering a window class. Given a set of attributes (window class style, cursor, background brush, and icon), a synthetic name is generated, and the resulting window class is registered. For example,

const char* AfxRegisterWndClass(UINT nClassStyle, HCURSOR hCursor,    HBRUSH hbrBackground, HICON hIcon);

This function returns a temporary string of the generated registered window class name. See the Class Library Reference for more details.

The string returned is a temporary pointer to a static string buffer which is valid until the next call to AfxRegisterWndClass. If you want to keep this string around, store it in a CString variable. For example,

CString strWndClass = AfxRegisterWndClass(CS_DBLCLK, ...);
...
CWnd* pWnd = new CWnd;
pWnd->Create(strWndClass, ...);
...

AfxRegisterWndClass will throw a CResourceException if the window class failed to register (either because of bad parameters, or out of Windows memory).

The RegisterClass and AfxRegisterClass Functions

If you want to do anything more sophisticated than what AfxRegisterWndClass provides, you may call the Windows API RegisterClass or the MFC function AfxRegisterClass. The CWnd, CFrameWnd and CMDIChildWndCreate functions take a lpszClassName string name for the window class as the first parameter. Any window class name can be used, regardless of how it was registered.

It is important to use AfxRegisterClass (or AfxRegisterWndClass) in a DLL on Win32. Win32 does not automatically unregister classes registered by a DLL, so this must be done explicitly when the DLL is terminated. By using AfxRegisterClass instead of RegisterClass this is done automatically for you. AfxRegisterClass maintains a list of unique classes registered by your DLL and will automatically unregister then when the DLL terminates. When using RegisterClass in a DLL, you must insure that all classes are unregistered when the DLL is terminated (in your DllMain function). Failure to do so may cause RegisterClass to fail unexpectedly when your DLL is used by another client application.

Technical Notes by Number |  Technical Notes by Category