Debian Codegraph @

Documentation/Overview/gui_theme.xml

raw
1 <xml>
2 <head>
3 <title>Creating a custom GUI style</title>
4 </head>
5 <body>
6
7 <p>ClanGUI contains a powerful mechanism to code custom themes, or styles as
8 we call them in ClanGUI. Styles are very flexible, yet very easy to implement.
9 This document will guide you through creation of a custom style.</p>
10
11 <h3>Styles overview</h3>
12
13 <p>Each component in ClanGUI is clearly separated into logic and presentation.
14 When creating a new style for a component (for example CL_Button), you create
15 a new class which does the drawing of a component - the logic is still the same
16 between different styles.</p>
17
18 <p>A CL_StyleManager is used to attach styles to each component available. So
19 in order to create a new style you need two parts - a stylemanager, and then
20 the style-classes for each component you want a new look for.</p>
21
22 <h3>When do I need to create my own GUI style?</h3>
23
24 <p>The standard GUI style in ClanGUI very much resembles any desktop-gui used
25 in applications. This doesn't always fit with games.</p>
26
27 <p>Some of the components in the default GUI style supports surfaces, like CL_Button.
28 So, if you only wants some nice-looking buttons in your game which use predrawed
29 pictures, you can still use the default style. But if you want a custom-looking
30 inputbox or scrollbar, you need to create a custom style.</p>
31
32 <h3>Creating a stylemanager</h3>
33
34 <p>Create a new file called <b>stylemanager_coolstyle.h</b>, and insert the following
35 code into it:</p>
36
37 <code>
38 #ifndef header_stylemanager_coolstyle
39 #define header_stylemanager_coolstyle
40
41 #include <ClanLib/gui.h>
42 #include <ClanLib/guistyleboring.h>
43
44 class CL_StyleManager_CoolTheme : public CL_StyleManager_Boring
45 {
46 public:
47 CL_StyleManager_CoolTheme(CL_ResourceManager *resources);
48
49 // Connect component styles to component.
50 // The 'type' parameter indicates what type the component is.
51 virtual void connect_styles(const std::string &type, CL_Component *owner);
52 };
53
54 #endif
55 </code>
56
57 <p>The new stylemanager (CoolTheme) inherits the CL_StyleManager_Boring. This
58 means it will use the default style for any components you don't define a new style
59 for. Note that it is not neccessary to inherit from CL_StyleManager_Boring - you
60 could also inherit from CL_StyleManager, but if you then try to use a component for
61 which you haven't created a style for, nothing will be drawn for the component.
62 You could also use the CL_StyleManager_Silver for a slightly fancier default style.</p>
63
64 <p>The connect_styles() is the function which attaches the styles to the various
65 components. Make sure you inherit this function.</p>
66
67 <p>Next, create a new file called <b>stylemanager_coolstyle.cpp</b>, and insert the
68 following code into it:</p>
69
70 <code>
71 #include "stylemanager_coolstyle.h"
72 #include "button_coolstyle.h"
73
74 CL_StyleManager_CoolTheme::CL_StyleManager_CoolTheme(CL_ResourceManager *resources)
75 : CL_StyleManager_Boring(resources)
76 {
77 }
78
79 void CL_StyleManager_CoolTheme::connect_styles(const std::string &type, CL_Component *component)
80 {
81 if (type == "button")
82 {
83 CL_Button *button = (CL_Button *)component;
84 button->set_style(new CL_Button_CoolTheme(button, this));
85 }
86 else
87 {
88 CL_StyleManager_Boring::connect_styles(type, component);
89 }
90 }
91 </code>
92
93 <p>A file called <b>button_coolstyle.h</b> is included here; we'll get back to that in the next
94 section.</p>
95
96 <p>The connect_styles() function has two parameters - <b>type</b> and <b>component</b>.</p>
97
98 <p>The <b>type</b> parameter contains the name of the component to be styled - examples are
99 label, button, frame, inputbox, scrollbar, radiobutton, listbox, window, etc. For each
100 component you want to put a style on, make a new test for the type, and attach the style
101 using the set_style() function in the component. Notice how its done through creating
102 a new style class called CL_Button_CoolTheme.</p>
103
104 <p>Any components we don't attach, we just pass on to the default stylemanager. You can skip
105 doing this if you have styled all the component you want to use, or don't want to use the
106 default stylemanager at all.</p>
107
108 <h3>Creating a styled component</h3>
109
110 <p>Create a new file called <b>button_coolstyle.h</b>, and insert the following
111 code into it:</p>
112
113 <code>
114 #ifndef header_button_coolstyle
115 #define header_button_coolstyle
116
117 #include <ClanLib/gui.h>
118 #include "stylemanager_coolstyle.h"
119
120 class CL_Button_CoolTheme : public CL_ComponentStyle
121 {
122 public:
123 CL_Button_CoolTheme(CL_Button *button, CL_StyleManager_CoolTheme *style);
124
125 private:
126 CL_Slot slot_paint;
127 void on_paint();
128
129 CL_Button *button;
130 };
131
132 #endif
133 </code>
134
135 <p>Each component-style inherits from the class CL_ComponentStyle. The CL_Button
136 object you get in the constructor is the logic class for the button. You can
137 query it for states (is_down()) and size etc.</p>
138
139 <p>In this simple style, we only prepare to hook into the sig_paint signal -
140 therefore the slot_paint and on_paint() code. Read on for more specifics on this.</p>
141
142 <p>Create a new file called <b>button_coolstyle.cpp</b>, and insert the following
143 code into it:</p>
144
145 <code>
146 #include <ClanLib/display.h>
147 #include "button_coolstyle.h"
148
149 CL_Button_CoolTheme::CL_Button_CoolTheme(CL_Button *button, CL_StyleManager_CoolTheme *style)
150 : CL_ComponentStyle(button)
151 {
152 this->button = button;
153
154 slot_paint = button->sig_paint().connect(this, &CL_Button_CoolTheme::on_paint);
155 }
156
157 void CL_Button_CoolTheme::on_paint()
158 {
159 int button_width = button->get_width();
160 int button_height = button->get_height();
161
162 CL_Display::fill_rect(CL_Rect(1, 1, button_width - 1, button_height - 1), CL_Color(70, 120, 255));
163
164 if(button->is_down())
165 CL_Display::draw_rect(CL_Rect(0, 0, button_width, button_height), CL_Color::white);
166 else
167 CL_Display::draw_rect(CL_Rect(0, 0, button_width, button_height), CL_Color::black);
168 }
169 </code>
170
171 <p>In the constructor we hook into the sig_paint signal of the CL_Button. This allows
172 us to do custom drawing of the button.</p>
173
174 <p>The on_paint() function fetches the size of the button, and draws some simple rects,
175 based on the button state - if its pressed down or not.</p>
176
177 <h3>Testing the new style</h3>
178
179 <p>We have now created a very simple style, using only one themed component - a CL_Button.
180 Lets try to test it, and see if it behaves as we expect it to do.</p>
181
182 <code>
183 #include <ClanLib/core.h>
184 #include <ClanLib/gui.h>
185 #include <ClanLib/gl.h>
186 #include <ClanLib/application.h>
187 #include <ClanLib/display.h>
188
189 #include "stylemanager_coolstyle.h"
190
191 class StyleTest : public CL_ClanApplication
192 {
193 public:
194 int main(int argc, char** argv)
195 {
196 try
197 {
198 CL_SetupCore setup_core;
199 CL_SetupGUI setup_gui;
200 CL_SetupDisplay setup_display;
201 CL_SetupGL setup_gl;
202
203 CL_DisplayWindow window("StyleTest", 640, 480);
204
205 CL_ResourceManager resources("gui.xml");
206 CL_StyleManager_CoolTheme style(&resources);
207 CL_GUIManager gui(&style);
208
209 CL_Button button(CL_Rect(10, 10, 100, 40), "", &gui);
210
211 while (!CL_Keyboard::get_keycode(CL_KEY_ESCAPE))
212 {
213 CL_Display::clear(CL_Color::grey);
214 gui.show();
215 CL_Display::flip();
216 CL_System::keep_alive(10);
217 }
218 }
219 catch (CL_Error e)
220 {
221 std::cout << e.message.c_str() << std::endl;
222 }
223
224 return 0;
225 }
226 } app;
227 </code>
228
229 <p>Remember to copy the Resources/GUIStyleBoring files into your project,
230 so it has some fonts and resources to use. These can be replaced later with your own
231 resources.</p>
232
233 <h3>Some example GUI styles</h3>
234
235 <table border="0" cellpadding="10">
236 <tr>
237 <td align="center"><p><a href="Images/silver.jpg"><img src="Images/silver.jpg" alt=Silver height="80" border="1"></a></p>
238 <p> ClanGUIs default theme Silver</p>
239 </td>
240 <td align="center"><p><a href="Images/boring.jpg"><img src="Images/boring.jpg" alt=Boring height="80" border="1"></a></p>
241 <p>ClanGUIs default theme Boring</p>
242 </td>
243 <td align="center"><p><a href="Images/supaplex.jpg"><img src="Images/supaplex.jpg" alt=SupaPlex height="80" border="1"></a></p>
244 <p>The game Supaplex</p>
245 </td>
246 </tr>
247 <tr>
248 <td align="center"><p><a href="Images/race.jpg"><img src="Images/race.jpg" alt=Race height="80" border="1"></a></p>
249 <p>The game Race</p>
250 </td>
251 <td align="center"><p><a href="Images/raceeditor.jpg"><img src="Images/raceeditor.jpg" alt="Race Editor" height="80" border="1"></a></p>
252 <p>The gameeditor in Race</p>
253 </td>
254 <td align="center"><p><a href="Images/apoc.jpg"><img src="Images/apoc.jpg" alt=APOC height="80" border="1"></a></p>
255 <p>The game APOC</p>
256 </td>
257 </tr>
258 </table>
259
260 </body>
261 </xml>