The Beginner Guide to Loading Data Files and Initialisation
Ok. Now you have read The Beginner Guide to Getting CEGUI Rendering and The Beginner Guide to Resource Groups, the next rung on the ladder to success is to actually load in the files that CEGUI will be using to produce some output!
Contents
Overview: Data Files
CEGUI uses a variety of data files and initially there may be some confusion over what these are, how they relate to each other and how they get loaded. So before we get started with the meat of all this, I will introduce the data files, what they are, what they're used for, and how they get loaded into CEGUI.
XML, XSD? It's all XML!
With the notable exceptions of graphical image files and loadable modules (DLL and so files, etc), the majority of the data files used by CEGUI are actually XML. This leads us to the first obstacle that people run into; the .xsd schema files.
Although the Expat XML parsing library is now becoming CEGUI's default library, the previous long time default, and CrazyEddie's own preferred XML parsing library is the Xerces-C++ library from the Apache Software Foundation. The advantage of using this particular library to handle parsing XML is that it provides schema validation. Schema validation is a means by which we can check, at parse time, whether the input file contains the expected data and that the data is correctly specified. To do this, the system requires some additional files which are known as schema files, which have the .xsd file extension - the master copies of CEGUI's schema files are currently found in the cegui_mk2/XMLRefSchema/ directory. Anyway, the only thing you need to know about these .xsd files for now is that, when using Xerces-C++ as a parser, they must be available to the ResourceProvider system; this is best achieved by setting up a resource group to a directory containing the schema files and setting that group as the default to be used by CEGUI::XercesParser when loading schema files (The Beginner Guide to Resource Groups shows how to do this).
The Data Files
As mentioned above, with a couple of exceptions, all data files in CEGUI are XML. Rather than using the generic '.xml' file extension, the data files are named according to what the files actually represent; so .imageset for an Imageset and .font for a Font, etc. Below is a very brief overview of each file type; more advanced discussion of the files and their capabilities can be found elsewhere.
Imageset
Effectively, an Imageset is just a collection of defined regions upon the source image / texture file (which is also specified in the Imageset definition). Each of these defined regions has a unique name and is known within the system as an Image. An Image as defined in an Imageset is the basic level of imagery used by CEGUI. By modifying the source image / texture file and also the position and size of the defined regions within the Imageset files you can easily change the appearance of what gets drawn by CEGUI.
Font
A Font file, unsurprisingly, defines a font for use in CEGUI. There are two types of font which can be defined:
- FreeType Font
- This is a font based upon a true-type (.ttf) font file. It is denoted with Type="FreeType" in the .font file starting with version 0.5.0 of CEGUI. In previous versions it was known as "Dynamic".
- Pixmap Font
- Also known as a bitmapped font, this type of font is based upon an Imageset which defines Images for the font glyphs. It is denoted with Type="Pixmap" in the .font file starting with version 0.5.0 of CEGUI. In previous versions it was known as "Static".
Scheme
A Scheme is a largely means to group other data files together, it's also the most convenient way to load and register widget types. A Scheme can contain one or more of the following (which will be loaded and initialised when the scheme is loaded):
- Imageset (either a full Imageset via XML, or a single image via an image file)
- Font
- Window Set
- Window Renderer Set
- Window Alias
- Falagard Mapping
Imageset and Font
These have already been mentioned above. The specifications here just get them to load as part of the scheme.
Window Set
Basically specifies the name of a loadable module (.dll / .so, etc), 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.
Window Renderer Set
Specifies the name of a loadable module (.dll / .so, etc), 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 CEGUI perform rendering by making use of the 'Falagard' skinning system (though this is not a strict requirement).
Window Alias
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).
Falagard Mapping
Used to create a usable Window Type type from a Target Type which names the base type containing the functionality, a Renderer which names a Window Renderer that can control rendering for the specified target type, and a LookNFeel which names a skin to be applied (these are normally specified via XML looknfeel files).
Layout
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.
Config
CEGUI Supports the use of a config file. This file allows you to specify some defaults, such as a Scheme to load, a layout to load, initialisation and termination script files (when using a ScriptModule), and some other things which are not discussed here.
Loading the Basic Files
In order to get things up and running you need to load in some files. The minimal set of files required are:
- Imageset
- Font
- Scheme
The good thing about the Scheme file is that it can be used to load the other two automatically. For the purposes of this tutorial, we will load a scheme file and a font file - it is assumed the scheme automatically loads an Imageset for us. This is done as follows:
// load in the scheme file, which auto-loads the TaharezLook imageset
CEGUI::SchemeManager::getSingleton().loadScheme( "TaharezLook.scheme" );
// load in a font. The first font loaded automatically becomes the default font. if(! CEGUI::FontManager::getSingleton().isFontPresent( "Commonwealth-10" ) )
CEGUI::FontManager::getSingleton().createFont( "Commonwealth-10.font" );
In the above code snippet (and in the sample files) it is assumed that the resource group locations and the default groups have all been set up as described in The Beginner Guide to Resource Groups.
Simple Defaults Initialisation
Finally, you need to specify some defaults. This is to ensure that the system always has a font and mouse cursor available for when a window or widget specifies no preference of its own.
In reality, we no longer need to specify a default font, since the FontManager will now automatically set the first loaded font as the default. Although if this is not the default font you require, you can set a different one as you desire. The code to set a default font is as follows:
System::getSingleton().setDefaultFont( "Commonwealth-10" );
The other default object you need to set is the mouse cursor. This is to ensure 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 (NB: This uses the TaharezLook imageset which was loaded with the scheme above).
System::getSingleton().setDefaultMouseCursor( "TaharezLook", "MouseArrow" );
If you intend to use tool tips, usually you specify the name of the ToolTip based widget type that you want used. It is actually possible to set this on a per-window basis, though that is not normally required, and is beyond the scope of this little introduction. Anyway, to specify the tool tip window type:
System::getSingleton().setDefaultToolTip( "TaharezLook/Tooltip" );
Conclusion
Here we have discovered the very basics of what the various data files used by CEGUI are, how they are loaded, and the minimal initialisation needed for CEGUI applications. Other articles will discuss each of the data files types in greater detail allowing advanced uses to be discovered.
