| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>GUI Resources</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<p align="center"> |
| 8 |
<a href="#component">Component</a> | |
| 9 |
<a href="#button">Button</a> | |
| 10 |
<a href="#frame">Frame</a> | |
| 11 |
<a href="#image">Image</a> | |
| 12 |
<a href="#inputbox">InputBox</a> | |
| 13 |
<a href="#label">Label</a> | |
| 14 |
<a href="#listbox">ListBox</a> | |
| 15 |
<a href="#progressbar">ProgressBar</a> | |
| 16 |
<a href="#radiobutton">RadioButton</a> | |
| 17 |
<a href="#scrollbar">ScrollBar</a> | |
| 18 |
<a href="#window">Window</a> |
| 19 |
</p> |
| 20 |
|
| 21 |
<h3>GUI definition files (.xml)</h3> |
| 22 |
<p> |
| 23 |
Instead of hardcoding every GUI components by code, you can use a GUI definition file to define the placement, |
| 24 |
attributes and hierarchy of GUI components. The GUI definition format looks a lot like the ClanLib resource |
| 25 |
manager format, so if you're familiar with that, you should easily get acquainted with the GUI definition |
| 26 |
format. GUI files do not have sections. Instead, components can contain child-components within a <components> |
| 27 |
tag, simply function as "sections". This means that the hierarchical structure of the GUI is directly readable |
| 28 |
from the GUI definition file. Let's look at a small example; |
| 29 |
</p> |
| 30 |
<code> |
| 31 |
<components> |
| 32 |
<window name="my_window" x="10" y="10" width="600" height="400" title="My Window" > |
| 33 |
<components> |
| 34 |
<button name="my_button" x="25" y="25" width="100" height="20" text="My Button" /> |
| 35 |
<label name="my_label" x="25" y="50" text="My label" /> |
| 36 |
</components> |
| 37 |
</window> |
| 38 |
</components> |
| 39 |
</code> |
| 40 |
|
| 41 |
<p>A window named my_window is the top-level component here. As this component is at the top of the component |
| 42 |
hierarchy, the x, y position is directly mapped to the parent GUI item. Since this window has no GUI parent, |
| 43 |
the coordinates aremapped to your <codelink>CL_DisplayWindow</codelink>. Each sub-somponent's x/y values are |
| 44 |
relative to the current position of their parent. This means that my_button will always be offset (25, 25) |
| 45 |
pixels from the upper-left corner of the client area of the window, and that both my_button and my_label |
| 46 |
will be dragged along if my_window is moved. Width and height is not relative to any parents, and is measured |
| 47 |
in pixels also. However, all sub-components are clipped within the screen area of the parent. |
| 48 |
</p> |
| 49 |
|
| 50 |
<p>Every component type recognize different sets of values in the .xml file. Some values |
| 51 |
are mandatory for a component (they have to exist in the .xml-file for the initialization to succeed), |
| 52 |
and some are optional, and have default values in case they don't exist. All component types require |
| 53 |
the 'x' and 'y' value, describing the position/offset of the component in question. |
| 54 |
</p> |
| 55 |
|
| 56 |
<p>Note that all components need to be within a <components> tag. This goes for |
| 57 |
the root items, and also children of other components.</p> |
| 58 |
|
| 59 |
<p>Example code to load a GUI definition file:</p> |
| 60 |
|
| 61 |
<code> |
| 62 |
CL_ResourceManager resources("resources.xml"); |
| 63 |
CL_StyleManager_Silver style(&resources); |
| 64 |
CL_GUIManager gui(&style); |
| 65 |
|
| 66 |
CL_ComponentManager manager("mygui.xml", &gui); |
| 67 |
|
| 68 |
gui.run(); |
| 69 |
</code> |
| 70 |
|
| 71 |
<p>This code is fairly simple, but a few things need to be explained.</p> |
| 72 |
<ul> |
| 73 |
<li>The "resources.xml" file <b>must</b> contain items that describe the GUI style. The easiest way to do this is to copy the files required from the "Resources" directory of your ClanLib distribution.</li> |
| 74 |
<li>The "mygui.xml" file contains the GUI layout code, as listed above.</li> |
| 75 |
<li>Finally, calling "gui.run();" will block all further execution. This may, or may not be what you want. You can call "gui.show();" to draw the GUI to the screen exactly once. For more information, see <codelink>CL_GUIManager</codelink>.</li> |
| 76 |
</ul> |
| 77 |
<p>To access individual components from a definition file, you use the |
| 78 |
CL_ComponentManager::get_component function. Some examples:</p> |
| 79 |
|
| 80 |
<code> |
| 81 |
// Hook up the button click signal to a function |
| 82 |
CL_Button *my_button = (CL_Button *) manager.get_component("my_button"); |
| 83 |
CL_Slot s = my_button->sig_clicked().connect(this, &App::on_button_clicked); |
| 84 |
</code> |
| 85 |
|
| 86 |
<p>If you have RTTI enabled in your project, you can also use the following approach:</p> |
| 87 |
<code> |
| 88 |
CL_Button *my_button; |
| 89 |
manager.get_component("my_button", &my_button); |
| 90 |
</code> |
| 91 |
|
| 92 |
<br/> |
| 93 |
<h3>Methods for running a GUI and rendering game graphics</h3> |
| 94 |
<p>If you want to draw directly to the screen <b>and</b> run a GUI at the same time, there are two options |
| 95 |
available to you.</p> |
| 96 |
<h4>Option 1: Use gui.show()</h4> |
| 97 |
<p>Instead of calling "gui.run()" in the above example, you can simply call "gui.show()" every time the GUI needs |
| 98 |
to be drawn to the screen. It's up to you to decide how often to redraw the GUI. Calling "gui.show()" from within |
| 99 |
your own render loop is very easy to do, but is slow without code to detect when the GUI needs to be redrawn.</p> |
| 100 |
<h4>Option 2: Use the sig_paint event.</h4> |
| 101 |
<p>A sig_paint signal is emitted every time the GUI is redrawn. You can use this event to draw your own graphics |
| 102 |
before the GUI is drawn to the screen. Simply connect one of your own methods to the paint event:</p> |
| 103 |
<code> |
| 104 |
CL_Slot m_slotOnPaint = gui.sig_paint().connect(this, &Game::OnRender); |
| 105 |
</code> |
| 106 |
<p>All you need to do is create the "Game::OnRender" class (obviously replace "Game" with the name of your class).</p> |
| 107 |
<h3>Putting GUI definitions inside ClanLib resource files</h3> |
| 108 |
|
| 109 |
<p> |
| 110 |
Now that ClanLib uses XML for both the resources and the gui definitions, you can actually put them |
| 111 |
both into the same file. |
| 112 |
</p> |
| 113 |
|
| 114 |
<code> |
| 115 |
<resources> |
| 116 |
<!-- Include all resources from the silver theme here too --> |
| 117 |
<surface name="button_up" file="resources/button_up.tga" /> |
| 118 |
|
| 119 |
<components name="gui"> |
| 120 |
<button x="10" y="190" surface_up="button_up" /> |
| 121 |
</components> |
| 122 |
</resources> |
| 123 |
</code> |
| 124 |
|
| 125 |
<p>And some code to load it:</p> |
| 126 |
<code> |
| 127 |
CL_ResourceManager resources("resources.xml"); |
| 128 |
CL_StyleManager_Silver style(&resources); |
| 129 |
CL_GUIManager gui(&style); |
| 130 |
|
| 131 |
CL_ComponentManager manager("gui", &resources, &gui); |
| 132 |
|
| 133 |
gui.run(); |
| 134 |
</code> |
| 135 |
|
| 136 |
<br/> |
| 137 |
<h3>Component options</h3> |
| 138 |
|
| 139 |
<p>The following section describes all the component attributes available for |
| 140 |
each component.</p> |
| 141 |
|
| 142 |
<br/> |
| 143 |
<h4><a name="component">Component</a></h4> |
| 144 |
|
| 145 |
<p>This is the base class all other components inherit. So every other component |
| 146 |
has these basic attributes.</p> |
| 147 |
|
| 148 |
<p>Tag name: <b><component></b><br/> |
| 149 |
Class name: <codelink>CL_Component</codelink></p> |
| 150 |
|
| 151 |
<ul> |
| 152 |
<li>Attribute <b>name</b>: Name of gui component.<br/> |
| 153 |
<i>Valid values</i>: String<br> |
| 154 |
<i>Default value</i>: "" |
| 155 |
</li> |
| 156 |
<li>Attribute <b>x</b>: Position x of component.<br/> |
| 157 |
<i>Valid values</i>: Integer<br> |
| 158 |
<i>Default value</i>: 0 |
| 159 |
</li> |
| 160 |
<li>Attribute <b>y</b>: Position y of component.<br/> |
| 161 |
<i>Valid values</i>: Integer<br> |
| 162 |
<i>Default value</i>: 0 |
| 163 |
</li> |
| 164 |
<li>Attribute <b>width</b>: Width of component.<br/> |
| 165 |
<i>Valid values</i>: Integer<br> |
| 166 |
<i>Default value</i>: 0 |
| 167 |
</li> |
| 168 |
<li>Attribute <b>height</b>: Height of component.<br/> |
| 169 |
<i>Valid values</i>: Integer<br> |
| 170 |
<i>Default value</i>: 0 |
| 171 |
</li> |
| 172 |
<li>Attribute <b>visible</b>: Visibility of component.<br/> |
| 173 |
<i>Valid values</i>: Boolean<br> |
| 174 |
<i>Default value</i>: true |
| 175 |
</li> |
| 176 |
<li>Attribute <b>enabled</b>: If the component is enabled or disabled.<br/> |
| 177 |
<i>Valid values</i>: Boolean<br> |
| 178 |
<i>Default value</i>: true |
| 179 |
</li> |
| 180 |
<li>Attribute <b>tab_id</b>: Tab id.<br/> |
| 181 |
<i>Valid values</i>: Integer<br> |
| 182 |
<i>Default value</i>: 0 |
| 183 |
</li> |
| 184 |
</ul> |
| 185 |
|
| 186 |
<p>Examples:</p> |
| 187 |
<code> |
| 188 |
<component name="component1" x="10" y="10" width="100" height="20" /> |
| 189 |
<component name="component2" x="10" y="30" width="70" height="20" enabled="false" tab_id="3"/> |
| 190 |
<component name="component3" x="10" y="50" width="80" height="40" visible="false" /> |
| 191 |
</code> |
| 192 |
|
| 193 |
<br/> |
| 194 |
<h4><a name="button">Button</a></h4> |
| 195 |
|
| 196 |
<p>Tag name: <b><button></b><br/> |
| 197 |
Class name: <codelink>CL_Button</codelink></p> |
| 198 |
|
| 199 |
<ul> |
| 200 |
<li>Attribute <b>text</b>: The text on the button.<br/> |
| 201 |
<i>Valid values</i>: String<br> |
| 202 |
<i>Default value</i>: "" |
| 203 |
</li> |
| 204 |
<li>Attribute <b>toggled</b>: If the button is toggled by default or not.<br/> |
| 205 |
<i>Valid values</i>: Boolean<br> |
| 206 |
<i>Default value</i>: false |
| 207 |
</li> |
| 208 |
<li>Attribute <b>togglemode</b>: The togglemode, if false the button is sticky.<br/> |
| 209 |
<i>Valid values</i>: Boolean<br> |
| 210 |
<i>Default value</i>: false |
| 211 |
</li> |
| 212 |
</ul> |
| 213 |
|
| 214 |
<p>Examples:</p> |
| 215 |
<code> |
| 216 |
<button name="button1" togglemode="true" x="10" y="10" width="100" height="20" text="Stick me!" /> |
| 217 |
<button name="button2" x="10" y="40" width="100" height="20" text="Press me!" /> |
| 218 |
<button name="button3" x="10" y="70" text="Auto size" /> |
| 219 |
</code> |
| 220 |
|
| 221 |
<br/> |
| 222 |
<h4><a name="frame">Frame</a></h4> |
| 223 |
|
| 224 |
<p>Tag name: <b><frame></b><br/> |
| 225 |
Class name: <codelink>CL_Frame</codelink></p> |
| 226 |
|
| 227 |
<ul> |
| 228 |
<li>Attribute <b>filled</b>: If the frame should be filled or transparent.<br/> |
| 229 |
<i>Valid values</i>: Boolean<br/> |
| 230 |
<i>Default value</i>: false |
| 231 |
</li> |
| 232 |
</ul> |
| 233 |
|
| 234 |
<p>Examples:</p> |
| 235 |
<code> |
| 236 |
<frame name="frame1" x="10" y="10" width="100" height="20" filled="true" /> |
| 237 |
<frame x="10" y="35" width="100" height="20" /> |
| 238 |
</code> |
| 239 |
|
| 240 |
<br/> |
| 241 |
<h4><a name="image">Image</a></h4> |
| 242 |
|
| 243 |
<p>Tag name: <b><image></b><br/> |
| 244 |
Class name: <codelink>CL_Image</codelink></p> |
| 245 |
|
| 246 |
<ul> |
| 247 |
<li>Attribute <b></b>:<br/> |
| 248 |
<i>Valid values</i>: <br> |
| 249 |
<i>Default value</i>: |
| 250 |
</li> |
| 251 |
</ul> |
| 252 |
|
| 253 |
<p>Example:</p> |
| 254 |
<code> |
| 255 |
</code> |
| 256 |
|
| 257 |
<br/> |
| 258 |
<h4><a name="inputbox">InputBox</a></h4> |
| 259 |
|
| 260 |
<p>Tag name: <b><inputbox></b><br/> |
| 261 |
Class name: <codelink>CL_InputBox</codelink></p> |
| 262 |
|
| 263 |
<ul> |
| 264 |
<li>Attribute <b>text</b>: Default input of the inputbox.<br/> |
| 265 |
<i>Valid values</i>: String<br> |
| 266 |
<i>Default value</i>: "" |
| 267 |
</li> |
| 268 |
<li>Attribute <b>passwordmode</b>: Password mode sets if the inputbox should display only * when entering text.<br/> |
| 269 |
<i>Valid values</i>: Boolean<br> |
| 270 |
<i>Default value</i>: false |
| 271 |
</li> |
| 272 |
<li>Attribute <b>read_only</b>: If read only, it is not possible to enter text into the inputbox.<br/> |
| 273 |
<i>Valid values</i>: Boolean<br> |
| 274 |
<i>Default value</i>: false |
| 275 |
</li> |
| 276 |
<li>Attribute <b>max_length</b>: Max number of characters allowed.<br/> |
| 277 |
<i>Valid values</i>: Integer<br> |
| 278 |
<i>Default value</i>: unlimited |
| 279 |
</li> |
| 280 |
</ul> |
| 281 |
|
| 282 |
<p>Examples:</p> |
| 283 |
<code> |
| 284 |
<inputbox name="inputbox1" x="10" y="10" width="100" height="20" text="Default value" /> |
| 285 |
<inputbox name="inputbox2" x="10" y="35" width="100" height="20" max_length="4" passwordmode="true" /> |
| 286 |
</code> |
| 287 |
|
| 288 |
<br/> |
| 289 |
<h4><a name="label">Label</a></h4> |
| 290 |
|
| 291 |
<p>Tag name: <b><label></b><br/> |
| 292 |
Class name: <codelink>CL_Label</codelink></p> |
| 293 |
|
| 294 |
<ul> |
| 295 |
<li>Attribute <b>text</b>: The text of the label.<br/> |
| 296 |
<i>Valid values</i>: String<br> |
| 297 |
<i>Default value</i>: "" |
| 298 |
</li> |
| 299 |
</ul> |
| 300 |
|
| 301 |
<p>Example:</p> |
| 302 |
<code> |
| 303 |
<label x="10" y="10" width="100" height="20" text="Welcome to ClanGUI!" /> |
| 304 |
</code> |
| 305 |
|
| 306 |
<br/> |
| 307 |
<h4><a name="listbox">ListBox</a></h4> |
| 308 |
|
| 309 |
<p>Tag name: <b><listbox></b><br/> |
| 310 |
Class name: <codelink>CL_ListBox</codelink></p> |
| 311 |
|
| 312 |
<ul> |
| 313 |
<li>Child element <b>item</b>: Defines a item in the listbox. |
| 314 |
<ul> |
| 315 |
<li>Attribute <b>value</b>: Text of the listitem.<br/> |
| 316 |
<i>Valid values</i>: String<br> |
| 317 |
<i>Default value</i>: "" |
| 318 |
</li> |
| 319 |
</ul> |
| 320 |
</li> |
| 321 |
</ul> |
| 322 |
|
| 323 |
<p>Example:</p> |
| 324 |
<code> |
| 325 |
<listbox name="listbox1" x="10" y="10" width="100" height="100"> |
| 326 |
<item value="Item 1" /> |
| 327 |
<item value="Item 2" /> |
| 328 |
<item value="Item 3" /> |
| 329 |
</listbox> |
| 330 |
</code> |
| 331 |
|
| 332 |
<br/> |
| 333 |
<h4><a name="progressbar">ProgressBar</a></h4> |
| 334 |
|
| 335 |
<p>Tag name: <b><progressbar></b><br/> |
| 336 |
Class name: <codelink>CL_ProgressBar</codelink></p> |
| 337 |
|
| 338 |
<ul> |
| 339 |
<li>Attribute <b>steps</b>: Number of steps in the progressbar.<br/> |
| 340 |
<i>Valid values</i>: Integer<br> |
| 341 |
<i>Default value</i>: 0 |
| 342 |
</li> |
| 343 |
</ul> |
| 344 |
|
| 345 |
<p>Example:</p> |
| 346 |
<code> |
| 347 |
<progressbar name="progressbar1" x="10" y="10" width="100" height="20" steps="100" /> |
| 348 |
</code> |
| 349 |
|
| 350 |
<br/> |
| 351 |
<h4><a name="radiobutton">RadioButton</a></h4> |
| 352 |
|
| 353 |
<p>Tag name: <b><radiobutton></b><br/> |
| 354 |
Class name: <codelink>CL_RadioButton</codelink></p> |
| 355 |
|
| 356 |
<ul> |
| 357 |
<li>Attribute <b></b>:<br/> |
| 358 |
<i>Valid values</i>: <br> |
| 359 |
<i>Default value</i>: |
| 360 |
</li> |
| 361 |
</ul> |
| 362 |
|
| 363 |
<p>Example:</p> |
| 364 |
<code> |
| 365 |
</code> |
| 366 |
|
| 367 |
<br/> |
| 368 |
<h4><a name="scrollbar">ScrollBar</a></h4> |
| 369 |
|
| 370 |
<p>Tag name: <b><scrollbar></b><br/> |
| 371 |
Class name: <codelink>CL_ScrollBar</codelink></p> |
| 372 |
|
| 373 |
<ul> |
| 374 |
<li>Attribute <b>orientation</b>: The orientation of the scrollbar, horizontal or vertical.<br/> |
| 375 |
<i>Valid values</i>: hor, horz, horizontal, 1 = horizontal orientation - ver, vert, vertical, 0 = vertical orientation<br> |
| 376 |
<i>Default value</i>: vertical |
| 377 |
</li> |
| 378 |
<li>Attribute <b>min</b>: Minimum value of the scrollbar range.<br/> |
| 379 |
<i>Valid values</i>: Integer<br> |
| 380 |
<i>Default value</i>: 0 |
| 381 |
</li> |
| 382 |
<li>Attribute <b>max</b>: Maximum value of the scrollbar range.<br/> |
| 383 |
<i>Valid values</i>: Integer<br> |
| 384 |
<i>Default value</i>: value of minimum |
| 385 |
</li> |
| 386 |
<li>Attribute <b>value</b>: Current value of the scrollbar range.<br/> |
| 387 |
<i>Valid values</i>: Integer<br> |
| 388 |
<i>Default value</i>: value of minimum |
| 389 |
</li> |
| 390 |
<li>Attribute <b>tracking</b>: Enables or disables tracking.<br/> |
| 391 |
<i>Valid values</i>: Boolean<br> |
| 392 |
<i>Default value</i>: false |
| 393 |
</li> |
| 394 |
</ul> |
| 395 |
|
| 396 |
<p>Examples:</p> |
| 397 |
<code> |
| 398 |
<scrollbar name="scrollbar1" x="160" y="10" width="20" height="220" min="0" orientation="ver" max="100" /> |
| 399 |
<scrollbar name="scrollbar2" x="10" y="230" width="150" height="20" min="0" max="10" orientation="hor" /> |
| 400 |
</code> |
| 401 |
|
| 402 |
<br/> |
| 403 |
<h4><a name="window">Window</a></h4> |
| 404 |
|
| 405 |
<p>Tag name: <b><window></b><br/> |
| 406 |
Class name: <codelink>CL_Window</codelink></p> |
| 407 |
|
| 408 |
<ul> |
| 409 |
<li>Attribute <b>title</b>: Title of the window.<br/> |
| 410 |
<i>Valid values</i>: String<br> |
| 411 |
<i>Default value</i>: "" |
| 412 |
</li> |
| 413 |
</ul> |
| 414 |
|
| 415 |
<p>Example:</p> |
| 416 |
<code> |
| 417 |
<window name="window1" x="10" y="10" width="400" height="300" title="This is a window" /> |
| 418 |
</code> |
| 419 |
|
| 420 |
</body> |
| 421 |
</xml> |