Using the Windows Template Library Part 1: Getting Started
by R.Mack

Get the source code for this article here.

Introduction

Since Microsoft's introduction of DirectX, game developers have dealt with the challenge of encapsulating the Win32 windowing API. The obvious choice, really the only ready-made choice aside from Borland's ObjectWindows, was MFC, but its large footprint and inefficient implementation led many developers to either develop their own in-house solution or use the Win32 API directly. Today, however, there is an alternative to MFC known as the Windows Template Library that provides the desired encapsulation without incurring a large footprint or poor performance.

This is the first in a series of articles that intends to introduce developers to the use of this sparsely documented library in a game development context. While development utilities are an obvious application for the WTL, and by the end of this series the reader should have gained enough experience to use it in such a manner, this series' true focus will be on using the WTL to aid in developing the actual game application.

Requirements

I make a few assumptions in this article. First I assume that the reader has a basic understanding of Win32 programming. He or she should be capable of creating a simple Win32 application. No knowledge of MFC, ATL, or WTL will be required. I also assume that the reader is using VC 6.0 SP 5 or VC .NET. Other compilers may work but I cannot make any guarantees. Before continuing with this article you'll also want to make sure you have the WTL 3.1 or 7.0 libraries and have added the WTL\Include path to your list of include directories. The libraries can be obtained from the MSDN download site.

Active Template Library (ATL)

Before we get into using the WTL we'll need to define what the Active Template Library is and its relation to the WTL. The Active Template Library is a set of template classes developed by Microsoft to aid in the development of ActiveX controls and COM objects. Since many ActiveX controls interact with the user in some fashion, Microsoft implemented classes to encapsulate the Windows user interface elements. ATL's classes were designed to be lightweight and fast making the ATL Window Classes (a.k.a WTL) a very attractive alternative to MFC and straight Win32 API programming. With that out of the way we're ready to begin.

Getting Started

Let's start at the beginning. Create an empty Win32 Application project and add a file to it called main.cpp. Make it a windows executable that simply returns.

#include <windows.h>

int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                     LPSTR lpCmdLine, int nCmdShow)
{
  return 0;
}

Because the WTL is an extension of ATL and is actually intended to be used in conjunction with developing COM objects / COM servers, there are a few items that need to be added to main.cpp to appease the ATL library. We'll need to include atlbase.h and atlapp.h and define a global variable called _Module. We'll also add initialization and termination calls for _Module.

The _Module variable is used by ATL to help encapsulate the functionality required by COM servers. It's tightly coupled to the ATL libraries so it has to be defined, and its name can't be changed. A typical ATL project would define _Module as an instance of a CComModule object. Here we define its type as CAppModule, a derivative of CComModule that adds support for message loops. _Module gives the ATL libraries access to the application instance as well as some information about the operating environment. Let's not worry about the details of _Module just yet. We'll cover it in more detail in another article. Below is our new main.cpp file.

#include <windows.h>
#include <atlbase.h>
#include <atlapp.h>

CAppModule _Module;

int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                     LPSTR lpCmdLine, int nCmdShow)
{
  _Module.Init(NULL, hInstance);

  _Module.Term();

  return 0;
}

Having made these few changes, we're going to leave main.cpp alone for a bit. At this point all that's missing is a window, its window procedure, and a message loop. Let's move on and get to know the classes the WTL provides for wrapping and implementing windows and their window procedures.

The CWindow Class

The CWindow class is nothing more than a light wrapper around an HWND. It implements most of the standard Win32 window functions and adds a few useful functions like CenterWindow() and ResizeClient(). Keep in mind that the CWindow object and the window itself are separate entities. The construction and destruction of the window is independent of the CWindow object. Another important thing to note is that CWindow cannot be used to implement a window. It can only be used to wrap existing windows or create windows using an existing window class [2], [3].

To create an edit control using CWindow we simply use CWindow's Create() function.

CWindow EditCtrl;

EditCtrl.Create(_T("EDIT"), hParent, CWindow::rcDefault,_T(""),WS_CHILD);

The first parameter is the name of the window class; in this case "EDIT". The second is the HWND of the parent window. The third parameter is a RECT structure defining the size and position of the window. The fourth is the windows caption, and the fifth is the style. There are actually a few more parameters but they provide default values, and this example doesn't need to change these values. For complete documentation see the CWindow reference on MSDN [3].

