The Beginners Guide to Data Files and Defaults Initialisation

Author

Paul D Turner

It is assumed that prior to reading this tutorial you are already familiar with the concepts surrounding CEGUI's ResourceProvider and have correctly initialised your Renderer and the CEGUI System objects. If you've not yet covered these topics, it is highly recommended that you read The Beginners Guide to Getting CEGUI Rendering and The Beginners Guide to resource loading with ResourceProviders.

Introduction

CEGUI 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 required to be set - you will almost certainly want to set for the majority of your applications using CEGUI.

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 CEGUI.

Font, Imageset, LookNFeel, Scheme, XSD? It's all XML!

With the exception of graphical image files, script language files and loadable modules (.dll /. so files, etc), all the data files used with CEGUI are XML based. This actually leads us to the first potential obstacle that you may run into: the .xsd schema files.

Schema Validation with Xerces-C++

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 http://xerces.apache.org/xerces-c).

The advantage of using this particular parser is that it provides schema validation. 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 scheme files described below) - are required. The schema files used to validate the XML for CEGUI can be found in the datafiles/xml_schema/ directory within the CEGUI distribution, and have the .xsd file extension.

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 ResourceProvider 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 CEGUI::XercesParser when loading schema files (the specifics on how to do this are covered in The Beginners Guide to resource loading with ResourceProviders).

The Data Files

As previously mentioned, the majority of the data files in CEGUI 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 Imageset and .font for a Font (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.

Imageset

An Imageset is a collection of named regions upon some source surface, such as an image file or texture. In CEGUI terminology, each of these named regions is an Image and is the basic level of imagery used by CEGUI. By modifying the source image file or texture content, or by modifying the areas of the defined regions within the Imageset file, you can easily change the appearance of what gets drawn by CEGUI.

For a complete description of imageset files, please see Imageset XML files.

Font

A Font file, unsurprisingly, defines a font for use in CEGUI. There are at present two types of font which may be defined:

• FreeTypeFont: This is a font based upon a standard font file (such as a true-type '.ttf' font). A FreeTypeFont is specified via the attribute Type="FreeType" in the .font XML file.
• PixmapFont: This type of font is based upon an Imageset which defines Images for the font glyphs, and is best thought of as a bitmapped font. A PixmapFont is specified via the attribute Type="Pixmap" in the .font XML file.

For a complete description of font files, please see Font XML files.

LookNFeel

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 CEGUI.

For a complete description of looknfeel files (and other skinning related material), please see Falagard skinning system for CEGUI

Scheme

A Scheme 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 Scheme can contain one or more of the following:

• Imageset Specifies an Imageset file to be loaded as part of the scheme.
• Font Specifies a Font file to be loaded as part of the scheme.
• LookNFeel Specifies a LookNFeel file to be loaded as part of the scheme.
• WindowSet 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 CEGUI (especially if the module is provided by a third party).
• WindowRendererSet 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 CEGUI perform rendering by making use of the 'Falagard' skinning system (though this is not a strict requirement).
• WindowAlias 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).
• FalagardMapping Creates a new usable window type by linking a concrete window/widget type, a window renderer type and a widget look definition.

For a complete description of scheme files, please see Scheme XML 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.

For a complete description of layout files, please see Layout XML files.

Config

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 ScriptModule), without writing a line of C++ code beyond that which creates the Renderer and System objects.

For a complete description of config files, please see CEGUI Configuration XML files.

Loading the Basic Files

In order to get things up and running you need to load in some files. The typical set of files needed are:

• Imageset
• Font
• LookNFeel
• Scheme

The good thing about the Scheme 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 Imageset and LookNFeel for us. Loading the scheme and font files is done as follows:

// create (load) the TaharezLook scheme file
// (this auto-loads the TaharezLook looknfeel and imageset files)
CEGUI::SchemeManager::getSingleton().create( "TaharezLook.scheme" );

// create (load) a font.
// The first font loaded automatically becomes the default font, but note
// that the scheme might have already loaded a font, so there may already
// be a default set - if we want the "Commonweath-10" font to definitely
// be the default, we should set the default explicitly afterwards.
CEGUI::FontManager::getSingleton().create( "Commonwealth-10.font" );

In the above code (and in the CEGUI samples) it is assumed that the resource group locations and the default groups have all been set up as described in The Beginners Guide to resource loading with ResourceProviders.

System Defaults Initialisation

Finally, you need to specify some default options for the System. 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.

The FontManager 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:

System::getSingleton().setDefaultFont( "Commonwealth-10" );

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):

System::getSingleton().setDefaultMouseCursor( "TaharezLook", "MouseArrow" );

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:

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.