Lesson 2 - Creating a basic window
In this lesson you will be introduced to the event-driven programming model. You will learn how Windows uses messages to communicate with applications, how event based programming works, what callback functions are, and while doing this create a basic windows application.
Before you begin
If you do not have the platform SDK help files (WinAPI docs), download the win32.hlp file. Though old, it is a valuable resource. Or you can download the Platform SDK form msdn.
Begin
Add the following code to main.cpp
:
/* DrawLite - Windows Programming Tutorial
* by Pravin Paratey (March 08, 2007)
*
* Source released under
* Creative Commons Attribution-Noncommercial-No Derivative Works 3.0
* http://creativecommons.org/licenses/by-nc-nd/3.0/
*/
#include <windows.h>
LRESULT CALLBACK MainWndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam);
int WINAPI
WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR lpCmdLine, int nCmdShow)
{
MSG msg;
HWND hwnd;
WNDCLASSEX wcx;
wcx.cbSize = sizeof(WNDCLASSEX); // Must always be sizeof(WNDCLASSEX)
wcx.style = CS_DBLCLKS; // Class styles
wcx.lpfnWndProc = MainWndProc; // Pointer to callback procedure
wcx.cbClsExtra = 0; // Extra bytes to allocate following the wndclassex structure
wcx.cbWndExtra = 0; // Extra bytes to allocate following an instance of the structure
wcx.hInstance = hInst; // Instance of the application
wcx.hIcon = LoadIcon(NULL, IDI_APPLICATION); // Class Icon
wcx.hCursor = LoadCursor(NULL, IDC_ARROW); // Class cursor
wcx.hbrBackground = (HBRUSH) (COLOR_WINDOW); // Background brush
wcx.lpszMenuName = NULL; // Menu Resource
wcx.lpszClassName = "DrawLite"; // Name of this class
wcx.hIconSm = LoadIcon(NULL, IDI_APPLICATION); // Small icon for this class
// Register this window class with MS-Windows
if (!RegisterClassEx(&wcx))
return 0;
hwnd = CreateWindowEx(0, //Extended window style
"DrawLite", // Window class name
"Lesson 2 - A simple win32 application", // Window title
WS_OVERLAPPEDWINDOW, // Window style
CW_USEDEFAULT, CW_USEDEFAULT, // (x,y) pos of the window
500, 400, // Width and height of the window
HWND_DESKTOP, // HWND of the parent window (can be null also)
NULL, // Handle to menu
hInst, // Handle to application instance
NULL); // Pointer to window creation data
// Check if window creation was successful
if (!hwnd)
return 0;
// Make the window visible
ShowWindow(hwnd,SW_SHOW);
// Process messages coming to this window
while (GetMessage(&msg,NULL,0,0))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
return msg.wParam;
}
LRESULT CALLBACK MainWndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
switch(msg)
{
case WM_DESTROY: // User closed the window
PostQuitMessage(0);
break;
default:
return DefWindowProc(hwnd, msg, wParam, lParam);
}
return 0;
}
{: class=“prettyprint linenums:1”}
Phew. That was long! Press F9
to compile and run. You have a basic window on your screen!
Breaking it up
Event driven programming model
Each time windows has to communicate with your application, it sends messages to your application. Once all initializations have been done and the window shown on screen, all your application has to do is poll for windows messages.
The lines up to 54 create and show the window and the lines 57-61 poll for messages.
The
GetMessage()
function gets the next message to be processed from the message queue.GetMessage()
returns a non-zero value for every message other thanWM_QUIT
. This means that the while loop continues until it is time to quit.TranslateMessage()
translates virtual key messages to character messages.DispatchMessage()
dispatches the message to a window procedure. This means that for messages coming to our window, theMainWndProc()
is called by Windows throughDispatchMessage()
.How does Windows know which function to call? Well, we tell Windows during
WNDCLASSEX
initialization {line 24}.
WNDCLASSEX structure
Every window that you create has an associated WNDCLASSEX
structure. The WNDCLASSEX
structure provides all the information necessary for Windows to do perform window related functions like drawing its icon, cursor, menu, calling the callback function which will receive messages and so on.
The WNDCLASSEX
structure is defined as,
typedef struct _WNDCLASSEX {
UINT cbSize; // This must always be set to sizeof(WNDCLASSEX)
UINT style; // This specifies the class styles. Take a look at
// your SDK documentation for the values this member can take.
WNDPROC lpfnWndProc; // Pointer to the WndProc which will handle this windows messages.
int cbClsExtra; // Number of extra bytes to allocate at the end of the WNDCLASSEX structure.
int cbWndExtra; // Number of extra bytes to allocate at the end of the window instance.
HANDLE hInstance; // Identifies the instance that the window procedure of this class is within.
HICON hIcon; // Handle to the icon associated with windows of this class.
HCURSOR hCursor; // Handle to the cursor for windows of this class.
HBRUSH hbrBackground; // Identifies the class background brush.
LPCTSTR lpszMenuName; // Identifies the menu for windows of this class.
LPCTSTR lpszClassName; // Pointer to a NULL terminated string or an atom specifying the class of this structure.
HICON hIconSm; // Handle to the small icon associated with this class.
} WNDCLASSEX;
{: class=“prettyprint”}
Registering your window class
After you’ve created your window class, you need to tell Windows about it. This is done by registering the class with windows. The function call is RegisterClassEx(..)
. Once this is done, you can create instances of this window by calling CreateWindowEx(..)
with the proper arguments.
Creating the window
A window is created by calling the CreateWindowEx(..)
defined as,
HWND CreateWindowEx(
DWORD dwExStyle, // extended window style
LPCTSTR lpClassName, // pointer to registered class name
LPCTSTR lpWindowName, // pointer to window name
DWORD dwStyle, // window style
int x, // horizontal position of window
int y, // vertical position of window
int nWidth, // window width
int nHeight, // window height
HWND hWndParent, // handle to parent or owner window
HMENU hMenu, // handle to menu, or child-window identifier
HINSTANCE hInstance, // handle to application instance
LPVOID lpParam // pointer to window-creation data
);
Lines 39-48 create the window. If the creation was successful a non-zero handle is returned by CreateWindowEx
after which ShowWindow()
shows the window on the screen.
Tip: Refer to your documentation
It is a good idea to keep referring to these functions in your SDK docs while reading this tutorial.
Callback functions
A callback function is the one that receives the messages sent to your application. This is where you do something about the message. We provide a pointer to this function while defining the window class {line 18}.
Callback functions have to be defined as,
LRESULT CALLBACK function-name(
HWND hwnd, // Handle of window which received this message
UINT msg, // The message
WPARAM wParam, // Extra information
LPARAM lParam // Extra information
);
{: class=“prettyprint”}
- HWND hwnd
- The handle of the window is specified so that you know which window to act upon. This is necessary because you may have created more than one instance of the window.
- UINT msg
- This contains the message sent.
- WPARAM wParam and WPARAM lParam
- wParam and lParam are used to pass extra info about the message. For example a WM_LBUTTONDOWN (left mouse button down) message will have the x and y co-ordinates as the upper and lower word of lParam and wParam will tell if any modifier keys (ctrl, alt, shift) have been pressed.
MainWndProc
LRESULT CALLBACK MainWndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
switch (msg)
{
...
{: class=“prettyprint linenums:66”}
The switch statement lets us select which message was sent. There are over 200 messages that windows can send your application. To read about them, just search for WM_
in your SDK docs.
WM_DESTROY
...
case WM_DESTROY: // User closed the window
PostQuitMessage(0);
break;
...
{: class=“prettyprint linenums:69”}
The WM_DESTROY
message is sent to your application when the user teminates the application either by clicking the X at the upper right corner, pressing Alt+F4, or quits the application by other means.
PostQuitMessage()
causes GetMessage(..)
{line 57} to return false and thus breaking out of the while loop and exiting the application. The argument to PostQuitMessage
is the return value to the system.
DefWindowProc(..)
What about the other 200 or so messages? Surely you, the programmer, aren’t going to write code for all the 200 messages. Fortunately, Windows provides the DefWindowProc(..)
function which handles all the messages. For the purposes of displaying a simple window, your MainWndProc could very well have consisted of,
LRESULT CALLBACK MainWndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
return DefWindowProc(hwnd, msg, wParam, lParam);
}
What this means is that every time you want to do something about a message, add the case switch for the message and write the code which does something about it. All messages that you don’t want to handle should be passed to the DefWindowProc()
. This is what we have done in our code.
...
default: // Call the default window handler
return DefWindowProc(hwnd,msg,wParam,lParam);
...
{: class=“prettyprint linenums:72”}
## C++ is about classes
Before we go any further, let’s organize that code into classes. This helps us manage our code better. Add a new file to the project and name it MainWindow.h
. Add the following code to it:
/* DrawLite - Windows Programming Tutorial
* by Pravin Paratey (March 08, 2007)
*
* Source released under
* Creative Commons Attribution-Noncommercial-No Derivative Works 3.0
* http://creativecommons.org/licenses/by-nc-nd/3.0/
*/
#include <windows.h>
class MainWindow
{
public:
MainWindow(HINSTANCE hInstance);
~MainWindow();
static LRESULT CALLBACK MainWndProc (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam);
bool Run(int nCmdShow);
private:
WNDCLASSEX m_wndClass;
static HINSTANCE m_hInstance;
HWND m_hwnd;
static char m_szClassName[];
};
{: class=“prettyprint linenums:1”}
Next, add another file called MainWindow.cpp
with the following code:
/* DrawLite - Windows Programming Tutorial
* by Pravin Paratey (March 08, 2007)
*
* Source released under
* Creative Commons Attribution-Noncommercial-No Derivative Works 3.0
* http://creativecommons.org/licenses/by-nc-nd/3.0/
*/
#include <windows.h>
#include "MainWindow.h"
char MainWindow::m_szClassName[] = "DrawLite";
MainWindow::MainWindow(HINSTANCE hInstance)
{
m_hInstance = hInstance; // Save Instance handle
m_wndClass.cbSize = sizeof(WNDCLASSEX); // Must always be sizeof(WNDCLASSEX)
m_wndClass.style = CS_DBLCLKS; // Class styles
m_wndClass.lpfnWndProc = MainWndProc; // Pointer to callback procedure
m_wndClass.cbClsExtra = 0; // Extra bytes to allocate following the wndclassex structure
m_wndClass.cbWndExtra = 0; // Extra bytes to allocate following an instance of the structure
m_wndClass.hInstance = hInstance; // Instance of the application
m_wndClass.hIcon = LoadIcon(NULL, IDI_APPLICATION); // Class Icon
m_wndClass.hCursor = LoadCursor(NULL, IDC_ARROW); // Class cursor
m_wndClass.hbrBackground = (HBRUSH) (COLOR_WINDOW); // Background brush
m_wndClass.lpszMenuName = NULL; // Menu Resource
m_wndClass.lpszClassName = m_szClassName; // Name of this class
m_wndClass.hIconSm = LoadIcon(NULL, IDI_APPLICATION); // Small icon for this class
}
MainWindow::~MainWindow()
{
}
LRESULT CALLBACK MainWindow::MainWndProc (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
switch (msg)
{
case WM_DESTROY:
PostQuitMessage (0);
break;
default:
return DefWindowProc (hwnd, msg, wParam, lParam);
}
return 0;
}
bool MainWindow::Run(int nCmdShow)
{
if(!RegisterClassEx(&m_wndClass))
return false;
m_hwnd = CreateWindowEx(
0,
m_szClassName,
"Draw Lite",
WS_OVERLAPPEDWINDOW,
CW_USEDEFAULT,
CW_USEDEFAULT,
500,
400,
NULL,
NULL,
m_hInstance,
NULL
);
if(!m_hwnd)
return false;
ShowWindow(m_hwnd, nCmdShow);
return true;
}
{: class=“prettyprint linenums:1”}
Next change main.cpp
to look like so:
/* DrawLite - Windows Programming Tutorial
* by Pravin Paratey (March 08, 2007)
*
* Source released under
* Creative Commons Attribution-Noncommercial-No Derivative Works 3.0
* http://creativecommons.org/licenses/by-nc-nd/3.0/
*/
#include <windows.h>
#include "MainWindow.h"
int WINAPI
WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR lpCmdLine, int nCmdShow)
{
MSG msg;
MainWindow *winMain = new MainWindow(hInst);
if(!winMain->Run(nCmdShow))
{
delete winMain;
return 1; // error
}
// Run the message loop. It will run until GetMessage() returns 0
while (GetMessage (&msg, NULL, 0, 0))
{
// Translate virtual-key messages into character messages
TranslateMessage(&msg);
// Send message to WindowProcedure
DispatchMessage(&msg);
}
delete winMain;
return msg.wParam;
}
{: class=“prettyprint linenums:1”}
Adding Functionality
Lets pop up a message box which will display the co-ordinates of the point where the left mouse button was pressed. To do this you will have to handle the WM_LBUTTONDOWN message.
Add this code to MainWindow.cpp
at line 44
...
PostQuitMessage(0);
break;
case WM_LBUTTONDOWN:
char str[256];
POINT pt;
pt.x = LOWORD(lParam);
pt.y = HIWORD(lParam);
wsprintf(str,"Co-ordinates are\nX=%i and Y=%i",pt.x,pt.y);
MessageBox(hwnd, str, "Left Button Clicked", MB_OK);
break;
default:
...
{: class=“prettyprint linenums:41”}
Press F9. This is what you should see when you click anywhere inside the window.
Exercise
Try this exercise. Pop up a message every time a key is pressed on the keyboard. Hint: Handle the WM_CHAR message. Remember to refer to your SDK docs.If you could manage that, give yourself a pat on the back. You now understand the basics of event-driven programming - the mechanism which Windows uses to communicate with your application. You have crossed one of the more difficult hurdles in learning windows programming.
Don’t worry if you could not do the exercise or if things are still a bit hazy. These concepts will be used in every single lesson after this and it will soon become second nature to you.