Specifying a Program Window

The first step in creating a window is to define just what sort of window it is that you want to create. Windows defines a special struct type called WNDCLASSEX to contain the data specifying a window. The data that is stored in an instance of the struct defines a window class, which determines the type of window. You need to create a variable of type WNDCLASSEX, and give values to each of its members. After you’ve filled in the variables, you can pass it to Windows (via a function that you’ll see later) to register the class. When that’s been done, whenever you want to create a window of that class, you can tell Windows to look up the class that you have already registered.

The definition of the WNDCLASSEX structure is:

struct WNDCLASSEX
{
  UINT cbSize;            // Size of this object in bytes
  UINT style;             // Window style
  WNDPROC lpfnWndProc;    // Pointer to message processing function
  int cbClsExtra;         // Extra bytes after the window class
  int cbWndExtra;         // Extra bytes after the window instance
  HINSTANCE hInstance;    // The application instance handle
  HICON hIcon;            // The application icon
  HCURSOR hCursor;        // The window cursor
  HBRUSH hbrBackground;   // The brush defining the background color
  LPCTSTR lpszMenuName;   // A pointer to the name of the menu resource
  LPCTSTR lpszClassName;  // A pointer to the class name
  HICON hIconSm;          // A small icon associated with the window
};

You construct an object of type WNDCLASSEX in the way that you saw when I discussed structures, for example:

WNDCLASSEX WindowClass;                // Create a window class object

You can now fill in values for the members of WindowClass. They are all public by default because WindowClass is a struct. Setting the value for the cbSize member of the struct is easy when you use the sizeof operator:

WindowClass.cbSize = sizeof(WNDCLASSEX);

The style member of the struct determines various aspects of the window’s behavior, in particular, the conditions under which the window should be redrawn. You can select from a number of options for this member’s value, each defined by a symbolic constant beginning with CS_.

Where two or more options are required, the constants can be combined to produce a composite value using the bitwise OR operator, |. For example:

WindowClass.style = CS_HREDRAW | CS_VREDRAW;

The option CS_HREDRAW indicates to Windows that the window is to be redrawn if its horizontal width is altered, and CS_VREDRAW indicates that it is to be redrawn if the vertical height of the window is changed. In the preceding statement, you have elected to have the window redrawn in either case. As a result, Windows sends a message to your program indicating that you should redraw the window whenever the width or height of the window is altered by the user. Each of the possible options for the window style is defined by a unique bit in a 32-bit word being set to 1. That’s why the bitwise OR is used to combine them. These bits indicating a particular style are usually called flags. Flags are used very frequently, not only in Windows but also in C++, because they are an efficient way of representing and processing features that are either there or not, or parameters that are either true or false.

The member lpfnWndProc stores a pointer to the function in your program that handles messages for the window you create. The prefix to the name signifies that this is a long pointer to a function. If you followed the herd and called the function to handle messages for the application WindowProc(), you would initialize this member with the statement:

WindowClass.lpfnWndProc = WindowProc;

The next two members, cbClsExtra and cbWndExtra, allow you to ask that extra space be provided internally to Windows for your own use. An example of this could be when you want to associate additional data with each instance of a window to assist in message handling for each window instance. Normally you won’t need extra space allocated for you, in which case you set the cbClsExtra and cbWndExtra members to zero.

The hInstance member holds the handle for the current application instance, so you should set this to the hInstance value that was passed to WinMain() by Windows:

WindowClass.hInstance = hInstance;

The members hIcon, hCursor, and hbrBackground are handles that in turn reference objects that represent:

• The application when minimized
• The cursor the window uses
• The background color of the client area of the window

As you saw earlier, a handle is just a 32-bit integer (or 64-bit when compiled in 64-bit mode) used as an ID to represent something. These members are set using Windows API functions. For example:

WindowClass.hIcon = LoadIcon(nullptr, IDI_APPLICATION); 
WindowClass.hCursor = LoadCursor(nullptr, IDC_ARROW); 
WindowClass.hbrBackground = static_cast<HBRUSH>(GetStockObject(GRAY_BRUSH));

All three members are set to standard Windows values by these function calls. The icon is a default provided by Windows and the cursor is the standard arrow cursor used by the majority of Windows applications. A brush is a Windows object used to fill an area, in this case the client area of the window. The function GetStockObject() returns a generic type for all stock objects, so you need to cast it to type HBRUSH. In the preceding example, it returns a handle to the standard gray brush, and the background color for our window is thus set to gray. This function can also be used to obtain other standard objects for a window, such as fonts, for example. You could also set the hIcon and hCursor members to nullptr, in which case Windows would provide the default icon and cursor. If you set hbrBackground to nullptr, your program is expected to paint the window background, and messages are sent to your application whenever this becomes necessary.

