Annotation

At first glance, it may seem like I’m reinventing the wheel; Windows
already comes with a very complex, very functional GUI. Unfortunately, while
the Windows GUI is great for office apps, quite frequently, it’s not suited for
many games. Games tend to want a more precise control over the GUI than
Windows can provide (for example, games may want to use alpha-blending to
implement partially transparent windows - easy if you’ve written your own GUI,
but next to impossible using the Windows GUI).
This article will walk you though how to create a GUI using C++ and
DirectX. The series is divided into several parts, each dealing with a specific
aspect of GUI programming:
Part I: The Basics, and the Mouse
Part II: Windows
Part III: Controls
Part IV: Resource Editors and Other Madness
NOTE: This document was originally four separate articles on
www.gamedev.net. I’ve concatenated all four into one for the XGDC, but they
remain otherwise unchanged. - Mason

Mason McCuskey
Part I: The Basics, and the Mouse

Start with the basics - The Rendering Loop

The Mouse
Part II: Windows

The Design
The Plan
The Implementation
Window Management Code
Coordinate Systems
Window Drawing Code
Window Messages
Wrapping It Up
Part III: Implementing Controls
 GUI Controls We’ll Need
Breaking It Down: Complex Controls As Combinations of Simple
Ones
The Static Controls

Pushbutton Controls
Carets and The Textbox Control
Progress Bars
Sliders and Scrollbars

The Listbox Control

Part IV: Resource Editors and Other Madness

Saving Windows
Loading Windows
Resource Editors
Subclassing
Speeding up GUI Rendering
Conclusion
Mason McCuskey
Developing a GUI in C++ and DirectX
Part I: The Basics, and the Mouse
Before I get started, I want to throw out a disclaimer: I’m going to outline
the approach I used when I created the GUI system for my upcoming title,
Quaternion. Treat this text as one solution to a very intricate problem, nothing
more. I’m not saying that this way of making a GUI is the fastest or easiest way;
I’m simply outlining a solution that worked for me. Also, this text is not
complete. Like one of those Bob-Vila TV episodes, it skips over the easy stuff
and concentrates on the interesting. There is no attached source file; there are
code snippets in the text, and that’s it. In that code, I’ve stripped out a lot of
layers of indirection that aren’t relevant to what I’m trying to show (i.e. the
wrappers that you’d probably have for your DirectX functions, non-relevant
initialization and cleanup code, etc). Also, beware of bugs - I’ve done lots of bug
checking, but I’m only human. If you find a bug, please let me know about it by
emailing mason@spin-studios.com.
I’m making several assumptions about your knowledge. I’m assuming you
know the basics of how event-driven programming works (message queues, etc),
and I’m assuming you have a strong grasp of PDL (the commenting language - if
you don’t know what this is, read Code Complete, by Steve McConnell), and
C++. I used C++ to implement my GUI system, because I’m a card-carrying
member of the C++ fan club, and because the OOP of C++ work great for
implementing window and control types. Shameless plug for the C++ language:
Note the power of OOP in this solution, and ask yourself if you could do the
same thing as easily in C.
Let’s start by defining our scope. It’s important to realize up front that we’re
not remaking Windows 95, we’re just trying to get a simple GUI up for a game,
so we don’t have to implement every single control and GUI construct. We only
need a few parts for this simple GUI: a mouse pointer, a generic window, and
some dialog controls to place within that window. We’re also going to need a
resource editor, a program that will allow us to design dialogs by graphically
dropping controls at various places.
Start with the basics - The Rendering Loop
I’m going to start at the top, by defining a function that will calculate and
draw one frame of our GUI system. Let’s call this function RenderGUI(). In
PDL, RenderGUI does something like this:
void CApplication::RenderGUI(void) {
// get position and button status of mouse cursor
// calculate mouse cursor’s effects on windows / send messages
// render all windows
// render mouse
// flip to screen
}
Pretty straightforward for now. Basically, we grab the new position and
status of the mouse cursor, calculate any changes that are caused by the new
position, render all our windows, render the mouse cursor, then push the whole
thing to the screen.
The Mouse
Now that we’ve got a main function, we’re going to create a mouse class.
This mouse class will initialize the rodent, and will be responsible for querying
its position and storing the results. Here’s the definition:
class CMouse {
public:
CMouse(); // boring
~CMouse(); // boring

int Init(LPDIRECTINPUT di); // we’ll talk about this later

int Refresh(void); // we’ll talk about this later

int GetButton(int index) {

if (index ‹ 0 || index › NUMMOUSEBUTTONS) return(0);
return(m_button[index]);
}

CPoint GetPosition(void) { return(m_position); }

enum { NUMMOUSEBUTTONS = 3 }; // three button mouse

private:
LPDIRECTINPUTDEVICE m_mousedev;
char m_button[NUMMOUSEBUTTONS]; // state of buttons
CPoint m_position; // actual screen position
};
Pretty straightforward class definition. We’ve got two data pieces, m_button
and m_position, abstracted by two functions, GetButton and GetPosition(). Then
we’ve got Init and Refresh functions, which initialize the mouse and Refresh its
button and position information. The m_mousedev is an interface to our mouse
device; we get this interface during Init(), and use it in Refresh to communicate
with DirectInput.
So… before we go any further with CMouse, let’s look at the code to
initialize DirectInput. Note that this code doesn’t belong in our CMouse::Init()
routine; the DirectInput pointer is used by the entire game, not just the mouse, so
the code that inits DirectInput should go in your main init function - the same
time you init DirectDraw, DirectSound, etc. A DirectInput interface pointer is
different than a DirectInput device pointer; you use DirectInput pointers to get
DirectInputDevice pointers.
Here’s the code to initialize the master DirectInput interface pointer:
LPDIRECTINPUT di = NULL;
 hr = DirectInputCreate(hinst, DIRECTINPUT_VERSION, &di, NULL);
