CEGUI Wiki - Crazy Eddie's GUI System (Open Source) - User contributions [en]

Template:CEGUIDownloadsRC

2006-08-22T15:32:10Z

Lindquist:

<div style="text-align:center; color:#884400; border:1px dashed #888888; margin:0.9em">
'''Note that the downloads on this page are the official file releases from the CEGUI Team. The downloads on this page corresponds to Release Candidate version of CEGUI. Please test this version and report all bugs on the Mantis bug tracker. For additional, community provided downloads, please visit the [[Community Downloads|Community Downloads page]]'''
</div>
{| cellspacing="0" cellpadding="0" width="100%" background-color="transparent"
| style="width:50%; border:none; margin:none; padding:none;" valign="top" | 
<div style="background:#2f1fef; padding:0px; border:1px solid #888888; margin-right:5px; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.2em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#339933; font-size:100%">'''Core Library Source Downloads'''</span>
</div>

<div style="background:#ffffff; padding:0.5em">
<div style="background:#ffffff; padding:0px; border:1px dashed #888888; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.1em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#3349dd; font-size:100%">'''Crazy Eddie's GUI System Mk-2 Source Code (tar.gz archive)'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
* Version {{{cegui}}} of the source code for Crazy Eddie's GUI System Mk-2, supplied as a bz2 compressed tarball.
* This package is intended for linux and Apple Mac users.
* [http://prdownloads.sourceforge.net/crayzedsgui/CEGUI-{{{cegui}}}.tar.gz?download Download Now!]
</div>
</div>

<div style="background:#ffffff; padding:0px; border:1px dashed #888888; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.1em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#3349dd; font-size:100%">'''Crazy Eddie's GUI System Mk-2 Source Code (zip archive)'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
* Version {{{cegui}}} of the source code for Crazy Eddie's GUI System Mk-2, supplied as a compressed zip archive.
* This package is intended for Microsoft Windows users.
* [http://prdownloads.sourceforge.net/crayzedsgui/CEGUI-{{{cegui}}}.zip?download Download Now!]
* Read this thread for details: http://www.cegui.org.uk/phpBB2/viewtopic.php?t=1665&start=0&postdays=0&postorder=asc&highlight=
</div>
</div>
</div>
</div>

<div style="background:#2f1fef; padding:0px; border:1px solid #888888; margin-left:5px; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.2em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#339933; font-size:100%">'''Crazy Eddie's GUI Simple Image Loading Library (SILLY)'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
<div style="background:#ffffff; padding:0px; border:1px dashed #888888; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.1em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#3349dd; font-size:100%">'''Source Code (tarball)'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
* Version {{{silly}}} of the source code for Crazy Eddie's GUI Simple Image Loading Library, supplied as a tar.gz compressed tarball.
* This package is intended for linux and Apple Mac users.
* [http://prdownloads.sourceforge.net/crayzedsgui/SILLY-{{{silly}}}.tar.gz?download Download Now!]
</div>
<div style="text-align:center; line-height:100%; padding:0.1em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#3349dd; font-size:100%">'''Source Code (zip archive)'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
* Version {{{silly}}} of the source code for Crazy Eddie's GUI Simple Image Loading Library, supplied as a zip compressed archive.
* This package is intended for Win32 users.
* [http://prdownloads.sourceforge.net/crayzedsgui/SILLY-{{{silly}}}.zip?download Download Now!]
</div>
</div>
</div>
</div>

<div style="background:#2f1fef; padding:0px; border:1px solid #888888; margin-right:5px; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.2em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#339933; font-size:100%">'''Core Library Win32 Dependency Downloads'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
<div style="background:#ffffff; padding:0px; border:1px dashed #888888; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.1em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#3349dd; font-size:100%">'''MSVC++ 8 dependency package for CEGUI Mk-2 {{{cegui}}}'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
* This package contains all library for use by MSVC++ 8 (MSVC++ 2005) users.
* This package is for use with CEGUI {{{cegui}}} series of releases.
* [http://prdownloads.sourceforge.net/crayzedsgui/CEGUI-{{{dependency}}}-deps-vc8.zip?download Download Now!]
</div>
</div>

<div style="background:#ffffff; padding:0px; border:1px dashed #888888; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.1em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#3349dd; font-size:100%">'''MSVC++ 7.1 dependency package for CEGUI Mk-2 {{{cegui}}}'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
* This package contains the all library for use by MSVC++ 7.1 (MSVC++>Net 2003) users.
* This package is for use with CEGUI {{{dependency}}} series of releases.
* [http://prdownloads.sourceforge.net/crayzedsgui/CEGUI-{{{dependency}}}-deps-vc71.zip?download Download Now!]
</div>
</div>
</div>
</div>

| style="border:none; margin:none; padding:none;" valign="top" | 
<div style="background:#2f1fef; padding:0px; border:1px solid #888888; margin-left:5px; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.2em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#339933; font-size:100%">'''Crazy Eddie's GUI System Layout Editor'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
<div style="background:#ffffff; padding:0px; border:1px dashed #888888; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.1em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#3349dd; font-size:100%">'''CELayoutEditor Windows Installer'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
* Out-of-the-box installer, which is built against the stable CEGUI {{{cegui}}} release. Includes sample layout(s).
* Version {{{editor}}} (version renamed to match the corresponding cegui library)
* [http://prdownloads.sourceforge.net/crayzedsgui/CELayoutEditorSetup_0.5-RC2.exe Download Now!]
</div>
</div>

<div style="background:#ffffff; padding:0px; border:1px dashed #888888; margin-bottom:10px">
<div style="text-align:center; line-height:100%; padding:0.1em; background-color:#eeeeee; border-bottom:1px dashed #888888;">
<span style="color:#3349dd; font-size:100%">'''CELayoutEditor Source Distributions'''</span>
</div>
<div style="background:#ffffff; padding:0.5em">
* These zip- and gz packages contain the exact sources from which the installer is build. It's for Linux users and for those who don't have access to Subversion or are not familiar with the hussle.
* It at least compiles to the CEGUI {{{cegui}}} source release with gcc, VC7.1, VC8.
<br>
* The installer is above this download link, so make sure you pick the one you feel most comfortable with.
<br>
* [http://prdownloads.sourceforge.net/crayzedsgui/CELayoutEditor_0.5-RC2.zip?download Download zip version!]
* [http://prdownloads.sourceforge.net/crayzedsgui/CELayoutEditor-0.5.0-RC2.tar.gz?download Download gz version!]

</div>
</div>

</div>
</div>
|}

Scheme files

2006-08-16T22:52:36Z

Lindquist: /* Document structure */

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

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

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

Scheme files

2006-08-16T22:52:13Z

Lindquist: /* Document structure */

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

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

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

Scheme files

2006-08-16T22:50:53Z

Lindquist: Scheme XML spec update for 0.5

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

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'''
** '''WindowAlias'''
** '''FalagardMapping'''

All elements 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 ;)

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

Scheme files

2006-08-16T22:40:25Z

Lindquist: Scheme XML spec update for 0.5

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

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'''
** '''WindowAlias'''
** '''FalagardMapping'''

All elements 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.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++.

=== 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 ;)

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

FAQ

2006-08-05T06:45:33Z

Lindquist: fixed bad code in "how to subscribe..." (reported on forum)

== General Questions ==
=== What is CEGUI? ===
CEGUI stands for ''Crazy Eddie's Gui System''; a free library providing windowing and widgets for graphics APIs / engines where such functionality is not natively available, or severely lacking. The library is object orientated, written in C++, and targeted at games developers who should be spending their time creating great games, not building GUI sub-systems!

CEGUI is used as the GUI of choice in the [http://www.ogre3d.org Ogre3D project] but supports Microsoft® DirectX® 8.1 and 9, OpenGL, and the Irrlicht engine natively.

CEGUI was started by Paul Turner ("[[User:CrazyEddie|CrazyEddie]]") about two years ago and is currently in it's second major revision, "Mk2". The project supports windows, linux and MacOS.

=== How is CEGUI licensed? ===
Up and until version 0.4.1, CEGUI '''is''' licenced under [http://www.gnu.org/licenses/lgpl.html LGPL], which basically means you can dynamically link to it (ie. use it as a library) in a non-GPL project, as long as you fulfil the other requirements of the LGPL.

However, as from 0.5 (not officially released yet), the library will be released under the [http://www.opensource.org/licenses/mit-license.php MIT] licence, which is less restrictive then LGPL. You may for example statically link to libraries. The main reason for this switch is the fact that the Ogre3D project has started to provide dual licensing to allow console development. And in order to keep CEGUI as their preferred GUI system, we have switched as well.

=== What is the situation with the Falagard components and the Creative Commons license? ===
There is no situation! The Creative Commons license only applies to the documentation where that notice appears; the source code, libraries, and all other materials relating to the Falagard skinning system are licensed under LGPL or MIT (depending upon the version; see above).

=== Why is the Falagard documentation licensed seperately? Why is it not LGPL/MIT like the rest of the library? ===
Originally that documentation was only to be available as a PDF file intended for self-printing into a mini-book, and the "this work" portion of the license notification applies to the text of that book; the documentation is considered a seperate work from the code / library itself, and so it licensed seperately.

=== How much does CEGUI cost? ===
Nothing. The use of CEGUI is totally free within the bounds of the license as described above.

=== I am developing a commercial, closed-source product. Should i use the 0.4 or 0.5 version of the library? ===
When you are creating a product for PC, where it is possible for users to update any of your used third-party DLL's (a requirement for LGPL), you can choose both versions. However if you are shipping a product on a read-only device, such as a console DVD, you must use 0.5 or higher, because the MIT license does not require that users can update anything.

However before deciding, do always carefully check the mentioned licenses to make sure that your project doesn't do something uncommon.

=== I am not happy with the LGPL / MIT license, do you offer alternative licensing? ===
No. Alternative licensing is not available, nor is it planned. But you won't find anything much less restrictive then the MIT license.

=== Does CEGUI rely upon any third party libraries? If so what are they? ===
CEGUI currently depends upon the following external libraries:
{| width="100%"
|| '''Library''' || '''Required''' || '''Url''' || '''License'''
|-
|| FreeType2 || yes || [http://www.freetype.org/freetype2/index.html http://www.freetype.org/freetype2/index.html] || BSD-like [http://www.freetype.org/FTL.TXT FreeType License] ou [http://www.freetype.org/GPL.TXT GPL]
|-
|| Perl C Regular Expression || yes || [http://www.pcre.org/ http://www.pcre.org/] || [http://www.pcre.org/license.txt BSD]
|-
|| Xerces-C++ || no || [http://xerces.apache.org/ http://xerces.apache.org/] || [http://www.apache.org/licenses/LICENSE-2.0.html Apache Software License, Version 2.0]
|-
|| Expat || no || [http://expat.sourceforge.net/ http://expat.sourceforge.net/] || [http://www.opensource.org/licenses/mit-license.html MIT]
|-
|| Libxml || no || [http://www.xmlsoft.org/ http://www.xmlsoft.org/] || [http://www.opensource.org/licenses/mit-license.html MIT]
|-
|| DevIL || no || [http://openil.sourceforge.net/ http://openil.sourceforge.net/] || [http://openil.sourceforge.net/license.php LGPL License Version 2.1]
|}
You will also require a supported rendering system, and some form of input library.

=== Do I have to compile the third part libraries myself? ===
It depends. Under Linux and similar systems, you will need to perform your own compilation. For Microsoft® Windows® users, we have supplied packages containing binary versions of the libraries for a selection of popular compiler configurations. See the "Current Releases" on the home page.

=== You mentioned something about "supported rendering systems", what's that all about and which systems are supported? ===
CEGUI can be used with various rendering systems. There are currently CEGUI renderer modules for Microsoft® DirectX® 8.1 and 9, OpenGL, the Ogre engine, and the Irrlicht engine.

=== There is no renderer module for my rendering engine or API of choice, will other rendering system be supported? ===
It is likely that, over time, CEGUI will add support for other APIs and engines. Having said this, it is fairly simple to write your own renderer module for CEGUI, so you might consider taking that option if you do not want to wait.

=== And what about input libraries? ===
CEGUI requires you to ''inject'' inputs into it, these inputs can come from any source that you choose. All you need to do is pass mouse movements, mouse button up and down events, and keyboard inputs to CEGUI.

=== Why doesn't CEGUI collect its own inputs? Why do I need to inject the inputs myself? ===
CEGUI does not collect its own input so that the system can remain as flexible as possible. We didn't want to tie people down to one system or input library.

=== I have seen mention of a Lua scripting module, how can I get this? ===
The Lua scripting module is provided with CEGUI and resides in the same source repository. Downloading CEGUI binary/source/svn will get you everything you need.

=== I can't find many of the things you talk about in my crayzedsgui code, what's wrong? ===
You probably have one of the older Mk-1 alpha releases. Get the newer Mk-2 releases instead, the archive files for these generally have names with cegui_mk2 in them.

=== Why are there two versions of the system? ===
The Mk-1 version was a Windows®/DirectX® only library and was really a dry run for what became the Mk-2 system. There was only ever 'alpha' versions of the Mk-1 code, so it was never anywhere near finished.

=== Are the Mk-1 and Mk-2 systems interface compatible? ===
No. The interfaces of the two systems are totally different, although many of the general concepts have remained the same.

=== The Mk-1 system is so much more lightweight than the Mk-2 system. Can I still use the Mk-1 code? Is the Mk-1 code still being developed and supported? ===
Short Answer: Not really.

Long Answer: There were too many weak areas within the Mk-1 system and development on this version has ceased completely. There is no longer any support for the Mk-1 version; in general it would be better for everyone if they migrated to the Mk-2 version of the system.

=== I am having major troubles integrating CEGUI with my project, will you do it for me? ===
No. The CEGUI developers have enough to do without writing users projects for them. Follow the Howto's and Tutorials from the home page.

=== I have (or think I have) found a bug. How should I proceed? ===
If you are certain that it's a bug and not, for example, a misunderstanding of what is happening, then the bug should be reported via the [http://www.cegui.org.uk/mantis/index.php | Mantis Tracker] However, before submitting a bug to the tracker, it is asked that you first do a quick search to see if the bug has already been reported. If you are unsure whether something is a bug or not, then it may be discussed on the web site forums prior to submitting a bug report to the project bug tracker.

=== I notice that feature/widget 'X' is missing. Will this be added to CEGUI? ===
Requests for new features and/or widgets are welcomed in this forum: http://www.cegui.org.uk/phpBB2/viewforum.php?f=3&sid=587eedf3463c00490686f8cddc61a257
This is the best way because most people will read it, including the team. This helps others to give input as well, which migth result in clearly defined requests.

Note that no promises are made with regards to which features will and will not be added, or how long such things will take, but all requests will be seriously considered.

=== How can I get involved with CEGUI development? ===
Each new member gets added by invitation by the current team. Most probably because that person has contributed some valuable patches, or is of great help in the forums. It will of course depend on the current state of the project to know which positions are required.

So the best way to become involved is to show your face at the web site forums, the irc channel, and state what your intentions are (to help in avoiding duplicated effort), thereby becoming a constructive individual for CEGUI and its community. And some patches are a huge pro!

=== Is there managed code / Microsoft .Net support for the CEGUI library? ===
Yes, there is ''ceguisharp'' at http://ceguisharp.sourceforge.net/ This is a C# port of the library which will support Managed Direct 3D, OpenGL, as well as higher-level engines such as the excellent Axiom rendering engine.

=== This FAQ doesn't answer my question, what should I do now? ===
Feel free to post your question on the web site forums, somebody will gladly answer your question and/or offer further advice.

== Building CEGUI ==

This section has moved to [http://www.cegui.org.uk/wiki/index.php/HOWTO:_Obtain_the_library_source_from_subversion New location]

== Usage Questions ==
''(This whole section should be moved to a Tutorial or a Howto).''
=== What is the correct way to subscribe for an event? ===
Event notification is a vital aspect of GUI programming. CEGUI handles those using subscribers.
In order to subscribe a window for an event, you have to call the method 'Window::subscribeEvent', passing the function
to be called when the specified event occurs, and the instance on which the method is called.

class MyButtonHandler
{
private:
PushButton* mButton;

public:
MyButtonHandler::MyButtonHandler(PushButton* btn) : mButton(btn)
{
btn->subscribeEvent(PushButton::EventClicked, Event::Subscriber(&MyButtonHandler::ButtonClicked,this));
}

bool MyButtonHandler::ButtonClicked(const EventArgs&)
{
//This function gets called when the button is clicked
std::cout << "Button clicked" << std::endl;
}

The 'subscribeEvent' method returns an Event::Connection, which can be used later to unsubscribe for a registered event with
the 'disconnect' method.

Event::Connection myCon = btn->subscribeEvent(...);

...

myCon->disconnect();

In order to totally remove the event itself, you have to call the 'removeEvent' function:
all the connections to the specified event will be disconnected.
There's also an Event::ScopedConnection, which can be used to auto-unsubscribe when the event goes out of scope.

Similar way for the scripted events, which can be subscribed with the 'subscribeScriptedEvent' method.
In addition, you can do it in XML, using this syntax:

<Event Name="Clicked" Function="luabtn_clicked" />

=== How can I make the ListBox highlight the selected item? ===
In order to highlight selected items you need to set selection brush image and the selection colours of that item. The selection image is modulated by the colours you set. Note, that the alpha component needs to be smaller than 1.0, for the content of the selected item to be seen.
// set selection highlight to a half transparent blue to red gradient.
colour blue(0.0, 0.0, 1.0, 0.5);
colour red(1.0, 0.0, 0.0, 0.5);
myListBoxItem->setSelectionColours(blue, blue, red, red);
// this default image is a simple white rectangle
myListBoxItem->setSelectionBrushImage("TaharezLook", "ListboxSelectionBrush");

=== How can I remove the border of a StaticImage? ===
Either put the following property into the window definition:
<Property Name="FrameEnabled" Value="false" />
Or set it by code:
myStaticImage->setFrameEnabled(false);

=== How can I set the background of a StaticImage? ===
The first thing you need in order to do this is an Imageset that defines the Image that you wish to use. When wanting to use an image file for this as you suggest, you basically have an imageset defined like this:
<?xml version="1.0" ?>
<Imageset Name="BackdropImageset" Imagefile="backdrop.tga" NativeHorzRes="1024" NativeVertRes="768" AutoScaled="true">
<Image Name="Backdrop" XPos="0" YPos="0" Width="1024" Height="768" />
</Imageset>

What this does is define an Imageset using the backdrop.tga. A single image "Backdrop" is defined that starts at location (0,0) and is 1024 x 768 in size. You should be careful in that the source image file should have dimensions that are powers of two - this is because the image is loaded as a texture, and may be stretched if the powers-of-two requirement is not observed.<br>
Once you have your imageset defined, you can load it either by adding a reference to it in whichever scheme you are loading, or manually using the ImagesetManager:
CEGUI::ImagesetManager::getSingleton().createImageset("myImageset.imagset");
Once the thing is loaded, you set the image into the StaticImage like so:
myStaticImage->setImage("BackdropImageset", "Backdrop");
Notice that the names we specify here are the ones that were originally specified in the imageset XML file.<br>

=== I can't see the items I've added to my Combobox, how do I get the list to show when I press the button? ===
The height you specify for the combobox widget includes the height of the drop down list; it's not just for the 'Editbox' portion of the widget (the height of which is usually automatically determined based upon the font). Ensure that when specifying the height for your combobox, you have provided sufficient space for the list to appear.

=== What properties are available for use in XML layouts, and what format do I use for the value strings? ===
If you start at the documentation for the base Property class ([http://www.cegui.org.uk/api_reference/classCEGUI_1_1Property.html Property base]), you will get an inheritance diagram showing all properties in the system. When you click one, you'll get its page. Each page has a description of the format in which you should provide its value.

Besides, as an overview, each widget has its properties placed within an appropriately named C++ namespace within the [http://www.cegui.org.uk/api_reference/namespaces.html namespaces section of the API reference].

Also, remember that properties are inherited. So for example, when looking up properties for a PushButton, also check the properties for ButtonBase and Window too - since these properties are also available to you.

Developer Team

2006-07-23T00:21:42Z

Lindquist:

Something about the team should go here

SDL to CEGUI keytable

2006-07-17T21:23:26Z

Lindquist: adding syntax highlighting

As this was a very boring thing to do, I'll share it with the rest of you ;)

With this function injecting KeyDown and KeyUp events to CEGUI works like you'd expect.

<code><cpp/>
/************************************************************************
Translate a SDLKey to the proper CEGUI::Key
*************************************************************************/
CEGUI::uint SDLKeyToCEGUIKey(SDLKey key)
{
using namespace CEGUI;
switch (key)
{
case SDLK_BACKSPACE: return Key::Backspace;
case SDLK_TAB: return Key::Tab;
case SDLK_RETURN: return Key::Return;
case SDLK_PAUSE: return Key::Pause;
case SDLK_ESCAPE: return Key::Escape;
case SDLK_SPACE: return Key::Space;
case SDLK_COMMA: return Key::Comma;
case SDLK_MINUS: return Key::Minus;
case SDLK_PERIOD: return Key::Period;
case SDLK_SLASH: return Key::Slash;
case SDLK_0: return Key::Zero;
case SDLK_1: return Key::One;
case SDLK_2: return Key::Two;
case SDLK_3: return Key::Three;
case SDLK_4: return Key::Four;
case SDLK_5: return Key::Five;
case SDLK_6: return Key::Six;
case SDLK_7: return Key::Seven;
case SDLK_8: return Key::Eight;
case SDLK_9: return Key::Nine;
case SDLK_COLON: return Key::Colon;
case SDLK_SEMICOLON: return Key::Semicolon;
case SDLK_EQUALS: return Key::Equals;
case SDLK_LEFTBRACKET: return Key::LeftBracket;
case SDLK_BACKSLASH: return Key::Backslash;
case SDLK_RIGHTBRACKET: return Key::RightBracket;
case SDLK_a: return Key::A;
case SDLK_b: return Key::B;
case SDLK_c: return Key::C;
case SDLK_d: return Key::D;
case SDLK_e: return Key::E;
case SDLK_f: return Key::F;
case SDLK_g: return Key::G;
case SDLK_h: return Key::H;
case SDLK_i: return Key::I;
case SDLK_j: return Key::J;
case SDLK_k: return Key::K;
case SDLK_l: return Key::L;
case SDLK_m: return Key::M;
case SDLK_n: return Key::N;
case SDLK_o: return Key::O;
case SDLK_p: return Key::P;
case SDLK_q: return Key::Q;
case SDLK_r: return Key::R;
case SDLK_s: return Key::S;
case SDLK_t: return Key::T;
case SDLK_u: return Key::U;
case SDLK_v: return Key::V;
case SDLK_w: return Key::W;
case SDLK_x: return Key::X;
case SDLK_y: return Key::Y;
case SDLK_z: return Key::Z;
case SDLK_DELETE: return Key::Delete;
case SDLK_KP0: return Key::Numpad0;
case SDLK_KP1: return Key::Numpad1;
case SDLK_KP2: return Key::Numpad2;
case SDLK_KP3: return Key::Numpad3;
case SDLK_KP4: return Key::Numpad4;
case SDLK_KP5: return Key::Numpad5;
case SDLK_KP6: return Key::Numpad6;
case SDLK_KP7: return Key::Numpad7;
case SDLK_KP8: return Key::Numpad8;
case SDLK_KP9: return Key::Numpad9;
case SDLK_KP_PERIOD: return Key::Decimal;
case SDLK_KP_DIVIDE: return Key::Divide;
case SDLK_KP_MULTIPLY: return Key::Multiply;
case SDLK_KP_MINUS: return Key::Subtract;
case SDLK_KP_PLUS: return Key::Add;
case SDLK_KP_ENTER: return Key::NumpadEnter;
case SDLK_KP_EQUALS: return Key::NumpadEquals;
case SDLK_UP: return Key::ArrowUp;
case SDLK_DOWN: return Key::ArrowDown;
case SDLK_RIGHT: return Key::ArrowRight;
case SDLK_LEFT: return Key::ArrowLeft;
case SDLK_INSERT: return Key::Insert;
case SDLK_HOME: return Key::Home;
case SDLK_END: return Key::End;
case SDLK_PAGEUP: return Key::PageUp;
case SDLK_PAGEDOWN: return Key::PageDown;
case SDLK_F1: return Key::F1;
case SDLK_F2: return Key::F2;
case SDLK_F3: return Key::F3;
case SDLK_F4: return Key::F4;
case SDLK_F5: return Key::F5;
case SDLK_F6: return Key::F6;
case SDLK_F7: return Key::F7;
case SDLK_F8: return Key::F8;
case SDLK_F9: return Key::F9;
case SDLK_F10: return Key::F10;
case SDLK_F11: return Key::F11;
case SDLK_F12: return Key::F12;
case SDLK_F13: return Key::F13;
case SDLK_F14: return Key::F14;
case SDLK_F15: return Key::F15;
case SDLK_NUMLOCK: return Key::NumLock;
case SDLK_SCROLLOCK: return Key::ScrollLock;
case SDLK_RSHIFT: return Key::RightShift;
case SDLK_LSHIFT: return Key::LeftShift;
case SDLK_RCTRL: return Key::RightControl;
case SDLK_LCTRL: return Key::LeftControl;
case SDLK_RALT: return Key::RightAlt;
case SDLK_LALT: return Key::LeftAlt;
case SDLK_LSUPER: return Key::LeftWindows;
case SDLK_RSUPER: return Key::RightWindows;
case SDLK_SYSREQ: return Key::SysRq;
case SDLK_MENU: return Key::AppMenu;
case SDLK_POWER: return Key::Power;
default: return 0;
}
return 0;
}
</code>

Usage is like so:

<code><cpp/>
SDL_Event e;
while (SDL_PollEvent(&e))
{
if (e.type == SDL_KEYDOWN)
{
CEGUI::uint kc = SDLKeyToCEGUIKey(e.key.keysym.sym);
CEGUI::System::getSingleton().injectKeyDown(kc);
}
}
</code>

--[[User:lindquist|lindquist]] 19:24, 8 Nov 2005 (CET)

Using CEGUI with SDL and OpenGL

2006-07-17T21:15:20Z

Lindquist: adding syntax highlighting

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

<code><cpp/>
if (SDL_Init(SDL_INIT_VIDEO)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}
</code>

Here we initialise SDL with video support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

<code><cpp/>
if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}
</code>

Now OpenGL is ready. But we still need to set a decent configuration:

<code><cpp/>
glEnable(GL_CULL_FACE);
glDisable(GL_FOG);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);
</code>

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're using CEGUI for all your rendering needs this would be fine. Normally you would want the normal perspective projection setup though:

<code><cpp/>
glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();
</code>

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

<code><cpp/>
#include "renderers/OpenGLGUIRenderer/openglrenderer.h"
</code>

It must be created before starting CEGUI.

<code><cpp/>
CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);
</code>

Then the CEGUI::System must be initialised:

<code><cpp/>
new CEGUI::System(renderer);
</code>

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

<code><cpp/>
SDL_ShowCursor(SDL_DISABLE);
</code>

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

<code><cpp/>
SDL_EnableUNICODE(1);
</code>

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

<code><cpp/>
SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);
</code>

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make it all happen, we use a simple main loop that just keeps pushing on those frames:

<code><cpp/>
void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}
</code>

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager.

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user press or release keyboard or mouse buttons, we need to tell CEGUI about it, for this we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

<code><cpp/>
void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONUP:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}
</code>

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

<code><cpp/>
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
</code>

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

<code><cpp/>
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);
</code>

Luckily the key code is just the SDL scancode, so we inject that directly. (This only seems to be true on windows. On other platforms you will need to use a translation function. One can be found here [[SDL to CEGUI keytable]])

<code><cpp/>
// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if (e.key.keysym.unicode != 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode);
}
</code>

Instead of formatting the keypress ourselves, we let SDL do it for us. We could check if we actually got a valid ASCII code, but we want support for local characters as well, so we won't do that. For more information, take a look at the SDL documentation for this feature. [http://www.libsdl.org/cgi/docwiki.cgi/SDL_5fkeysym SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly (As with KeyDown you will need to use a translation function for non Windows platforms. Check KeyDown above for more info):

<code><cpp/>
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
</code>

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel events. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

<code><cpp/>
void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}
</code>

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was released:

<code><cpp/>
void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}
</code>

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other ways to use timers with SDL, but I chose this approach as it is simple to use, and provides decent precision.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' function which in turn will set a new value to it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Let's take a look at the function:

<code><cpp/>
void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}
</code>

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks (a single insanely invalid timepulse will be injected).
I'll leave it up to you to fix that if it's a problem.

=== Rendering ===
Now all that's left is renderingthe GUI.

<code><cpp/>
void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}
</code>

The line:

<code><cpp/>
CEGUI::System::getSingleton().renderGUI();
</code>

does all the CEGUI magic and sets OpenGL state itself. As long as the viewport is setup, it will render the GUI.

=== Error Handling ===
The neat C++ architecture of CEGUI suggests that C++ exceptions are used for error handling. This is completely true.
Whenever an error occurs, a sub-class of ''CEGUI::Exception'' is thrown.

There are many scenarios where an exception can be thrown. And whether or not these should be considered fatal depends on the application. To make sure you catch the CEGUI exceptions a regular ''try'' block is used. Like so:

<code><cpp/>
try
{
// do some cegui code
}
catch (CEGUI::Exception& e)
{
fprintf(stderr,"CEGUI Exception occured: %s", e.getMessage().c_str());
// you could quit here
}
</code>

This should provide you with the basic steps needed to get interactive with CEGUI in your SDL application.
Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Using CEGUI with SDL and OpenGL

2006-07-17T21:11:39Z

Lindquist: adding syntax highlighting

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

<code><cpp/>
if (SDL_Init(SDL_INIT_VIDEO)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}
</code>

Here we initialise SDL with video support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

<code><cpp/>
if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}
</code>

Now OpenGL is ready. But we still need to set a decent configuration:

<code><cpp/>
glEnable(GL_CULL_FACE);
glDisable(GL_FOG);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);
</code>

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're using CEGUI for all your rendering needs this would be fine. Normally you would want the normal perspective projection setup though:

<code><cpp/>
glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();
</code>

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

<code><cpp/>
#include "renderers/OpenGLGUIRenderer/openglrenderer.h"
</code>

It must be created before starting CEGUI.

<code><cpp/>
CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);
</code>

Then the CEGUI::System must be initialised:

<code><cpp/>
new CEGUI::System(renderer);
</code>

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

<code><cpp/>
SDL_ShowCursor(SDL_DISABLE);
</code>

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

<code><cpp/>
SDL_EnableUNICODE(1);
</code>

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

<code><cpp/>
SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);
</code>

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make it all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager.

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user press or release keyboard or mouse buttons, we need to tell CEGUI about it, for this we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONUP:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly. (This only seems to be true on windows. On other platforms you will need to use a translation function. One can be found here [[SDL to CEGUI keytable]])

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if (e.key.keysym.unicode != 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. We could check if we actually got a valid ASCII code, but we want support for local characters as well, so we won't do that. For more information, take a look at the SDL documentation for this feature. [http://www.libsdl.org/cgi/docwiki.cgi/SDL_5fkeysym SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly (As with KeyDown you will need to use a translation function for non Windows platforms. Check KeyDown above for more info):

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel events. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was released:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other ways to use timers with SDL, but I chose this approach as it is simple to use, and provides decent precision.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' function which in turn will set a new value to it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks (a single insanely invalid timepulse will be injected).
I'll leave it up to you to fix that if it's a problem.

=== Rendering ===
Now all that's left is renderingthe GUI.

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets OpenGL state itself. As long as the viewport is setup, it will render the GUI.

=== Error Handling ===
The neat C++ architecture of CEGUI suggests that C++ exceptions are used for error handling. This is completely true.
Whenever an error occurs, a sub-class of ''CEGUI::Exception'' is thrown.

There are many scenarios where an exception can be thrown. And whether or not these should be considered fatal depends on the application. To make sure you catch the CEGUI exceptions a regular ''try'' block is used. Like so:

try
{
// do some cegui code
}
catch (CEGUI::Exception& e)
{
fprintf(stderr,"CEGUI Exception occured: %s", e.getMessage().c_str());
// you could quit here
}

This should provide you with the basic steps needed to get interactive with CEGUI in your SDL application.
Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Changes and Porting Tips for 0.5.0

2006-05-20T23:28:19Z

Lindquist:

Note that this is incomplete, work in progress, documentation.
==Introduction==
The 0.5.0 release of Crazy Eddie's GUI System is the first of what will likely be a series of releases containing breaking changes for client code and data files. We feel these breaking changes are required as we move closer to the 1.0 release of CEGUI, and also as the design and usage patterns for CEGUI change; the results are a generally more streamlined system as we move from one idiom to another, as opposed to becoming more and more bloated due to retaining vast amounts of code and kludges for backward compatibility reasons.

This document is a general overview and guide to the breaking changes between the 0.4.x series of releases and the 0.5.0 release. As and when other breaking releases are made, additional documentation will be provided as necessary.

==Changes and Porting==
This section is intended as a general overview of the breaking changes made. Blah, blah, blah.

===Code Changes===
This sub-section details changes made to the CEGUI system code and API which will affect client code.

====The new WindowRenderer system====
One of the main issues with the previous widget module approach, was that it became exceptionally difficult to sub-class a widget type where some custom behavioural changes or additions were required.
*** TODO ***

====CEGUI::System Constructor====
The overloaded constructors for the main CEGUI::System object have been removed and replaced with a single, unified, constructor. Using the new constructor it is still possible to do all the things that used to be possible, while making the whole system construction process a little more uniform.

The new constructor has the form:
System(Renderer* renderer,
ResourceProvider* resourceProvider = 0,
XMLParser* xmlParser = 0,
ScriptModule* scriptModule = 0,
const String& configFile = "",
const String& logFile = "CEGUI.log");

As can be seen, the Renderer module is, of course, still mandatory, though you are free to provide all or none of the other optional arguments and passing in 0 where no object, or no custom object, is required.

For the most basic uses of the system, where only the Renderer is passed in, no changes will be required.

====System::setTooltip changed to System::setDefaultTooltip====
The member function
System::setTooltip
has been renamed as
System::setDefaultTooltip
this was a change for API consistency. Update your code to use the new name for this member.

====Window MetricsMode removed====
The concept of a singular 'MetricsMode' for a window is now obsolete and is replaced with the 'Unified' metrics system (which comprises of both a relative 'scale' value and an absolute 'offset' value).

The class members, properties and all associated items affecting MetricsMode have been removed from the system and the use of the Unified metrics system is now mandatory.

====Window Metrics and other conversion members removed====
Member functions in the Window class that were concerned with converting values between the various metric modes have all been removed.
There may still be the need to perform some conversions of co-ordinates, so this functionality is now provided by the external utility class CEGUI::CoordConverter.
Window Size and Positioning

Due to the removal of the MetricsMode concept, and the now mandatory use of 'Unified' co-ordinate values, the means by which you specify size and position is now by using the unified type members.

*getXPosition, getRelativeXPosition and getAbsoluteXPosition members are replaced with getWindowXPosition.
*getYPosition, getRelativeYPosition and getAbsoluteYPosition members are replaced with getWindowYPosition.
*getPosition, getRelativePosition and getAbsolutePosition members are replaced with getWindowPosition.
*getWidth, getRelativeWidth and getAbsoluteWidth members are replaced with getWindowWidth
*getHeight, getRelativeHeight and getAbsoluteHeight members are replaced with getWindowHeight
*getSize, getRelativeSize and getAbsoluteSize members are replaced with getWindowSize
*getRect, getRelativeRect and getAbsoluteRect members are replaced with getWindowArea
*getMaximumSize member is replaced with getWindowMaxSize
*getMinimumSize member is replaced with getWindowMinSize
*setWidth members are replaced with setWindowWidth
*setHeight members are replaced with setWindowHeight
*setSize members are replaced with setWindowSize
*setXPosition members are replaced with setWindowXPosition.
*setYPosition members are replaced with setWindowYPosition.
*setPosition members are replaced with setWindowPosition.
*setAreaRect and setRect members are replaced with setWindowArea
*setMaximumSize member is replaced with setWindowMaxSize
*setMinimumSize member is replaced with setWindowMinSize

====Component Widget creation abstract members====
If you have sub-classed any Window types in order to create a new “Widget Module”, part of your responsibility was to provide implementations for various abstract member functions whose job it was to create the various component widgets required by the container window. These members were typically named createXXX (for example, Combobox::createEditbox).

These abstract member functions and the internal calls to them have all been removed from the system. The component widgets are now specified within the looknfeel xml files are are automatically created by the Falagard looknfeel system as and when required.
You should remove any code that creates these component widgets and add appropriate <Child> tags to your looknfeel xml files instead.

====Component Widget member fields====
If you had sub-classed any of the Window types, either to provide some modified behaviour or perhaps for a “Widget Module” as part of creating a custom look, you would previously have had access to some member variables that held pointers to component widgets of the more complicated widget types (for example, the Scrollbar widget would have held pointers to the two PushButton widgets and the Thumb widget that it was composed of). These members have now been removed and replaced with 'getter' member functions; this is important because in the future the actual Window objects used for these component parts may not be valid for the entire life of the containing Window. That is, the component Windows may get destroyed and re-created, thus invalidating any cached pointers.

The old member variables and the getter function that replaces them are listed here:
*** TODO ***

====RenderableElement, RenderableImage and RenderableFrame classes====
These classes have all been removed from the system entirely. Everything that these classes achieved with regards to rendering for window and widget types can now be done via the Falagard looknfeel system.

For window based rendering, you should remove your use of Renderable* classes in favour of ImageryComponent and FrameComponent elements in your looknfeel xml files.
If you were using the Renderable* classes to perform rendering outside of the window rendering systems, you will now need to find alternative, custom, means to do this.

====Static, StaticImage and StaticText classes====
These classes are now removed from the base system and have been implemented as WindowRenderer classes. Generally, your interface to these widget types should now use a simple default window and the properties system.

The look'n'feel spec for these two widgets have changed as well.

StaticImage:
<pre>
The LookNFeel should provide the following:

States:
- Enabled - basic rendering for enabled state.
- Disabled - basic rendering for disabled state.
- EnabledFrame - frame rendering for enabled state
- DisabledFrame - frame rendering for disabled state.
- WithFrameEnabledBackground - backdrop rendering for enabled state with frame enabled.
- WithFrameDisabledBackground - backdrop rendering for disabled state with frame enabled.
- NoFrameEnabledBackground - backdrop rendering for enabled state with frame disabled.
- NoFrameDisabledBackground - backdrop rendering for disabled state with frame disabled.
- WithFrameImage - image rendering when frame is enabled
- NoFrameImage - image rendering when frame is disabled (defaults to WithFrameImage if not present)
</pre>

StaticText:
<pre>
The LookNFeel should provide the following:

States:
- Enabled - basic rendering for enabled state.
- Disabled - basic rendering for disabled state.
- EnabledFrame - frame rendering for enabled state
- DisabledFrame - frame rendering for disabled state.
- WithFrameEnabledBackground - backdrop rendering for enabled state with frame enabled.
- WithFrameDisabledBackground - backdrop rendering for disabled state with frame enabled.
- NoFrameEnabledBackground - backdrop rendering for enabled state with frame disabled.
- NoFrameDisabledBackground - backdrop rendering for disabled state with frame disabled.

Named Areas (missing areas will default to 'WithFrameTextRenderArea'):
WithFrameTextRenderArea
WithFrameTextRenderAreaHScroll
WithFrameTextRenderAreaVScroll
WithFrameTextRenderAreaHVScroll
NoFrameTextRenderArea
NoFrameTextRenderAreaHScroll
NoFrameTextRenderAreaVScroll
NoFrameTextRenderAreaHVScroll

</pre>

====Dynamic addition of Events to Windows and other EventSet based objects====
It used to be that all available Event objects would be pre-added to an EventSet when it was constructed. When an Event was accessed which had not been added to the EventSet an appropriate exception was thrown.

This behaviour has now changed. Events are only added to an EventSet when a handler for that event is first subscribed. A side effect of this is that EventSet does now not throw exceptions, either when firing a non-existing Event (now reclassified as simply an event which has no subscribers), or when subscribing to an Event that does not yet exist, since the Event is now automatically created and added to the EventSet.

If your code currently relies on exceptions being thrown by the events system, you will need to change this to a more pro-active approach (by manually checking if an event exists yet), instead of reactive (catching exceptions).

====TinyXML moved to CEGUITinyXML namespace====
If you were for some reason using our integrated copy of TinyXML directly in your application, we have moved this module into the namespace 'CEGUITinyXML'. This was done to avoid clashes and conflicts where the client contained it's own copy of TinyXML.

To continue to directly use the integrated TinyXML, just add the namespace qualifier where appropriate.

If you are just using the TinyXML based implementation of CEGUI::XMLParser, you do not need to change anything.

===Data File Changes===
This sub-section details changes that will affect the xml data files used with CEGUI.

====Updated XSD files for Xerces====
Even the most rudimentary changes to the xml formats we use mean that if you're using the Xerces-C, or other, validating XML parser, then you will need to update you projects to use the new .xsd files. These are collected together for convenience in the XMLRefSchema subdirectory.

=== Falagard Additions ===
From lack of a better place to put this I'll list the additions that have been made to Falagard here.

'''PropertyLinkDefinition'''
New element that will create a property that is a link to another property of a child window.

Attributes:
* type (type, optional and not currently used for anything)
* name (name of the property link)
* widget (name suffix of the child widget to link to)
* targetProperty (the target property to link to. Optional, will default to ''name'' if not given)
* initialValue (starting value for the property. Optional, will default to empty)
* layoutOnWrite (will make the widget redo the child layout when the property is written. Optional, defaults to ''false'')
* redrawOnWrite (will make the widget redraw when the property is written. Optional, default to ''false'')

'''controlProperty'''

New attribute added to ''Section''. Value is the name of a property, and if specified the Section will only render when the property has a value of ''True''.

'''TextComponent'''

Two new sub-elements are now valid for ''TextComponent''.

''TextProperty'', and ''FontProperty''. Must be specified in that order after the (optional) ''Text'' element.
Both have one required attribute ''name'' which takes the name of a property which will contain the text to draw, or the name of the font to use for rendering.

In case these new elements are used along with the ''Text'' element, the string and font specified in the ''Text'' element will be used as defaults if the ''TextProperty'' or ''FontProperty'' evaluates to empty strings.

To be continued...

FAQ

2006-05-20T17:27:01Z

Lindquist:

== General Questions ==
=== What is CEGUI? ===
CEGUI is ''Crazy Eddie's Gui System''; a cross platform Gui/widget library for use in games and other multi-media projects where use of standard operating system Gui libraries is either not possible, or is very difficult.

=== How is CEGUI licensed? ===
CEGUI is licensed under the LGPL (Lesser/Library General Public License). For details of this license, please visit the following web-site: http://www.gnu.org/copyleft/lesser.html.

Starting from the 0.5 release CEGUI will be licensed under the [http://www.opensource.org/licenses/mit-license.php MIT license]

=== How much does CEGUI cost? ===
Nothing. The use of CEGUI is totally free within the bounds of the license as described above.

=== I am developing a commercial, closed-source product. Since CEGUI 0.4 is licensed under LGPL, this means that can't I use the library, right? ===
No, that's not right. So long as you link dynamically to CEGUI and associated libraries, then you do not have to release any of your own source or .o/.obj files, though do carefully check the LGPL, and the licenses for the third party libraries for full details of what is and is not permissible.

=== I am not happy with the LGPL / MIT license, do you offer alternative licensing? ===
No. Alternative licensing is not available, nor is it planned.

=== And what if I need to develop to a plataform wich doesn´t support dynamic linking? ===
Use the 0.5 release as the MIT license allows static linking.

=== Does CEGUI rely upon any third party libraries? If so what are they? ===
CEGUI currently depends upon the following external libraries:

* FreeType2
* Xerces-C++ (optional, built-in TinyXML parser is provided)

You will also require a supported rendering system, and some form of input library.

=== Where can I get these third party libraries? ===

* FreeType2: http://www.freetype.org/
* Xerces-C++: http://xml.apache.org/xerces-c/

=== Do I have to compile the third part libraries myself? ===
It depends. Under Linux and similar systems, you will need to perform your own compilation. For Microsoft® Windows® users, we have supplied packages containing binary versions of the libraries for a selection of popular compiler configurations.

=== You mentioned something about "supported rendering systems", what's that all about and which systems are supported? ===
CEGUI can be used with various rendering systems. There are currently CEGUI renderer modules for Microsoft® DirectX® 8.1 and 9, OpenGL, the Ogre engine, and the Irrlicht engine.

=== There is no renderer module for my rendering engine or API of choice, will other rendering system be supported? ===
It is likely that, over time, CEGUI will add support for other APIs and engines. Having said this, it is fairly simple to write your own renderer module for CEGUI, so you might consider taking that option if you do not want to wait.

=== And what about input libraries? ===
CEGUI requires you to ''inject'' inputs into it, these inputs can come from any source that you choose. All you need to do is pass mouse movements, mouse button up and down events, and keyboard inputs to CEGUI.

=== Why doesn't CEGUI collect its own inputs? Why do I need to inject the inputs myself? ===
CEGUI does not collect its own input so that the system can remain as flexible as possible. We didn't want to tie people down to one system or input library.

=== I have seen mention of a Lua scripting module, how can I get this? ===
The Lua scripting module is provided with CEGUI and resides in the same source repository. Downloading CEGUI binary/source/svn will get you everything you need.

=== I can't find many of the things you talk about in my crayzedsgui code, what's wrong? ===
You probably have one of the older Mk-1 alpha releases. Get the newer Mk-2 releases instead, the archive files for these generally have names with cegui_mk2 in them.

=== Why are there two versions of the system? ===
The Mk-1 version was a Windows®/DirectX® only library and was really a dry run for what became the Mk-2 system. There was only ever 'alpha' versions of the Mk-1 code, so it was never anywhere near finished.

=== Are the Mk-1 and Mk-2 systems interface compatible? ===
No. The interfaces of the two systems are totally different, although many of the general concepts have remained the same.

=== The Mk-1 system is so much more lightweight than the Mk-2 system. Can I still use the Mk-1 code? Is the Mk-1 code still being developed and supported? ===
Short Answer: Not really.

Long Answer: There were too many weak areas within the Mk-1 system and development on this version has ceased completely. There is no longer any support for the Mk-1 version; in general it would be better for everyone if they migrated to the Mk-2 version of the system.

=== I am having major troubles integrating CEGUI with my project, will you do it for me? ===
No. The CEGUI developers have enough to do without writing users projects for them.

=== I have (or think I have) found a bug. How should I proceed? ===
If you are certain that it's a bug and not, for example, a misunderstanding of what is happening, then the bug should be reported via the project bug tracking system. However, before submitting a bug to the tracker, it is asked that you first do a quick search to see if the bug has already been reported. If you are unsure whether something is a bug or not, then it may be discussed on the web site forums prior to submitting a bug report to the project bug tracker.

=== I notice that feature/widget 'X' is missing. Will this be added to CEGUI? ===
Requests for new features and/or widgets are welcomed. You can discuss such things on the web site forums and then submit a feature request to the project feature request tracking system. Although it is asked that you first search to ensure that the feature has not already been requested; if the feature has already been requested feel free to add a note to the tracker item stating your support for the feature request. Note that no promises are made with regards to which features will and will not be added, or how long such things will take, but all requests will be seriously considered.

=== How can I get involved with CEGUI development? ===
The best way to become involved is to visit the web site forums, state what your intentions are (to help in avoiding duplicated effort), and then start submitting some patches to the project patch tracking system.

=== Is there managed code / Microsoft .Net support for the CEGUI library? ===
Yes, there is ''ceguisharp'' at http://realmforgewiki.castlegobs.nl/index.php/CEGUI This is a C# port of the library which uses the excellent Axiom rendering engine.

=== This FAQ doesn't answer my question, what should I do now? ===
Feel free to post your question on the web site forums, somebody will gladly answer your question and/or offer further advice.

== Build Questions ==

(A work in Progress)

=== Building CEGUI ===
# General Requirements
# Dependency installs

=== Building from CVS ===
''(The following instructions are for unix systems)''

==== Configuring CEGUI ====
First, we need to generate the configure script, as well as a few other files.
In the cegui_mk2 directory, run:
$ sh ./bootstrap
Now, it's time to actually run configure:
$ ./configure

==== Building CEGUI ====
With all this one, we can now build CEGUI.
Type:
$ make
Once that's finished, we can install it!
Type:
$ make install

Tada!

=== CEGUI Layout Editor Build ===
For full details, please refer to this seperate wiki page: http://www.cegui.org.uk/wiki/index.php/The_%22official%22_layout_editor
# Dependency installs (for versions > 0.4.0)
Install wxWidgets
# Building

== Usage Questions ==
=== What is the correct way to subscribe for an event? ===
Event notification is a vital aspect of GUI programming. CEGUI handles those using subscribers.
In order to subscribe a window for an event, you have to call the method 'Window::subscribeEvent', passing the function
to be called when the specified event occurs, and the instance on which the method is called.

class MyButtonHandler
{
private:
PushButton* mButton;

public:
MyButtonHandler::MyButtonHandler(PushButton* btn) : mButton(btn)
{
btn->subscribeEvent(PushButton::EventClicked, Event::Subscriber(MyButtonHandler::ButtonClicked,this));
}

MyButtonHandler::ButtonClicked()
{
//This function gets called when the button is clicked
std::cout << "Button clicked" << std::endl;
}

The 'subscribeEvent' method returns an Event::Connection, which can be used later to unsubscribe for a registered event with
the 'disconnect' method.

Event::Connection myCon = btn->subscribeEvent(...);

...

myCon->disconnect();

In order to totally remove the event itself, you have to call the 'removeEvent' function:
all the connections to the specified event will be disconnected.
There's also an Event::ScopedConnection, which can be used to auto-unsubscribe when the event goes out of scope.

Similar way for the scripted events, which can be subscribed with the 'subscribeScriptedEvent' method.
In addition, you can do it in XML, using this syntax:

<Event Name="Clicked" Function="luabtn_clicked" />

=== How can I make the ListBox highlight the selected item? ===
In order to highlight selected items you need to set selection brush image and the selection colours of that item. The selection image is modulated by the colours you set. Note, that the alpha component needs to be smaller than 1.0, for the content of the selected item to be seen.
// set selection highlight to a half transparent blue to red gradient.
colour blue(0.0, 0.0, 1.0, 0.5);
colour red(1.0, 0.0, 0.0, 0.5);
myListBoxItem->setSelectionColours(blue, blue, red, red);
// this default image is a simple white rectangle
myListBoxItem->setSelectionBrushImage("TaharezLook", "ListboxSelectionBrush");

=== How can I remove the border of a StaticImage? ===
Either put the following property into the window definition:
<Property Name="FrameEnabled" Value="false" />
Or set it by code:
myStaticImage->setFrameEnabled(false);

=== How can I set the background of a StaticImage? ===
The first thing you need in order to do this is an Imageset that defines the Image that you wish to use. When wanting to use an image file for this as you suggest, you basically have an imageset defined like this:
<?xml version="1.0" ?>
<Imageset Name="BackdropImageset" Imagefile="backdrop.tga" NativeHorzRes="1024" NativeVertRes="768" AutoScaled="true">
<Image Name="Backdrop" XPos="0" YPos="0" Width="1024" Height="768" />
</Imageset>

What this does is define an Imageset using the backdrop.tga. A single image "Backdrop" is defined that starts at location (0,0) and is 1024 x 768 in size. You should be careful in that the source image file should have dimensions that are powers of two - this is because the image is loaded as a texture, and may be stretched if the powers-of-two requirement is not observed.<br>
Once you have your imageset defined, you can load it either by adding a reference to it in whichever scheme you are loading, or manually using the ImagesetManager:
CEGUI::ImagesetManager::getSingleton().createImageset("myImageset.imagset");
Once the thing is loaded, you set the image into the StaticImage like so:
myStaticImage->setImage("BackdropImageset", "Backdrop");
Notice that the names we specify here are the ones that were originally specified in the imageset XML file.<br>

=== What properties are available for use in XML layouts, and what format do I use for the value strings? ===
Each widget has its properties placed within an appropriately named C++ namespace, so all you need to do is look up the appropriate namespace within the [http://www.cegui.org.uk/api_reference/namespaces.html namespaces section of the API reference].

Also, remember that properties are inherited. So for example, when looking up properties for a PushButton, also check the properties for ButtonBase and Window too - since these properties are also available to you.

=== I can't see the items I've added to my Combobox, how do I get the list to show when I press the button? ===

The height you specify for the combobox widget includes the height of the drop down list; it's not just for the 'Editbox' portion of the widget (the height of which is usually automatically determined based upon the font). Ensure that when specifying the height for your combobox, you have provided sufficient space for the list to appear.

Template:CEGUIWikiGettingStarted

2006-05-18T21:06:18Z

Lindquist:

* [[What is CEGUI]]?
* [[FAQ|Frequently Asked Questions]]
* [[Tutorials]]
* [[CodeSnippets]]
* [[HOW-TO series]]
* [["Falagard" Skinning System Documentation]]
* [[The "official" layout editor]]
* [[XML File formats]]
* [[X-Files: CEGUI Case]]
* [[User Contributed Material]]
* [[Assembling a Toolset]]
* [[Porting to the 0.5.0 Release]]
* [[CEGUI Developer Corner]]

Changes and Porting Tips for 0.5.0

2006-05-18T20:59:20Z

Lindquist: /* Static, StaticImage and StaticText classes */

Tooltips

2006-04-17T13:13:57Z

Lindquist:

I am not an expert but I would like to share what I have learned and gleaned about the ''Tooltip'' widget.

API References:
[http://www.cegui.org.uk/api_reference/classCEGUI_1_1Tooltip.html Tooltip]
[http://www.cegui.org.uk/api_reference/classCEGUI_1_1System.html System]

As you would expect, the ''Tooltip'' works very similar to most tooltip systems. Basically the user hovers the mouse over a CEGUI widget and when a specified time has elapsed the tooltip is displayed for a specified amount of time. As with most of the CEGUI widgets the ''Tooltip'' widget is based upon the CEGUI ''Window'' class widget.

''Please note that the following example source code was gleaned and edited from project specific code so there may be some syntax errors.''

== Creating the Default System ''Tootip'' widget ==

CEGUI will manage a single default, system wide ''Tooltip'' widget for you that will take care of displaying your tooltip text. You have to initialize it by calling '''CEGUI::System::setTooltip()'' one time, somehwere in your code. I would recommend calling this right after initializing the CEGUI system. Here's a sample call:

<pre>
// Create default ToolTip item
CEGUI::System::getSingleton().setTooltip( (CEGUI::utf8*)"TaharezLook/Tooltip" );
</pre>

Yep, that's all there is too it.
In newer versions of CEGUI the method has been renamed to setDefaultTooltip for consistency.

== Setting the ''Tootip'' text to display ==

There are two methods for setting your tooltip text: In your code or in your layout file.

'''Setting the ''Tooltip'' text in your code'''

You can hardcode toolip text in your code by using the ''WindowObject::setTooltipText()'' function like so:
<pre>
CEGUI::PushButton *mPushButton = (CEGUI::PushButton *)mWinMgr->createWindow(
(CEGUI::utf8*)"TaharezLook/PushButton", (CEGUI::utf8*)"PushButton");
// Set other properties like size, position, etc.
mPushButton->setTooltipText("This is a tooltip.");
</pre>

'''Setting the ''Tooltip'' text in your layout (xml) file'''

The prefered method is to set the tooltip text in your layout file and you can do it like so:
<pre>
<Window Type="TaharezLook/Editbox" Name="Login/EditBox/Password">
<Property Name="AbsoluteRect" Value="l:128.000000 t:0.000000 r:486.000000 b:46.000000" />
<Property Name="AlwaysOnTop" Value="True" />
<Property Name="RelativeRect" Value="l:0.250000 t:0.000000 r:0.950000 b:1.000000" />
<Property Name="Text" Value="{Enter Password Here}" />
<Property Name="Tooltip" Value="Enter your password here." />
</Window>

</pre>

'''Ensure that the Tooltip is registered in your .Scheme file'''
<pre>
<WindowSet Filename="CEGUITaharezLook">
....
<WindowFactory Name="TaharezLook/Tooltip" />
....
</WindowSet>
</pre>
'''Ensure that imageset contains graphics for the Tooltip'''
<pre>
<Imageset Name="TaharezLook" Imagefile="TaharezLook.png" NativeHorzRes="800" NativeVertRes="600" AutoScaled="true">
....
<Image Name="TooltipLeftEdge" XPos="217" YPos="225" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipRightEdge" XPos="246" YPos="225" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipTopEdge" XPos="224" YPos="218" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipBottomEdge" XPos="224" YPos="248" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipTopLeft" XPos="217" YPos="218" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipTopRight" XPos="246" YPos="218" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipBottomLeft" XPos="217" YPos="248" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipBottomRight" XPos="246" YPos="248" Width="7" Height="7" XOffset="0" YOffset="0"/>
<Image Name="TooltipMiddle" XPos="2" YPos="2" Width="64" Height="64" XOffset="0" YOffset="0"/>
...
</Imageset>
</pre>

== How to display the ''Tooltip'' ==

'''Inject Time Pulse'''

''CEGUI::System::injectTimePulse(float timeElapsed)''

This is a very important piece of information that is not well documented in the current CEGUI system: ''Time Pulse Injection''. The CEGUI system, to my knowledge, does not keep track of time for you by itself - it needs help. You must inject into the CEGUI System elapsed time. If you don't do this, then your ''Tooltip'' and other time sensitive window events (like fades, etc) will not work or will not work properly. What is the ''value'' you inject? The ''value'' should be the amount of time that has elapsed since the previous injection call. Refer to the ''CEGUI::System::injectTimePulse()''. The best place to inject a time pulse into the CEGUI system is in a main loop. Here are a couple of examples of how to implement this:

'''Inject Time Pulse: via a MAIN Loop'''

<pre>

#include <time.h>
...
clock_t mLastTimeInjection=clock();
...
// Your main loop
while ( true )
{
...
// Make sure the CEGUI System is initialized and running
// and if it is, inject a time pulse
if ( CEGUI::System::getSingletonPtr() )
{
CEGUI::System::getSingleton().injectTimePulse( ( clock() - mLastTimeInjection ) * 0.001f );
mLastTimeInjection = clock();
} // CEGUI Time pulse
...
} // while
...

</pre>

'''Inject Time Pulse: via an Ogre::FrameListenter'''
<pre>

bool clsMyFrameListener::frameStarted(const Ogre::FrameEvent& evt)
{
...
// Make sure the CEGUI System is initialized and running
// and if it is, inject a time pulse
if ( CEGUI::System::getSingletonPtr() )
CEGUI::System::getSingleton().injectTimePulse( evt.timeSinceLastFrame );
...
return true;
} //frameStarted

</pre>

The finer the resolution of the injection, the better your fades will look. Injecting time every one second or greater will make your ''fades'' just popup instead of ''fading'' in.

== Conclusion ==

That's really all there is to it. My biggest ''gotcha'' was the not knowing about the ''CEGUI::System::injectTimePulse()'' and how important it was. Once I stumbled upon that everything else fell into place.

Some advanced notes. You can have more than one ''Tooltip'' widget. There maybe some scenerios where just one ''Tooltip'' widget won't work (like for a different look and feel from that of the default one, etc.). You can create another ''Tooltip'' widget using the standard CEGUI method for creating all the window widgets then use the ''CEGUI::Window::setToolTip()'' function to set the widget to use the desired ''Tooltip''.

XML File formats

2006-03-27T22:03:13Z

Lindquist:

*[[Scheme files]] - Reference manual for the scheme XML format.
*[[Layout files]] - Reference manual for the layout XML format.
*[[Imageset files]] - Reference manual for the layout XML format.
*[[Font files]] - Reference manual for the font XML format.
* Looknfeel files - Check the [["Falagard" Skinning System Documentation]].

===Related Documents===
* [[Overview of GUI files]] - an brief overview of what role each these xml files plays.

XML File formats

2006-03-27T22:02:44Z

Lindquist:

*[[Scheme files]] - Reference manual for the scheme XML format.
*[[Layout files]] - Reference manual for the layout XML format.
*[[Imageset files]] - Reference manual for the layout XML format.
*[[Font files]] - Reference manual for the font XML format.
* Looknfeel files - Check the [["Falagard" Skinning System Documentation]]

===Related Documents===
* [[Overview of GUI files]] - an brief overview of what role each these xml files plays.

Using CEGUI with SDL and OpenGL

2005-09-13T11:24:16Z

Lindquist: Updated link to documentation for SDL_keysym

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're using CEGUI for all your rendering needs this would be fine. Normally you would want the normal perspective projection setup though:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make it all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. [http://www.microsoft.com Microsoft] Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user press or release keyboard or mouse buttons, we need to tell CEGUI about it, for this we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://www.libsdl.org/cgi/docwiki.cgi/SDL_5fkeysym SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel events. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was released:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other ways to use timers with SDL, but I chose this approach as it is simple to use, and provides decent precision.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' function which in turn will set a new value to it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...
I'll leave it up to you to fix that if it's a problem.

=== Rendering ===
Now all that's left is renderingthe GUI.

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets OpenGL state itself. As long as the viewport is setup, it will render the GUI.

=== Error Handling ===
The neat C++ architecture of CEGUI suggests that C++ exceptions are used for error handling. This is completely true.
Whenever an error occurs, a sub-class of ''CEGUI::Exception'' is thrown.

There are many scenarios where an exception can be thrown. And whether or not these should be considered fatal depends on the application. To make sure you catch the CEGUI exceptions a regular ''try'' block is used. Like so:

try
{
// do some cegui code
}
catch (CEGUI::Exception& e)
{
fprintf(stderr,"CEGUI Exception occured: %s", e.getMessage().c_str());
// you could quit here
}

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Writing CEGUI scripts

2005-07-05T20:03:22Z

Lindquist:

The code on this page is Lua script using the CEGUILua bindings available in CEGUI 0.3.
The code snippets might not be specifically useful, but they should show off some of the posibilities with CEGUI and Lua used together. And give an idea of how to write these scripts.

Off we go :)

--[[User:Lindquist|Lindquist]] 20:56, 9 Jun 2005 (BST)

== Change logging level ==
local logger = CEGUI.Logger:getSingleton() -- get the logger
local lvl = logger:getLoggingLevel() -- get logging level

if lvl < CEGUI.Insane then -- if logging level is less than insane
logger:setLoggingLevel(lvl+1) -- then increase it
end
Bumps up the logging level a notch unless we're already at Insane.

== Load a scheme ==
CEGUI.SchemeManager:getSingleton():loadScheme("../datafiles/schemes/TaharezLook.scheme")
Loads the TaharezLook scheme.

== Simple Interface ==
-- create the GUI sheet
local sheet = CEGUI.WindowManager:getSingleton():createWindow("DefaultGUISheet","root");
CEGUI.System:getSingleton():setGUISheet(sheet) -- and attach it to the system

-- create a FrameWindow
local fw = CEGUI.WindowManager:getSingleton():createWindow("TaharezLook/FrameWindow","framewnd");
-- add it to the sheet
sheet:addChildWindow(fw)

-- set its size and position
local sz = CEGUI.Size:new_local(0.5,0.5)
local pos = CEGUI.Point:new_local(0.2,0.1)
fw:setSize(sz)
fw:setPosition(pos)
-- disable user sizing
fw:setProperty("SizingEnabled","False")

-- make the close button work
fw:subscribeEvent("CloseClicked","fwCloseClicked")

-- the CloseClicked event handler
function fwCloseClicked(eventArgs)
local we = CEGUI.toWindowEventArgs(eventArgs)
CEGUI.WindowManager:getSingleton():destroyWindow(we.window) -- destroy the frame window
end
Creates a GUISheet and attaches it to the System. Then creates a FrameWindow, sets its size and position. Disables the sizing feature and subscribes a scripted event handler to destroy the window when the close button is clicked.

== Alternative casting ==
-- the CloseClicked event handler
function fwCloseClicked(eventArgs)
local we = tolua.cast(eventArgs,"CEGUI::WindowEventArgs")
CEGUI.WindowManager:getSingleton():destroyWindow(we.window) -- destroy the frame window
end
A modified close button click handler (from the previous snippet) showing an alternative way to cast EventArgs to WindowEventArgs

== Load a layout ==
local w = CEGUI.WindowManager:getSingleton():loadWindowLayout("../datafiles/layouts/test.layout")
CEGUI.System:getSingleton():getGUISheet():addChildWindow(w)
Loads a XML layout and adds the returned window to the active GUISheet.

== Menubar with popup ==
-- do the menubar
local bar = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/Menubar","the_menu_bar")
bar:setSize(CEGUI.Size:new_local(1,0.1))
CEGUI.System:getSingleton():getGUISheet():addChildWindow(bar)

-- add a menuitem to the bar
local item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/MenubarItem","the_menu_bar_item")
item:setText("Bar item")
bar:addChildWindow(item)

-- add a popupmenu to the bar's menuitem
local pop = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenu","the_popup_menu")
item:addChildWindow(pop)

-- add a few menuitems to the popup
item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenuItem","the_popup_menu_item_1")
item:setText("Popup item 1")
pop:addChildWindow(item)

item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenuItem","the_popup_menu_item_2")
item:setText("Popup item 2")
pop:addChildWindow(item)
Creates a simple menubar and adds a popupmenu with two items to it.

Tutorials

2005-07-05T20:00:54Z

Lindquist:

=== CrazyEddie's Beginner Guides ===
* [[The Beginner Guide to Getting CEGUI Rendering]] - How to initialise CEGUI to render properly.
* [[The Beginner Guide to Loading Data Files and Initialisation]] - How to load some data files and perform basic system initialisation.
* [[The Beginner Guide to Creating a CEGUI Window]] - How to create a simple window and get it on screen.
* [[The Beginner Guide to Injecting Inputs]] - How to inject inputs into CEGUI and get interactive.

=== Lua Scripting with CEGUI ===
* [[Getting Started with Lua and CEGUI]] - How to initialise CEGUI with a Lua script module and configuration file.
* [[Handling Events from Lua]] - How to load Lua script files and bind CEGUI events to Lua functions.
* [[Writing CEGUI scripts]] - Code snippets
* [[Adding LuaScriptModile to Sample_FirstWindow]] - Experience adding scripting to an existing sample.

=== SDL Tutorials ===
* [[Using CEGUI with SDL and OpenGL]] - Guidelines on how to get SDL, OpenGL and CEGUI running together.

Writing CEGUI scripts

2005-07-04T14:40:43Z

Lindquist:

All code on this page is Lua script using the CEGUILua bindings available on CVS HEAD.
The code snippets might not be specifically useful, but they should show off some of the posibilities with CEGUI and Lua used together. And give an idea of how to write these scripts.

Off we go :)

--[[User:Lindquist|Lindquist]] 20:56, 9 Jun 2005 (BST)

== Change logging level ==
local logger = CEGUI.Logger:getSingleton() -- get the logger
local lvl = logger:getLoggingLevel() -- get logging level

if lvl < CEGUI.Insane then -- if logging level is less than insane
logger:setLoggingLevel(lvl+1) -- then increase it
end
Bumps up the logging level a notch unless we're already at Insane.

== Load a scheme ==
CEGUI.SchemeManager:getSingleton():loadScheme("../datafiles/schemes/TaharezLook.scheme")
Loads the TaharezLook scheme.

== Simple Interface ==
-- create the GUI sheet
local sheet = CEGUI.WindowManager:getSingleton():createWindow("DefaultGUISheet","root");
CEGUI.System:getSingleton():setGUISheet(sheet) -- and attach it to the system

-- create a FrameWindow
local fw = CEGUI.WindowManager:getSingleton():createWindow("TaharezLook/FrameWindow","framewnd");
-- add it to the sheet
sheet:addChildWindow(fw)

-- set its size and position
local sz = CEGUI.Size:new_local(0.5,0.5)
local pos = CEGUI.Point:new_local(0.2,0.1)
fw:setSize(sz)
fw:setPosition(pos)
-- disable user sizing
fw:setProperty("SizingEnabled","False")

-- make the close button work
fw:subscribeEvent("CloseClicked","fwCloseClicked")

-- the CloseClicked event handler
function fwCloseClicked(eventArgs)
local we = CEGUI.toWindowEventArgs(eventArgs)
CEGUI.WindowManager:getSingleton():destroyWindow(we.window) -- destroy the frame window
end
Creates a GUISheet and attaches it to the System. Then creates a FrameWindow, sets its size and position. Disables the sizing feature and subscribes a scripted event handler to destroy the window when the close button is clicked.

== Alternative casting ==
-- the CloseClicked event handler
function fwCloseClicked(eventArgs)
local we = tolua.cast(eventArgs,"CEGUI::WindowEventArgs")
CEGUI.WindowManager:getSingleton():destroyWindow(we.window) -- destroy the frame window
end
A modified close button click handler (from the previous snippet) showing an alternative way to cast EventArgs to WindowEventArgs

== Load a layout ==
local w = CEGUI.WindowManager:getSingleton():loadWindowLayout("../datafiles/layouts/test.layout")
CEGUI.System:getSingleton():getGUISheet():addChildWindow(w)
Loads a XML layout and adds the returned window to the active GUISheet.

== Menubar with popup ==
-- do the menubar
local bar = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/Menubar","the_menu_bar")
bar:setSize(CEGUI.Size:new_local(1,0.1))
CEGUI.System:getSingleton():getGUISheet():addChildWindow(bar)

-- add a menuitem to the bar
local item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/MenubarItem","the_menu_bar_item")
item:setText("Bar item")
bar:addChildWindow(item)

-- add a popupmenu to the bar's menuitem
local pop = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenu","the_popup_menu")
item:addChildWindow(pop)

-- add a few menuitems to the popup
item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenuItem","the_popup_menu_item_1")
item:setText("Popup item 1")
pop:addChildWindow(item)

item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenuItem","the_popup_menu_item_2")
item:setText("Popup item 2")
pop:addChildWindow(item)
Creates a simple menubar and adds a popupmenu with two items to it.

Writing CEGUI scripts

2005-07-04T14:30:55Z

Lindquist:

All code on this page is Lua script using the CEGUILua bindings available on CVS HEAD.
The code snippets might not be specifically useful, but they should show off some of the posibilities with CEGUI and Lua used together. And give an idea of how to write these scripts.

Off we go :)

--[[User:Lindquist|Lindquist]] 20:56, 9 Jun 2005 (BST)

== Change logging level ==
local logger = CEGUI.Logger:getSingleton() -- get the logger
local lvl = logger:getLoggingLevel() -- get logging level

if lvl < CEGUI.Insane then -- if logging level is less than insane
logger:setLoggingLevel(lvl+1) -- then increase it
end
Bumps up the logging level a notch unless we're already at Insane.

== Load a scheme ==
CEGUI.SchemeManager:getSingleton():loadScheme("../datafiles/schemes/TaharezLook.scheme")
Loads the TaharezLook scheme.

== Simple Interface ==
-- create the GUI sheet
local sheet = CEGUI.WindowManager:getSingleton():createWindow("DefaultGUISheet","root");
CEGUI.System:getSingleton():setGUISheet(sheet) -- and attach it to the system

-- create a FrameWindow
local fw = CEGUI.WindowManager:getSingleton():createWindow("TaharezLook/FrameWindow","framewnd");
-- add it to the sheet
sheet:addChildWindow(fw)

-- set its size and position
local sz = CEGUI.Size:new_local(0.5,0.5)
local pos = CEGUI.Point:new_local(0.2,0.1)
fw:setSize(sz)
fw:setPosition(pos)
-- disable user sizing
fw:setProperty("SizingEnabled","False")

-- make the close button work
fw:subscribeEvent("CloseClicked","fwCloseClicked")

-- the CloseClicked event handler
function fwCloseClicked(eventArgs)
local we = CEGUI.toWindowEventArgs(eventArgs)
CEGUI.WindowManager:getSingleton():destroyWindow(we.window) -- destroy the frame window
end
Creates a GUISheet and attaches it to the System. Then creates a FrameWindow, sets its size and position. Disables the sizing feature and subscribes a scripted event handler to destroy the window when the close button is clicked.

== Load a layout ==
local w = CEGUI.WindowManager:getSingleton():loadWindowLayout("../datafiles/layouts/test.layout")
CEGUI.System:getSingleton():getGUISheet():addChildWindow(w)
Loads a XML layout and adds the returned window to the active GUISheet.

== Menubar with popup ==
-- do the menubar
local bar = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/Menubar","the_menu_bar")
bar:setSize(CEGUI.Size:new_local(1,0.1))
CEGUI.System:getSingleton():getGUISheet():addChildWindow(bar)

-- add a menuitem to the bar
local item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/MenubarItem","the_menu_bar_item")
item:setText("Bar item")
bar:addChildWindow(item)

-- add a popupmenu to the bar's menuitem
local pop = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenu","the_popup_menu")
item:addChildWindow(pop)

-- add a few menuitems to the popup
item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenuItem","the_popup_menu_item_1")
item:setText("Popup item 1")
pop:addChildWindow(item)

item = CEGUI.WindowManager:getSingleton():createWindow("WindowsLook/PopupMenuItem","the_popup_menu_item_2")
item:setText("Popup item 2")
pop:addChildWindow(item)
Creates a simple menubar and adds a popupmenu with two items to it.

Writing CEGUI scripts

2005-06-09T19:56:21Z

Lindquist:

Writing CEGUI scripts

2005-06-02T02:17:08Z

Lindquist:

All code on this page is Lua script.

== Change logging level ==
local logger = CEGUI.Logger:getSingleton() -- get the logger
local lvl = logger:getLoggingLevel() -- get logging level

if lvl < CEGUI.Insane then -- if logging level is less than insane
logger:setLoggingLevel(lvl+1) -- then increase it
end
Bumps up the logging level a notch unless we're already at Insane.

== Load a scheme ==
CEGUI.SchemeManager:getSingleton():loadScheme("../datafiles/schemes/TaharezLook.scheme")
Loads the TaharezLook scheme.

== Simple Interface ==
-- create the GUI sheet
local sheet = CEGUI.WindowManager:getSingleton():createWindow("DefaultGUISheet","root");
CEGUI.System:getSingleton():setGUISheet(sheet) -- and attach it to the system

-- create a FrameWindow
local fw = CEGUI.WindowManager:getSingleton():createWindow("TaharezLook/FrameWindow","framewnd");
-- add it to the sheet
sheet:addChildWindow(fw)

-- set its size and position
local sz = CEGUI.Size:new_local(0.5,0.5)
local pos = CEGUI.Point:new_local(0.2,0.1)
fw:setSize(sz)
fw:setPosition(pos)
-- disable user sizing
fw:setProperty("SizingEnabled","False")

-- make the close button work
fw:subscribeEvent("CloseClicked","fwCloseClicked")

-- the CloseClicked event handler
function fwCloseClicked(eventArgs)
local we = CEGUI.toWindowEventArgs(eventArgs)
CEGUI.WindowManager:getSingleton():destroyWindow(we.window) -- destroy the frame window
end
Creates a GUISheet and attaches it to the System. Then creates a FrameWindow, sets its size and position. Disables the sizing feature and subscribes a scripted event handler to destroy the window when the close button is clicked.

== Load a layout ==
local w = CEGUI.WindowManager:getSingleton():loadLayout("../datafiles/layouts/test.layout")
CEGUI.System:getSingleton():getGUISheet():addChildWindow(w)
Loads a XML layout and adds the returned window to the active GUISheet.

Tutorials

2005-06-02T02:03:02Z

Lindquist:

=== CrazyEddie's 'Imbeciles' Guides ===
* [[The Imbeciles Guide to Getting CEGUI Rendering]] - How to initialise CEGUI to render properly.
* [[The Imbeciles Guide to Loading Data Files and Initialisation]] - How to load some data files and perform basic system initialisation.
* [[The Imbeciles Guide to Creating a CEGUI Window]] - How to create a simple window and get it on screen.
* [[The Imbeciles Guide to Injecting Inputs]] - How to inject inputs into CEGUI and get interactive.

=== Lua Scripting with CEGUI Guides ===
* [[Getting Started with Lua and CEGUI]] - How to initialise CEGUI with a Lua script module and configuration file.
* [[Handling Events from Lua]] - How to load Lua script files and bind CEGUI events to Lua functions.
* [[Writing CEGUI scripts]] - Code snippets

=== SDL Tutorials ===
* [[Using CEGUI with SDL and OpenGL]] - Guidelines on how to get SDL, OpenGL and CEGUI running together.

Writing CEGUI scripts

2005-06-02T02:02:47Z

Lindquist:

The Lua language is very versatile. It has mechanisms to override alot of its functionality, and [http://www.codenix.com/~tolua/ tolua++] makes heavy use of these mechanisms, in not just being a clever tool to generate Lua bindings for C++ code, it also introduces a set of new functions to allow basic object-oriented programming in Lua.

All code on this page is Lua script.

== Change logging level ==
local logger = CEGUI.Logger:getSingleton() -- get the logger
local lvl = logger:getLoggingLevel() -- get logging level

if lvl < CEGUI.Insane then -- if logging level is less than insane
logger:setLoggingLevel(lvl+1) -- then increase it
end
Bumps up the logging level a notch unless we're already at Insane.

== Load a scheme ==
CEGUI.SchemeManager:getSingleton():loadScheme("../datafiles/schemes/TaharezLook.scheme")
Loads the TaharezLook scheme.

== Simple Interface ==
-- create the GUI sheet
local sheet = CEGUI.WindowManager:getSingleton():createWindow("DefaultGUISheet","root");
CEGUI.System:getSingleton():setGUISheet(sheet) -- and attach it to the system

-- create a FrameWindow
local fw = CEGUI.WindowManager:getSingleton():createWindow("TaharezLook/FrameWindow","framewnd");
-- add it to the sheet
sheet:addChildWindow(fw)

-- set its size and position
local sz = CEGUI.Size:new_local(0.5,0.5)
local pos = CEGUI.Point:new_local(0.2,0.1)
fw:setSize(sz)
fw:setPosition(pos)
-- disable user sizing
fw:setProperty("SizingEnabled","False")

-- make the close button work
fw:subscribeEvent("CloseClicked","fwCloseClicked")

-- the CloseClicked event handler
function fwCloseClicked(eventArgs)
local we = CEGUI.toWindowEventArgs(eventArgs)
CEGUI.WindowManager:getSingleton():destroyWindow(we.window) -- destroy the frame window
end
Creates a GUISheet and attaches it to the System. Then creates a FrameWindow, sets its size and position. Disables the sizing feature and subscribes a scripted event handler to destroy the window when the close button is clicked.

== Load a layout ==
local w = CEGUI.WindowManager:getSingleton():loadLayout("../datafiles/layouts/test.layout")
CEGUI.System:getSingleton():getGUISheet():addChildWindow(w)
Loads a XML layout and adds the returned window to the active GUISheet.

Using CEGUI with SDL and OpenGL

2005-06-01T03:02:21Z

Lindquist:

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDLInit(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're using CEGUI for all your rendering needs this would be fine. Normally you would want the normal perspective projection setup though:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make it all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. [http://www.microsoft.com Microsoft] Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user press or release keyboard or mouse buttons, we need to tell CEGUI about it, for this we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://sdldoc.csn.ul.ie/sdlkeysym.php SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel events. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was released:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other ways to use timers with SDL, but I chose this approach as it is simple to use, and provides decent precision.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' function which in turn will set a new value to it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...
I'll leave it up to you to fix that if it's a problem.

=== Rendering ===
Now all thats left is rendering something. :)

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets OpenGL state itself. As long as the viewport is setup, it will render the GUI.

=== Error Handling ===
The neat C++ architecture of CEGUI suggests that C++ exceptions are used for error handling. This is completely true.
Whenever an error occurs, a sub-class of ''CEGUI::Exception'' is thrown.

There are many scenarios where an exception can be thrown. And whether or not these should be considered fatal depends on the application. To make sure you catch the CEGUI exceptions a regular ''try'' block is used. Like so:

try
{
// do some cegui code
}
catch (CEGUI::Exception& e)
{
fprintf(stderr,"CEGUI Exception occured: %s", e.getMessage().c_str());
// you could quit here
}

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Tutorials

2005-05-23T23:36:03Z

Lindquist:

=== CrazyEddie's 'Imbeciles' Guides ===
* [[The Imbeciles Guide to Getting CEGUI Rendering]] - How to initialise CEGUI to render properly.
* [[The Imbeciles Guide to Loading Data Files and Initialisation]] - How to load some data files and perform basic system initialisation.
* [[The Imbeciles Guide to Creating a CEGUI Window]] - How to create a simple window and get it on screen.
* [[The Imbeciles Guide to Injecting Inputs]] - How to inject inputs into CEGUI and get interactive.

=== Lindquist's Lua Scripting with CEGUI Guides ===
* [[Getting Started with Lua and CEGUI]] - How to initialise CEGUI with a Lua script module and configuration file.
* [[Handling Events from Lua]] - How to load Lua script files and bind CEGUI events to Lua functions.

=== SDL Tutorials ===
* [[Using CEGUI with SDL and OpenGL]] - Guidelines on how to get SDL, OpenGL and CEGUI running together.

Using CEGUI with SDL and OpenGL

2005-05-22T22:20:11Z

Lindquist:

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDLInit(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuiration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're only using CEGUI to display graphics this would be fine. Normally you would want a default 3D perspective setup:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make is all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user presses or release keyboard or mouse buttons, we need to tell CEGUI about it so we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event is takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://sdldoc.csn.ul.ie/sdlkeysym.php SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel event. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was pressed:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other to use timers with SDL, but I chose this approach as it is simple to use.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' which in turn will set a new value in it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Long sentence but it not that hard. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...

=== Rendering ===
Now all thats left is rendering something. :)

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets OpenGL state itself. As long as the viewport is setup, it will render the GUI.

=== Error Handling ===
The neat C++ architecture of CEGUI suggests that C++ exceptions are used for error handling. This is completely true.
Whenever an error occurs, a sub-class of ''CEGUI::Exception'' is thrown.

There are many scenarios where an exception can be thrown though, but a simple approach would be to simply treat all CEGUI exceptions as ''fatal errors''. That is - clean up and exit the application.

try
{
// do some cegui code
}
catch (CEGUI::Exception& e)
{
fprintf(stderr,"CEGUI Exception occured: %s", e.getMessage().c_str());
// you could quit here
}

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-20T16:52:06Z

Lindquist:

The Lua scripting module for CEGUI is based on [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.6pre2-1].
As these libraries were difficult (or impossible) to find in working precompiled versions, I decided to include them with the scripting module (That is the source is included, and there are makefiles available).
There is no link to the tolua++ version used on their website, but it's available [http://www.codenix.com/~tolua/tolua++_1.0.6pre2-1.tar.gz here]

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. and Lua, so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan = CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

--[[User:Lindquist|Lindquist]] 19:25, 5 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-10T10:58:29Z

Lindquist:

The Lua scripting module for CEGUI is based on [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.6pre2-1].
As these libraries were difficult (or impossible) to find in working precompiled versions, I decided to include them with the scripting module.
There is no link to the tolua++ version used on their website, but it's available [http://www.codenix.com/~tolua/tolua++_1.0.6pre2-1.tar.gz here]

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. and Lua, so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan = CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

--[[User:Lindquist|Lindquist]] 19:25, 5 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-08T22:47:37Z

Lindquist:

The Lua scripting module for CEGUI is based on [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.6pre2-1].
As these libraries were difficult (or impossible) to find in working precompiled versions, I decided to include them with the scripting module.

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. and Lua, so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan = CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

--[[User:Lindquist|Lindquist]] 19:25, 5 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-08T22:46:57Z

Lindquist:

The Lua scripting module for CEGUI is based on [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.6pre2-1].
As these libraries were diffucult to find in working precompiled versions, I decided to include them with the scripting module.

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. and Lua, so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan = CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

--[[User:Lindquist|Lindquist]] 19:25, 5 May 2005 (BST)

Using CEGUI with SDL and OpenGL

2005-05-08T19:18:22Z

Lindquist: /* Rendering */

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDLInit(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuiration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're only using CEGUI to display graphics this would be fine. Normally you would want a default 3D perspective setup:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make is all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user presses or release keyboard or mouse buttons, we need to tell CEGUI about it so we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event is takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://sdldoc.csn.ul.ie/sdlkeysym.php SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel event. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was pressed:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other to use timers with SDL, but I chose this approach as it is simple to use.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' which in turn will set a new value in it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Long sentence but it not that hard. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...

=== Rendering ===
Now all thats left is rendering something. :)

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets OpenGL state itself. As long as the viewport is setup, it will render the GUI.

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Using CEGUI with SDL and OpenGL

2005-05-08T19:18:01Z

Lindquist: /* Time Pulses */

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDLInit(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuiration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're only using CEGUI to display graphics this would be fine. Normally you would want a default 3D perspective setup:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make is all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user presses or release keyboard or mouse buttons, we need to tell CEGUI about it so we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event is takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://sdldoc.csn.ul.ie/sdlkeysym.php SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel event. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was pressed:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other to use timers with SDL, but I chose this approach as it is simple to use.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' which in turn will set a new value in it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Long sentence but it not that hard. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...

=== Rendering ===
Now all thats left is rendering something. :)

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets state itself. As long as the viewport is setup, it will render the GUI.

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Using CEGUI with SDL and OpenGL

2005-05-08T19:17:41Z

Lindquist:

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDLInit(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuiration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're only using CEGUI to display graphics this would be fine. Normally you would want a default 3D perspective setup:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make is all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user presses or release keyboard or mouse buttons, we need to tell CEGUI about it so we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event is takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://sdldoc.csn.ul.ie/sdlkeysym.php SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel event. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was pressed:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other to use timers with SDL, but I chose this approach as it is simple to use.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' which in turn will set a new value in it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Long sentence but it not that hard. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...

=== Rendering ===
Now all thats left is rendering something. :)

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets state itself. As long as the viewport is setup, it will render the GUI.

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Using CEGUI with SDL and OpenGL

2005-05-08T19:16:57Z

Lindquist: /* Time Pulses */

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDLInit(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuiration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're only using CEGUI to display graphics this would be fine. Normally you would want a default 3D perspective setup:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make is all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user presses or release keyboard or mouse buttons, we need to tell CEGUI about it so we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event is takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://sdldoc.csn.ul.ie/sdlkeysym.php SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel event. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was pressed:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other to use timers with SDL, but I chose this approach as it is simple to use.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' which in turn will set a new value in it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Long sentence but it not that hard. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line gets the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...

=== Rendering ===
Now all thats left is rendering something. :)

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets state itself. As long as the viewport is setup, it will render the GUI.

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Using CEGUI with SDL and OpenGL

2005-05-08T19:15:26Z

Lindquist: /* Rendering */

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDLInit(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuiration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're only using CEGUI to display graphics this would be fine. Normally you would want a default 3D perspective setup:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make is all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user presses or release keyboard or mouse buttons, we need to tell CEGUI about it so we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event is takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://sdldoc.csn.ul.ie/sdlkeysym.php SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel event. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was pressed:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other to use timers with SDL, but I chose this approach as it is simple to use.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' which in turn will set a new value in it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Long sentence but it not that hard. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line get the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...

=== Rendering ===
Now all thats left is rendering something. :)

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );

// render the GUI :)
CEGUI::System::getSingleton().renderGUI();

// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets state itself. As long as the viewport is setup, it will render the GUI.

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Tutorials

2005-05-08T15:23:25Z

Lindquist:

=== CrazyEddie's 'Imbeciles' Guides ===
* [[The Imbeciles Guide to Getting CEGUI Rendering]] - How to initialise CEGUI to render properly.
* [[The Imbeciles Guide to Loading Data Files and Initialisation]] - How to load some data files and perform basic system initialisation.
* [[The Imbeciles Guide to Creating a CEGUI Window]] - How to create a simple window and get it on screen.
* [[The Imbeciles Guide to Injecting Inputs]] - How to inject inputs into CEGUI and get interactive.

=== Lindquist's Lua Scripting with CEGUI Guides ===
* [[Getting Started with Lua and CEGUI]] - How to initialise CEGUI with a Lua script module and configuration file.
* [[Handling Events from Lua]] - How to load Lua script files and bind CEGUI events to Lua functions.

=== SDL Tutorials ===
* [[Using CEGUI with SDL and OpenGL]] - How to get SDL, OpenGL and CEGUI running together.

Tutorials

2005-05-08T15:23:10Z

Lindquist:

=== CrazyEddie's 'Imbeciles' Guides ===
* [[The Imbeciles Guide to Getting CEGUI Rendering]] - How to initialise CEGUI to render properly.
* [[The Imbeciles Guide to Loading Data Files and Initialisation]] - How to load some data files and perform basic system initialisation.
* [[The Imbeciles Guide to Creating a CEGUI Window]] - How to create a simple window and get it on screen.
* [[The Imbeciles Guide to Injecting Inputs]] - How to inject inputs into CEGUI and get interactive.

=== Lindquist's Lua Scripting with CEGUI Guides ===
* [[Getting Started with Lua and CEGUI]] - How to initialise CEGUI with a Lua script module and configuration file.
* [[Handling Events from Lua]] - How to load Lua script files and bind CEGUI events to Lua functions.

=== SDL Tutorials ===
* [[Using CEGUI with SDL and OpenGL]] - How to get SDL, OpenGL and CEGUI running together.

Using CEGUI with SDL and OpenGL

2005-05-08T15:21:13Z

Lindquist:

[http://www.libsdl.org SDL (Simple DirectMedia Layer)] is an excellent library for writing portable games and other multimedia applications, but as it is a low-level library, it has no native support for GUI interfaces.

When using [http://www.opengl.org OpenGL] for rendering, using CEGUI with SDL is not hard.

I'll assume that you've read the imbiciles tutorials, and have used SDL with OpenGL.
And know C / C++ ...

=== Initialisation ===
Before we can do anything, we need to initialise our libraries.
First SDL:

if (SDLInit(SDL_INIT_VIDEO|SDL_INIT_TIMER)<0)
{
fprintf(stderr, "Unable to initialise SDL: %s", SDL_GetError());
exit(0);
}

Here we initialise SDL with video and timer support. We need this for CEGUI.
O.K. now SDL is ready to go. So let's fire up OpenGL:

if (SDL_SetVideoMode(800,600,0,SDL_OPENGL)==NULL)
{
fprintf(stderr, "Unable to set OpenGL videomode: %s", SDL_GetError());
SDL_Quit();
exit(0);
}

Now OpenGL is ready. But we still need to set a decent configuiration:

glEnable(GL_CULL_FACE);
glClearColor(0.0f,0.0f,0.0f,1.0f);
glViewport(0,0, 800,600);

The OpenGL renderer that comes with CEGUI sets the matrices itself, so if you're only using CEGUI to display graphics this would be fine. Normally you would want a default 3D perspective setup:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();

SDL and OpenGL are now both ready for action. So it's time to initialise CEGUI.
First we need the renderer.

#include "renderers/OpenGLGUIRenderer/openglrenderer.h"

It must be created before starting CEGUI.

CEGUI::OpenGLRenderer* renderer = new CEGUI::OpenGLRenderer(0,800,600);

Then the CEGUI::System must be initialised:

new CEGUI::System(renderer);

Remember that you have to load a widget set, set the mouse cursor and a default font before CEGUI is completely ready. This is described in the other tutorials.

By default the SDL cursor is displayed, so we'll remove that:

SDL_ShowCursor(SDL_DISABLE);

As keypress characters needs to be injected into CEGUI, we activate unicode translation for SDL key events:

SDL_EnableUNICODE(1);

This makes it alot easier as we don't have to worry about modifier keys and keyboard layouts ourselves. More about this later on...

Key repeat is a nice feature for the text input widgets in CEGUI, so we use SDL to generate them:

SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);

Everything is ready now, and we can start the main loop :)

=== The Main Loop ===
To make is all happen, we use a simple main loop that just keeps pushing on those frames:

void main_loop()
{
bool must_quit = false;

// get "run-time" in seconds
double last_time_pulse = 0.001*static_cast<double>(SDL_GetTicks());

while (!must_quit)
{
inject_input(must_quit);
inject_time_pulse(last_time_pulse);
render_gui();
}
}

This function will run the main loop until the ''bool'' value ''must_quit'' becomes ''true''. In this tutorial this will happen when the user clicks the close button provided by the window manager (fx. Windows).

The ''double'' value ''last_time_pulse'' holds the time of the latest time pulse injection. More about this later.

Each function in the ''while'' loop will be described below.

There are endless ways of making your main loop. I took a simple approach to ease writing this tutorial.

=== Injecting Input ===
When the user presses or release keyboard or mouse buttons, we need to tell CEGUI about it so we use the injection functions of ''CEGUI::System''.

Here is what our inject_input function looks like:

void inject_input(bool& must_quit)
{
SDL_Event e;

// go through all available events
while (SDL_PollEvent(&e))
{
// we use a switch to determine the event type
switch (e.type)
{
// mouse motion handler
case SDL_MOUSEMOTION:
// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);
break;

// mouse down handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button down event
handle_mouse_down(e.button.button);
break;

// mouse up handler
case SDL_MOUSEBUTTONDOWN:
// let a special function handle the mouse button up event
handle_mouse_up(e.button.button);
break;

// key down
case SDL_KEYDOWN:
// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}
break;

// key up
case SDL_KEYUP:
// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);
break;

// WM quit event occured
case SDL_QUIT:
must_quit = true;
break;

}

}

}

First I'll explain the events that get handled directly in the ''inject_input'' function.

'''Mouse Motion''':

// we inject the mouse position directly.
CEGUI::System::getSingleton().injectMousePosition(
static_cast<float>(e.motion.x),
static_cast<float>(e.motion.y)
);

There is nothing special here. Like stated in the comment the mouse position is just injected directly.

There are two ways of injecting mouse motion. One where you inject how much the cursor moved, and one where you inject the mouse cursor position. The last one is failsafe.
Then first one only works correctly in fullscreen mode, or with input grabbed. The reason for this is that in regular windowed mode, the mouse can be moved outside the application window, and during this time no mouse motion event are generated. So if we enter the window at another position, the real mousecursor and CEGUI's mouse cursor will be offset, which will break mouse usage.

'''Key Down'''<br />
This event is takes a little more work. CEGUI requires that key characters (the printable character the key represents) are injected alongside key codes.

// to tell CEGUI that a key was pressed, we inject the scancode.
CEGUI::System::getSingleton().injectKeyDown(e.key.keysym.scancode);

Luckily the key code is just the SDL scancode, so we inject that directly.

// as for the character it's a litte more complicated. we'll use for translated unicode value.
// this is described in more detail below.
if ((e.key.keysym.unicode & 0xFF80) == 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode & 0x7F);
}

Instead of formatting the keypress ourselves, we let SDL do it for us. For more information, take a look at the SDL documentation for this feature. [http://sdldoc.csn.ul.ie/sdlkeysym.php SDL_keysym].

'''Key Up'''<br />
This one is simple. Only the keycode need to injected. So we just use the scancode directly:

// like before we inject the scancode directly.
CEGUI::System::getSingleton().injectKeyUp(e.key.keysym.scancode);

'''Mouse Button Down and Mouse Wheel'''<br />
CEGUI and SDL are a little different when it comes to mouse button and mouse wheel event. So a little conversion is necessary. Here's the ''handle_mouse_down'' function that gets called when a mouse button down event occurs in SDL. It takes one parameter, a ''Uint8'' describing the mouse button that was pressed.

void handle_mouse_down(Uint8 button)
{
switch ( button )
{
// handle real mouse buttons
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonDown(CEGUI::RightButton);
break;

// handle the mouse wheel
case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

I chose a very "manual" conversion, but it works fine. Everything should be pretty self-explainatory.
As you can see mouse wheel events are emitted as mouse button down events in SDL.

'''Mouse Button Up'''<br />
The mouse button up event is handled very much like the mouse button down event, except there are no mousewheel release events.
Like ''handle_mouse_down'' it takes one parameter, a ''Uint8'' describing the mouse button that was pressed:

void handle_mouse_up(Uint8 button)
{
switch ( button )
{
case SDL_BUTTON_LEFT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::LeftButton);
break;
case SDL_BUTTON_MIDDLE:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case SDL_BUTTON_RIGHT:
CEGUI::System::getSingleton().injectMouseButtonUp(CEGUI::RightButton);
break;
}
}

=== Time Pulses ===
SDL has a built-in millisecond counter which we will use for this example. There are other to use timers with SDL, but I chose this approach as it is simple to use.

Remember in the main loop where we stored the current "run-time" in seconds ? This value will be passed as a reference to ''inject_time_pulse'' which in turn will set a new value in it.

CEGUI's interface for injecting time pulses requires that you pass the time in seconds that has passed since the last time pulse injection. Long sentence but it not that hard. Let's take a look at the function:

void inject_time_pulse(double& last_time_pulse)
{
// get current "run-time" in seconds
double t = 0.001*SDL_GetTicks();

// inject the time that passed since the last call
CEGUI::System::getSingleton().injectTimePulse( float(t-last_time_pulse) );

// store the new time as the last time
last_time_pulse = t;
}

* The first line get the actual "run-time" when called.
* The second line injects the time pulse as the difference between the current time and the last time.
* The third line stores the current time as the last time a time pulse was injected.

This will work for about 47 days... After that the counter wraps to zero and it breaks...

=== Rendering ===
Now all thats left is rendering something. :)

void render_gui()
{
// clear the colour buffer
glClear( GL_COLOR_BUFFER_BIT );
// render the GUI :)
CEGUI::System::getSingleton().renderGUI();
// Update the screen
SDL_GL_SwapBuffers();
}

The line:

CEGUI::System::getSingleton().renderGUI();

does all the CEGUI magic and sets state itself. As long as the viewport is setup, it will render the GUI.

That's it. Now you know how to use SDL, OpenGL and CEGUI together. Have fun.

--[[User:Lindquist|Lindquist]] 16:21, 8 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-07T23:51:30Z

Lindquist:

The Lua scripting module for CEGUI is based on [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.5].
As these libraries were diffucult to find in working precompiled versions, I decided to include them with the scripting module.

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. and Lua, so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan = CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

--[[User:Lindquist|Lindquist]] 19:25, 5 May 2005 (BST)

Handling Events from Lua

2005-05-07T19:40:56Z

Lindquist:

Moving the handling of GUI events outside of your project code, and into Lua scripts can add a great deal of flexibilty to your interface. Simple GUI related stuff can be easily prototyped, and modified during testing.

Event handlers in Lua are just regular Lua functions that take one parameter. An CEGUI::EventArgs struct.
The functions you register as event handlers must already be registered with the system, so unless you load them all from your init-script, you will need to load some script files before doing any Lua handled events.

Here we go...

== Loading the script files ==
There are two ways of loading your script files. You can use the C++ interface or you can do it from Lua in your init-script.
The two approaches are very alike, as the Lua version uses a direct binding to the same C++ function.

CEGUI::System::executeScriptFile(const CEGUI::String& filename, const CEGUI::String& resourceGroup = "");

Obviously this function takes two parameters, a filename and the resource group.
I think most people ignore the last parameter pretty much.

Calling this function with the Lua scripting module correctly attached to CEGUI, will execute the specified Lua script file.
This means that functions etc. declared within these files will be accessible to your program, except of course if they are declared ''local''.

So. From C++ you would do something like this:

CEGUI::System::getSingleton().executeScriptFile("../datafiles/scripts/guiscript.lua");

If anything goes wrong an exception is thrown.

From Lua you could use this code:

CEGUI.System:getSingleton():executeScriptFile("../datafiles/scripts/guiscript.lua")

any global code in these script files will also be executed so be sure to manage each execution if necessary (with a counter fx).

== Registering Events to Lua Functions ==
Now that we have our scripts loaded and all, we are ready to bind some events to our scripted handlers.

The function to use when binding scripted events is a little different from the regular C++ one.

Event::Connection subscribeScriptedEvent(const String& name, const String& subscriber_name);

''name'' is the name of the event you want to subscribe. As usual. ''subscriber_name'' is a string holding the name of the Lua function to bind to the event.

After this call the Lua function specified will be registered as the event handler. And works exactly like the C++ version (except being Lua of course)

Here's a little snippet to bind a PushButton Clicked event to a Lua function:

CEGUI::PushButton* pb = (CEGUI::PushButton*)CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/Button","lua_powered_button");
pb->setSize(CEGUI::Size(0.1f,0.1f));
pb->setPosition(CEGUI::Point(0.1f,0.1f));
pb->subscribeScriptedEvent("Clicked","luabtn_clicked");
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(pb);

This code would create a simple TaharezLook button, subscribe the Lua function ''luabtn_clicked'' to its ''Clicked'' event, and finally add it to the current GUI sheet.

Now let's take a look at that Lua event handler:

function luabtn_clicked(e)
{
local we = CEGUI.toWindowEventArgs(e)
we.window:setText("handled from Lua");
}

Here we make sure the button text is ''handled from Lua'' when the button is clicked.
We use a utility function:

CEGUI.toWindowEventArgs(e)

it's obvious what it does, and converters for the other EventArgs class are also available.

== Registering Lua Event Handlers from XML Layouts ==
It's very easy to bind scripted event handlers to the windows in your XML layouts.

Take a look a this example:

<?xml version="1.0"?>
<GUILayout>
<Window Type="TaharezLook/Button" Name="lua_powered_button">
<Property Name="Width" Value="0.1" />
<Property Name="Height" Value="0.1" />
<Property Name="XPosition" Value="0.1" />
<Property Name="YPosition" Value="0.1" />
<Event Name="Clicked" Function="luabtn_clicked" />
</Window>
</GUILayout>

This simple layout create the same button as described above and even bind the scripted event handler to it.

now you know how to do stuff with your GUI without writing C++ code.

--[[User:Lindquist|Lindquist]] 17:10, 6 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-06T18:41:56Z

Lindquist: /* Init / Exit Script */

The Lua scripting module for CEGUI is based on pure [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.4].
As these libraries were diffucult to find in working precompiled versions, I decided to include them with the scripting module.

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. and Lua, so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan = CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

--[[User:Lindquist|Lindquist]] 19:25, 5 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-06T18:41:10Z

Lindquist:

The Lua scripting module for CEGUI is based on pure [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.4].
As these libraries were diffucult to find in working precompiled versions, I decided to include them with the scripting module.

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. and Lua, so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan= CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

--[[User:Lindquist|Lindquist]] 19:25, 5 May 2005 (BST)

Tutorials

2005-05-06T16:10:36Z

Lindquist: /* Lindquist's Lua Scripting with CEGUI Guides */

=== CrazyEddie's 'Imbeciles' Guides ===
* [[The Imbeciles Guide to Getting CEGUI Rendering]] - How to initialise CEGUI to render properly.
* [[The Imbeciles Guide to Loading Data Files and Initialisation]] - How to load some data files and perform basic system initialisation.
* [[The Imbeciles Guide to Creating a CEGUI Window]] - How to create a simple window and get it on screen.
* [[The Imbeciles Guide to Injecting Inputs]] - How to inject inputs into CEGUI and get interactive.

=== Lindquist's Lua Scripting with CEGUI Guides ===
* [[Getting Started with Lua and CEGUI]] - How to initialise CEGUI with a Lua script module and configuration file.
* [[Handling Events from Lua]] - How to load Lua script files and bind CEGUI events to Lua functions.

Handling Events from Lua

2005-05-06T16:10:30Z

Lindquist:

Moving the handling of GUI events outside of your project code, and into Lua scripts can add a great deal of flexibilty to your interface. Simple GUI related stuff can be easily prototyped, and modified during testing.

Event handlers in Lua are just regular Lua functions that take one parameter. An CEGUI::EventArgs struct.
The functions you register as event handlers must already be registered with the system, so unless you load them all from your init-script, you will need to load some script files before doing any Lua handled events.

Here we go...

== Loading the script files ==
There are two ways of loading your script files. You can use the C++ interface or you can do it from Lua in your init-script.
The two approaches are very alike, as the Lua version uses a direct binding to the same C++ function.

CEGUI::System::executeScriptFile(const CEGUI::String& filename, const CEGUI::String& resourceGroup = "");

Obviously this function takes two parameters, a filename and the resource group.
I think most people ignore the last parameter pretty much.

Calling this function with the Lua scripting module correctly attached to CEGUI, will execute the specified Lua script file.
This means that functions etc. declared within these files will be accessible to your program, except of course if they are declared ''local''.

So. From C++ you would do something like this:

CEGUI::System::getSingleton().executeScriptFile("../datafiles/scripts/guiscript.lua");

If anything goes wrong an exception is thrown.

From Lua you could use this code:

CEGUI.System:getSingleton():executeScriptFile("../datafiles/scripts/guiscript.lua")

any global code in these script files will also be executed so be sure to manage each execution if necessary (with a counter fx).

== Registering Events to Lua Functions ==
Now that we have our scripts loaded and all, we are ready to bind some events to our scripted handlers.

The function to use when binding scripted events is a little different from the regular C++ one.

Event::Connection subscribeScriptedEvent(const String& name, const String& subscriber_name);

''name'' is the name of the event you want to subscribe. As usual. ''subscriber_name'' is a string holding the name of the Lua function to bind to the event.

After this call the Lua function specified will be registered as the event handler. And works exactly like the C++ version (except being Lua of course)

Here's a little snippet to bind a PushButton Clicked event to a Lua function:

CEGUI::PushButton* pb = (CEGUI::PushButton*)CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/Button","lua_powered_button");
pb->setSize(CEGUI::Size(0.1f,0.1f));
pb->setPosition(CEGUI::Point(0.1f,0.1f));
pb->subscribeScriptedEvent("Clicked","luabtn_clicked");
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(pb);

This code would create a simple TaharezLook button, subscribe the Lua function ''luabtn_clicked'' to its ''Clicked'' event, and finally add it to the current GUI sheet.

Now let's take a look at that Lua event handler:

function luabtn_clicked(e)
{
local we = CEGUI.toWindowEventArgs(e)
we.window:setText("handled from Lua");
}

Here we make sure the button text is ''handled from Lua'' when the button is clicked.
We use a utility function:

CEGUI.toWindowEventArgs(e)

it's obvious what it does, and converters for the other EventArgs class are also available.

now you know how to do stuff with your GUI without writing C++ code.

--[[User:Lindquist|Lindquist]] 17:10, 6 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-05T18:25:29Z

Lindquist:

The Lua scripting module for CEGUI is based on pure [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.4].
As these libraries were diffucult to find in working precompiled versions, I decided to include them with the scripting module.

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan= CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

--[[User:Lindquist|Lindquist]] 19:25, 5 May 2005 (BST)

Getting Started with Lua and CEGUI

2005-05-05T18:23:22Z

Lindquist:

The Lua scripting module for CEGUI is based on pure [http://www.lua.org Lua 5.0.2] and [http://www.codenix.com/~tolua/ tolua++ 1.0.4].
As these libraries were diffucult to find in working precompiled versions, I decided to include them with the scripting module.

When using CEGUI with a scripting module a lot of the interface programming can be replaced by scripts, these script can be modified and used without recompling your program, thus leave more time for tweaking your UI instead of waiting for your compiler to finish.

The current Lua script module is still fairly early in development.
It supports most of the core system, and the base window class, more specific widgets can currently only be configured using the properties system.

At this time the Lua script module is only in CVS.

Ok. Let's get started. I assume that you are familiar with the CEGUI basics. Initialisation, creating windows etc. so I'll pick up from about there.

== Initialisation ==
The Lua scripting module exports all the manager classes and such it is possible to do the basic CEGUI initialization from Lua.

the basic CEGUI init sequence is like this:

#include "LuaScriptModule.h"

CEGUI::''YourRendererOfChoice''* renderer = new ''YourRendererOfChoice'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule();
new CEGUI::System( renderer, script_module );

now the CEGUI::System is created and the scripting module is attached properly.
In this case the constructor of the LuaScriptModule created a Lua state for us. You can also pass a lua_State* as the first parameter to the LuaScriptModule constructor to use your own Lua state instead:

...
lua_State* s = ''your_lua_state'';
CEGUI::LuaScriptModule* script_module = new CEGUI::LuaScriptModule(s);
...

You would probably want to do this if you are using custom functions in the init-script.

== Init / Exit Script ==
CEGUI supports a configuration file. The filename for this is an optional parameter to the CEGUI::System constructor. It defaults to cegui.config

This configuration file gives you the posibility to execute a script file during system creation and destruction.
A configuration file could look like this:

<?xml version="1.0" ?>
<CEGUIConfig InitScript="../datafiles/scripts/init_script.lua" TerminateScript="../datafiles/scripts/exit_script.lua" />

init_script.lua is a text file containing the Lua script code to be executed on init.
Here's an example:

-- get CEGUI singletons
local logger = CEGUI.Logger:getSingleton()
logger:logEvent( ">>> Init script says hello" )
--logger:setLoggingLevel( CEGUI.Informative )

-- get a local reference to the singletons we use (not required)
local system = CEGUI.System:getSingleton()
local fontman = CEGUI.FontManager:getSingleton()
local schememan= CEGUI.SchemeManager:getSingleton()

-- load schemes
schememan:loadScheme( "../datafiles/schemes/TaharezLook.scheme" )
schememan:loadScheme( "../datafiles/schemes/WindowsLook.scheme" )

-- load and set default font
local font = fontman:createFont( "../datafiles/fonts/Commonwealth-10.font" )
system:setDefaultFont( font )

-- set default mouse cursor
system:setDefaultMouseCursor( "TaharezLook","MouseArrow" )

logger:logEvent( "<<< Init script says goodbye" )

you don't have to have both init and exit scripts, but if you allocate "global" memory from the initscript you should free it in the exit script.

Now you know how to initialise CEGUI with the Lua scripting module.
More tutorials will follow soon with more advanced topics.

Tutorials

2005-05-05T18:23:16Z

Lindquist: /* Lindquist's Lua Scripting and CEGUI Guides */

=== CrazyEddie's 'Imbeciles' Guides ===
* [[The Imbeciles Guide to Getting CEGUI Rendering]] - How to initialise CEGUI to render properly.
* [[The Imbeciles Guide to Loading Data Files and Initialisation]] - How to load some data files and perform basic system initialisation.
* [[The Imbeciles Guide to Creating a CEGUI Window]] - How to create a simple window and get it on screen.
* [[The Imbeciles Guide to Injecting Inputs]] - How to inject inputs into CEGUI and get interactive.

=== Lindquist's Lua Scripting with CEGUI Guides ===
* [[Getting Started with Lua and CEGUI]] - How to initialise CEGUI with a Lua script module and configuration file.