The lpszMenuName member is set to the name of a resource defining the window menu, or to nullptr if there is no menu for the window:

WindowClass.lpszMenuName = nullptr;

You will look into creating and using menu resources when you use the AppWizard.

The lpszClassName member of the struct stores the name that you supply to identify this particular class of window. You would usually use the name of the application for this. You need to keep track of this name because you will need it again when a window is created. This member would therefore be typically set with the statements:

static LPCTSTR szAppName {_T("OFWin")};    // Define window class name
WindowClass.lpszClassName = szAppName;     // Set class name

I have defined szAppName using the _T() macro that is defined in the tchar.h header. The LPCTSTR type is defined as const wchar_t* if UNICODE is defined for the application, or const char* if it is not. The _T() macro will create a string of the correct type automatically.

The last member is hIconSm, which identifies a small icon associated with the window class. If you specify this as nullptr, Windows searches for a small icon related to the hIcon member and uses that.

Creating a Program Window

After you have set the members of your WNDCLASSEX structure to the values required, the next step is to tell Windows about it. You do this by calling the Windows API function RegisterClassEx(). Given that your WNDCLASSEX structure object is WindowClass, the statement to do this would be:

RegisterClassEx(&WindowClass);

Easy, isn’t it? The address of the struct is passed to the function, and Windows extracts and squirrels away all the values that you have set in the structure members. This process is called registering the window class. Just to remind you, the term class here is used in the sense of classification and is not the same as the idea of a class in C++, so don’t confuse the two. Each instance of the application must make sure that it registers the window classes that it needs.

After Windows knows the characteristics of the window that you want, and the function that is going to handle messages for it, you can go ahead and create it. You call the CreateWindow() function for this. The window class that you have created determines the broad characteristics of the application window, and further arguments to CreateWindow() add additional characteristics. Because an application may have several windows in general, CreateWindow() returns a handle to the window it created that you can store to enable you to refer to that particular window later. There are many API calls that require you to specify the window handle as a parameter. Let’s look at a typical use of CreateWindow(). This might be:

HWND hWnd;                                // Window handle
...
hWnd = CreateWindow(
        szAppName,                        // the window class name
        _T("A Basic Window the Hard Way"),// The window title
        WS_OVERLAPPEDWINDOW,              // Window style as overlapped
        CW_USEDEFAULT,                    // Default screen position of upper left
        CW_USEDEFAULT,                    // corner of our window as x,y.
        CW_USEDEFAULT,                    // Default window size, width...
        CW_USEDEFAULT,                    // ...and height
        nullptr,                          // No parent window
        nullptr,                          // No menu
        hInstance,                        // Program Instance handle
        nullptr                           // No window creation data
      );

The hWnd variable of type HWND is a 32-bit integer handle to a window, or 64-bit in 64-bit mode. You use this variable to record the window handle that CreateWindow() returns. The first argument that you pass to CreateWindow() is the class name. This is used to identify the WNDCLASSEX object that you passed to the operating system previously in the RegisterClassEx() function call, so that information from this struct can be used in the window creation process.

The second argument to CreateWindow() defines the text that is to appear on the title bar. The third argument specifies the style that the window has after it is created. The option specified here, WS_OVERLAPPEDWINDOW, combines several options. It defines the window as having the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. This results in an overlapped window, which is a window intended to be the main application window, with a title bar and a thick frame, which has a title bar icon, system menu, and maximize and minimize buttons. A window that you specify as having a thick frame has borders that can be resized.

The next four arguments determine the position and size of the window on the screen. The first two are the screen coordinates of the upper-left corner of the window, and the second two define the width and height. The value CW_USEDEFAULT indicates that you want Windows to assign the default position and size for the window. This tells Windows to arrange successive windows in cascading positions down the screen. CW_USEDEFAULT only applies to windows specified as WS_OVERLAPPED.

The next argument value is nullptr, indicating that the window being created is not a child window (i.e., not a window that is dependent on a parent window). If you wanted it to be a child window, you would set this argument to the handle of the parent window. The next argument is also nullptr, indicating that no menu is required. You then specify the handle of the current instance of the program that was passed to the program by Windows. The last argument for window creation data is nullptr because you just want a simple window in the example. If you wanted to create a multiple-document interface (MDI) client window, the last argument would point to a structure related to this. You’ll learn more about MDI windows later in the book.

