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
|
<!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 resource loading with ResourceProviders</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 resource loading with ResourceProviders </div> </div>
</div>
<div class="contents">
<div class="textblock"><dl class="author"><dt><b>Author:</b></dt><dd>Paul D Turner</dd></dl>
<p>This tutorial introduces the <a class="el" href="classCEGUI_1_1ResourceProvider.html" title="Abstract class that defines the required interface for all resource provider sub-classes.">CEGUI::ResourceProvider</a> concept, explains how to set up resource groups and directories in the DefaultResourceProvider and how to specify the default resource groups to be used by various parts of the system.</p>
<p><br/>
</p>
<h2><a class="anchor" id="resprov_tutorial_intro"></a>
What is a ResourceProvider?</h2>
<p><a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> uses a ResourceProvider object to provide a bridge between the <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> library and external file loading systems - whether this might be the basic underlying file system of the machine executing the code, or something a bit more exotic such as the resource management sub-systems offered by the Ogre3D and Irrlicht engines; by providing custom implementations of the ResourceProvider interface, it is possible for <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> to seamlessly integrate with all of these systems.</p>
<p><br/>
</p>
<h2><a class="anchor" id="resprov_tutorial_default_rp"></a>
DefaultResourceProvider Explained</h2>
<p>CEGUI's default resource provider, DefaultResourceProvider, supplies some basic functionality for those who do not yet have, or do not need, a more sophisticated alternative. As well as supplying the functions required by <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> for actually loading file data, DefaultResourceProvider also has some rudimentary support for 'resource groups'. Here, a resource group is basically a label given to a directory location on the system. This allows one to have logical grouping of files within directories and then to be able to refer to those locations via a simple label rather than hard coded paths. This then means that should you need to change the location of some data files, you just need to update the resource group location instead of updating path information throughout your code and XML files.</p>
<p>For users of the Ogre3D library - or users with other custom resource providers not derived from DefaultResourceProvider - <em>you should not follow the parts of this tutorial that deal with defining resouce groups and their directories</em> (you should especially ignore any example code that casts to DefaultResouceProvider). These users should follow the usual procedures for using the underlying resouce system in use (for example, in Ogre3D you might set up your resource locations in code using the Ogre::ResourceManager or via a resources.cfg file).</p>
<p>This said, <em>all users</em> should follow the parts of this tutorial dealing with setting the default resouce groups for the various resource classes, as detailed in <a class="el" href="resprov_tutorial.html#resprov_tutorial_default_resource_groups">Specifying Default Resource Groups</a>.</p>
<h3><a class="anchor" id="resprov_tutorial_default_rp_groups"></a>
Specifying Resource Groups and Directories</h3>
<p>The DefaultResourceProvider allows you to define any number of named resource groups and to specify a directory to be accessed by each of those groups. What this means is that you can create a resource group, say <code>"imagesets"</code>, and assign a directory to that group, for example <code>"./mygame/datafiles/gui/imagesets/"</code>. When loading an Imageset through the ImagesetManager, you might then specify the resource group to be used as <code>"imagesets"</code> and the system will look in the predefined location <code>"./mygame/datafiles/gui/imagesets/"</code>. Note that at present each resource group may only have a single directory associated with it.</p>
<p>A small code example is in order to clarify what has been said. Instead of loading resources by giving an explicit path, like this: </p>
<div class="fragment"><pre class="fragment">Imageset& wlis = ImagesetManager::getSingleton().create(
<span class="stringliteral">"./mygame/datafiles/gui/imagesets/WindowsLook.imageset"</span>);
</pre></div><p>At initialisation time, you set up a resource group in the default resource provider, like this: </p>
<div class="fragment"><pre class="fragment">DefaultResourceProvider* rp = <span class="keyword">static_cast<</span>DefaultResourceProvider*<span class="keyword">></span>(
<a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().getResourceProvider());
rp->setResourceGroupDirectory(<span class="stringliteral">"imagesets"</span>, <span class="stringliteral">"./mygame/datafiles/gui/imagesets/"</span>);
</pre></div><p>Then later on in the code, when you need to load an imageset, just do this: </p>
<div class="fragment"><pre class="fragment">Imageset& wlis = ImagesetManager::getSingleton().create(
<span class="stringliteral">"WindowsLook.imageset"</span>, <span class="stringliteral">"imagesets"</span>);
</pre></div><p>Note how when creating the imageset from a file we do not specify any path information; the path information is obtained from the resource group specified, in the example this is <code>"imagesets"</code>. We will later show you how you set default resource groups for each of the resource types - then you do not have to specify the group when you load a resource (unless you're loading it from a group other than the default, of course).</p>
<p>Something important to consider is that when using this resource group approach, data files that contain references to other data files should not contain relative path information - they should, in general, just have the actual file name of the file being referred to - this way the resource group system can be put to better use, and it also makes it easier to move files around later - since rather than having to 'fix up' all the relative paths, you just have to update the resource group paths instead.</p>
<p><br/>
</p>
<h2><a class="anchor" id="resprov_tutorial_default_resource_groups"></a>
Specifying Default Resource Groups</h2>
<p>Each of the core system classes that represents a loadable resource has static members to set and get a default resource group. This resource group will be used when loading the specific data files needed by a given class - in the case of the Imageset class, the default resource group should reference a directory holding the imageset xml and texture image files.</p>
<p>For each of the resource consuming classes, the static members are named the same (special exception is the xerces based XML paser - see below): </p>
<div class="fragment"><pre class="fragment"><span class="keyword">const</span> String& getDefaultResourceGroup();
<span class="keywordtype">void</span> setDefaultResourceGroup(<span class="keyword">const</span> String& groupname);
</pre></div><p>The following is a list of the core resource loading classes and the resources that they load:</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...">CEGUI::Imageset</a></code> : Imageset xml and texture image files.</li>
<li><code><a class="el" href="classCEGUI_1_1Font.html" title="Class that encapsulates a typeface.">CEGUI::Font</a></code> : Font xml and freetype loadable font files.</li>
<li><code><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...">CEGUI::Scheme</a></code> : Scheme xml files.</li>
<li><code><a class="el" href="classCEGUI_1_1WindowManager.html" title="The WindowManager class describes an object that manages creation and lifetime of Window objects...">CEGUI::WindowManager</a></code> : Window layout xml files.</li>
<li><code><a class="el" href="classCEGUI_1_1WidgetLookManager.html" title="Manager class that gives top-level access to widget data based "look and feel" specifications loaded ...">CEGUI::WidgetLookManager</a></code> : LookNFeel xml files</li>
<li><code><a class="el" href="classCEGUI_1_1ScriptModule.html" title="Abstract interface required for all scripting support modules to be used with the CEGUI system...">CEGUI::ScriptModule</a></code> : Script files in whichever scripted langauge.</li>
</ul>
<p>There is one special exception, as mentioned above, this is the Xerces-C++ based XML parser. For this there is a special resource group setting to specify where the .xsd schema files - used for XML schema validation - can be found. For this special case, you instead use the PropertySet interface and access a property named <code>SchemaDefaultResourceGroup</code>. The use of the property interface mainly serves to eliminate the need to link directly with the xerces xml based parser module just to set the default schema resource group.</p>
<p>Because you may not know ahead of time which XML parser module is actually being used - and therefore may not know whether the property exists - you should check the existence of the propery before setting it. This is better than checking the XML parser ID string for "Xerces" because it allows you to seamlessly work with any future parser module that may also offer validation (so long as it exposes the same property).</p>
<p>For example: </p>
<div class="fragment"><pre class="fragment"><span class="comment">// setup default group for validation schemas</span>
<a class="code" href="classCEGUI_1_1XMLParser.html" title="This is an abstract class that is used by CEGUI to interface with XML parser libraries.">CEGUI::XMLParser</a>* parser = <a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().getXMLParser();
<span class="keywordflow">if</span> (parser-><a class="code" href="classCEGUI_1_1PropertySet.html#a9e934325c0524576b12fa471eeecf115" title="Checks to see if a Property with the given name is in the PropertySet.">isPropertyPresent</a>(<span class="stringliteral">"SchemaDefaultResourceGroup"</span>))
parser-><a class="code" href="classCEGUI_1_1PropertySet.html#af6709b76d1e35c963e5d5c9b9111cdf7" title="Sets the current value of a Property.">setProperty</a>(<span class="stringliteral">"SchemaDefaultResourceGroup"</span>, <span class="stringliteral">"schemas"</span>);
</pre></div><p>One final thing to consider, is that the ResourceProvider class also has a default resource group. This should be considered a global or master default; it is used whenever a specific resource loading class has no default of it's own specified. This would prove useful if you have all your data in a single directory.</p>
<p><br/>
</p>
<h2><a class="anchor" id="resprov_tutorial_example"></a>
A final, Complete Example</h2>
<p>To close, we will show how you might perform the initialisation of resource groups and their target directories to access the data files within the datafiles directory that comes with <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>, and how we assign the default groups to be used for all of the resource types.</p>
<p>After initialising the core <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...">CEGUI::System</a> object as usual, we then specify a set of resource groups and their target directories (this assumes the working directory will be the 'bin' directory within the <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> package: </p>
<div class="fragment"><pre class="fragment"><span class="comment">// initialise the required dirs for the DefaultResourceProvider</span>
<a class="code" href="classCEGUI_1_1DefaultResourceProvider.html">CEGUI::DefaultResourceProvider</a>* rp = <span class="keyword">static_cast<</span><a class="code" href="classCEGUI_1_1DefaultResourceProvider.html">CEGUI::DefaultResourceProvider</a>*<span class="keyword">></span>
(<a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().getResourceProvider());
rp-><a class="code" href="classCEGUI_1_1DefaultResourceProvider.html#a0cc6e5400fad358d270475584934cce6" title="Set the directory associated with a given resource group identifier.">setResourceGroupDirectory</a>(<span class="stringliteral">"schemes"</span>, <span class="stringliteral">"../datafiles/schemes/"</span>);
rp-><a class="code" href="classCEGUI_1_1DefaultResourceProvider.html#a0cc6e5400fad358d270475584934cce6" title="Set the directory associated with a given resource group identifier.">setResourceGroupDirectory</a>(<span class="stringliteral">"imagesets"</span>, <span class="stringliteral">"../datafiles/imagesets/"</span>);
rp-><a class="code" href="classCEGUI_1_1DefaultResourceProvider.html#a0cc6e5400fad358d270475584934cce6" title="Set the directory associated with a given resource group identifier.">setResourceGroupDirectory</a>(<span class="stringliteral">"fonts"</span>, <span class="stringliteral">"../datafiles/fonts/"</span>);
rp-><a class="code" href="classCEGUI_1_1DefaultResourceProvider.html#a0cc6e5400fad358d270475584934cce6" title="Set the directory associated with a given resource group identifier.">setResourceGroupDirectory</a>(<span class="stringliteral">"layouts"</span>, <span class="stringliteral">"../datafiles/layouts/"</span>);
rp-><a class="code" href="classCEGUI_1_1DefaultResourceProvider.html#a0cc6e5400fad358d270475584934cce6" title="Set the directory associated with a given resource group identifier.">setResourceGroupDirectory</a>(<span class="stringliteral">"looknfeels"</span>, <span class="stringliteral">"../datafiles/looknfeel/"</span>);
rp-><a class="code" href="classCEGUI_1_1DefaultResourceProvider.html#a0cc6e5400fad358d270475584934cce6" title="Set the directory associated with a given resource group identifier.">setResourceGroupDirectory</a>(<span class="stringliteral">"lua_scripts"</span>, <span class="stringliteral">"../datafiles/lua_scripts/"</span>);
<span class="comment">// This is only really needed if you are using Xerces and need to</span>
<span class="comment">// specify the schemas location</span>
rp-><a class="code" href="classCEGUI_1_1DefaultResourceProvider.html#a0cc6e5400fad358d270475584934cce6" title="Set the directory associated with a given resource group identifier.">setResourceGroupDirectory</a>(<span class="stringliteral">"schemas"</span>, <span class="stringliteral">"../datafiles/xml_schemas/"</span>);
</pre></div><p> Now that is done, we have a nice set of resource groups defined with their target directories set. Finally, to get the system to use these directories, we set the default resource groups to be used: </p>
<div class="fragment"><pre class="fragment"><span class="comment">// set the default resource groups to be used</span>
<a class="code" href="classCEGUI_1_1Imageset.html#a7b857ebfef6268a02c5d2a67eec8e5a6" title="Sets the default resource group to be used when loading imageset data.">CEGUI::Imageset::setDefaultResourceGroup</a>(<span class="stringliteral">"imagesets"</span>);
<a class="code" href="classCEGUI_1_1Font.html#aeacd6cb9b090f66544a17817207adb7f" title="Sets the default resource group to be used when loading font data.">CEGUI::Font::setDefaultResourceGroup</a>(<span class="stringliteral">"fonts"</span>);
<a class="code" href="classCEGUI_1_1Scheme.html#a89422b2073ea60c1496efba52a660179" title="Sets the default resource group to be used when loading scheme xml data.">CEGUI::Scheme::setDefaultResourceGroup</a>(<span class="stringliteral">"schemes"</span>);
<a class="code" href="classCEGUI_1_1WidgetLookManager.html#a30088f26a69d88e7671e3afaa54de653" title="Sets the default resource group to be used when loading LookNFeel data.">CEGUI::WidgetLookManager::setDefaultResourceGroup</a>(<span class="stringliteral">"looknfeels"</span>);
<a class="code" href="classCEGUI_1_1WindowManager.html#af5acad18ec7a601e2d40db253a0111d9" title="Sets the default resource group to be used when loading layouts.">CEGUI::WindowManager::setDefaultResourceGroup</a>(<span class="stringliteral">"layouts"</span>);
<a class="code" href="classCEGUI_1_1ScriptModule.html#a4879fd1d26e19b57a37a835c4b7b9bf1" title="Sets the default resource group to be used when loading script files.">CEGUI::ScriptModule::setDefaultResourceGroup</a>(<span class="stringliteral">"lua_scripts"</span>);
<span class="comment">// setup default group for validation schemas</span>
<a class="code" href="classCEGUI_1_1XMLParser.html" title="This is an abstract class that is used by CEGUI to interface with XML parser libraries.">CEGUI::XMLParser</a>* parser = <a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().getXMLParser();
<span class="keywordflow">if</span> (parser-><a class="code" href="classCEGUI_1_1PropertySet.html#a9e934325c0524576b12fa471eeecf115" title="Checks to see if a Property with the given name is in the PropertySet.">isPropertyPresent</a>(<span class="stringliteral">"SchemaDefaultResourceGroup"</span>))
parser-><a class="code" href="classCEGUI_1_1PropertySet.html#af6709b76d1e35c963e5d5c9b9111cdf7" title="Sets the current value of a Property.">setProperty</a>(<span class="stringliteral">"SchemaDefaultResourceGroup"</span>, <span class="stringliteral">"schemas"</span>);
</pre></div><h2><a class="anchor" id="resprov_tutorial_conclusion"></a>
Conclusion</h2>
<p>This has been a brief introduction to the ResouceProvider system used by <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>. You have seen how to create and use resource groups with CEGUI's DefaultResourceProvider, and how to specify default resource groups for each resource type used by <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>. </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>
|
