A more advanced window

A more advanced window

We will create the next example with the wizard too. It is a handy way of avoiding writing a lot of boilerplate code. But it is obvious that we will need to understand every bit of what the wizard generates. We create a new project, as usual with the "project" then "Create" menu option, and we give it the name of "winexample". The wizard shows us a lot of dialogs with many options that will be explained later, so just stick with the defaults. Choose a single window application:

After pressing the "next" button till the dialog boxes disappear, we press F9, compile the whole, and we run it. We see a single white window, with a status bar at the bottom, a summary menu, and nothing else. Well, this is the skeleton of a windows application. Let's see it in more detail.

We start as always in the same place. We go to the WinMain function, and we try to figure out what is it doing. Here it is:

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, INT nCmdShow)

}

return msg.wParam;

We have the same schema that we saw before, but this time with some variations. We init the application (registering the window class, etc), we load the keyboard accelerators, we create the window, the status bar, we show our window, and then we enter the message loop until we receive a WM_QUIT, that breaks it. We return the value of the "wParam" parameter of the last message received (WM_QUIT of course).

Simple isn't it?

Now let's look at it in more detail.

The "InitApplication" procedure initializes the WNDCLASS structure with a little more care now, since we are not using our DefDialogProc any more, there are a lot of things we have to do ourselves. Mostly, that procedure uses the standard settings:

static BOOL InitApplication(void)

The style of the window used is a combination of integer constants like CS_HREDRAW, and others, combined using the OR operator, the vertical bar. What does this mean?

This is a standard way of using bits in C. If you go to the definition of CS_HREDRAW (right-click in that name and choose the "Goto definition" option), you will see that the value is 2. Other constants like CS_DBLCLKS have a value of 8. All those numbers are a power of two. Well, a power of two by definition will always have a single bit set. All other bits will be zero. If you OR those numbers with each other, you will obtain a number that has the bits set that correspond to the different values used. In our case this statement is equivalent to:

Wc.style = 2 | 1 | 8;

8 ored with 1 is 1 0 0 1, ored with 2 is 1 0 1 1, what is equal to 11 in decimal notation.

This is a very common way of using flags in C. Now, if you want to know if this window is a window that answers to double-clicks, you just have to query the corresponding bit in the style integer to get your answer. You do this with the following construct:

If (wc.style & CS_DBLCLKS)

We test in this if expression, if the value of the "style" integer ANDed with 8 is different than zero. Since CS_DBLCLKS is a power of two, this AND operation will return the value of that single bit. Note too that 1 is a power of two since 2 to the power of zero is one.

We will return to this at the end of this section.

Coming back to our initialization procedure, there are some new things, besides this style setting. But this is just a matter of reading the windows documentation. No big deal. There are many introductory books that augment their volume just with the easy way of including a lot of windows documentation in their text. Here we will make an exception.

But what is important however is that you know how to look in the documentation! Suppose you want to know what the hell is that CS_DBLCLKS constant, and what does it exactly mean. You press F1 in that identifier and nothing. It is not in the index.

Well, this constant appears in the context of RegisterClass API. When we look at the documentation of RegisterClass, we find a pointer to the doc of the WNDCLASS structure. Going there, we find in the description of the style field, all the CS_* constants, neatly explained.

Note that not all is in the index. You have to have a feeling of where to look. Lcc-win32 comes with a help file of reasonable size to be downloaded with a standard modem. It is 13MB compressed, and it has the essentials. A more detailed documentation complete with the latest stuff is in the Software Development Kit (SDK) furnished by Microsoft. It is available at their Web site, and it has a much more sophisticated help engine.

After initializing the window class, the WinMain function loads the accelerators for the application. This table is just a series of keyboard shortcuts that make easy to access the different menu items without using the mouse and leaving the keyboard. In the resource editor you can edit them, add/delete/change, etc. To do this you start the resource editor and you press the "dir" button in the upper right. You will see the following display.

You click in the "Accelerator" tree tab, and you will see the following:

We have here the accelerator called IDM_EXIT that has the value of 300. This is just Ctrl+Q for quit. The key value is 81, the ASCII value of the letter 'q', with a flag indicating that the control key must be pressed, to avoid quitting just when the user happens to press the letter q in the keyboard!

Double-clicking in the selected line leads us to yet another dialog:

Here you can change the accelerator as you want. The flags are explained in the documentation for the resource editor.

But this was just another digression, we were speaking about WinMain and that statement: LoadAccelerators. Well, let's go back to that piece of code again.

After loading the accelerators, the status bar is created at the bottom of the window, and then, at last, we show the window. Note that the window is initially hidden, and it will be shown only when all things have been created and are ready to be shown. This avoids screen flickering, and saves execution time. It would be wasteful to redraw the window before we created the status bar, since we would have to do that again after it is created.

We will speak about status bar later, since that is not crucial now. What really is important is the message loop that begins right after we call ShowWindow.

while (GetMessage(&msg,NULL,0,0))

}

This loop calls the API GetMessage. If that returns TRUE, we call the API to translate the accelerators. This API will convert a sequence of keystrokes into a WM_COMMAND message, as it was sent by a menu, if it finds a correspondence between the keystrokes and the accelerator table that we loaded just a few lines above. If TranslateAccelerator doesn't find any correspondence, we go on by calling TranslateMessage, that looks for sequences of key pressing and key up messages, and does the dirty work of debouncing the keyboard, handling repeat sequences, etc. At last, we dispatch our message to the procedure indicated in the window class.

And that is it. We loop and loop and loop, until we eventually get a WM_QUIT, that provokes that GetMessage returns FALSE, and the while loop is finished.

Wow. Finished?

We have hardly started. What is interesting now, is that we have a skeleton to play with. We will show in the next sections how we add things like a dialog box, etc.

Summary:

Windows programming looks intimidating at first. But it is just the looks.

Before we go on, however, as promised, let's look in more details to how flags are set/unset in C.

Flags are integers where each bit is assigned a predefined meaning. Usually with a pre-processor define statement, powers of two are assigned a symbolic meaning like in the case of CS_DBLCLKS above. In a 32-bit integer we can stuff 32 of those. We test those flags with:

if (flag & CONSTANT)

we set them with:

flag |= CONSTANT;

we unset them with:

flag &= ~CONSTANT;

This last statement needs further explanations. We use the AND operator with the complement of the constant. Since those constants have only one bit set, the complement of the constant is an integer with all the bits turned into ones except the bit that we want to unset. We AND that with our flag integer: since all bits but the one we want to set to zero are one, we effectively turn off that bit only, leaving all others untouched.