if (FAILED(hr)) {
// error processing
}
That will put a valid DirectInput interface pointer into di. (Don’t forget to
Release() it when your game ends!)
Now that we’ve got a DirectInput interface, let’s begin fleshing out our
CMouse by implementing CMouse::Init().
bool CMouse::Init(LPDIRECTINPUT di) {
// Obtain an interface to the system mouse device.
hr = di-›CreateDevice(GUID_SysMouse,
(LPDIRECTINPUTDEVICE*)&di_mouse, NULL);
if (FAILED(hr)) {/* handle errors! */}

// Set the data format to "mouse format".

hr = m_mousedev-›SetDataFormat(&c_dfDIMouse);
if (FAILED(hr)) {/* handle errors! */}

// Set the cooperativity level

hr = m_mousedev-›SetCooperativeLevel(hwnd, DISCL_NONEXCLUSIVE |
DISCL_FOREGROUND);
if (FAILED(hr)) {/* handle errors! */}
}
That code does three important things. First, it gets a valid DirectInput
mouse device interface, and puts it in di_mouse. Next, it sets the data format and
the cooperative level for the device, basically letting windows know that we
want to query the device as if it were a mouse, and that we don’t want to take
exclusive ownership of it. (Exclusive ownership means that we’re the only app
that can use the mouse - by specifying DISCL_NONEXCLUSIVE, we’ve told
Windows that we’re going to be sharing the mouse with other applications.)
Now let’s flesh out CMouse::Refresh(), the function responsible for
updating the CMouse’s internal button state and position variables. Here’s the
code.
void CMouse::Refresh(void) {
C done = 0;
int q;
HRESULT hr;
POINT p;
DIMOUSESTATE dims;

if (!m_di) return;

// clear our struct - eventually, directinput will fill this in

memset(&dims, 0, sizeof(DIMOUSESTATE));
 if (!m_mousedev) return; // we don’t have a pointer! Bail!

while (!done) {
hr = m_mousedev-›GetDeviceState(sizeof(DIMOUSESTATE), &dims);
if (FAILED(hr)) {
if (hr == DIERR_INPUTLOST || hr == DIERR_NOTACQUIRED) {
// device lost… reacquire
hr = m_mousedev-›Acquire();
if (FAILED(hr)) {
// houston, we have a problem… clear & bail
clear();
done=1;
}
} else {
// it’s some other error - clear and bail!
m_mousedev.clear();
done = 1;
}
} else // read mouse successfully!
{
done = 1;
}
} //while !done

m_position.z += dims.lZ;

if (m_vga-›isfullscreen()) {
// we're in fullscreen, so this is easy… just copy the coords
m_position.x += dims.lX;
m_position.y += dims.lY;
} else {
// we're in window mode, so this is not-so-easy…
// grab the relative mouse position
GetCursorPos(&p);
ScreenToClient((HWND)m_vga-›gethwnd(), &p);

if (p.x ‹ 0 || p.y ‹ 0) {
// the cursor is out of our window! "hide" it!
m_mousedev.setposition(KJM_AXES_X,
m_vga-›getscreendims().getwidth());
m_mousedev.setposition(KJM_AXES_Y,
m_vga-›getscreendims().getheight());
} else {
m_mousedev.setposition(KJM_AXES_X, p.x);
m_mousedev.setposition(KJM_AXES_Y, p.y);
}
}
 m_mousedev.constrainpos(KJM_AXES_X, 0,
m_vga-›getscreendims().getwidth());
m_mousedev.constrainpos(KJM_AXES_Y, 0,
m_vga-›getscreendims().getheight());

for (q=0; q ‹ KJM_NUMMOUSEBUTTONS; q++) {

m_mousedev.setbutton(q, (dims.rgbButtons[q] & 0x80));
}
}
Part II: Windows
We’ll be using C++ heavily here. If you’re rusty on pure virtual functions,
dynamic_cast’ing, etc., grab a C++ book and brush up before continuing.
The Design
Before we dive into code, it’s important to make a blueprint of what we’re
aiming for.
In the finished GUI of our game, we’ll use a tree to keep track of every
window displayed on the screen. The window tree is a simple n-node tree. At the
root of the tree is the Windows Desktop (or, if you’re in X, the “root window” -
now you know why they call it that). The children of the Desktop window are
(usually) main windows; their children are dialog boxes, and the dialog boxes’
children are the individual dialog controls (buttons, textboxes, etc). An important
distinction - the appearance of a window is NOT determined by its place in the
tree. For example, many games place buttons directly on their desktop windows,
as well as in dialogs.
And yes, buttons are windows too. This is a very important frame of mind.
A button is just a window with a funny appearance. In fact, all of the GUI
controls are simply windows with different appearances. This is where the power
of C++ comes in. If we create a generic window class, and give it a few virtual
functions, we can then easily create our different controls by overriding the base
window class’s behavior. This use of polymorphism is extremely elegant; so
elegant, in fact, that many C++ books use it as an example. (I’ll talk more about
this in Part III.)
That’s our basic design, now, let’s work through an implementation
strategy…
The Plan
I took the following steps when I implemented my GUI:
1) First I coded some basic window management code. This chunk of code
is responsible for the window tree, adding / deleting windows (i.e., new’ing and
deleting window pointers), showing / hiding them, moving them to the top of the
Z-Order, etc. I stubbed out the window drawing procedure by simply drawing
rectangles where my windows should be, then drawing a number in the top-left
corner of them to indicate their z-order.
Understand up front that your life will become tremendously easier if you
buy or make a good, solid, template class for arrays of pointers. The STL
(Standard Template Library) that ships with most versions of C++ has several
good template-able pointer array classes, but if you want to make your own, do it
formally - test it thoroughly and completely before you start implementing your
window manager. The last things you need right now are subtle memory leaks or
null pointer references caused by a shoddy array class.
2) Once I had basic window management functions, I spent some time
thinking about my coordinate systems. Coded up some ClientToScreen()
functions, and some other misc. stuff.
3) Next, I tackled the window drawing code. I derived a “fancy window”
class, and showed it how to draw itself using a set of nine sprites - four sprites
for the corners, four sprites for the edges, and one sprite for the background (see
diagram) ‹‹DIAGRAM››.
Using nine window sprites, it’s possible to create windows that sport a
unique, artistic appearance, and yet are still dynamically re-sizeable (ala
StarDock’s WindowBlinds). The downside to this is that you’ll need a fairly
smart drawing library, one that can handle tiling sprites, stretching them, and
centering them, as well as a very complex window creation program (something
the artists can use to construct their windows), to really make this method work
well. And, of course, you’ll pay in window drawing speed, too.
4) Once the drawing code for the generic window was complete, I started
implementing the controls. Coding controls is straightforward, but again,
requires very thorough testing. I started with the simple controls: statics, icons,
etc., and worked my way up from there, as explained earlier.
5) Finally, after all of my controls were complete, I coded up a simple
Resource Editor, a program that allows someone to graphically place controls
and layout dialog boxes. The resource editor took me a good month to do, but I
highly suggest doing it (instead of just using text files to position stuff) - it’s
much easier to create dialog boxes graphically, and it was a good exercise:
during development I uncovered several bugs in my controls’ code, things that
would have proven very difficult to catch in the actual game.
I toyed, for a very long time, with the idea of creating a program that would
convert an MSVC++ resource (.RC) file into a custom resource file useable by
my GUI. In the end, I decided such a program would be more trouble than what
it would be worth. The whole reason I was writing a GUI was to get away from
the confines of Windows, and to truly do that, I needed my own editor, tied to
my own resource file format and my own way of doing things. I decided to
implement a WYSIWYG Resource Editor in MFC from the ground up. My
needs, my decision; your needs may be different. If anyone out there tries to
write a converter, I’d love to hear about it.
So… let’s start with step one: basic window management functions.
The Implementation
Here we go. Here’s a good start for our base-class window definition:
class gui_window {
public:
gui_window(); // boring
virtual ~gui_window(); // boring
virtual void init(void); // boring
gui_window *getparent(void) { return(m_pParent); }

/////////////
// section I: window management controls
/////////////

int addwindow(gui_window *w);

int removewindow(gui_window *w);

void show(void) { m_bIsShown = true; }

void hide(void) { m_bIsShown = false; }
bool isshown(void) { return(m_bIsShown); }
void bringtotop(void);
bool isactive(void);

/////////////
// Section II: coordinates
/////////////

void setpos(coord x1, coord y1); // boring

void setsize(coord width, coord height); // boring

void screentoclient(coord& x, coord& y);

int virtxtopixels(coord virtx); // convert GUI units to actual

pixels
int virtytopixels(coord virty); // ditto

virtual gui_window *findchildatcoord(coord x, coord y, int

flags = 0);

/////////////
// Section III: Drawing Code
/////////////

// renders this window + all children recursively

