Debian Codegraph @

Documentation/Overview/gui_overview.xml

raw
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>&lt;insert picture here pointing at the different components
52 of notepad&gt;</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>