Example: simple_window
Sometimes people come on IRC and ask "How do I make a window?"...Well it's not entirely that simple I'm afraid. It's not difficult once you know what you're doing but there are quite a few things you need to do to get a window to show up; And they're more than can be simply explained over a chat room, or a quick note.I always liked to do things first and learn them later...so here is the code to a simple window which will be explained shortly.
#include <windows.h> const char g_szClassName[] = "myWindowClass"; // Step 4: the Window Procedure LRESULT CALLBACK WndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) { switch(msg) { case WM_CLOSE: DestroyWindow(hwnd); break; case WM_DESTROY: PostQuitMessage(0); break; default: return DefWindowProc(hwnd, msg, wParam, lParam); } return 0; } int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) { WNDCLASSEX wc; HWND hwnd; MSG Msg; //Step 1: Registering the Window Class wc.cbSize = sizeof(WNDCLASSEX); wc.style = 0; wc.lpfnWndProc = WndProc; wc.cbClsExtra = 0; wc.cbWndExtra = 0; wc.hInstance = hInstance; wc.hIcon = LoadIcon(NULL, IDI_APPLICATION); wc.hCursor = LoadCursor(NULL, IDC_ARROW); wc.hbrBackground = (HBRUSH)(COLOR_WINDOW+1); wc.lpszMenuName = NULL; wc.lpszClassName = g_szClassName; wc.hIconSm = LoadIcon(NULL, IDI_APPLICATION); if(!RegisterClassEx(&wc)) { MessageBox(NULL, "Window Registration Failed!", "Error!", MB_ICONEXCLAMATION | MB_OK); return 0; } // Step 2: Creating the Window hwnd = CreateWindowEx( WS_EX_CLIENTEDGE, g_szClassName, "The title of my window", WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT, 240, 120, NULL, NULL, hInstance, NULL); if(hwnd == NULL) { MessageBox(NULL, "Window Creation Failed!", "Error!", MB_ICONEXCLAMATION | MB_OK); return 0; } ShowWindow(hwnd, nCmdShow); UpdateWindow(hwnd); // Step 3: The Message Loop while(GetMessage(&Msg, NULL, 0, 0) > 0) { TranslateMessage(&Msg); DispatchMessage(&Msg); } return Msg.wParam; }For most part this is the simplest windows program you can write that actually creates a functional window, a mere 70 or so lines. If you got the first example to compile then this one should work with no problems.
A Window Class has NOTHING to do with C++ classes.
const char g_szClassName[] = "myWindowClass";The variable above stores the name of our window class, we will use it shortly to register our window class with the system.
WNDCLASSEX wc;
wc.cbSize = sizeof(WNDCLASSEX); wc.style = 0; wc.lpfnWndProc = WndProc; wc.cbClsExtra = 0; wc.cbWndExtra = 0; wc.hInstance = hInstance; wc.hIcon = LoadIcon(NULL, IDI_APPLICATION); wc.hCursor = LoadCursor(NULL, IDC_ARROW); wc.hbrBackground = (HBRUSH)(COLOR_WINDOW+1); wc.lpszMenuName = NULL; wc.lpszClassName = g_szClassName; wc.hIconSm = LoadIcon(NULL, IDI_APPLICATION); if(!RegisterClassEx(&wc)) { MessageBox(NULL, "Window Registration Failed!", "Error!", MB_ICONEXCLAMATION | MB_OK); return 0; }
This is the code we use in WinMain()
to register our window class.
We fill out the members of a WNDCLASSEX
structure and call
RegisterClassEx()
.
The members of the struct affect the window class as follows:
cbSize
style
CS_*
), not to be confused with Window Styles (WS_*
) This can usually be set to 0
.
lpfnWndProc
cbClsExtra
0
.
cbWndExtra
0
.
hInstance
WinMain()
).
hIcon
hCursor
hbrBackground
lpszMenuName
lpszClassName
hIconSm
We then call RegisterClassEx()
and check for failure, if it fails we pop up a message
which says so and abort the program by returning from the WinMain()
function.
Once the class is registered, we can create a window with it. You should look
up the paramters for CreateWindowEx()
(as you should ALWAYS do when using a new API call),
but I'll explain them briefly here.
HWND hwnd;
hwnd = CreateWindowEx( WS_EX_CLIENTEDGE, g_szClassName, "The title of my window", WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT, 240, 120, NULL, NULL, hInstance, NULL);
The first parameter (WS_EX_CLIENTEDGE
) is the extended windows style, in this
case I have set it to give it a sunken inner border around the window. Set it
to 0
if you'd like to see the difference. Also play with other values to
see what they do.
Next we have the class name (g_szClassName
), this tells the system what kind
of window to create. Since we want to create a window from the class we just registered,
we use the name of that class. After that we specify our window name or title
which is the text that will be displayed in the Caption, or Title Bar on our window.
The parameter we have as WS_OVERLAPPEDWINDOW
is the Window Style parameter.
There are quite a few of these and you should look them up and experiment to
find out what they do. These will be covered more later.
The next four parameters (CW_USEDEFAULT, CW_USEDEFAULT, 320, 240
) are the
X and Y co-ordinates for the top left corner of your window, and the width
and height of the window. I've set the X and Y values to CW_USEDEFAULT
to let windows choose
where on the screen to put the window. Remeber that the left of the screen is an
X value of zero and it increases to the right; The top of the screen is a Y value
of zero which increases towards the bottom. The units are pixels, which is
the smallest unit a screen can display at a given resolution.
Next (NULL, NULL, g_hInst, NULL
) we have the Parent Window handle,
the menu
handle, the application instance handle, and a pointer to window creation data.
In windows, the windows on your screen are arranged in a heirarchy of parent and child
windows. When you see a button on a window, the button is the Child and it is contained within
the window that is it's Parent.
In this example, the parent handle is NULL
because we have no parent, this is our main or Top Level window.
The menu is NULL
for now since we don't have one yet. The instance handle is
set to the value that is passed in as the first parameter to WinMain()
. The
creation data (which I almost never use) that can be used to send additional data to the
window that is being created is also NULL
.
If you're wondering what this magic NULL
is, it's simply defined as 0
(zero). Actually, in C it's defined as ((void*)0)
, since it's intended for
use with pointers. Therefore you will possibly get warnings if you use NULL for integer
values, depending on your compiler and the warning level settings. You can choose to ignore
the warnings, or just use 0
instead.
Number one cause of people not knowing what the heck is wrong with their programs is probably
that they didn't check the return values of their calls to see if they failed or not.
CreateWindow()
will fail at some point even if you're an experianced
coder, simply because there are lots of mistakes that are easy to make. Untill you learn
how to quickly identify those mistakes, at least give yourself the chance of figuring out
where things go wrong, and Always check return values!
if(hwnd == NULL) { MessageBox(NULL, "Window Creation Failed!", "Error!", MB_ICONEXCLAMATION | MB_OK); return 0; }
After we've created the window and checked to make sure we have a valid handle
we show the window, using the last parameter in WinMain()
and then update it to
ensure that it has properly redrawn itself on the screen.
ShowWindow(hwnd, nCmdShow); UpdateWindow(hwnd);
The nCmdShow
parameter is optional, you could simply pass in SW_SHOWNORMAL
all the time and be done with it. However using the parameter passed into WinMain()
gives
whoever is running your program to specify whether or not they want your window to start off
visible, maximized, minimized, etc... You will find options for these in the properties of
windows shortcuts, and this parameter is how the choice is carried out.
This is the heart of the whole program, pretty much everything that your program does passes through this point of control.
while(GetMessage(&Msg, NULL, 0, 0) > 0) { TranslateMessage(&Msg); DispatchMessage(&Msg); } return Msg.wParam;
GetMessage()
gets a message from your application's message queue. Any time the user
moves the mouse, types on the keyboard, clicks on your window's menu, or does any
number of other things, messages are generated by the system and entered into your
program's message queue. By calling GetMessage()
you are requesting the next
available message to be removed from the queue and returned to you for processing. If there
is no message, GetMessage()
Blocks. If you are unfamiliar with the term, it
means that it waits untill there is a message, and then returns it to you.
TranslateMessage()
does some additional processing on keyboard
events like generating WM_CHAR
messages to go along with WM_KEYDOWN
messages.
Finally DispatchMessage()
sends the message out to the window that the
message was sent to. This could be our main window or it could be another one, or a control,
and in some cases a window that was created behind the scenes by the sytem or another program.
This isn't something you need to worry about because all we are concerned with is that
we get the message and send it out, the system takes care of the rest making sure it
gets to the proper window.
LRESULT CALLBACK WndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) { switch(msg) { case WM_CLOSE: DestroyWindow(hwnd); break; case WM_DESTROY: PostQuitMessage(0); break; default: return DefWindowProc(hwnd, msg, wParam, lParam); } return 0; }
The window procedure is called for each message, the HWND
parameter is
the handle of your window, the one that the message applies to. This is important
since you might have two or more windows of the same class and they will use the
same window procedure (WndProc()
). The difference is that the parameter
hwnd
will be different depending on which window it is. For example when
we get the WM_CLOSE
message we destroy the window. Since we use the window handle
that we received as the first paramter, any other windows will not be affected, only the
one that the message was intended for.
WM_CLOSE
is sent when the user presses the Close Button
or types Alt-F4. This will cause the window
to be destroyed by default, but I like to handle it explicitly, since this is the perfect
spot to do cleanup checks, or ask the user to save files etc. before exiting the program.
When we call DestroyWindow()
the system sends the WM_DESTROY
message to the window getting destroyed, in this case it's our window, and then destroys
any remaining child windows before finally removing our window from the system. Since this
is the only window in our program, we are all done and we want the program to exit, so we
call PostQuitMessage()
. This posts the WM_QUIT
message to the
message loop. We never receive this message, because it causes GetMessage()
to return FALSE
, and as you'll see in our message loop code, when that happens
we stop processing messages and return the final result code, the wParam
of
WM_QUIT
which happens to be the value we passed into PostQuitMessage()
.
The return value is only really useful if your program is designed to be called by another program
and you want to return a specific value.
Phew. Well that's it! If I haven't explained stuff clearly enough yet, just hang in there and hopefully things will become more clear as we get into more usefull programs.