Difference between revisions of "Scheme files"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
(→‎Introduction)
 
(16 intermediate revisions by 5 users not shown)
Line 3: Line 3:
 
The scheme file concerns resource loading.
 
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.
+
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 it's 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...
+
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.
 
This document is largely based on the 'Readme.txt' file in the 'XMLRefSchema' directory of the source distribution by Paul himself.
 +
 +
'''NOTE:''' These XML files are case sensitive, so the XML Elements/Attributes will be written in the case required rather than by capitalization rules.
  
 
== Document structure ==
 
== Document structure ==
Line 18: Line 20:
 
** '''LookNFeel'''
 
** '''LookNFeel'''
 
** '''WindowSet'''
 
** '''WindowSet'''
−
*** '''WindowFactory'''  
+
*** '''WindowFactory'''
 +
** '''WindowRendererSet''' (CEGUI 0.5.X only)
 +
*** '''WindowRendererFactory'''
 
** '''WindowAlias'''
 
** '''WindowAlias'''
 
** '''FalagardMapping'''
 
** '''FalagardMapping'''
  
−
All elements can be repeated. Two imagesets - for example - are after all a fairly common ;-)
+
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.
 
Each element will be described individually below.
Line 30: Line 34:
  
 
Attributes:
 
Attributes:
−
* '''Name''' - Specifies the name that the scheme will use within the system. ''Required''.
+
* '''version''' - specifies the version of the resource file. Should be specified for all files, current CEGUI scheme version is: 5
 +
* '''name''' - Specifies the name that the scheme will use within the system. ''Required''.
  
 
''GUIScheme'' is the root element and is the only "global" tag.
 
''GUIScheme'' is the root element and is the only "global" tag.
 +
<source lang="xml">
 
  <?xml version="1.0" ?>
 
  <?xml version="1.0" ?>
−
  <GUIScheme Name="MyScheme">
+
  <GUIScheme version="5" name="MyScheme">
 
     ...
 
     ...
 
     ... resources ...
 
     ... resources ...
 
     ...
 
     ...
 
  </GUIScheme>
 
  </GUIScheme>
 +
</source>
  
 
All schemes will have this XML as all the "magic" goes inside it :-)
 
All schemes will have this XML as all the "magic" goes inside it :-)
  
 
=== Imageset ===
 
=== Imageset ===
−
Specifies an Imageset to be loaded as part of this scheme. Has attributes but no sub-elements.
+
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.
 
If an imageset with the requested name already exists, the file specified is not loaded.
  
 
Attributes:
 
Attributes:
−
* '''Name''' - The name of the Imageset. ''Required''.
+
* '''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''.
+
* '''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''.
+
* '''resourceGroup''' - The resource group identifier to pass to the resource provider when loading the file. ''Optional''.
  
 +
<source lang="xml">
 
  <?xml version="1.0" ?>
 
  <?xml version="1.0" ?>
−
  <GUIScheme Name="MyScheme">
+
  <GUIScheme version="5" name="MyScheme">
−
     '''<Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />'''
+
     '''<Imageset name="MyImages" filename="../datafiles/imagesets/MyImages.imageset" />'''
 
  </GUIScheme>
 
  </GUIScheme>
 +
</source>
  
 
In this example the file "../datafiles/imagesets/MyImages.imageset" must define the imageset named "MyImages".
 
In this example the file "../datafiles/imagesets/MyImages.imageset" must define the imageset named "MyImages".
  
−
=== ImagesetFromFile ===
+
=== ImagesetFromImage ===
−
Specifies an Imageset to be loaded as part of this scheme. Has attributes but no sub-elements.
+
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.
 
If an imageset with the requested name already exists, the file specified is not loaded.
  
 
Attributes:
 
Attributes:
−
* '''Name''' - The name of the Imageset. ''Required''.
+
* '''name''' - The name of the Imageset. ''Required''.
−
* '''Filename''' - Filename of the image file to load in order to create this 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''.
+
* '''resourceGroup''' - The resource group identifier to pass to the resource provider when loading the image file. ''Optional''.
  
 +