If the edit control already existed and we simply wished to use the CWindow methods to access it, we could use CWindow's Attach() method to assign the existing HWND to the CWindow object. There's also a corresponding Detach() method that clears the handle from the CWindow object. Additionally, CWindow provides a convenient constructor that takes an HWND and attaches the CWindow object to it.

void SomeFunction(HWND hEditCtrl)
{
  CWindow EditCtrl;

  EditCtrl.Attach(hEditCtrl);
  EditCtrl.SetWindowText(_T("This is a Test"));
}

//  or

void SomeFunction2(HWND hEditCtrl)
{
  CWindow EditCtrl(hEditCtrl);

  EditCtrl.SetWindowText(_T("This is a Test"));
}

CWindow also implements operator= and an HWND conversion operator. This allows CWindow objects to be assigned HWNDs

EditCtrl  =  hEditCtrl;

and anywhere an HWND is called for a CWindow can be used instead.

CWindow EditCtrl;

EditCtrl.Create(_T("EDIT"), NULL, CWindow::rcDefault,_T(""),WS_CHILD);
SomeFunction(EditCtrl);

Don't worry about allowing a CWindow object to go out of scope while a window handle is still attached; the window will not be destroyed. As mentioned earlier, the lifetime of the CWindow object and the window itself are independent. To actually destroy the attached window use CWindow's DestroyWindow() method.

For complete documentation on CWindow and its methods see the CWindow reference on MSDN [3], [1].

The CWindowImpl Class