 int renderall(coord x, coord y, int drawme = 1);

gui_wincolor& getcurrentcolorset(void) { return(isactive() ?

m_activecolors : m_inactivecolors); }

/////////////
// Messaging stuff to be discussed in later Parts
/////////////

int calcall(void);

virtual int wm_paint(coord x, coord y);

virtual int wm_rendermouse(coord x, coord y);
virtual int wm_lbuttondown(coord x, coord y);
virtual int wm_lbuttonup(coord x, coord y);
virtual int wm_ldrag(coord x, coord y);
virtual int wm_lclick(coord x, coord y);
virtual int wm_keydown(int key);
virtual int wm_command(gui_window *win, int cmd, int param) {
return(0); };
virtual int wm_cansize(coord x, coord y);
virtual int wm_size(coord x, coord y, int cansize);
virtual int wm_sizechanged(void) { return(0); }
virtual int wm_update(int msdelta) { return(0); }

protected:

virtual void copy(gui_window& r); // deep copies one window to

another

gui_window *m_pParent;
uti_pointerarray m_subwins;
uti_rectangle m_position;

// active and inactive colorsets

gui_wincolor m_activecolor;
gui_wincolor m_inactivecolor;

// window caption
uti_string m_caption;
};
First of all, notice the virtual destructor on the window class. This may not
seem like it’s needed just yet, but we’ll eventually be deriving controls from this
class, so it’s important that it have a virtual destructor.

As you peruse the functions we’ll be talking about, keep in mind that
recursion is everywhere. For example, our game will be drawing the entire GUI
system by making a call to the renderall() method of the root window, which will
in turn call the renderall() methods of its subwindows, which will call renderall()
for their subwindows, and so on. Most of the functions follow this recursive
pattern.

The whole GUI system will be contained within one global static variable -
the root window. To be on the safe side, I encapsulated this variable within a
global GetDesktop() function.

Also, notice that the class definition is rife with virtual keywords. This is
where C++’s polymorphism is working for us. Need to change how certain types
of windows (or controls - say, buttons) deal with a “left mouse button has just
been pushed down” event? Simple, derive a class from the base window and
override its wm_lbuttondown() method. The system will automatically call the
derived class’s method where appropriate; behold the power of C++.

