Scheme files

Introduction

CEGUI is pretty modular in many aspects. Resource loading, rendering, scripting and window-factories, can all be controlled by client modules. The scheme file concerns resource loading.

The first thing most users do when initialising CEGUI, is to load a scheme. This could for example be "../datafiles/schemes/TaharezLookSkin.scheme". This scheme file is probably the most used currently, and will load the Falagard version of classic TaharezLook into the library.

If one takes a closer look at this file, they'll see that it is a XML document, ready to be edited... The nice thing here is that it's no longer necessary to recompile, to change the resources to be loaded. Furthermore a scheme acts like a "resource package" as we can unload all resources that is loaded by a scheme given we know its name. From a coding perspective this is nice as it simplifies the resource management. All you have to create/destroy is the scheme it self. CEGUI worries about all the individual resources specified in the XML file for you...

This document is largely based on the 'Readme.txt' file in the 'XMLRefSchema' directory of the source distribution by Paul himself.

Document structure

A CEGUI sheme follows a "strict" order dependent structure that looks like this:

• GUIScheme
  • Imageset
  • ImagesetFromImage
  • Font
  • LookNFeel
  • WindowSet
    • WindowFactory
  • WindowRendererSet (CEGUI 0.5.X only)
    • WindowRendererFactory
  • WindowAlias
  • FalagardMapping

All elements are optional and can be repeated. Two imagesets - for example - are after all a fairly common ;-)

Each element will be described individually below.

GUIScheme

Root element. Has a name attribute, and a collection of sub-elements which can be Imageset, ImagesetFromFile, Font, LookNFeel, WindowSet, FalagardMapping and WindowAlias elements.

Attributes:

• Name - Specifies the name that the scheme will use within the system. Required.

GUIScheme is the root element and is the only "global" tag.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     ...
     ... resources ...
     ...
 </GUIScheme>

All schemes will have this XML as all the "magic" goes inside it :-)

Imageset

Specifies an Imageset to be loaded as part of this scheme. Has attributes but no sub-elements. If an imageset with the requested name already exists, the file specified is not loaded.

Attributes:

• Name - The name of the Imageset. Required.
• Filename - Filename of the Imageset file. If the imageset created by this file does not = Name above, an exception is thrown. Required.
• ResourceGroup - The resource group identifier to pass to the resource provider when loading the file. Optional.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     '''<Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />'''
 </GUIScheme>

In this example the file "../datafiles/imagesets/MyImages.imageset" must define the imageset named "MyImages".

ImagesetFromFile

Specifies an Imageset to be loaded as part of this scheme. Has attributes but no sub-elements. If an imageset with the requested name already exists, the file specified is not loaded.

Attributes:

• Name - The name of the Imageset. Required.
• Filename - Filename of the image file to load in order to create this Imageset. Required.
• ResourceGroup - The resource group identifier to pass to the resource provider when loading the image file. Optional.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     '''<ImagesetFromFile Name="MyBackground" Filename="../datafiles/imagesets/MyBackground.tga" />'''
 </GUIScheme>

In this example the file "../datafiles/imagesets/MyBackground" is a Targa (.TGA) image file. By default an Imageset loaded like this defines a single image named full_image that covers the entire texture (the content of the image file).

Font

Specifies a Font to be loaded as part of the scheme. Has attributes but no sub-elements. If a font with the requested name already exists, the file specified is not loaded.

Attributes:

• Name - The name of the Font Required.
• Filename - Filename of the Font file. If the font created by this file does not = Name above, an exception is thrown. Required.
• ResourceGroup - The resource group identifier to pass to the resource provider when loading the file. Optional.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     '''<Font Name="MyFont" Filename="../datafiles/fonts/MyFont.font" />'''
 </GUIScheme>

The Font element always loads font XML files. These are not covered here.

LookNFeel

Specifies a LookNFeel to be loaded as part of the scheme. Has attributes but no sub-elements. The XML file loaded by this element may contain many widget looks which will all become available.

Attributes:

• Filename - Filename of the LookNFeel file to parse. Required.
• ResourceGroup - The resource group identifier to pass to the resource provider when loading the file. Optional.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
     '''<LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />'''
 </GUIScheme>

Loading a look'n'feel specification is not enough. We must create a FalagardMapping as well. More on this soon. Just know that now the widget looks specified in MySkin.looknfeel are available to falagard mappings. At least the imageset we use in MySkin is available ;-)

WindowSet

Specifies a module containing concrete GUI elements and their factories. Has attributes and zero or more WindowFactory sub-elements. That is you can optionally specify WindowFactory sub-elements. If they are omitted all available factories in the module are loaded.