The CWindowImpl class, unlike the CWindow class, actually implements a window. To use CWindowImpl we define a new class that inherits from CWindowImpl. This new class must be passed as the first parameter of the template. The second parameter is a base class whose default value is CWindow. This allows CWindowImpl to inherit all the methods provided by CWindow (CWindowImpl also uses CWindow's m_hWnd member to store the HWND when a CWindowImpl instance is used to create a window. Because of this dependency the second parameter of the CWindowImpl template must be CWindow or a derivative of CWindow). For the time being we'll leave the second parameter as is. The third and final parameter is a traits class. The traits class provides information about the window styles used when creating a window [4], [1]. We'll also ignore this parameter for now. Below is the beginning of CWindowImpl's definition.

template <class T, class TBase = CWindow, class TWinTraits = CControlWinTraits>
class ATL_NO_VTABLE CWindowImpl : public CWindowImplBaseT< TBase, TWinTraits >
{
  public:
	DECLARE_WND_CLASS(NULL)
…

Let's add a new file to our project called mainwnd.h. To it we'll add a class called MainWnd that inherits from CWindowImpl. We'll also need to include atlwin.h. Below is our start of mainwnd.h.

#include <atlwin.h>

class MainWnd : public CWindowImpl<MainWnd>
{
};

Defining a Window Class

In standard Win32 programming we define a window class by creating an instance of a WNDCLASSEX structure, setting its members, and passing it to RegisterClassEx(). Note that when I refer to a window class I'm speaking of the properties set in and registered with the WNDCLASSEX structure and not a C++ class. CWindowImpl simplifies this by providing a handful of macros used to help define and register the window class. The DECLARE_WND_CLASS macro in the CWindowImpl definition listed earlier is one of these macros. Passing NULL creates a window class using a random class name. Since DECLARE_WND_CLASS(NULL) is declared in CWindowImpl, any classes derived from CWindowImpl also inherit this functionality. If you want to give your window class a specific name you'll need to override CWindowImpl's declaration. To do this, simply pass the name you wish to use to DECLARE_WND_CLASS in your derived class [1], [2]. Go ahead and make this change to mainwnd.h. Use anything you like for the class name. Our new mainwnd.h file should look something like the code below.

#include <atlwin.h>

class MainWnd : public CWindowImpl<MainWnd>
{
public:
  DECLARE_WND_CLASS(_T("Specific_Class_Name"))

};

We'll spend more time working with window classes later. For now the DECLARE_WND_CLASS macro is all we need to get our window class defined.

Message Handling

Like all windows, our window will receive messages sent by the operating system. Most of the messages require nothing more than the default processing provided by windows. Others we'll wish to provide custom handling for. In standard Win32 programming this is accomplished through the window procedure associated with the window class. CWindowImpl provides a more convenient method. It uses a set of macros to map window messages to functions in a fashion very similar to MFC. The message map is begun with the BEGIN_MSG_MAP macro and terminated with the END_MSG_MAP macro.

#include <atlwin.h>

class MainWnd : public CWindowImpl<MainWnd>
{
public:
  DECLARE_WND_CLASS(_T("Specific_Class_Name"))

  BEGIN_MSG_MAP(MainWnd)
  END_MSG_MAP()
};

The BEGIN_MSG_MAP macro takes the name of the class containing it as its only parameter. Sandwiched between the beginning and ending macros are the message handler macros that actually map window messages to functions [1], [2]. There are a number of message handling macros, but for now we'll only be working with one: the MESSAGE_HANDLER macro. The following line maps the WM_DESTROY window message to a function called OnDestroy().

MESSAGE_HANDLER(WM_DESTROY, OnDestroy)

For each message that needs handling, add a MESSAGE_HANDLER macro with the message ID as the first parameter and the name of the function to call as the second. Let's edit mainwnd.h, and add a MESSAGE_HANDLER for the WM_DESTROY message.

#include <atlwin.h>

class MainWnd : public CWindowImpl<MainWnd>
{
public:
  DECLARE_WND_CLASS(_T("Specific_Class_Name"))

  BEGIN_MSG_MAP(MainWnd)
    MESSAGE_HANDLER(WM_DESTROY, OnDestroy)
  END_MSG_MAP()

Functions mapped with the MESSAGE_HANDLER macro should have the following definition.

LRESULT SomeFunctionName( UINT, WPARAM, LPARAM, BOOL& );

The first parameter (UINT) is the message itself (WM_CREATE, WM_PAINT, etc.). The second and third are the same LPARAM and WPARAM parameters sent to a typical window procedure. The fourth is a flag that indicates whether the message has been handled or not, and is set to TRUE by default. Setting the value to FALSE will cause the message to undergo default message processing once the function returns [5].

Let's add our handler for the WM_DESTROY message to our MainWnd class. The code below shows how our new mainwnd.h file should look.

#include <atlwin.h>

class MainWnd : public CWindowImpl<MainWnd>
{
public:
  DECLARE_WND_CLASS(_T("Specific_Class_Name"))

  BEGIN_MSG_MAP(MainWnd)
    MESSAGE_HANDLER(WM_DESTROY, OnDestroy)
  END_MSG_MAP()

 LRESULT OnDestroy( UINT uMsg, WPARAM wParam, LPARAM lParam, BOOL &bHandled )
  {
      PostQuitMessage(0);
      bHandled = FALSE;
      return 0;
  }

};

Having implemented our WM_DESTROY handler, the MainWnd class is now complete. It doesn't do much. It just posts the quit message when the window is closed, but this is all we need for our first attempt at using the WTL. We're now ready to return to main.cpp, create our window, and set up the message loop.

Creating the Window

If you were to open atlwin.h and looked at the definition of CWindowImpl, you'd find that it only implements one method: Create(). All other functionality is inherited from CwindowImplBaseT and BaseT [2]. The definition of CWindowImpl's Create() method is listed below.

HWND Create(HWND hWndParent, RECT& rcPos, LPCTSTR szWindowName = NULL,
                  DWORD dwStyle = 0, DWORD dwExStyle = 0,
                  UINT nID = 0, LPVOID lpCreateParam = NULL)

As you can see, only the first two parameters are required; the rest provide default values. The parameters themselves are pretty standard. The first is the parent window, and the second is a RECT defining the size and position of the window. The third is the windows caption. The fourth and fifth specify the windows style, and the sixth is a control ID usually used with child windows like button's and menu's. The last parameter is assigned to the lpParam value of the CREATESTRUCT structure passed with the WM_CREATE message [4], [2].

Let's return to main.cpp and add code to create our window. First we'll need to include mainwnd.h. Notice that I included it after the definition of _Module (see listing below). This is necessary to prevent compilation errors since atlwin.h, which is included in mainwnd.h, requires that _Module be defined. Let's also declare a variable of type MainWnd, called mainwnd; and add a calls to Create(), ShowWindow(), and UpdateWindow().

#include <windows.h>
#include <atlbase.h>
#include <atlapp.h>

CAppModule _Module;

#include "mainwnd.h"

int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                     LPSTR lpCmdLine, int nCmdShow)
{
  MainWnd mainwnd;

  _Module.Init(NULL, hInstance);

  mainwnd.Create(NULL,CWindow::rcDefault,_T("Main Window"),
                                WS_OVERLAPPEDWINDOW);
  mainwnd.ShowWindow(nCmdShow);
  mainwnd.UpdateWindow();

  _Module.Term();

  return 0;
}

Everything here should be pretty straightforward with the possible exception of the value I passed for the second parameter (CWindow::rcDefault). This is simply a RECT structure with default values. CWindow exposes it for the sake of convenience [3].

The Message Loop

Moving right along we'll now add our message loop to main.cpp. The WTL provides a class called CMessageLoop to simplify adding message loops. This class, along with Module, work together to route messages to our windows. CMessageLoop exposes a member function called Run() that actually starts the message loop. Run() returns the WPARAM value of the WM_QUIT message which in turn is the value that was passed to PostQuitMessage(). I don't want to get too involved with the details of WTL's message loops here; we'll cover them in more detail in part 2 of this series.

We now have a completed, albeit simple WTL application. The listing below shows our new, complete main.cpp file.

#include <windows.h>
#include <atlbase.h>
#include <atlapp.h>

CAppModule _Module;

#include "mainwnd.h"

int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                     LPSTR lpCmdLine, int nCmdShow)
{
  CMessageLoop theLoop;
  MainWnd mainwnd;

  _Module.Init(NULL, hInstance);
  _Module.AddMessageLoop(&theLoop);

  mainwnd.Create(NULL,CWindow::rcDefault,_T("Main Window"),
                                WS_OVERLAPPEDWINDOW);
  mainwnd.ShowWindow(nCmdShow);
  mainwnd.UpdateWindow();

  int nRet = theLoop.Run();

  _Module.RemoveMessageLoop();
  _Module.Term();

  return nRet;
}

WTL vs. Win32?

How does the WTL compare to straight Win32 programming? Comparing the performance of this application with a similar one developed using just the Win32 API would be kind of pointless, as far as speed is concerned. There just isn't enough functionality here to make much of a comparison. Even with additional functionality the point is rather moot. Most of the applications time is spent simply waiting for messages. My release build of the WTL application weighs in at around 40kb, and the Dependency Walker utility reported that it only used the most basic system dll's. A similar Win32 application weighed in at 36kb (about 4kb smaller) and had exactly the same dependencies as the WTL version. This isn't surprising since the WTL application had the bare minimum to begin with. What this 4kb in code size bought us is an object-oriented approach to creating and implementing windows. Considering the increase in maintainability the WTL code has over the Win32 code, I consider this a bargain. Below is the Win32 application I used in my comparison.

Win32app.cpp

#include <windows.h>

LRESULT CALLBACK WndProc (HWND, UINT, WPARAM, LPARAM);

int APIENTRY WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance,
                      PSTR szCmdLine, int iCmdShow)
{

     TCHAR    szAppName[] = TEXT("Main Window");
     HWND     hwnd;
     MSG      msg;
     WNDCLASS wndclass;

     wndclass.style         = CS_HREDRAW | CS_VREDRAW;
     wndclass.lpfnWndProc   = WndProc;
     wndclass.cbClsExtra    = 0;
     wndclass.cbWndExtra    = 0;
     wndclass.hInstance     = hInstance;
     wndclass.hIcon         = LoadIcon (NULL, IDI_APPLICATION);
     wndclass.hCursor       = LoadCursor (NULL, IDC_ARROW);
     wndclass.hbrBackground = (HBRUSH) GetStockObject (WHITE_BRUSH);
     wndclass.lpszMenuName  = NULL;
     wndclass.lpszClassName = szAppName;

     if (!RegisterClass(&wndclass))
     {
          MessageBox(NULL, TEXT("RegisterClass() Failed"), 
                     szAppName, MB_ICONERROR);
          return 0;
     }
     
     hwnd = CreateWindow(szAppName,TEXT("Main Window"),
                         WS_OVERLAPPEDWINDOW,CW_USEDEFAULT,
                         CW_USEDEFAULT,CW_USEDEFAULT,
                         CW_USEDEFAULT,NULL,NULL,hInstance,NULL);
     
     ShowWindow(hwnd,iCmdShow);
     UpdateWindow(hwnd);
     
     while (GetMessage(&msg,NULL,0,0))
     {
          TranslateMessage(&msg);
          DispatchMessage(&msg);
     }
     return msg.wParam;
}