<source lang="xml">
 
  <?xml version="1.0" ?>
 
  <?xml version="1.0" ?>
−
  <GUIScheme Name="MyScheme">
+
  <GUIScheme version="5" name="MyScheme">
−
     '''<ImagesetFromFile Name="MyBackground" Filename="../datafiles/imagesets/MyBackground.tga" />'''
+
     '''<ImagesetFromFile name="MyBackground" filename="../datafiles/imagesets/MyBackground.tga" />'''
 
  </GUIScheme>
 
  </GUIScheme>
 +
</source>
  
 
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).
 
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).
Line 79: Line 90:
  
 
Attributes:
 
Attributes:
−
* '''Name''' - The name of the Font ''Required''.
+
* '''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''.
+
* '''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''.
+
* '''resourceGroup''' - The resource group identifier to pass to the resource provider when loading the file. ''Optional''.
  
 +
<source lang="xml">
 
  <?xml version="1.0" ?>
 
  <?xml version="1.0" ?>
−
  <GUIScheme Name="MyScheme">
+
  <GUIScheme version="5" name="MyScheme">
−
     '''<Font Name="MyFont" Filename="../datafiles/fonts/MyFont.font" />'''
+
     '''<Font name="MyFont" filename="../datafiles/fonts/MyFont.font" />'''
 
  </GUIScheme>
 
  </GUIScheme>
 +
</source>
  
 
The Font element always loads font XML files. These are not covered here.
 
The Font element always loads font XML files. These are not covered here.
Line 95: Line 108:
  
 
Attributes:
 
