Windows API Programming

Introduction

When writing applications for a PC running Microsoft Windows we need to use the Windows API (sometimes referred to as the Windows 32 API or Win32). When writing games we use it as a base for our DirectX applications. We also may want to use it to create game tools, like level editors, effects editors, resource managers etc. When working on a Playstation 1 game I used the API to create level editors that created world data that could then be passed to the Playstation. So even if you intend to work only with consoles it is still useful to learn to program. DirectX of course runs under Windows and some knowledge of the API is needed in order to get a DirectX application up and running.

The Windows API provides a lot of functionality that we will not be using. For our minimum needs we need to be able to create a window and receive user input. We may also want some dialogs and some menus the user can interface with.

Other Resources

The pages on this site give you an introduction to programming the Windows API. Enough is given to support our DirectX applications but there is much more you can do with the API than is described here. If you want to study Windows API programming I recommend Charles Petzold's Programming Windows book (see the resources page for more details).

Event Driven Programming

Probably when writing programs in the past you have been in total control. The flow of the program is controlled solely by you, that is why Windows programming sometimes comes as a bit of a surprise! Windows programs are event driven. In other words your program responds to window events only. So when windows tells you your window needs redrawing you redraw it (you should not do this at any other time) and when it tells you the user has selected a menu item you can then act on it. Your program should be well behaved, after all it is sharing Windows with other programs e.g. other apps that are running, the clock, etc. So you should only do work when Windows allows you to do it and you should not do much before returning control to Windows so as to let other programs have a slice of the action.

So there is a shift in the way you think about programming, instead of controlling the flow you wait for events (messages) sent to you by Windows. This actually saves you a lot of trouble in the long run. Imagine it did not work in this way - you would have to keep track of which windows are open and which is the current one and keep checking for mouse movement and users clicking on items all the time - it would be a pain. Why not let Windows handle all that boring work. In fact later on when you write your own games you often do need to do this for your own User Interface (UI) and its a lot of work.

Don't be alarmed!

When you first see a Windows program you might be slightly perturbed :) It looks like nothing on earth and can put people off straight away. However when you look closely at the code and break it down you will see it is not so indecipherable after all.

The first strange things you may notice are variable types like UINT , APIENTRY and LRESULT. These are just typedefs (think of these as synonyms) for the common types you know already. e.g. UINT is a typedef for unsigned int. So why don't Microsoft use unsigned int? Well the reason is they would like Windows to run on everything from a toaster to a super computer and so they want platform independence. Because different platforms use different sized types they want to be able to change the type dependant on the platform, so if you are compiling the code for a toaster UINT may be a typedef for something different than a PC unsigned int.

Luckily Microsoft do have a habit of writing all their platform independent types in capitals so we can easily spot them. If you want to know what the real type is right-click in Viz on the type (e.g. UINT) and select 'go to definition' from the drop down menu. You may need to recompile with browse info enabled first but this is always a good idea anyway. When you do this the windows header file where the type is defined is opened at the definition.

Another issue is that the Windows API is C based, not C++. This means most C++ Windows programs have one main.cpp file that has all the C code relating to windows and the rest is in classes as normal.

A Simple Windows Program

Getting Started

The smallest useful windows program requires us to create a window, provide a function to receive messages sent to that window and to provide a program loop that checks for the application terminating.

Since we are programming using someone else's library (Microsoft's) we need to link to their library which contains all their code and include their header files that define the interfaces to the library.

Note: We do not normally start from scratch but use the App Wizard in Viz or reuse old projects , this way we already have the libraries included in the settings and don't have to add them. The App Wizard can be found when you create a new project in Viz.

The Windows API is split amongst a number of libraries, commonly you will find the following:

kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib

Any of your source files that use Windows API calls must include the headers defining the functions, fortunately you normally only need to include: #include <windows.h> which in turn includes all the other headers needed.

Note: Windows provides capabilities for a large number of functions, a lot of stuff that we never need so we can tell windows that we don't want all the extra junk, we just want a nice simple set of functions, by writing the following before including windows.h:

#define WIN32_LEAN_AND_MEAN

In fact there is a way of making it even learner and meaner :) and turning off more stuff:

#define VC_EXTRALEAN

For what these turn off see the MSDN page here: Faster Builds and Smaller Header Files

Required Functions

There are two functions we must have in every windows program, one entry function called WinMain and one to handle messages to our window called WndProc (you can call it what you want but this is the traditional name for the main window function).

The two functions are described on separate pages for the sake of room, follow the links below

WinMain - The application entry point

WndProc - Your function to receive messages sent to your window

Conclusion

So you now have a Windows program up and running. It is quite simple in that it just shows a main window but it is the starting point for the development of pretty much every Windows application.

Advanced

There is much more you can do with the Windows API. You can create menus and dialogs using the resource editor and draw graphics using the Graphics Device Interface (GDI) commands. I have written notes below for those who wish to explore these areas further:

All these functions are useful for creating game editors etc. However to write an actual game GDI is much too slow and so instead we need to use dedicated APIs like OpenGL or the DirectX set of APIs.