LRESULT CALLBACK WndProc (HWND hwnd, UINT message,
                          WPARAM wParam, LPARAM lParam)
{     
     switch(message)
     {          
     case WM_DESTROY:
          PostQuitMessage (0);
          return 0;
     }
     return DefWindowProc(hwnd,message,wParam,lParam);
}

WTL vs. MFC?

So, how about MFC? Again, performance is difficult to measure. But we do see a big difference in code size and dependencies. A similar MFC app actually weighed in less than its WTL counterpart, around 16kb. This is somewhat misleading because a good portion of the code was contained in mfc42.dll. With static linking the MFC app grew to 100kb, and the Dependency Walker still reported dependencies on comctl32.dll and the bloated shell32.dll. Not too big a deal but it does demonstrate the kind of overhead an MFC application is subject to that the WTL application gets to avoid. Below is the MFC application I used for this comparison.

MFCapp.h

class CMyApp : public CWinApp
{
public:
    virtual BOOL InitInstance ();
};

class CMainWindow : public CFrameWnd
{
public:
    CMainWindow ();

protected:
    DECLARE_MESSAGE_MAP ()
};


MFCapp.cpp

#include <afxwin.h>
#include "MFCapp.h"

CMyApp myApp;

BOOL CMyApp::InitInstance ()
{
    m_pMainWnd = new CMainWindow;
    m_pMainWnd->ShowWindow (m_nCmdShow);
    m_pMainWnd->UpdateWindow ();
    return TRUE;
}

