1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Crazy Eddies GUI System: The Beginners Guide to Data Files and Defaults Initialisation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.4 -->
<script type="text/javascript">
function hasClass(ele,cls) {
return ele.className.match(new RegExp('(\\s|^)'+cls+'(\\s|$)'));
}
function addClass(ele,cls) {
if (!this.hasClass(ele,cls)) ele.className += " "+cls;
}
function removeClass(ele,cls) {
if (hasClass(ele,cls)) {
var reg = new RegExp('(\\s|^)'+cls+'(\\s|$)');
ele.className=ele.className.replace(reg,' ');
}
}
function toggleVisibility(linkObj) {
var base = linkObj.getAttribute('id');
var summary = document.getElementById(base + '-summary');
var content = document.getElementById(base + '-content');
var trigger = document.getElementById(base + '-trigger');
if ( hasClass(linkObj,'closed') ) {
summary.style.display = 'none';
content.style.display = 'block';
trigger.src = 'open.png';
removeClass(linkObj,'closed');
addClass(linkObj,'opened');
} else if ( hasClass(linkObj,'opened') ) {
summary.style.display = 'block';
content.style.display = 'none';
trigger.src = 'closed.png';
removeClass(linkObj,'opened');
addClass(linkObj,'closed');
}
return false;
}
</script>
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Crazy Eddies GUI System <span id="projectnumber">0.7.6</span></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">The Beginners Guide to Data Files and Defaults Initialisation </div> </div>
</div>
<div class="contents">
<div class="textblock"><dl class="author"><dt><b>Author:</b></dt><dd>Paul D Turner</dd></dl>
<p>It is assumed that prior to reading this tutorial you are already familiar with the concepts surrounding CEGUI's <a class="el" href="classCEGUI_1_1ResourceProvider.html" title="Abstract class that defines the required interface for all resource provider sub-classes.">ResourceProvider</a> and have correctly initialised your <a class="el" href="classCEGUI_1_1Renderer.html" title="Abstract class defining the basic required interface for Renderer objects.">Renderer</a> and the <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> <a class="el" href="classCEGUI_1_1System.html" title="The System class is the CEGUI class that provides access to all other elements in this system...">System</a> objects. If you've not yet covered these topics, it is highly recommended that you read <a class="el" href="rendering_tutorial.html">The Beginners Guide to Getting CEGUI Rendering</a> and <a class="el" href="resprov_tutorial.html">The Beginners Guide to resource loading with ResourceProviders</a>.</p>
<p><br/>
</p>
<h2><a class="anchor" id="datafile_tutorial_intro"></a>
Introduction</h2>
<p><a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> uses a variety of different data files and - at least initially - it's possible there may be some confusion as to what exactly all these files are and how they relate to one another. In addition, there are some system wide defaults that - while not technically <em>required</em> to be set - you will almost certainly want to set for the majority of your applications using <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>.</p>
<p>This tutorial will serve as an introduction to these topics in order that you can be more comfortable with the data files and with setting the basic default options used with <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>.</p>
<p><br/>
</p>
<h2><a class="anchor" id="datafile_tutorial_allxml"></a>
Font, Imageset, LookNFeel, Scheme, XSD? It's all XML!</h2>
<p>With the exception of graphical image files, script language files and loadable modules (.dll /. so files, etc), all the data files used with <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> are XML based. This actually leads us to the first potential obstacle that you may run into: the .xsd schema files.</p>
<h3><a class="anchor" id="datafile_tutorial_validation"></a>
Schema Validation with Xerces-C++</h3>
<p>Although the Expat based XML parser module has now (largely) become the default choice for parsing the XML data files, the previous long time default - and still this authors preferred choice - is the parser based upon the Xerces-C++ library from the Apache Software Foundation (see <a href="http://xerces.apache.org/xerces-c">http://xerces.apache.org/xerces-c</a>).</p>
<p>The advantage of using this particular parser is that it provides <em>schema validation</em>. For the uninitiated, schema validation is a means by which the incoming XML data can be checked to ensure it is well formed and that it contains the required information. In order for this validation to work, some additional files - unsurprisingly known as schema files (not to be confused with CEGUI's own <em>scheme files</em> described below) - are required. The schema files used to validate the XML for <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> can be found in the <code>datafiles/xml_schema/</code> directory within the <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> distribution, and have the .xsd file extension.</p>
<p>The main thing you need to know for now is that when using the Xerces-C++ based XML parser, these .xsd files must be available to the <a class="el" href="classCEGUI_1_1ResourceProvider.html" title="Abstract class that defines the required interface for all resource provider sub-classes.">ResourceProvider</a> system; this is probably best achieved by setting up a resource group to the directory containing the schema files and setting that group as the default to be used by <a class="el" href="classCEGUI_1_1XercesParser.html" title="Implementation of XMLParser using Xerces-C++.">CEGUI::XercesParser</a> when loading schema files (the specifics on how to do this are covered in <a class="el" href="resprov_tutorial.html">The Beginners Guide to resource loading with ResourceProviders</a>).</p>
<p><br/>
</p>
<h2><a class="anchor" id="datafile_tutorial_files"></a>
The Data Files</h2>
<p>As previously mentioned, the majority of the data files in <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> are XML based. Rather than using a generic '.xml' file extension, the data files are usually named according to what the files actually represent; for example .imageset for an <a class="el" href="classCEGUI_1_1Imageset.html" title="Offers functions to define, access, and draw, a set of image components on a single graphical surface...">Imageset</a> and .font for a <a class="el" href="classCEGUI_1_1Font.html" title="Class that encapsulates a typeface.">Font</a> (this naming convention is not, however, a requirement of the system - you are free to name the files any way you like). There now follows a very brief overview of the purpose each file type.</p>
<h3><a class="anchor" id="datafile_tutorial_imageset"></a>
Imageset</h3>
<p>An <a class="el" href="classCEGUI_1_1Imageset.html" title="Offers functions to define, access, and draw, a set of image components on a single graphical surface...">Imageset</a> is a collection of named regions upon some source surface, such as an image file or texture. In <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> terminology, each of these named regions is an <a class="el" href="classCEGUI_1_1Image.html" title="Class that represents a single Image of an Imageset.">Image</a> and is the basic level of imagery used by <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>. By modifying the source image file or texture content, or by modifying the areas of the defined regions within the <a class="el" href="classCEGUI_1_1Imageset.html" title="Offers functions to define, access, and draw, a set of image components on a single graphical surface...">Imageset</a> file, you can easily change the appearance of what gets drawn by <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>.</p>
<p>For a complete description of imageset files, please see <a class="el" href="xml_imageset.html">Imageset XML files.</a></p>
<h3><a class="anchor" id="datafile_tutorial_font"></a>
Font</h3>
<p>A <a class="el" href="classCEGUI_1_1Font.html" title="Class that encapsulates a typeface.">Font</a> file, unsurprisingly, defines a font for use in <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>. There are at present two types of font which may be defined:</p>
<ul>
<li><a class="el" href="classCEGUI_1_1FreeTypeFont.html" title="Implementation of the Font class interface using the FreeType library.">FreeTypeFont</a>: This is a font based upon a standard font file (such as a true-type '.ttf' font). A <a class="el" href="classCEGUI_1_1FreeTypeFont.html" title="Implementation of the Font class interface using the FreeType library.">FreeTypeFont</a> is specified via the attribute <code>Type="FreeType"</code> in the .font XML file.</li>
<li><a class="el" href="classCEGUI_1_1PixmapFont.html" title="Implementation of the Font class interface using static Imageset's.">PixmapFont</a>: This type of font is based upon an <a class="el" href="classCEGUI_1_1Imageset.html" title="Offers functions to define, access, and draw, a set of image components on a single graphical surface...">Imageset</a> which defines Images for the font glyphs, and is best thought of as a bitmapped font. A <a class="el" href="classCEGUI_1_1PixmapFont.html" title="Implementation of the Font class interface using static Imageset's.">PixmapFont</a> is specified via the attribute <code>Type="Pixmap"</code> in the .font XML file.</li>
</ul>
<p>For a complete description of font files, please see <a class="el" href="xml_font.html">Font XML files.</a></p>
<h3><a class="anchor" id="datafile_tutorial_looknfeel"></a>
LookNFeel</h3>
<p>LookNFeel files form a major part of CEGUI's skinning system. Each will contain one or more WidgetLook definitions that describe to the system various imagery and child widget components, their locations, additional property values and so on an so forth. These WidgetLook specifications are later bound to concrete elements within the system to form what are ultimately represented as the windows and widgets in <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>.</p>
<p>For a complete description of looknfeel files (and other skinning related material), please see <a class="el" href="fal_man.html">Falagard skinning system for CEGUI</a></p>
<h3><a class="anchor" id="datafile_tutorial_scheme"></a>
Scheme</h3>
<p>A <a class="el" href="classCEGUI_1_1Scheme.html" title="A class that groups a set of GUI elements and initialises the system to access those elements...">Scheme</a> file is a largely means to group other data files and resources together, and to define some of their interactions, and form a single point to load what might be considered a 'skin' for CEGUI's windows and widgets. A <a class="el" href="classCEGUI_1_1Scheme.html" title="A class that groups a set of GUI elements and initialises the system to access those elements...">Scheme</a> can contain one or more of the following:</p>
<ul>
<li><code><a class="el" href="classCEGUI_1_1Imageset.html" title="Offers functions to define, access, and draw, a set of image components on a single graphical surface...">Imageset</a></code> Specifies an <a class="el" href="classCEGUI_1_1Imageset.html" title="Offers functions to define, access, and draw, a set of image components on a single graphical surface...">Imageset</a> file to be loaded as part of the scheme.</li>
<li><code><a class="el" href="classCEGUI_1_1Font.html" title="Class that encapsulates a typeface.">Font</a></code> Specifies a <a class="el" href="classCEGUI_1_1Font.html" title="Class that encapsulates a typeface.">Font</a> file to be loaded as part of the scheme.</li>
<li><code>LookNFeel</code> Specifies a LookNFeel file to be loaded as part of the scheme.</li>
<li><code>WindowSet</code> Specifies the name of a loadable module, and a set of widget names contained within that module that you wish to register with the system (if no names are listed, all available types in the module are registered). This is a convenient way of adding additional core widget types to <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> (especially if the module is provided by a third party).</li>
<li><code>WindowRendererSet</code> Specifies the name of a loadable module, and a set of window renderer names contained within that module that you wish to register with the system (if no names are listed, all available types in the module are registered). A 'Window Renderer' is an object that can control rendering for some base window type(s), all the window renderer objects supplied with <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> perform rendering by making use of the 'Falagard' skinning system (though this is not a strict requirement).</li>
<li><code>WindowAlias</code> Provides a means to refer to a window / widget type by alternative names, it can also be used to 'hide' an already registered widget type with another widget type (so that other widget type gets used instead).</li>
<li><code>FalagardMapping</code> Creates a new usable window type by linking a concrete window/widget type, a window renderer type and a widget look definition.</li>
</ul>
<p>For a complete description of scheme files, please see <a class="el" href="xml_scheme.html">Scheme XML files.</a></p>
<h3><a class="anchor" id="datafile_tutorial_layout"></a>
Layout</h3>
<p>A layout file contains an XML representation of a window layout. Each nested 'Window' element defines a window or widget to be created, the 'Property' elements define the desired settings and property values for each window defined.</p>
<p>For a complete description of layout files, please see <a class="el" href="xml_layout.html">Layout XML files.</a></p>
<h3><a class="anchor" id="datafile_tutorial_config"></a>
Config</h3>
<p>CEGUI's config file support allows you to specify all the system defaults, initial resources to be loaded, as well as initialisation and termination script files to execute (when using a <a class="el" href="classCEGUI_1_1ScriptModule.html" title="Abstract interface required for all scripting support modules to be used with the CEGUI system...">ScriptModule</a>), without writing a line of C++ code beyond that which creates the <a class="el" href="classCEGUI_1_1Renderer.html" title="Abstract class defining the basic required interface for Renderer objects.">Renderer</a> and <a class="el" href="classCEGUI_1_1System.html" title="The System class is the CEGUI class that provides access to all other elements in this system...">System</a> objects.</p>
<p>For a complete description of config files, please see <a class="el" href="xml_config.html">CEGUI Configuration XML files.</a></p>
<p><br/>
</p>
<h2><a class="anchor" id="datafile_tutorial_load_basics"></a>
Loading the Basic Files</h2>
<p>In order to get things up and running you need to load in some files. The typical set of files needed are:</p>
<ul>
<li><a class="el" href="classCEGUI_1_1Imageset.html" title="Offers functions to define, access, and draw, a set of image components on a single graphical surface...">Imageset</a></li>
<li><a class="el" href="classCEGUI_1_1Font.html" title="Class that encapsulates a typeface.">Font</a></li>
<li>LookNFeel</li>
<li><a class="el" href="classCEGUI_1_1Scheme.html" title="A class that groups a set of GUI elements and initialises the system to access those elements...">Scheme</a></li>
</ul>
<p>The good thing about the <a class="el" href="classCEGUI_1_1Scheme.html" title="A class that groups a set of GUI elements and initialises the system to access those elements...">Scheme</a> file - as you may have gathered from the above description - is that it can automatically load the other files for you. For the purposes of this tutorial, we will load a scheme file and a font file - it is assumed the scheme automatically loads an <a class="el" href="classCEGUI_1_1Imageset.html" title="Offers functions to define, access, and draw, a set of image components on a single graphical surface...">Imageset</a> and LookNFeel for us. Loading the scheme and font files is done as follows: </p>
<div class="fragment"><pre class="fragment"><span class="comment">// create (load) the TaharezLook scheme file</span>
<span class="comment">// (this auto-loads the TaharezLook looknfeel and imageset files)</span>
CEGUI::SchemeManager::getSingleton().<a class="code" href="classCEGUI_1_1NamedXMLResourceManager.html#a13093b377ff84b3cfbd285aaa83ee166" title="Creates a new T object from an XML file and adds it to the collection.">create</a>( <span class="stringliteral">"TaharezLook.scheme"</span> );
<span class="comment">// create (load) a font.</span>
<span class="comment">// The first font loaded automatically becomes the default font, but note</span>
<span class="comment">// that the scheme might have already loaded a font, so there may already</span>
<span class="comment">// be a default set - if we want the "Commonweath-10" font to definitely</span>
<span class="comment">// be the default, we should set the default explicitly afterwards.</span>
CEGUI::FontManager::getSingleton().<a class="code" href="classCEGUI_1_1NamedXMLResourceManager.html#a13093b377ff84b3cfbd285aaa83ee166" title="Creates a new T object from an XML file and adds it to the collection.">create</a>( <span class="stringliteral">"DejaVuSans-10.font"</span> );
</pre></div><p>In the above code (and in the <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> samples) it is assumed that the resource group locations and the default groups have all been set up as described in <a class="el" href="resprov_tutorial.html">The Beginners Guide to resource loading with ResourceProviders</a>.</p>
<p><br/>
</p>
<h2><a class="anchor" id="datafile_tutorial_setup_defaults"></a>
System Defaults Initialisation</h2>
<p>Finally, you need to specify some default options for the <a class="el" href="classCEGUI_1_1System.html" title="The System class is the CEGUI class that provides access to all other elements in this system...">System</a>. This ensures that the system always has a font and mouse cursor available for when a window or widget specifies no preference of its own.</p>
<p>The <a class="el" href="classCEGUI_1_1FontManager.html" title="Class providing a shared library of Font objects to the system.">FontManager</a> automatically sets the first loaded font as the system default. If this is not the default font you require, or if you can not guarantee the order fonts are loaded, you should set the default explicitly, as in this code: </p>
<div class="fragment"><pre class="fragment"><a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">System::getSingleton</a>().<a class="code" href="classCEGUI_1_1System.html#a14ee40f59dec7d59cda50ba73a1e2193" title="Set the default font to be used by the system.">setDefaultFont</a>( <span class="stringliteral">"DejaVuSans-10"</span> );
</pre></div><p>Another default object you'll normally set is a mouse cursor. This ensures that when you move the mouse over any element that does not set a cursor of its own, the cursor does not disappear. The code to set the default mouse cursor is as follows (This uses the TaharezLook imageset which was loaded by the scheme above): </p>
<div class="fragment"><pre class="fragment"><a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">System::getSingleton</a>().<a class="code" href="classCEGUI_1_1System.html#a6bc0cdd5908d26876fd86b0cf9119b1f" title="Set the image to be used as the default mouse cursor.">setDefaultMouseCursor</a>( <span class="stringliteral">"TaharezLook"</span>, <span class="stringliteral">"MouseArrow"</span> );
</pre></div><p>Finally, if you intend to use tool tips, you should specify the name of the ToolTip based widget type that you want used for that purpose. It is actually possible to set this on a per-window basis, though this is not normally required, and is beyond the scope of this introductory tutorial. The code to set the default tool tip window type looks like this: </p>
<div class="fragment"><pre class="fragment"><a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">System::getSingleton</a>().setDefaultToolTip( <span class="stringliteral">"TaharezLook/Tooltip"</span> );
</pre></div><p><br/>
</p>
<h2><a class="anchor" id="datafile_tutorial_conclusion"></a>
Conclusion</h2>
<p>Here we have discovered the very basics of what the various data files used by <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> are, how they are loaded, and the minimal initialisation needed for <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> applications. </p>
</div></div>
<hr class="footer"/><address class="footer"><small>Generated on Sun Jan 22 2012 16:07:40 for Crazy Eddies GUI System by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
</body>
</html>
|
