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. Do not confuse this with a C++ class — the MFC defines a class that represents a window but, this is not the same at all. You need to create a variable of type WNDCLASSEX, and give values to each of its members (just like filling in a form). 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've already registered.

The definition of the WNDCLASSEX structure is as follows:

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

All you need to do now is 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 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 must 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.

The members hIcon, hCursor, and hbrBackground are handles that in turn define the icon that represents the application when minimized, the cursor the window uses, and 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 are set using Windows API functions. For example:

WindowClass.hIcon = LoadIcon(0, IDI_APPLICATION);
WindowClass.hCursor = LoadCursor(0, 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 null, in which case Windows would provide the default icon and cursor. If you set hbrBackground to null, 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 zero if there is no menu for the window. 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 = L"OFWin";       // Define window class name
WindowClass.lpszClassName = szAppName;     // Set class name

I have defined szAppName as a Unicode string here. In fact, the LPCTSTR type is defined as const wchar_t* if UNICODE is defined for the application, or const char* if it is not. Thus, the definition for szAppName here assumes a Unicode application.

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

In fact, the WNDCLASSEX structure replaces another structure, WNDCLASS, that was used for the same purpose. The old structure did not include the cbSize member that stores the size of the structure in bytes or the hIconSm member.

After all the members of your WNDCLASSEX structure have been set to the values required, the next step is to tell Windows about it. You do this using the Windows API function RegisterClassEx(). Given that your structure 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. If you were using the obsolete WNDCLASS structure that I mentioned, you would have to use a different function here, RegisterClass().

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 use the function CreateWindow() for this. The window class that you've already created determines the broad characteristics of a window, and further arguments to the function CreateWindow() add additional characteristics. Because an application may have several windows in general, the function CreateWindow() returns a handle to the window 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 if you want to use them. You will look at a typical use of the CreateWindow() function at this point. This might be:

HWND hWnd;                              // Window handle
...
hWnd = CreateWindow(
        szAppName,                      // the window class name
        "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
        0,                              // No parent window
        0,                              // No menu
        hInstance,                      // Program Instance handle
        0                               // No window creation data
      );

The variable hWnd of type HWND is a 32-bit integer handle to a window, or 64-bit in 64-bit mode. You'll use this variable to record the value that the CreateWindow() function returns that identifies the window. The first argument that you pass to the function is the class name. This is used by Windows to identify the WNDCLASSEX struct that you passed to it previously, in the RegisterClassEx() function call, so that the 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, actually 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 of the window. 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 zero, indicating that the window being created is not a child window (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 zero, 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 zero 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 calling the CreateWindow() function, the window now exists but is not yet displayed on the screen. You need to 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 the function CreateWindow(). The second is the value nCmdShow that was passed to WinMain(), and that indicates how the window is to appear onscreen.

After calling the function ShowWindow(), the window appears onscreen 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 are not considered to be permanent — if you want the client area contents to be retained, you can't afford to 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. (In general, there can be several windows in an application.) The result of the call is that Windows sends a message to your program requesting that the client area be redrawn.

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, 0, 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 come back to your program. Windows allows execution to pass to another application, and you 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 their control of the processor from time to time. After your program calls GetMessage(), unless there is a message for your program, 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 in any event. 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 12-3.

Figure 12.3. FIGURE 12-3

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

You have looked at all the bits that need to go into the function 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 = L"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(0, IDI_APPLICATION);

  // Set window cursor to be the standard arrow
  WindowClass.hCursor = LoadCursor(0, IDC_ARROW);

  // Set gray brush for background color
  WindowClass.hbrBackground = static_cast<HBRUSH>(GetStockObject(GRAY_BRUSH));

  WindowClass.lpszMenuName = 0;             // No menu
  WindowClass.lpszClassName = szAppName;    // Set class name
  WindowClass.hIconSm = 0;                  // Default small icon

  // Now register our window class
  RegisterClassEx(&WindowClass);

// Now we can create the window
  hWnd = CreateWindow(
          szAppName,                       // the window class name
          L"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
          CW_USEDEFAULT,          // ....
          0,                      // No parent window
          0,                      // No menu
          hInstance,              // Program Instance handle
          0                       // No window creation data
        );

  ShowWindow(hWnd, nCmdShow);     // Display the window
  UpdateWindow(hWnd);             // Cause window client area to be drawn

  // The message loop
  while(GetMessage(&msg, 0, 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
}
                                                                       

After declaring the variables you need in the function, all the members of the WindowClass structure are initialized and the window is registered.

The next step is to call the CreateWindow() function to create the data for the physical appearance of the window, based on the arguments passed 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.

Finally, the message loop continues to retrieve messages for the application until a WM_QUIT message is obtained, whereupon 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 prototype of our WindowProc() function is:

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

The return type is LRESULT, which is a type defined by Windows and is normally equivalent to type long. Because the function is called by Windows through a pointer (you set the pointer up 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 defined by Windows that determines how the function arguments are handled. Therefore, you could use WINAPI here instead of CALLBACK, although the latter expresses better what this function is about. The four arguments that are passed provide information about the particular message causing the function to be called. The meaning of each of these arguments is described in the following table:

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

Messages are identified by the value message that is passed to WindowProc(). You can test this value against predefined symbolic constants, each of which relates to 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.

The process of decoding the message that Windows is sending is usually done using a switch statement in the WindowProc() function, based on the value of message. Selecting the message types that you want to process is then just a question of putting a case statement for each case in the switch. The typical structure of such a switch statement, with arbitrary cases included, is as follows:

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 may be hidden from sight in the Windows programs that you will write later using MFC. Each case corresponds to a particular value for the 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 providing default message handling.

In a complex program dealing specifically 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, you won't have to worry about this because it is all taken care of for you and you never see the WindowProc() function. All you need to do is to supply the code to process the particular 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
         L"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

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 the WindowProc() function. You do this by generating a WM_QUIT message with the following statement:

PostQuitMessage(0);

The argument here is an exit code. This Windows 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 in WinMain() returning FALSE and ending the message loop, so ending the program.

You have covered all the elements necessary to make up the complete WindowProc() function for your example. The code for the function is as follows:

// Listing OFWIN_2
LRESULT CALLBACK WindowProc(HWND hWnd, UINT message,
                          WPARAM wParam, LPARAM lParam)
{

HDC hDC;                       // Display context handle
  PAINTSTRUCT PaintSt;           // Structure defining area to be drawn
  RECT aRect;                    // A working rectangle

  switch(message)                // Process selected messages
  {
    case WM_PAINT:                     // Message is to redraw the window
      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
             L"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;

    default:                      // Any other message - we don't
                                  // want to know, so call
                                  // default message processing
      return DefWindowProc(hWnd, message, wParam, lParam);
  }
}
                                                                

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 different messages: WM_PAINT and WM_DESTROY. You hand all other messages back to Windows by calling the DefWindowProc() function in the default case for the switch. 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 you handle, a zero value is returned.