| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>Implementing a GUI with ClanLib</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<p>Thanks to the new GUI API in ClanLib, having a GUI in your game no longer |
| 8 |
has to be an ardous boring task. ClanLib GUI comes complete with |
| 9 |
implementations of most standard widgets/components, such as inputboxes, |
| 10 |
scrollbars, comboboxes, menus, listboxes, checkboxes and buttons.</p> |
| 11 |
|
| 12 |
<p>At the core of the ClanLib GUI API, lies the routing of GUI input to game |
| 13 |
code. ClanLib uses a signals/slot system for this. If you are familiar with |
| 14 |
QT, you should also be familiar with signals and slots, but if you're in |
| 15 |
doubt, you can read our signals and slots <a href="signals.html">overview</a>.</p> |
| 16 |
|
| 17 |
<p>The ClanLib GUI has a default look, eg. the way each component is |
| 18 |
displayed, but the logical functionality of each implemented base-component |
| 19 |
is entirely isolated from the displaying, so it's easy to create a |
| 20 |
customized GUI "style". Styles are managed through a style-manager that |
| 21 |
makes it easy to extend the default-style with new ones. This makes it |
| 22 |
possible for people to create a new GUI style, and release it for easy use |
| 23 |
by other ClanLib-users. An overview on how to create custom style can be |
| 24 |
read <a href="gui_theme.html">here</a>.</p> |
| 25 |
|
| 26 |
<p>There are two ways to create GUI components, using standard C++ objects, |
| 27 |
or using special GUI definition script files.</p> |
| 28 |
|
| 29 |
<p>TODO: Write about manually creating components</p> |
| 30 |
|
| 31 |
<p>GUIs can be defined in special GUI definition script files, which provide |
| 32 |
a flexible and powerful way to describe the layout of a GUI. Components are |
| 33 |
layered in a hierarchical fashion. Each component has a set of parameters |
| 34 |
(mandatory or optional) that describe the component, and through a |
| 35 |
naming-scheme, these components can be modified and hooked to callback |
| 36 |
functions at run-time. You can read more about that in the |
| 37 |
<a href="gui_resources.html">GUI resource overview</a>.</p> |
| 38 |
|
| 39 |
<h3>GUI systems in general</h3> |
| 40 |
|
| 41 |
<p>This is a little introduction in what a GUI framework is and how you use |
| 42 |
them. If you are already familiar with a GUI toolkit, MFC, Gtk+ og Qt, then |
| 43 |
odds are you know this already, so you might want to skip to the next |
| 44 |
section.</p> |
| 45 |
|
| 46 |
<p>When you look at a normal GUI application then it consists of a set of |
| 47 |
components (often referrered as widget or controls too). In the case of |
| 48 |
notepad (you do know notepad, right? :)), it consist of a window frame, |
| 49 |
menubar, a textbox and in newer versions there's a statusbar too:</p> |
| 50 |
|
| 51 |
<p align=center><insert picture here pointing at the different components |
| 52 |
of notepad></p> |
| 53 |
|
| 54 |
<p>Drawn as a tree, notepad looks like this:</p> |
| 55 |
|
| 56 |
<pre> |
| 57 |
+ Window (titlebar, resize frame around all of notepad) |
| 58 |
+ Menu bar |
| 59 |
+ File |
| 60 |
+ Edit |
| 61 |
+ View |
| 62 |
+ Help |
| 63 |
+ Textbox |
| 64 |
+ Statusbar |
| 65 |
</pre> |
| 66 |
|
| 67 |
<p>For each of these objects, you should construct a CL_Component that handles |
| 68 |
the user interaction in these areas of the screen:</p> |
| 69 |
|
| 70 |
<pre> |
| 71 |
CL_Window *window = new CL_Window(CL_Rect(0,0,640,480), gui); |
| 72 |
CL_MenuBar *menubar = new CL_MenuBar(CL_Rect(0,0,640,32), window); |
| 73 |
CL_TextBox *textbox = new CL_TextBox(CL_Rect(0,32,640,480-64), window); |
| 74 |
CL_StatusBar *statusbar = new CL_StatusBar(CL_Rect(0,480-32,640,32), window); |
| 75 |
</pre> |
| 76 |
|
| 77 |
<p>Note: clanGUI does not work exactly like this example, but it |
| 78 |
illustrates the concept.</p> |
| 79 |
|
| 80 |
<p>Whenever the user clicks on the menubar, the menubar object is notified. |
| 81 |
If he types text, the textbox object is notified, and so forth.</p> |
| 82 |
|
| 83 |
<p>Only one component can have the focus at a time. All keyboard activity is |
| 84 |
directed to this component until focus is put on another component. In the |
| 85 |
notepad example, the textbox will usually have the focus, but if you eg |
| 86 |
click on the File menu, then a popup component will be created that gets the |
| 87 |
focus. Pressing the arrow keys will then be sent to the popup menu component |
| 88 |
and it will move the selected item indicator.</p> |
| 89 |
|
| 90 |
<p>A GUI toolkit consist mainly of two parts: first a generic component |
| 91 |
class (CL_Component in clanGUI) which represents any object in the GUI tree. |
| 92 |
It does not do anything by itself, but its the interface in which you |
| 93 |
interact with the user in a certain space of the screen. Beside that, a GUI |
| 94 |
toolkit have a set of CL_Component inheriated objects that make it easier to |
| 95 |
do common UI tasks, this is usually inputboxes, labels, menus, frames, |
| 96 |
etc.</p> |
| 97 |
|
| 98 |
<h3>Event handling</h3> |
| 99 |
|
| 100 |
<p>One of the keys to learning how to use clanGUI is to understand how it |
| 101 |
uses signals and slots to do event handling. If someone clicks on a button |
| 102 |
component, the CL_Button object will emit its sig_clicked signal, and any |
| 103 |
slot connected to the signal will get called.</p> |
| 104 |
|
| 105 |
<p>Here's an example:</p> |
| 106 |
|
| 107 |
<pre> |
| 108 |
void MyApp::show_gui() |
| 109 |
{ |
| 110 |
CL_StyleManager_Silver style(....); |
| 111 |
CL_GUIManager gui(&style); |
| 112 |
|
| 113 |
CL_Button button_ok(CL_Rect(....), "Ok", &gui); |
| 114 |
CL_Button button_cancel(CL_Rect(....), "Cancel", &gui); |
| 115 |
|
| 116 |
CL_SlotContainer slots; |
| 117 |
slots.connect(button_ok.sig_clicked(), this, &MyApp::on_button_ok); |
| 118 |
slots.connect(button_cancel.sig_clicked(), this, &MyApp::on_button_cancel); |
| 119 |
|
| 120 |
gui.run(); |
| 121 |
} |
| 122 |
|
| 123 |
void MyApp::on_button_ok() |
| 124 |
{ |
| 125 |
std::cout << "Button ok was clicked!" << std::endl; |
| 126 |
} |
| 127 |
|
| 128 |
void MyApp::on_button_cancel() |
| 129 |
{ |
| 130 |
std::cout << "Button cancel was clicked!" << std::endl; |
| 131 |
} |
| 132 |
</pre> |
| 133 |
|
| 134 |
<p>Each of the components in clanGUI have their own special events that can |
| 135 |
occour, but a few signals are common for all GUI components:</p> |
| 136 |
|
| 137 |
<ul> |
| 138 |
<li>Key events (key down, key up, key repeat)</li> |
| 139 |
<li>Mouse events (mouse up, mouse down, mouse move)</li> |
| 140 |
<li>Paint events (begin_paint, paint, end_paint)</li> |
| 141 |
</ul> |
| 142 |
|
| 143 |
<p>If you want to do custom drawing in your GUI, you need to hook yourself |
| 144 |
in on the sig_paint signal of the component you want to customize. Normally |
| 145 |
you should not need to do this for normal objects, but if you want to make |
| 146 |
your own objects in the GUI, then you will most likely want to use most of |
| 147 |
the common signals.</p> |
| 148 |
|
| 149 |
|
| 150 |
<h3>ClanGUI System Basics</h3> |
| 151 |
|
| 152 |
<p>In order to be able to use any GUI toolkit properly and take fully |
| 153 |
advantage of its possibilities, it is essential to understand how the core |
| 154 |
classes operate and communicate with each others. In clanGUI there are the |
| 155 |
following core classes:</p> |
| 156 |
|
| 157 |
<ul> |
| 158 |
<li>CL_Component</li> |
| 159 |
<li>CL_ComponentStyle</li> |
| 160 |
<li>CL_StyleManager</li> |
| 161 |
<li>CL_GUIManager</li> |
| 162 |
<li>CL_ComponentManager</li> |
| 163 |
</ul> |
| 164 |
|
| 165 |
<h4>CL_Component</h4> |
| 166 |
|
| 167 |
<p>The component class is the core class of clanGUI. It presents any |
| 168 |
widget/control/window in the system and is responsible for drawing the |
| 169 |
components and feeding the components with user input.</p> |
| 170 |
|
| 171 |
<p>As with just about any other GUI toolkit out there, components are |
| 172 |
ordered in a tree. At the top of the tree, we have the root/desktop |
| 173 |
component. It represents the entire screen area and any child components on |
| 174 |
the screen. A typical child of the root component could be a window |
| 175 |
component, and the window component then has maybe a inputbox and two button |
| 176 |
child components. Anyone ever having looked at a GUI toolkit earlier in |
| 177 |
their life should be familiar with this concept.</p> |
| 178 |
|
| 179 |
<p>The root component in clanGUI is called CL_GUIManager. More on this when |
| 180 |
we examine the GUI manager more closely.</p> |
| 181 |
|
| 182 |
<p>CL_Component exports a large set of signals that any subclassed component |
| 183 |
usually connects signals to. The GUI emits these events whenever interaction |
| 184 |
with the component is required. Some examples of these signals are: |
| 185 |
sig_paint, sig_key_down, sig_mouse_move and sig_got_focus. For instance, if |
| 186 |
the GUI needs the component drawn, it will emit the sig_paint signal and all |
| 187 |
hooked up painting functions will then draw the component.</p> |
| 188 |
|
| 189 |
<h4>CL_ComponentStyle</h4> |
| 190 |
|
| 191 |
<p>The component style class is the component styling (theme) interface. |
| 192 |
When a component is instantiated, one component style class is attached |
| 193 |
to the component.</p> |
| 194 |
|
| 195 |
<p>The main purpose of the component style class is to seperate styling data |
| 196 |
and functions from the component class. This is directly compareable to a |
| 197 |
document/view relationship, where the component class is the document, and |
| 198 |
then style class is a view.</p> |
| 199 |
|
| 200 |
<p>To illustrate this a bit further, imagine we are constructing an input |
| 201 |
button. At construction time, an input button specific component style is |
| 202 |
attached. The style class connects a local member function to the sig_paint |
| 203 |
signal of its CL_Button owner and stores data needed for the styling as |
| 204 |
local member variables.</p> |
| 205 |
|
| 206 |
<p>When the GUI needs to draw the button, it will emit the sig_paint signal, |
| 207 |
which causes the member function in the style class to be called. This |
| 208 |
function then uses the public available attribute functions in its CL_Button |
| 209 |
owner to figure out what the text of the input button is and where its |
| 210 |
located, finally drawing the button on screen.</p> |
| 211 |
|
| 212 |
<p>This two level construction of a component allows us to construct |
| 213 |
component objects without knowing what style is being used, making styles |
| 214 |
totally transparent for anything but the styling objects.</p> |
| 215 |
|
| 216 |
<h4>CL_StyleManager</h4> |
| 217 |
|
| 218 |
<p>Something need to attach these component styles to a component. This is |
| 219 |
what the CL_StyleManager interface does. When a component is constructed, |
| 220 |
the very first thing it does is to contact its style manager, where it asks |
| 221 |
it to attach component styles to it.</p> |
| 222 |
|
| 223 |
<p>CL_StyleManager also function as a class factory. When loading components |
| 224 |
from gui definition files, the component manager asks the style manager to |
| 225 |
create an instance of a control based on a type string and a set of |
| 226 |
component options.</p> |
| 227 |
|
| 228 |
<h4>CL_GUIManager</h4> |
| 229 |
|
| 230 |
<p>The GUI manager is the root comopnent in clanGUI. It should always be the |
| 231 |
top-level component in any component tree. The GUI manager contain the main |
| 232 |
message pump for the GUI and is responsible for routing events from clanCore |
| 233 |
and clanDisplay into the GUI system.</p> |
| 234 |
|
| 235 |
<h4>CL_ComponentManager</h4> |
| 236 |
|
| 237 |
<p>The component manager is the interface used to load GUI component trees |
| 238 |
from a GUI definition file. Have a look on the login_view.cpp/h files in the |
| 239 |
CTalk example for an example of how to use it.</p> |
| 240 |
|
| 241 |
<p>TODO: Add some code examples</p> |
| 242 |
|
| 243 |
</body> |
| 244 |
</xml> |