Attributes:

• Filename - Specifies the name of the loadable module (dll / .so / etc). Required.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
     <LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />
     '''<WindowSet Filename="CEGUIFalagardBase" />'''
 </GUIScheme>

CEGUI 0.4.X provides 3 windowsets. Falagard, WindowsLook and TaharezLook. The above sample code is only valid for CEGUI 0.4.X.

CEGUI 0.5.X provides no widget sets. All the core widgets are part of the CEGUIBase library. It's still there though as it allows user widget modules to be loaded dynamically.

WindowRendererSet (CEGUI 0.5.X only)

Specifies a module containing WindowRenderer classes and their factories. Has attributes and zero or more WindowRendererFactory sub-elements. That is you can optionally specify WindowRendererFactory sub-elements. If they are omitted all available factories in the module are loaded.

Attributes:

• Filename - Specifies the name of the loadable module (dll / .so / etc). Required.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
     <LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />
     '''<WindowRendererSet Filename="CEGUIFalagardWRBase" />'''
 </GUIScheme>

CEGUI 0.5.0 only provides one WindowRendererSet. Falagard. It's perfectly possible to write your own WindowRendererSet in C++. Take a look at the CEGUIFalagardWRBase module if you're curious :)

WindowFactory

Specifies the factory name (GUI window type name) from the loadable module that is to be added to the list of available factories. Has attributes but no sub-elements.

Attributes:

• Name - Name of the factory / window type which is to be added.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
     <LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />
     <WindowSet Filename="CEGUIFalagardBase">
         '''<WindowFactory Name="Falagard/Button" />'''
     </WindowSet>
 </GUIScheme>

In this example we only load the "Falagard/Button" factory. If you only need a few widgets and not the whole set, this could save you some memory.

FalagardMapping in CEGUI 0.4.X

Maps a look'n'feel to a window factory and assigns the result to a new window type, in effect creating a new window factory for a specific look'n'feel. Has attributes but no sub-elements.

Attributes:

• WindowType - The name for the new "factory". Required.
• TargetType - The name of the target window factory which will have the look'n'feel assigned. Required.
• LookNFeel - The name of the look'n'feel to use. That's the WidgetLook name from the Falagard XML. Required.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
     <LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />
     <WindowSet Filename="CEGUIFalagardBase">
         <WindowFactory Name="Falagard/Button" />
     </WindowSet>
     '''<FalagardMapping WindowType="My/Button" TargetType="Falagard/Button" LookNFeel="MyButton" />'''
 </GUIScheme>

This would be a proper scheme to use the look'n'feel created in The Beginners Guide to Falagard skinning - Part I. The new type of button window would in this case be available from code or XML layouts by the type name "My/Button".

FalagardMapping in CEGUI 0.5.X

Maps a look'n'feel to a window factory and assigns the result to a new window type, in effect creating a new window factory for a specific look'n'feel. Has attributes but no sub-elements.

Attributes:

• WindowType - The name for the new "factory". Required.
• TargetType - The name of the target window factory which will have the look'n'feel assigned. Required.
• LookNFeel - The name of the look'n'feel to use. That's the WidgetLook name from the Falagard XML. Required.
• Renderer - Then name of the window renderer factory to use. This module implements the widget rendering code. Required.

 <?xml version="1.0" ?>
 <GUIScheme Name="MyScheme">
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
     <LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />
     <WindowSet Filename="CEGUIFalagardWRBase">
         <WindowFactory Name="Falagard/Button" />
     </WindowSet>
     '''<FalagardMapping WindowType="My/Button" TargetType="CEGUI/PushButton" LookNFeel="MyButton" Renderer="Falagard/Button" />'''
 </GUIScheme>

This would be a proper scheme to use the look'n'feel created in The Beginners Guide to Falagard skinning - Part I. The new type of button window would in this case be available from code or XML layouts by the type name "My/Button".

WindowAlias

Specifies an alias for a given window factory type or falagard mapping. Has attributes but no sub-elements.

Attributes:

• Alias - Name of the alias. This is the alternative name that 'Target' will be known by. Required.
• Target - Name of the window factory type, falagard mapping or existing alias that is to (also) be known as 'Alias'. Required.

Discussion

The scheme is obviously a bit more than just loading resources. It also ties the resources together. All of it can be done in code, but using a scheme file is flexible, and avoids recompiling often.

Schemes are especially useful for artists not familiar with C++ programming, as everything you "set up" in the scheme can be used from XML layouts. With Falagard this means that you can totally customize the user interface if the program is properly configured to do so without ever talking to the developers ;)

--lindquist 03:49, 14 Dec 2005 (CET)