Now that we’ve got the header, let’s start filling in some functions, starting
with the Window Management code…
Window Management Code
/**************************************************************************
addwindow: adds a window to this window's subwin array
***************************************************************************
int gui_window::addwindow(gui_window *w) {
if (!w) return(-1);
// only add it if it isn't already in our window list.
if (m_subwins.find(w) == -1) m_subwins.add(w);
w-›setparent(this);
return(0);
}

/**************************************************************************
removewindow: removes a window from this window's subwin array
***************************************************************************
int gui_window::removewindow(gui_window *w) {
w-›setparent(NULL);
return (m_subwins.findandremove(w));
}

/**************************************************************************
bringtotop: bring this window to the top of the z-order. the
top of the
z-order is the HIGHEST index in the subwin array.
***************************************************************************
void gui_window::bringtotop(void) {
if (m_parent) {
// we gotta save the old parent so we know who to add back to
gui_window *p = m_parent;
p-›removewindow(this);
p-›addwindow(this);
}
}

/**************************************************************************
isactive: returns true if this window is the active one (the
one with input focus).
***************************************************************************
bool gui_window::isactive(void) {
if (!m_parent) return(1);
if (!m_parent-›isactive()) return(0);
return(this ==
m_parent-›m_subwins.getat(m_parent-›m_subwins.getsize()-1));
}
This set of functions deals with what I call window management; adding
windows, deleting them, showing/hiding them, and changing their z-order. All of
these are really just array operations; this is where your array class gets a
workout.
The only thing interesting in the add / remove window functions is the
question, “who is responsible for the window pointer?” This is always a good
question to ask yourself in C++. Addwindow and removewindow both take
pointers to a window class. This means that to create a new window, your code
news it, then passes the pointer to the parent (desktop) window through
addwindow(). So who’s responsible for deleting the pointer you newed?
My answer was “the GUI doesn’t own the window pointers; the game itself
is responsible for adding them.” This is consistent with the C++ rule of thumb
that says “those who new things also delete them.”
The alternative to the method I chose was to say “the parent window is
responsible for the pointers of all his child windows.” That would mean that to
prevent memory leaks, each window must, in it’s (virtual) destructor (remember,
there’s derived classes), loop through its m_subwindows array and delete all of
the windows contained within it.
If you decide to implement a GUI-owns-pointer system, be aware of an
important trade-off - all of your windows must be dynamically allocated
(newed). A quick way to crash a system like that is to pass in the address of a
variable on the stack, i.e. say something like “addwindow(&mywindow)”, where
mywindow is declared as a local variable on the stack. Things will work until
mywindow goes out of scope, or until the destructor for the parent window is
called, whereupon it’ll try to delete that address and all hell will break loose. The
lesson is “be extra careful with pointers.”
That’s the main reason behind why I decided that my GUI would not own
the window pointer. If you’re passing a lot of complex window classes into and
out of your GUI (say, for example, you’re populating a tabbed property sheet),
you might prefer a system where the GUI doesn’t keep track of the pointers, and
where remove simply means “the pointer is now in my control; remove it from
your array, but don’t delete it.” This would also allow you to (carefully) use
addresses of local variables on the stack, provided you made sure that you
removewindow()’ed them before they went out of scope.
Moving on… Showing and hiding windows is accompished through a
boolean variable. Showwindow() and hidewindow() simply set or clear this
variable; the window drawing and message processing functions check this “is
window shown” flag before they do anything. Pretty easy stuff.
Z-ordering was also fairly easy. For those unfamiliar with the term, z-
ordering refers to the “stacking” of windows on top of each other. At first
thought, you may decide to implement z-ordering similar to how DirectDraw
does it for overlays - you might decide to give each window an integer that
describes its absolute z-order position, their place on the z axis - say, maybe, 0 is
the top of the screen, and negative -1000 is furthest back. I thought a bit about
implementing this type of z-ordering, but decided against it - absolute z-order
positions don’t concern me; I care more about relative z-order positions. That is,
I don’t really need to know “how far back” one window is from another; I
simply need to know whether a given window is behind another, or in front of it.
So, I decided to implement z-order like this: The window with the highest
index in the array, m_subwins, would be the window “on top.” The window at
[size-1] would be directly under it, followed by [size-2], etc. The window at
position [0] would be on the very bottom. In this way, processing z-ordering
became very easy. Also, killing two birds with one stone, I deemed that the
topmost window would always be the active window, or more technically, the
window with input focus. Although this restricted my GUI from making “always
on top” windows (for example: Windows NT’s task manager is always on top of
all other windows, regardless of who has the input focus), I felt it was worth it to
keep the code as simple as possible.
Also, I paid a small price for using array indices as z-orders was the array
shuffle that occurs when I tell a given window to move to the top of the z-order.
Say I tell window #2 to move to the top of a 50 window list; I’ve got to shift 48
windows down a slot to accommodate window #2’s new position at the end. The
good news is that moving a window to top of the z-order isn’t really a time-
critical function, and even if it were, there’s dozens of good, quick ways to
juggle array items like this - linked lists spring to mind.
Check out the cheap trick I used in the bringtotop() function. Since I know
that the window doesn’t own the pointers, I can just clobber the window and
then immediate re-add him, effectively repositioning him at the top of the array. I
did this solely because my pointer class, uti_pointerarray, already had code that
would delete an element and slide all higher elements backwards one slot.
So that’s window management. Now, onto the joy of coordinate systems…
Coordinate Systems
/**************************************************************************
virtual coordinate system to graphics card resolution
converters
***************************************************************************
const double GUI_SCALEX = 10000.0;
const double GUI_SCALEY = 10000.0;

int gui_window::virtxtopixels(int virtx) {

int width = (m_parent) ? m_parent-›getpos().getwidth() :
getscreendims().getwidth();
return((int)((double)virtx*(double)width/GUI_SCALEX));
}

int gui_window::virtytopixels(int virty) {

int height = (m_parent) ? m_parent-›getpos().getheight() :
getscreendims().getheight();
return((int)((double)virty*(double)height/GUI_SCALEY));
}

/**************************************************************************
findchildatcoord: returns the top-most child window at coord
(x,y); recursive.
***************************************************************************
gui_window *gui_window::findchildatcoord(coord x, coord y, int
flags) {
for (int q = m_subwins.getsize()-1; q ›= 0; q--) {
gui_window *ww = (gui_window *)m_subwins.getat(q);
if (ww) {
gui_window *found = ww-›findchildatcoord(x-m_position.getx1(),
y-m_position.gety1(), flags);
if (found) return(found);
}
}

// check to see if this window itself is at the coord - this

breaks the recursion
if (!getinvisible() && m_position.ispointin(x,y)) return(this);
return(NULL);
}
One of the top priorities for my GUI was resolution independence, and
what I call “stretchy dialog boxes.” Basically, I wanted my windows and dialog
boxes to scale themselves larger or smaller, depending on the screen resolution
of the system they were running on. On systems with higher resolutions, I
wanted the windows, controls, etc. to expand; on 640×480, I wanted things to
shrink.
What this really meant was that I needed to implement a virtual coordinate
system. I based my virtual coordinate system around an arbitrary number - I
effectively said, “Henceforth, I will assume that every window is 10,000×10,000
units, regardless of the actual size of that window,” and then let my GUI do the
work of scaling the coordinates. For the desktop window, the coordinates are
scaled to the physical resolution of the monitor.
I accomplished this through four functions: virtxtopixels(), virtytopixels(),
pixelstovirtx(), and pixelstovirty(). (Note: only two are listed in the code; I
figured you got the idea). These functions are responsible for converting
between the virtual 10,000×10,000 unit coordinates and either the actual
dimensions of the parent window, or the physical coordinates of the monitor.
Obviously, the rendering functions of the windows use these functions heavily.
The screentoclient() function is responsible for taking an absolute screen
position and converting it into relative virtual coordinates. Relative coordinates
have their origin at the upper-left of a window; it’s the same idea as world space
and object space, in 3D. Relative coordinates are indispensable for dialog boxes.
All coordinates in the GUI system are relative to something. The only
exception to this is the desktop window, whose coordinates are absolute. This
relative way of doing things ensures that child windows move when their parents
do, and that the structure of dialog boxes is consistent as the user drags them to
different locations. Also, because our entire virtual coordinate system is relative,
when a use stretches or shrinks a dialog box, all of the controls within that dialog
will stretch and shrink also, automatically trying their best to completely fill up
their new dimensions. This is an amazing trait, for those of us who have ever
tried to do the same thing in Win32.
Finally, the findchildatcoord() function takes a (virtual) coordinate and
determines which child window (if any) is under that coordinate - useful, for
example, when a mouse button is clicked, and we need to know which window
to send the button click event to. The function works by looping through the
subwindow array backwards (remember, the topmost window is at the back of
the array), doing some rectangle geometry to see if the point is in that window’s
rectangle. The flags parameter provides some extra conditions for determining if
a “hit” occurred; for example, when we start implementing controls, we’ll
realize that it’s often useful to prevent label and icon controls from registering a
“hit,” instead giving the windows beneath them a chance at the test - if a label is
placed on top of a button, the user can hit the button, even if technically, they’re
clicking on the label. The flags parameter controls those special cases.
 Now that we’ve got some coordinates, we can finally begin to draw our
window…
Window Drawing Code
Recursion is a double-edged sword. It makes the window drawing code
very easy to follow, but it also ends up touching pixels twice, which can be a
significant performance hit (say, for example, you have a stack of fifty windows,
all the same size and at the same screen position - the code will run through the
drawing loop fifty times, and touch the same set of pixels fifty times). This is a
notorious problem. There are certainly hidden-surface elimination algorithms
one could apply to this situation - in fact, this is an area I need to spend some
time with on my own code - Quaternion’s GUI is most active during the non-
game screens (title, closing, etc.), places where it’s perfectly OK for the GUI to
be a hog, because there isn’t anything else going on.
But, I am tinkering with it; I’m currently trying to employ the
DirectDrawClipper object in my drawing routines. So far, the initial code looks
pretty promising. Here’s the way it will work: The desktop window “clears” the
clipper object. Each window then draws is subwindows backwards, top one
first, bottom one last. After each window is drawn, it adds its screen rectangle to
the Clipper, effectively “excluding” that area from the windows below it (yes,
this assumes all windows are 100% opaque). This helps to ensure that at the very
least, each pixel will be touched only once; granted, the code is still churning
through all of the calculations and calls required for GUI rendering, (and the
clipper’s probably got its hands full, too), but at least the code isn’t actually
drawing redundant pixels. Whether the clipper object operates fast enough to
make this worthwhile remains to be seen.
I’m tossing around several other ideas, too - perhaps using the built-in z-
buffer on the 3D graphics card, or implementing some sort of dirty rectangle
setup. If you’ve got any ideas, let me know; or, try them yourself and let me
know what you found.
Most of the bulk of the window drawing code I cut out, because it’s very
specific to my situation (it calls my custom sprite classes). Suffice it to say that
once you know the exact screen dimensions of where you’re going to draw a
window, the actual drawing code is straightforward (and fun) to implement.
Fundamentally, my drawing code takes a set of nine sprites - four for the corners,
four for the edges, one for the background - and uses those sprites to draw the
window.
The color sets deserve a small explanation. I decided that each window
would have two unique color sets; one set for when that window is active, one
set for when it’s not. Before the drawing code gets started, it makes a call to
getappropriatecolorset(), which returns the correct color set for the window’s
activation status. Having separate colors for active and inactive windows is a
basic principle of GUI design; it was also fairly easy to implement.
Now our windows draw, so it’s time to start looking at messaging…
Window Messages
This section is the core of GUI implementation. Window messages are the
events that get sent to a window when the user performs certain actions -
clicking the mouse, moving it, hitting a key, etc. Some messages (like
wm_keydown) are sent to the active window, some (wm_mousemove) are sent
to the window the mouse is over, and some (wm_update) are always sent to the
desktop, regardless.
Microsoft Windows has a message queue. My GUI does not - when
calcall() figures out that it needs to send a message to a window, it stops right
there and “sends” it - it calls the appropriate wm_xxxx() virtual function for that
window. I’ve found that this method is just fine for simple GUIs. Unless you
have a really good reason, don’t bother with implementing a full-blown message
queue, storing things into it, and having separate threads pick up the messages
and dispatch them. For most game GUIs, it isn’t worth it.
As much as I’d like to, I can’t go into very much detail about calcall(), the
function that polls all the input devices and sends out the messages. It does many
things, and implements many behaviors that are specific to my GUI. For
example, you might want your GUI to behave like X-Windows, where the
window the mouse is over is always the active window. Or, you might want to
make the active window system modal (meaning nothing else can happen until
the user gets rid of it), like several Mac-based programs do. You might want the
ability to move windows by clicking anywhere in them, instead of just in their
title bar, like WinAmp. The implementation of calcall() will vary wildly
depending on which behaviors you decide to incorporate into your GUI.
I’ll give you a hint, though - the calcall() function is not stateless, in fact,
your calcall() function will probably end up being a rather complex state
machine. The perfect example of this is dragging and dropping things. In order
to properly calculate the difference between a normal “mouse button released”
event, and a similar but completely different “whatever the user was dragging
has just been dropped” event, calcall() must maintain a state. If you’re rusty on
finite state machines, save yourself a lot of headaches and brush up on them
before you tackle calcall()’s implementation.
The wm_xxx() functions included in the window header file were the ones I
felt represented the minimum set of messages a GUI would need to calculate and
dispatch. Your needs may differ, and there’s no reason why you have to stick to
the Microsoft Windows set of messages; if a custom message would be perfect
for you, now’s the time to implement it.
Wrapping It Up
In the first part of this article I PDL’d out a function called
CApplication::RenderGUI(), the master function behind calculating and drawing
our GUI:
void CApplication::RenderGUI(void) {
// get position and button status of mouse cursor
// calculate mouse cursor’s effects on windows / send messages
// render all windows
// render mouse
// flip to screen
}
Now, finally, we’re at a position where we can begin filling in some of that
PDL. Check it out:
void CApplication::RenderGUI(void) {
// get position and button status of mouse cursor
m_mouse.Refresh();

// calculate mouse cursor’s effects on windows / send messages

GetDesktop()-›PumpMessages();

// render all windows

GetDesktop()-›RenderAll();

// render mouse
m_mouse.Render();

// flip to screen
GetBackBuffer()-›Flip();
}
Hopefully, seeing this code now will show you how things are starting to
come together.
Part III: Implementing Controls
This section doesn’t have as much code as the others - this is mainly
because we programmers are fairly picky when it comes to the appearance of our
GUI. We like to code things up so that our buttons, our textboxes, and our GUI
appear unique, and fit our own aesthetic tastes. Consequently, everyone’s control
code will be slightly (or maybe drastically different), and it wouldn’t make sense
to include my particular drawing code. Besides, writing code to draw all the GUI
elements is fun, in fact, in my opinion, it’s the most fun you can have
implementing a GUI. Go wild.
That being said, let’s start by determining which GUI controls we need.
GUI Controls We’ll Need
I didn’t want to spend a lot of time implementing controls for my game
GUI; I wanted to stick with the smallest set of controls that I could. So, I came
up with a list of controls that I consider the minimum set for game GUIs…
· Static Text, Icon, and Group Boxes - vital. These controls label and group
the other controls in a dialog box. The static control is crucial; the frame control
we could probably live without, but it’s fairly simple, and in some cases can go a
long way towards making a dialog box easy to navigate, so I’m including it. Icon
controls should be simple, but should be able to animate, providing cool
background animations in our dialogs and menus (ala Theif: The Dark Project).
· Buttons and Checkboxes - vital. Weird button types (flat buttons,
pushbutton-style radio buttons) we can do without, but most games can’t live
without a basic button and checkbox.
· List control - important. I’ve found list controls, especially multi-column
list controls, indispensable when creating game GUIs. They’re used
everywhere. You’re going to want a very intelligent, heavyweight list control, as
good or better than the Windows List Control. For me, the list control was the
most difficult control to implement.
· Sliders and scrollbars - Important. Famous for controlling sound and
music volume. The bad news is that we’ll probably need horizontal and vertical
flavors of these guys; the good news is that they’re so similar you can implement
them very easily.
· Textboxes - Vital. You have to be able to enter your mega-3l33t, super-
kewl player handle somewhere, right?
· Progress Bars - Essential for displaying hit points, “I’m almost done
loading!”, etc.
Noticeably absent from this list are the spin button controls (which aren’t
crucial, and irritate me to no end anyway), radio buttons (we can get by with a
single selection listbox instead), and the drop-down combo box (again, we can
just use a list box), and tree control. By making the listbox control smart enough
to indent certain items, we can incorporate the functionality of the tree control
Tab controls aren’t included simply because my game doesn’t have enough
of a GUI to warrant them, though your needs may differ.
Even with all the omissions, the “minimum” list might seem daunting at
first, but we can simplify it quite a bit…
Breaking It Down: Complex Controls As
Combinations of Simple Ones
The list becomes much more manageable when we realize that the more
complex controls are just clever combinations of other, more simple controls.
For example, a scrollbar is basically just two buttons and a slider control. A
checkbox is a static control and two buttons (one “off” button, and one “on”
button). A plain old button could be implemented using three static icon controls
(just show/hide the appropriate ones to get the button to “press”), so that you can
reuse your drawing code. If you were really strapped for time, you could even
implement a progress bar as a slider that’s moved by the computer, though I
prefer having a separate control for this.
There are, however, disadvantages to this - namely, your GUI controls are
going to take up more system resources than they really need. Think about it -
each control is a window. Let’s say you’ve gone with the reuse philosophy, and
have created a button control that’s really just three different statics. That’s three
windows per button. Now, you build a scrollbar control, using two button
controls. That’s six windows per scrollbar control. Build a List control using
horizontal and vertical scrollbars, and you’re sitting at twelve windows per list.
It adds up quickly.
So it’s really just another example of the classic tradeoff between “how fast
can I develop it” and “how little resources can I get it to use?” If you need a very
high performance, no-waste GUI, implement each control from the ground up. If
you would instead a quick implementation, and don’t mind the performance hit,
you might choose to implement your controls so that the only control that would
actually draw to the screen would be the static, and all other controls would be
made up of combinations of statics.
When building my GUI, I tried to create a good balance between these two
extremes.
Now, let’s dive into the actual implementation of each control, starting with
everyone’s favorite, the static label.
The Static Controls
There are three kinds of static controls we’ll be looking at: static text
controls, static icon controls, and frame controls. All three of these controls are
very easy, because they take no messages - all they do is draw themselves at
certain positions.
Static text controls are by far the easiest control you’ll ever implement - just
draw your window’s caption at the upper-left of your window, and you’re done.
If you’re especially through, you might want to add code to justify your text a
certain way - for example, to center your text in your client rect, you might
employ the classic centering algorithm - take the width of your window, subtract
the width of the text you’re going to draw, and divide by two, telling you how
many pixels “in” (that is, how many pixels right from the left window edge) to
start drawing.
Static icon controls are a little tougher. Actually, the term “static icon
control” is a bit of a misnomer, given that we want our icon controls to be able to
animate. Even so, implementation of these icon controls isn’t tough, provided
you’ve got a solid sprite library to handle all the details of implementing
animation: checking the millisecond delta between this frame and the one that’s
on the screen now, using this delta to determine how many frames your sprites
should advance by, etc.
Icon controls only become painful to implement if you’re not redrawing
your entire GUI system every frame. In this case, you’ve somehow got to deal
with clipping the icon control, so that even though it’s being drawn every frame,
it doesn’t accidentally overwrite pixels belonging to a window that’s sitting on
top of it (but wasn’t changed, so therefore wasn’t drawn). I didn’t implement this
- my GUI gets redrawn every frame - but if you’re faced with this problem, you
might want to try setting up a clip list for each icon, using it to draw the icon,
and re-evaluating it when any window is moved, closed, or opened. This may or
may not be a viable solution - I just dreamt it up while writing this - but it seems
to be at least a good jumping off point.
Frame controls are also pretty straightforward. I implemented my frame
control by drawing a border around m_position, then drawing the window
caption at about position (5,5), in client coordinates (that is, about five pixels
right and five pixels down from the upper-left of the frame control), but you may
decide you want something a little fancier.
The one complex thing you might want to do for your static controls is to
change the behavior of the findwindow function slightly so that it “skips” all
windows that are static controls. That way, if a static text control is sitting on top
of a pushbutton, the user will be able to push the button “through” the static
control.
Speaking of, let’s now take a look at how to implement that button.

Pushbutton Controls

Pushbuttons are only slightly more difficult than static controls. Your
pushbutton control needs to keep track of whether it’s “pressed” (pushed down)
or “unpressed.” It does this by implementing two virtual functions,
wm_mousedown() and wm_mouseup(), which your main calcall() function
needs to call when appropriate.
Basically, in wm_mousedown(), you set a boolean variable, which I call the
“depressed flag,” to true, and in wm_mouseup(), you set it back to false. Then,
in your drawing code, if the depressed flag is set, you draw the button “pressed,”
otherwise, you draw it “unpressed.”
Next, add an additional condition - say, “only draw the button depressed if
the depressed flag is set, AND, the mouse cursor is within my client coordinates,
otherwise, set the depressed flag back to false.” This will give you buttons that
“pop out” if you move your mouse cursor off of them, and is very important for
accurately determining when a button is clicked.
In normal GUIs, when a button is clicked, it fires off an event to its parent
window, which then does whatever the button represents - i.e., clicking the close
button will close the window, clicking the save button will save the file,
whatever. My GUI considers a button clicked if and only if, inside
wm_mouseup(), the depressed flag is set. The only way the depressed flag can
still be set inside mouseup() is if the user both pressed and released the mouse
button while the pointer was inside the button. This allows users to “bail out” at
the last minute by holding the button down and dragging the mouse pointer
somewhere outside of the button to cancel the button click, just like in any other
GUI system.
That’s pushbuttons. Now, let’s take a peek at text boxes.

Carets and The Textbox Control

I chose to implement a very simple textbox control. It just captures keys,

and does no scrolling - but you might want something more complex, say, a
control that accurately handles the home, end, insert, and delete keys, or maybe
even one with support for cutting, copying, and pasting, via the windows
clipboard.
But before we can have a textbox, we need a caret. In case you’re not
familiar with the terminology, a caret is another word for a cursor - that’s right,
that little blinking vertical bar. Carets tell the user where the text they type is
going to go.
For the purposes of my GUI, I’ve made things simple - I’ve ordained that
the active window is the window that has the caret, period. This is how most
GUIs behave, and seems to be the best solution. Also, my GUI, like Windows,
considers the “caption” of the textbox to be the text that’s actually in the box.
So how do you implement the caret? Well, I decided that since it’s a given
that the caret always going to be drawn inside the active window, and that the
caret will only appear if the active window is a textbox, it makes sense to
consider the caret part of the textbox and implement it inside the textbox’s draw
function. This makes it really easy to implement - simply use an integer to
represent an index into the character array of the window caption, and your
textbox has all the information it needs to properly draw the caret.
Which means, basically, that if you’re a textbox, all you have to do to
render yourself is draw a border around your client area, draw your window
caption inside this border, and then, if you’re the active window, draw your caret
at the correct position. In my GUI, the maximum length of a string inside a
textbox is governed by the size of the textbox window, meaning that I don’t have
to deal with scrolling the text within the box. You, however, might want to some
way for the user to scroll through the contents of a textbox, allowing them to
enter a very long string in a very small box.
By far the most difficult thing about a textbox is the keyboard processing
that comes with it. Once we have a key, it’s easy to create a wm_keypressed()
virtual function, and call it, and it’s easy to implement the textbox handler for
wm_keypressed() so that it processes the key, and either tacks it onto the end of
the window caption, or processes special keys (backspace, etc. - this is where
your heavyweight string class pays for itself), and moves the caret.
The hard part is getting the key in the first place. Windows provides no less
than three completely different ways to query the keyboard - the
WM_KEYDOWN event, the GetKeyboardState() and GetAsyncKeyState()
functions, and of course, DirectInput. I used the DirectInput method, simply
because I already had done most of the heavy-lifting associated with DirectInput
back when I implemented the mouse cursor, and because getting the keyboard
state through DirectInput seemed to me the cleanest and most elegant solution.
 To use DirectInput’s keyboard functionality, the first thing you need to do is
set up a keyboard device. This is incredibly similar to how we set up the
DirectInput mouse device way back in Part I of this article. Basically, the only
difference here is that instead of telling DirectInput to treat our new device as a
mouse, we’re telling it to treat it as a keyboard (duh). If you’ve gone through
DirectInput for the mouse, doing the same stuff again for the keyboard should be
easy.
Once we’ve got our keyboard device we can query it.
To actual determine if a key was “hit” requires slightly more work.
Basically, to determine which keys are pressed, you need two snapshots of all
101 key states - you need a snapshot from the last frame, and a snapshot from
this frame. The keys that are down in this frame but not down last frame are the
keys that have been “pressed,” and they’re the keys you should send out
wm_keypressed() “messages” for.
Now, onto progress bars…
Progress Bars
Progess bars are just about as easy as static controls to implement, since
they only take a few messages.
Basically, you need to do two things with a progress bar - you need to tell it
a min/max range, and you need to tell it to “step” some number of units. For
example, say I wanted to put up a “Loading…” progress bar, because I had to
load 100 different game resources. I would create a progress bar with a range of
0 to 100. I would initally set the progress bar to zero, then, whenever I loaded a
game resource, I would “step” the progress bar by one unit. Whenever the
progress bar was stepped, it would redraw itself, showing graphically how far
along it was by displaying a bar whose length was proportionate to its client
area.
Progress bars are very similar to scroll bars; in fact, it might make sense to
implement your progess bars in terms of your scroll bars. I made my progress
bar separate from my scroll bars simply because I wanted the two to have
drastically different appearances - your needs may be different.
Sliders and Scrollbars
Drawing a slider or a scrollbar is similar to drawing a progress bar, in that
you need to express the slider’s current position as a percentage of its client
rectangle, giving you the position at which to draw the “pointer” (or, for a
scrollbar, the elevator). You’ll have to make some slight modifications for
horizontal vs. vertical controls - I got around these by implementing a base class,
gui_slider, which contained all of the common code, and all of the member
variables, and then implementing two specific derivatives, gui_slider_horz and
gui_slider_vert, which handled the differences in drawing and clicking logic.
As for processing mouse clicks, I opted for the easy way when I created my
sliders. If a mouse click occurs in the client area of a scrollbar, I automatically
scroll directly to that position. In my sliders, you can’t click in the “shaft” and
move the position by a page at a time - you jump directly to where you clicked.
This was a decision I made primarily because it was easy, but also because I
dislike the default Windows behavior of paging.
As for the scrollbar / slider logic, you’ve got the same basic setup as a
progress bar - min, max, and current positions. Unlike a progress bar, however,
the user can change the current position by clicking in the control.
Now, scrollbars. I decided, for my GUI, that scrollbars are just sliders with
two buttons tacked onto either side. These two buttons (the up/down or left/right
arrows) move the elevator one position. This method eliminated a lot of code
duplication between the pushbutton class and the scrollbars, and I would highly
recommend that you take a look at doing something similar.
Now that we’ve got scrollbars, we can tackle the most complex control of
them all… the listbox.

The Listbox Control

Resign yourself to this now - the listbox control is where
you’re going to be spending the most time.
// represents a column in our listbox
class gui_listbox_column {
public:
gui_listbox_column() {}
virtual ~gui_listbox_column() {}

virtual void draw(uti_rectangle& where);

void setname(const char *name) { m_name = name; }
uti_string getname(void) { return(m_name); }

int getwidth(void) { return(m_width); }

void setwidth(int w) { m_width = w; }

private:
uti_string m_name;
int m_width;
};

// an item in our listbox

class gui_listbox_item {
public:
gui_listbox_item() { m_isselected = 0; m_indent = 0; }
virtual ~gui_listbox_item() {}

virtual drawitem(int colnum, uti_rectangle& where);

void clearallcolumns(void); // boring

void setindent(int i) { m_indent = i; }
int getindent(void) { return(m_indent); }

void settext(int colnum, const char *text); // boring

uti_string gettext(int colnum = 0); // boring

void setitemdata(UL itemdata) { m_itemdata = itemdata; }

UL getitemdata(void) { return(m_itemdata); }

void setselected(int s = 1) { m_isselected = s; }

int getselected(void) { return(m_isselected); }

private:
int m_isselected;
int m_indent; // # of pixels to indent this item
UL m_itemdata;
uti_pointerarray m_coltext;
};

// the listbox itself

class gui_fancylistbox: public gui_window {
public:
gui_fancylistbox() { m_multiselect = 0; }
virtual ~gui_fancylistbox() { clear(); }

int getselected(int iter = 0);

 virtual int wm_command(gui_window *win, int cmd, int param);
virtual int wm_paint(coord x, coord y);
virtual int wm_lbuttondown(coord x, coord y);

gui_fancyscrollbar_horz& gethscroll(void) { return(m_hscroll);

}
gui_fancyscrollbar_vert& getvscroll(void) { return(m_vscroll);
}

virtual int wm_sizechanged(void); // the window's size has

changed somehow

gui_listbox_item *getitemat(int index); // boring

gui_listbox_item *additem(const char *text); // boring
int delitem(int index); // boring
int delallitems(void); // boring
gui_listbox_column *getcolumn(int index); // boring
int addcolumn(const char *name, int width); // boring
gui_listbox_column *getcolumnat(int index); // boring
int delcolumn(int index); // boring
int delallcolumns(void); // boring

int clear(void); // delete columns & items

int getnumitems(void);
int getnumcols(void);

void deselectall(void);
void selectitem(int item);
void selecttoggleitem(int item);

void deselitem(int item);

private:
int m_numdispobjsy;
int m_vertgutterwidth; // # of pixels between items vertically

gui_fancyscrollbar_horz m_hscroll;
gui_fancyscrollbar_vert m_vscroll;

bool m_multiselect; // is this multi-selectable?

uti_pointerarray m_items; // array of gui_listbox_items
uti_pointerarray m_columns; // array of gui_listbox_columns
};
The listbox is by far the most complex control you’ll make… but that’s
only because it’s the most versatile. A good listbox control, capable of multiple
columns, indenting, and multi-selection will prove practically indispensable in
your game’s GUI. Stop and think for a moment about all the places that listboxes
are used in the average game, and you’ll quickly see my point.
I tackled my listbox control by splitting it up into two separate controls: a
multi-column “report-style” list control, and an icon list control, which creates a
view similar to what you’d see when selecting “large icons” in an explorer
window.
The icon list control was fairly easy to do. It kept track of a list of static
icons (again, note the code reuse), all the same size. I divided the listbox width
by the width of the icons, which gave me the number of columns available. (If it
turned out that my listbox was smaller than the largest icon, I assume I have only
one column, and let the gui system take care of clipping the icons so that they
don’t overrun my client area). Once I had the number of columns, I calculated
how many rows I’d need by dividing the total number of icons by the number of
columns. This told me how to setup my included scrollbar (again - complex
controls as combinations of simple ones).
Note that these values will have to be recalculated whenever the control is
resized. For this reason, I set up a wm_sizechanged() message that calcall()
would call whenever the client area of a window was modified.
The report-style list control was a little more complex. I first created two
helper classes, gui_listbox_column and gui_listbox_item, which contained all of
the information about a given item and column in the list.
gui_listbox_column is the simpler of the two classes. The main listbox class
keeps, as a member variable, a dynamic array of gui_listbox_columns, which
represent the columns in the listbox right now. gui_listbox_column contains all
of the information needed for a column in our list box, including the name of the
column, the alignment of the column, whether it’s shown or hidden, its size, etc.
The main listbox class also keeps a dynamic array of gui_listbox_items.
The gui_listbox_item class contains everything related to a particular row (or
item) in our report-style listbox. By far the most important data member of this
class is the array of strings, representing the data for each column. I also decided
to let each item store an additional 32-bits of data with it, via the m_itemdata
member. This technique is similar to how Windows allows you to store 32-bits
of data by calling SetItemData() and GetItemData() for your listbox items. This
feature is important because it allows clients of the listbox to store a pointer with
each item - usually a pointer to the specific class associated with the item, so that
it’s readily available later.
As for drawing the columns and items… I decided that I’d like to have
absolute control over how each individual item/column in the listbox was drawn.
Towards this end, I decided to have the listbox draw its items and columns by
repeatedly calling two virtual functions, gui_listbox_item::draw() and
gui_listbox_column::draw(). Each function took one parameter - a rectangle
understood to be the location on the screen where the column or item was
supposed to be drawn. The default implementations of these draw() functions
just spit out the text associated with that particular column and subitem in that
rectangle; however, I could now easily derive and override draw() for items or
columns that required a unique appearance. This technique has seemed to work
for me so far, though I don’t claim that it’s the best or “right” way to do it.
Drawing the items required a little more work than the columns, however.
Items had to be drawn with or without a highlight, depending on whether they
were selected or not. Not a big deal, but important to remember.
Then there’s the issue of scrollbars. My report-view listbox contained two
members, m_horzscrollbar and m_vertscrollbar, both GUI scrollbars. Whenever
the size of the listbox was changed (wm_sizechanged()), it took a peek at the
width and height of the data it had, and either displayed or hid the scrollbars as
appropriate.
It’s been a whirlwind tour, but hopefully you have a general idea of what
lies ahead of you in your quest to create controls for your GUI. The only thing I
want to reiterate is “style is fun.” Don’t be afraid to take a few liberties as you
create your GUI - implement the stuff you’ve always wished for, and the stuff
that makes the most sense in your game. This is especially important if the game
your making relies heavily on the functionality of your GUI - like, say, you’re
making a RTS game.
But also remember that in creating your controls, your doing the same
balancing act as with the rest of your game - you’re weighing features against
development time. Give your players as easy and intuitive GUI as possible, but
also, don’t spend all your time making 50 different controls. You want to strike a
balance between functionality, the good thing, and complexity, the bad thing.
Part IV: Resource Editors and Other
Madness
This section will address a whole bunch of miscellaneous issues and ideas
to polish off your game GUI.
Saving Windows
Window serialization (or, saving and loading windows) may or may not be
crucial for your project. If your game GUI is minimal, you might be able to get
by with just hard-coding the windows into your game. But if your GUI’s more
complex than that, you’re going to want code that will save a window (and all its
children) to a file, and then load it back up again. For starters, having window
serialization code allows you to change your game’s GUI without recompiling,
and is a boon if you’re working with more than one person. So, let’s spend a
little time talking about how I implemented saving windows.
My plan of attack was easy - start at the main dialog window, and
recursively go through all of its child windows, saving each one to disk. If I were
programming in C, the first thing I would have said to myself would have been
“OK, so if I have to save these windows, I need a byte for each window that tells
me what type of window it is, so I can load it back up correctly. 1 is a button, 2
is a listbox, 3 is an icon, etc.”
This kind of problem is specifically what C++’s RTTI (Run Time Type
Identification) addresses. RTTI provides two things, a type_info class and a
typeid() function, which together allowed me to query an object for it’s class
name - “gui_window”, “gui_button”, etc. Instead of fiddling with enums and
IDs, I simply call typid() for each window I’m going to save, and “write down”
the class name of the window.
I saw two minor disadvantages to using RTTI’s object identification
functions to help save windows. First of all, the RTTI IDs are strings, not
integers, which means they’ll take up more space on disk (store them Pascal
style, that is, the first 4 bytes describe the length of the string, followed by the
string data itself). Second, if you change the name of one of your window
classes, you’ll break any window files that you’ve previously saved. For these
reasons, you might opt out of using RTTI in this manner - after all, just because a
technology is there doesn’t mean you have to use it. However, I found RTTI to
be a lifesaver in my code.
For more information on RTTI and these two functions, search for them in
your online help. Also, if you decide to use RTTI with Visual C++, make sure
you turn it on in your project settings, C/C++ tab, C++ language option.
Loading Windows
Loading windows is more difficult than saving them, primarily because you
have to new each window, load it up, and then remember to delete it when it’s no
longer needed.
This function is recursive, and looks like this in PDL:
void gui_window::load(int filehandle) {
// read window properties (colorsets, etc.)
// read total number of children for this window
// for each child…
// read window ID from disk
// new a gui_window derivative based on that ID
// tell the newly created window to load itself (recurse)
// next child
}
In other words, you’d load windows from disk exactly as you would expect.
First, you take care of the base window: read in its properties. Then, read in the
total number of children of the base window. For each child, read an ID byte,
new up a window based on that ID, and then tell that new window to load itself
(recurse down into it). Once all of your children are loaded, you’re done.
Of course, it’s also very important that your file structure mirrors this same
layout. Make sure your save code saves things in the same order that you’re
loading them.
Resource Editors
To really make your game GUI shine, you’re going to need a resource
editor. Certainly you don’t need one as slick and functional as Developer
Studio’s, but you at least need a basic application that will let you add, edit,
delete, and arrange things, and will save you the trouble of calculating out virtual
coordinate positions for all of the controls in your dialogs.
Writing a full-featured, WYSIWYG resource editor is beyond the scope of
this article, but I can give you a few miscellaneous tips for if you do decide to
attempt such a beast:
· Share your code. Specifically, make the resource editor share the same
rendering code as your actual game. This way, you get WYSIWYG support, and
you save yourself the trouble of having to implement two sets of GUI code. I
guarantee you, it’s easier to tweak your DirectX code so that it renders to a GDI
surface instead of to a double-buffered system than it is to re-implement an
entirely new drawing core. Remember also that it’s quite likely your GUI system
will change over time - you don’t want to constantly have to change code in two
different places.
· Don’t try to emulate DevStudio’s look and feel. In other words, don’t
waste time trying to figure out how to mimic the various features of the
DevStudio GUI (like, say, tabbed property sheets and preview windows). Don’t
feel bad if your Resource Editor is ugly in comparison; yes, it’s true that the
productivity of a team is directly proportional to how useful its tools are, but at
the same time, it’s very unlikely that anyone outside your team will be using
your Resource Editor, and you’re not using it to create a full-fledged GUI app;
you’re just making a few dialogs. You don’t need context sensitive help. You
don’t need context menus, unless in your opinion they ease a particularly tedious
operation. It’s OK if your resource editor isn’t polished, just so long as it gets the
job done.
· Emphasize data integrity over speed. The Resource Editor is a data
wrangler, not a high-performance app, and there’s nothing more annoying than
when a dialog you’ve spent an hour designing goes down the tubes because of a
program crash. When writing your GUI, preserving data should be your highest
goal - implement autosaves, undo buffers, etc, and go easy on the optimization.
Subclassing
Those of you who are familiar with the way Win32 does its windowing
probably already know what the term “subclass” means. For those of you who
don’t - when you “subclass” a window, you effectively “derive” a new window
type, and then wedge your new window type into places where the old window
used to be.
Let me explain that a little better. Say we need a Super Listbox. We’ve got a
normal listbox class, but it just doesn’t cut it for some reason; our game demands
the Super Listbox. So we derive a new “super listbox” class from our regular
listbox class. So far so good.
But how do we place the Super Listbox in our game’s dialog? Since the
Super Listbox is specific to our application, it wouldn’t make sense for us to add
functionality to our resource editor to support it. But, at the same time, how do
we tell our GUI system that for this one particular instance (our game), we’d like
all listboxes to really be Super Listboxes? That’s what subclassing is all about -
it’s not an exact, technical definition, but it will suffice for now.
The approach I’m about to illustrate is what I call “subclassing at load
time.” To understand it, let’s start with the basic loading code I described in the
last section. We’ve got a load function, which recursively news, loads, and then
adds windows. Specifically, we’ve got something that looks like this, in PDL:
// read total number of children for this window
// for each child…
// read window ID from disk
// new a gui_window derivative based on that ID
//…
// next child
To implement subclassing, I’ve told my window loading routine to “give
the application a chance to create a window of this type,” like so:
// read total number of children for this window
// for each child…
// read window ID from disk
// give application a chance to create a window of this type
// if the application didn’t create a window, then new a
gui_window derivative based on the ID
// else, use the application’s created window
//…
// next child
Specifically, I give the application this chance by way of a function pointer.
If the application needs to subclass a window, it fills in the function pointer with
the address of its own function. When the windows are loading, they call this
application function, passing in the ID of the window they want to create. If the
application wants to subclass a window from this ID, it news up the appropriate
object and returns the new pointer back to the window. If the app doesn’t want to
do anything special for this ID, it returns NULL, and the window function senses
this and news up the appropriate default object. This method allows the app to
“pre-filter” the incoming window ID bytes, and to override the default behavior
for certain window types. Perfect!
Using a method like this gave me a huge amount of freedom when it came
to creating custom controls. I went back and added code to my resource editor
that would let me change the IDs that were saved for each window. Then, when I
needed a custom control in the app, I just used my resource editor to change the
ID byte that was saved for that window. Saved on disk would be the ID, along
with the dimensions and all the other base-class properties for the custom
control!
Real quickly - there’s another way to do this same thing, and that is to
mirror the approach the STL has used when it needs to create things. The STL
uses special “allocator” classes, which are sort of like “factories,” in the sense
that clients tell them what they want created, and they create it. You could use
this same approach for creating windows.
It’d work something like this. Create a class and call it
gui_window_allocator or something. Implement one virtual function, say
CreateWindowOfType(…), which would take in a given window ID and spit
back out a brand new pointer to that window. Now you’ve got a very simple
allocator class, which your window loading code will use by default to new up
windows as they are needed.
Now, when your application wants to override the “new” behavior for the
windows, you simply derive a new, application-specific gui_window_allocator
class, and tell your window loading code to use this allocator instead of the
default one. This method is similar to providing a function pointer, only with a
bit more C++ thrown into the mix.
Speeding up GUI Rendering
Here’s another miscellaneous tidbit for you that will help you if you’re
trying to speed up your GUI drawing.
The key concept here, just like with optimizing any other drawing routine,
is simply “don’t draw what you don’t need to.” By default, the GUI spends a lot
of its time drawing stuff that hasn’t changed. You can, however, optimize this a
little, by telling the GUI to only draw windows that are “dirty.” The windows set
their dirty flag whenever their appearance needs to change, and they clear the
dirty flag once they’re drawn.
There’s one catch - since our GUI controls might be transparent, when a
control is marked as dirty, its parent window must also be marked as dirty. That
way, when it draws itself, the background is still intact, since the parent window
has also just redrawn.
Conclusion
I’d like this article to be as useful as possible, so now that you’ve read it, if
there’s anything you’d like me to expand on, or anything that I’ve missed, please
email me and let me know about it.
Also, check out my web site and my current project, Quaternion, at
http://www.spin-studios.com.
And, if you get a chance, drop by http://www.gamedev.net.
But most importantly… have fun developing your game!
Mason McCuskey is the leader of Spin Studios, a game development team
working to break into the industry by creating a great game, Quaternion, and
getting it published. He looks forward to your suggestions and comments, and
can be reached via his web site at http://www.spin-studios.com, or by email at
mason@spin-studios.com.