BEGIN_MESSAGE_MAP (CMainWindow, CFrameWnd)
END_MESSAGE_MAP ()

CMainWindow::CMainWindow ()
{
    Create (NULL, _T ("Main Window"));
}

Conclusion

In the context of game development our baby application still wants for a few basic features. For starters it'd be nice to replace the standard background window color with black. A mechanism for performing idle processing is also needed. The simple application developed in this article also bothers me in that is doesn't follow the grand tradition of displaying a "Hello World" message. I decided to leave this last item as an exercise for the reader since the new functionality is relatively simple to add. Just add a MESSAGE_HANDLER entry for the WM_PAINT message to the message map and use a function like TextOut() to display the text. The reader is encourage to make any other changes he or she likes. The files (and project) used in this article will not be needed in the articles to follow.

Those who downloaded the WTL 7.0 libraries will find a WTL AppWizard included with the download (I believe the WTL 3.1 download also includes it but can't quite remember). The wizard-generated files make for great example code. And some of the options it provides are just plain cool. See the WTL's readme file for installation instructions.

In part 2 of this series we'll take an in depth look at the class definition macros, see what exactly it is they do for us, and how to gain greater control of the attributes our CWindowImpl object uses when registering a window class. We'll also learn how to insert idle processing into our message loop and how to get our hands on messages before they've been translated. In the meantime I can be reached by emailing rmack005@hotmail.com or by posting a comment in this articles discussion forum, which I'll check frequently. Comments and suggestions are greatly appreciated. Now go play.

The code accompanying this article will compile with the WTL 7.1 libraries which can be obtained at the MSDN Download Site.

Acknowledgements

First I'd like to thank Ben "Kylotan" Sizer for the feedback he provided on an early draft of this article. His comments significantly improved its quality. I'd like to thank Olga Perez for her efforts to correct my grammar. You put up a valiant fight, though I'm not sure you won. And of course, I'd like to thank the staff at Gamedev.net for providing both a home and an audience for this article. Thanks again everyone.

References

[1] Michael Park, "ATL 3.0 Window Classes: An Introduction", MSDN.

[2] Brad King and George Shepherd, "Inside ATL", Microsoft Press, 1999 (Chapter 14)

[3] MSDN's CWindow Reference

[4] MSDN's CWindowImpl Reference

[5] MSDN's MESSAGE_HANDLER Reference

[The Code Project also hosted a semi-official documentation effort for the WTL. http://www.thecodeproject.com/ -Ed.]

Discuss this article in the forums

Date this article was posted to GameDev.net: 1/15/2004
(Note that this date does not necessarily correspond to the date the article was written)

See Also:
Featured Articles
Windows