Attributes:
−
* '''Filename''' - Filename of the LookNFeel file to parse. ''Required''.
+
* '''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''.
+
* '''resourceGroup''' - The resource group identifier to pass to the resource provider when loading the file. ''Optional''.
  
 +
<source lang="xml">
 
  <?xml version="1.0" ?>
 
  <?xml version="1.0" ?>
−
  <GUIScheme Name="MyScheme">
+
  <GUIScheme version="5" name="MyScheme">
−
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
+
     <Imageset name="MyImages" filename="../datafiles/imagesets/MyImages.imageset" />
−
     '''<LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />'''
+
     '''<LookNFeel filename="../datafiles/looknfeel/MySkin.looknfeel" />'''
 
  </GUIScheme>
 
  </GUIScheme>
 +
</source>
  
 
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 ;-)
 
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 ;-)
Line 110: Line 125:
  
 
Attributes:
 
Attributes:
−
* '''Filename''' - Specifies the name of the loadable module (dll / .so / etc). ''Required''.
+
* '''filename''' - Specifies the name of the loadable module (dll / .so / etc). ''Required''.
  
 +
<source lang="xml">
 
  <?xml version="1.0" ?>
 
  <?xml version="1.0" ?>
−
  <GUIScheme Name="MyScheme">
+
  <GUIScheme version="5" name="MyScheme">
−
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
+
     <Imageset name="MyImages" filename="../datafiles/imagesets/MyImages.imageset" />
−
     <LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />
+
     <LookNFeel filename="../datafiles/looknfeel/MySkin.looknfeel" />
−
     '''<WindowSet Filename="CEGUIFalagardBase" />'''
+
     '''<WindowSet filename="CEGUIFalagardBase" />'''
 
  </GUIScheme>
 
  </GUIScheme>
 +
</source>
  
−
CEGUI 0.4.0 provides 3 windowsets. Falagard, WindowsLook and TaharezLook. Using Falagard is recommended though and the two others will be removed from future versions of the library as the can be implemented in Falagard itself. It's perfectly possible to write your own WindowSet in C++.
+
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''.
 +
 
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 
 +
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 ===
 
=== WindowFactory ===
Line 125: Line 161:
  
 
Attributes:
 
Attributes:
−
* '''Name''' - Name of the factory / window type which is to be added.
+
* '''name''' - Name of the factory / window type which is to be added.
  
 +
<source lang="xml">
 
  <?xml version="1.0" ?>
 
  <?xml version="1.0" ?>
−
  <GUIScheme Name="MyScheme">
+
  <GUIScheme version="5" name="MyScheme">
−
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
+
     <Imageset name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
−
     <LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />
+
     <LookNFeel filename="../datafiles/looknfeel/MySkin.looknfeel" />
−
     <WindowSet Filename="CEGUIFalagardBase">
+
     <WindowSet filename="CEGUIFalagardBase">
−
         '''<WindowFactory Name="Falagard/Button" />'''
+
         '''<WindowFactory name="Falagard/Button" />'''
 
     </WindowSet>
 
     </WindowSet>
 
  </GUIScheme>
 
  </GUIScheme>
 +
</source>
  
 
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.
 
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 ===
+
=== 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.
 
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.
 
Has attributes but no sub-elements.
  
 
Attributes:
 
Attributes:
−
* '''WindowType''' - The name for the new "factory". ''Required''.
+
* '''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''.
+
* '''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''.
+
* '''lookNFeel''' - The name of the look'n'feel to use. That's the WidgetLook name from the [[Falagard]] XML. ''Required''.
  
 +
<source lang="xml">
 
  <?xml version="1.0" ?>
 
  <?xml version="1.0" ?>
−
  <GUIScheme Name="MyScheme">
+
  <GUIScheme name="MyScheme">
−
     <Imageset Name="MyImages" Filename="../datafiles/imagesets/MyImages.imageset" />
+
     <Imageset name="MyImages" filename="../datafiles/imagesets/MyImages.imageset" />
−
     <LookNFeel Filename="../datafiles/looknfeel/MySkin.looknfeel" />
+
     <LookNFeel filename="../datafiles/looknfeel/MySkin.looknfeel" />
−
     <WindowSet Filename="CEGUIFalagardBase">
+
     <WindowSet filename="CEGUIFalagardBase">
−
         <WindowFactory Name="Falagard/Button" />
+
         <WindowFactory name="Falagard/Button" />
 
     </WindowSet>
 
     </WindowSet>
−
     '''<FalagardMapping WindowType="My/Button" TargetType="Falagard/Button" LookNFeel="MyButton" />'''
+
     '''<FalagardMapping windowType="My/Button" targetType="Falagard/Button" lookNFeel="MyButton" />'''
 
  </GUIScheme>
 
  </GUIScheme>
 +
</source>
  
−
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".
+
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''.
 +
 
 +
<source lang="xml">
 +
  <?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>
 +
</source>
 +
 
 +
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 ===
 
=== WindowAlias ===
−
Specifies an alias for a given window factory type or falagard mapping. Has attributes but no sub-elements.
+
Specifies an alias for a given window factory type or falagard mapping. Has attributes but no sub-elements.
  
 
Attributes:
 
Attributes:
−
* '''Alias''' - Name of the alias. This is the alternative name that 'Target' will be known by. ''Required''.
+
* '''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''.
+
* '''target''' - Name of the window factory type, falagard mapping or existing alias that is to (also) be known as 'Alias'. ''Required''.
  
  
Line 171: Line 235:
  
 
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.
 
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 ;)
+
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 ;)
 +
 
 +
--[[User:lindquist]] 03:49, 14 Dec 2005 (CET)
  
−
--[[User:lindquist|lindquist]] 03:49, 14 Dec 2005 (CET)
+
[[Category:Manuals]]

Latest revision as of 21:36, 25 June 2014

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.

NOTE: These XML files are case sensitive, so the XML Elements/Attributes will be written in the case required rather than by capitalization rules.

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:

  • version - specifies the version of the resource file. Should be specified for all files, current CEGUI scheme version is: 5
  • 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 version="5" 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 version="5" 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".

ImagesetFromImage

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 version="5" 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 version="5" 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 version="5" 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 version="5" 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 version="5" 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 ;)

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

Retrieved from "http://cegui.org/wiki/index.php?title=Scheme_files&oldid=5402"