After you call CreateWindow(), the window exists but is not yet displayed on the screen. You must call another Windows API function to get it displayed:

ShowWindow(hWnd, nCmdShow);             // Display the window

Only two arguments are required here. The first identifies the window and is the handle returned by CreateWindow(). The second is the nCmdShow value that was passed to WinMain(), which indicates how the window is to appear on-screen.

Initializing the Program Window

After calling ShowWindow(), the window appears on-screen but still has no application content, so you need to get your program to draw in the client area of the window. You could just put together some code to do this directly in the WinMain() function, but this would be most unsatisfactory: in this case, the contents of the client area would not be permanent — if you want the client area contents to be retained, you can’t just output what you want and forget about it. Any action on the part of the user that modifies the window in some way, such as dragging a border or dragging the whole window, typically requires that the window and its client area are redrawn.

When the client area needs to be redrawn for any reason, Windows sends a particular message to your program, and your WindowProc() function needs to respond by reconstructing the client area of the window. Therefore, the best way to get the client area drawn in the first instance is to put the code to draw the client area in the WindowProc() function and get Windows to send the message requesting that the client area be redrawn to your program. Whenever you know in your program that the window should be redrawn (when you change something, for example), you need to tell Windows to send a message back to get the window redrawn.

You can ask Windows to send your program a message to redraw the client area of the window by calling another Windows API function, UpdateWindow(). The statement to accomplish this is:

UpdateWindow(hWnd);                // Cause window client area to be drawn

This function requires only one argument: the window handle hWnd, which identifies your particular program window. The result of the call is that Windows sends a message to your program requesting that the client area be redrawn.

Dealing with Windows Messages

The last task that WinMain() needs to address is dealing with the messages that Windows may have queued for your application. This may seem a bit odd because I said earlier that you needed the function WindowProc() to deal with messages, but let me explain a little further.

MSG msg;                                     // Windows message structure
while(GetMessage(&msg, nullptr, 0, 0) == TRUE)  // Get any messages
{
  TranslateMessage(&msg);                   // Translate the message
  DispatchMessage(&msg);                    // Dispatch the message
}

struct MSG
{
  HWND   hwnd;                // Handle for the relevant window
  UINT   message;             // The message ID
  WPARAM wParam;              // Message parameter (32-bits)
  LPARAM lParam;              // Message parameter (32-bits)
  DWORD  time;                // The time when the message was queued
  POINT  pt;                  // The mouse position
};

Multitasking

If there are no messages queued, the GetMessage() function does not return control to your program. Windows allows execution to pass to another application, and you will only get a value returned from calling GetMessage() when a message appears in the queue.

This mechanism was fundamental in enabling multiple applications to run under older versions of Windows and is referred to as cooperative multitasking because it depends on concurrent applications giving up control of the processor from time to time. After your program calls GetMessage(), unless there is a message for it another application is executed and your program gets another opportunity to do something only if the other application releases the processor, perhaps by a call to GetMessage() when there are no messages queued for it, but this is not the only possibility.

With current versions of Windows, the operating system can interrupt an application after a period of time and transfer control to another application. This mechanism is called pre-emptive multitasking because an application can be interrupted at any time. With pre-emptive multitasking, however, you must still program the message loop in WinMain() using GetMessage() as before, and make provision for relinquishing control of the processor to Windows from time to time in a long-running calculation (this is usually done using the PeekMessage() API function). If you don’t do this, your application may be unable to respond to messages to repaint the application window when these arise. This can be for reasons that are quite independent of your application — when an overlapping window for another application is closed, for example.

The conceptual operation of the GetMessage() function is illustrated in Figure 11-3.

Within the while loop, the first call to TranslateMessage() requests Windows to do some conversion work for keyboard-related messages. Then the call to DispatchMessage() causes Windows to dispatch the message, which it does by calling the WindowProc() function in your program to process the message. The return from DispatchMessage() does not occur until WindowProc() has finished processing the message. A WM_QUIT message indicates that the program should end, so this results in FALSE being returned to the application, which stops the message loop.

A Complete WinMain() Function

You have looked at all the bits that need to go into WinMain() so now you can assemble them into a complete function:

// Listing OFWIN_1
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                   LPSTR lpCmdLine, int nCmdShow)
{
  WNDCLASSEX WindowClass;     // Structure to hold our window's attributes
     
  static LPCTSTR szAppName {_T("OFWin")};     // Define window class name
  HWND hWnd;                                  // Window handle
  MSG msg;                                    // Windows message structure
     
  WindowClass.cbSize = sizeof(WNDCLASSEX);    // Set structure size
     
  // Redraw the window if the size changes
  WindowClass.style   = CS_HREDRAW | CS_VREDRAW;
     
  // Define the message handling function
  WindowClass.lpfnWndProc = WindowProc;
     
  WindowClass.cbClsExtra = 0;     // No extra bytes after the window class
  WindowClass.cbWndExtra = 0;     // structure or the window instance
     
  WindowClass.hInstance = hInstance;           // Application instance handle
     
  // Set default application icon
  WindowClass.hIcon = LoadIcon(nullptr, IDI_APPLICATION);
     
  // Set window cursor to be the standard arrow
  WindowClass.hCursor = LoadCursor(nullptr, IDC_ARROW);
     
  // Set gray brush for background color
  WindowClass.hbrBackground = static_cast<HBRUSH>(GetStockObject(GRAY_BRUSH));
     
  WindowClass.lpszMenuName = nullptr;         // No menu
  WindowClass.lpszClassName = szAppName;      // Set class name
  WindowClass.hIconSm = nullptr;              // Default small icon
     
  // Now register our window class
  RegisterClassEx(&WindowClass);
     
  // Now we can create the window
  hWnd = CreateWindow(
          szAppName,                          // the window class name
          _T("A Basic Window the Hard Way"),  // The window title
          WS_OVERLAPPEDWINDOW,                // Window style as overlapped
          CW_USEDEFAULT,                      // Default position of upper left
          CW_USEDEFAULT,                      // corner of our window as x,y...
          CW_USEDEFAULT,                      // Default window size
          CW_USEDEFAULT,                      // ....
          nullptr,                            // No parent window
          nullptr,                            // No menu
          hInstance,                          // Program Instance handle
          nullptr                             // No window creation data
        );
     
  ShowWindow(hWnd, nCmdShow);                 // Display the window
  UpdateWindow(hWnd);                         // Redraw window client area
     
  // The message loop
  while(GetMessage(&msg, nullptr, 0, 0) == TRUE) // Get any messages
  {
    TranslateMessage(&msg);                   // Translate the message
    DispatchMessage(&msg);                    // Dispatch the message
  }
     
  return static_cast<int>(msg.wParam);        // End, so return to Windows
}

You need a WindowProc() implementation to make this into a working Windows application. We will look at that after we explore how this code works.

How It Works

After declaring the variables that you need in WinMain(), all the members of the WindowClass structure are initialized and the window is registered. Next you call the CreateWindow() function to create the data for the physical appearance of the window based on the arguments and the data established in the WindowClass structure that was previously passed to Windows using the RegisterClassEx() function. The call to ShowWindow() causes the window to be displayed according to the mode specified by nCmdShow, and the UpdateWindow() function signals that a message to draw the window client area should be generated.

The message loop retrieves messages until a WM_QUIT message is issued for the application. When this occurs, the GetMessage() function returns FALSE and the loop ends. The value of the wParam member of the msg structure is passed back to Windows in the return statement.

The WindowProc() Function

The prototype of the WindowProc() function is:

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

The return type is LRESULT, which is a Windows type that is normally equivalent to type long. Because the function is called by Windows through a pointer (you set up the pointer with the address of WindowProc() in WinMain() in the WNDCLASSEX structure), you need to qualify the function as CALLBACK. I mentioned this specifier earlier, and its effect is the same as the WINAPI specifier that determines how the function arguments are handled. You could use WINAPI here instead of CALLBACK, although the latter expresses better what this function is about. The four arguments that are passed to WindowProc() provide information about the message causing the function to be called. The meaning of each argument is described in the following table:

The window that the incoming message relates to is identified by the first argument, hWnd. In this case, you have only one window, so you can ignore it.

Messages are identified by the message value that is passed to WindowProc(). You can test this value against predefined symbolic constants, each of which identifies a particular message. General windows messages begin with WM_, and typical examples are WM_PAINT, which corresponds to a request to redraw part of the client area of a window, and WM_LBUTTONDOWN, which indicates that the left mouse button was pressed. You can find the whole set of these by searching for WM_ in the MSDN Library.

Decoding a Windows Message

Decoding the message that Windows sends is usually done using a switch statement in the WindowProc() function, based on the value of message. You select the message types that you want to process by putting a case statement for each message ID in the switch. The typical structure of such a switch statement is:

switch(message)
{
  case WM_PAINT:
    // Code to deal with drawing the client area
    break;
     
  case WM_LBUTTONDOWN:
    // Code to deal with the left mouse button being pressed
    break;
     
  case WM_LBUTTONUP:
    // Code to deal with the left mouse button being released
    break;
     
  case WM_DESTROY:
    // Code to deal with a window being destroyed
    break;
     
  default:
    // Code to handle any other messages
}

Every Windows program has something like this somewhere, although it will be hidden from sight in the Windows programs that you will write later using MFC. Each case corresponds to a particular message ID and provides suitable processing for that message. Any messages that a program does not want to deal with individually are handled by the default statement, which should hand the messages back to Windows by calling DefWindowProc(). This is the Windows API function that provides default message handling.

In a complex program dealing with a wide range of possible Windows messages, this switch statement can become large and rather cumbersome. When you get to use the Application Wizard to generate a Windows application that uses the MFC, you won’t have to worry about this because it is all taken care of for you and you never see the WindowProc() function. You just need to supply the code to process the messages in which you are interested.

HDC hDC;                               // A display context handle
PAINTSTRUCT PaintSt;                   // Structure defining area to be redrawn
     
hDC = BeginPaint(hWnd, &PaintSt);      // Prepare to draw in the window

RECT aRect;                         // A working rectangle
GetClientRect(hWnd, &aRect);

SetBkMode(hDC, TRANSPARENT);           // Set text background mode

DrawText(hDC,                     // Device context handle
         _T("But, soft! What light through yonder window breaks?"),
         -1,                      // Indicate null terminated string
         &aRect,                  // Rectangle in which text is to be drawn
         DT_SINGLELINE|           // Text format - single line
         DT_CENTER|               //             - centered in the line
         DT_VCENTER               //             - line centered in aRect
      );

EndPaint(hWnd, &PaintSt);           // Terminate window redraw operation

Ending the Program

You might assume that closing the window closes the application, but to get this behavior, you actually have to add some more code. The reason that the application won’t close by default when the window is closed is that you may need to do some clearing up. It is also possible that the application may have more than one window. When the user closes the window by double-clicking the title bar icon or clicking the Close button, this causes a WM_DESTROY message to be generated. Therefore, to close the application, you need to process the WM_DESTROY message in WindowProc(). You do this by generating a WM_QUIT message:

PostQuitMessage(0);

The argument here is an exit code. This API function does exactly what its name suggests: it posts a WM_QUIT message in the message queue for your application. This results in the GetMessage() function that is called in WinMain() returning FALSE and ending the message loop, thus ending the program.

A Complete WindowProc() Function

You have covered all the elements necessary to assemble the complete WindowProc() function for the example. The code for the function is:

// Listing OFWIN_2
LRESULT CALLBACK WindowProc(HWND hWnd, UINT message,
                          WPARAM wParam, LPARAM lParam)
{
     
  switch(message)                // Process selected messages
  {
    case WM_PAINT:                     // Message is to redraw the window
      HDC hDC;                         // Display context handle
      PAINTSTRUCT PaintSt;             // Structure defining area to be drawn
      RECT aRect;                      // A working rectangle
      hDC = BeginPaint(hWnd, &PaintSt);// Prepare to draw the window
     
      // Get upper left and lower right of client area
      GetClientRect(hWnd, &aRect);
     
      SetBkMode(hDC, TRANSPARENT);     // Set text background mode
     
      // Now draw the text in the window client area
      DrawText(
             hDC,                 // Device context handle
             _T("But, soft! What light through yonder window breaks?"),
             -1,                  // Indicate null terminated string
             &aRect,              // Rectangle in which text is to be drawn
             DT_SINGLELINE|       // Text format - single line
             DT_CENTER|           //             - centered in the line
             DT_VCENTER);         //             - line centered in aRect
     
      EndPaint(hWnd, &PaintSt);   // Terminate window redraw operation
      return 0;
     
    case WM_DESTROY:              // Window is being destroyed
      PostQuitMessage(0);
      return 0;
  }
  return DefWindowProc(hWnd, message, wParam, lParam);
}

How It Works

Apart from the last statement, the entire function body is just a switch statement. A particular case is selected based on the message ID that is passed to the function through the message parameter. Because this example is simple, you need to process only two types of message: WM_PAINT and WM_DESTROY. You hand all other messages back to Windows by calling the DefWindowProc() function after the switch statement. The arguments to DefWindowProc() are those that were passed to the function, so you are just passing them back as they are. Note the return statement at the end of processing each message type. For the messages that you handle, a zero value is returned.