{{VersionBadge|0.7}}
{{Series|CEGUI In Practice|4}}

== CEGUI In-Practice 4 ==

Hello hello, you're making good headway through these tutorials! Alright, last lesson we got a glimpse of how to send input to CEGUI. This is useful, because today we're going to make a button. And not just any button, but a button which makes something happen! I know, exciting.

==== Some groundwork ====

First we need to look into how CEGUI handles event control.

CEGUI is based around the Event/Subscriber method. Meaning, something (A button, an edit box, a list box) fires off an event (MouseClick,Text Accepted, or Selection), and something else (The Application Class, another CEGUI Widget, anything!) is informed about it. It does this via the

<source lang="cpp">CEGUI::Window::subscribeEvent(const String& name,Event::Subscriber subscriber) </source>

The first argument is the Event that you wish to keep track of. Events are static const strings. You will find these in the respective header files for CEGUI Widget types. (Example CEGUIPushButton contains CEGUI::PushButton::EventClicked)

The second argument if the subscriber which will be called whenever this event occurs.

Lets suppose give an example of how to register our character to jump whenever a button is pressed. First lets create our Button whcih will make our character jump. Although this is bad coding style, we will create the button in global scope for ease of this example.
<source lang="cpp">
CEGUI::Window *gJumpBtnWindow = NULL;

void CreateJumpButton()
{
gJumpBtnWindow = CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/Button","JumpPushButton"); // Create Window
gJumpBtnWindow->setPosition(CEGUI::UVector2(CEGUI::UDim(0.75,0),CEGUI::UDim(0.50,0));
gJumpBtnWindow->setSize(CEGUI::UVector2(CEGUI::UDim(0,50),CEGUI::UDim(0,50));
gJumpBtnWindow->setText("Jump!");
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(gJumpBtnWindow);
}
</source>

The above code Creates the button of type "TaharezLook/Button", as exists in the .scheme file. Then it gives it the name of "JumpPushButton". And sets its size and position, followed by attaching it to the root GUI Window. this is review from two tutorials ago. However, the setText one is new. Its pretty Self explanetory I would assume, but it Sets the text for windows. PushButtons, EditBoxes, FrameWindows, etc all have a spot to display text and this function will do it.

now that we have created our button, lets create a class that will recieve this JumpPushButton's events. Please rememeber this is an example. In your application It likely won't be this simple!

<source lang="cpp">
class OurPlayer
{
public:
OurPlayer()
{
RegisterForEvents(); // Call our Register function
};
bool Jump(const CEGUI::EventArgs& /*e*/){}; // Jump for joy
private:
RegisterForEvents()
{
gJumpBtnWindow->subscribeEvent(CEGUI::PushButton::EventClicked,CEGUI::Event::Subscriber(&OurPlayer::Jump,this));
};
}
</source>

Alright, thats a neat little class right? I don't know how you're going to make your character jump, so you get to fill in that information, i'm just gonna show you how to interact with the GUI!

Alright, the really interesting line here is the RegisterForEvents() function. You may or may not have dealt with EventSubscribers before in other applications, so I will give a very brief intro to them.

Basically, they work by creating a structure which is supplied to CEGUI stating what function to call, and where to get an instance of a member that has that function. the first argument, &OurPlayer::Jump states that we want to use the function Jump which is a member of OurPlayer. The problem is it doesn't know WHICH OurPlayer we want to use? What if we are playing split screen and we have two OurPlayer classes? One for the Left player and one for the Right player? Now we need to specify which player. There is the second argument. in C++ '''this''' returns a pointer to the class execution is currently in. So since we're registering this event within a class, we tell it to use this, which will reference the class that called RegisterForEvents();

If we had created as follows:
<source lang="cpp">
OurPlayer *leftPlayer;
OurPlayer *rightPlayer;
</source>

then we would call the function like this

<source lang="cpp">
gJumpBtnWindow->subscribeEvent(CEGUI::PushButton::EventClicked,CEGUI::Event::Subscriber(&OurPlayer::Jump,leftPlayer));
</source>

So as you can see this allows for alot of possibilities. There are also events for:

* MouseClicked,
* MouseEnters,
* MouseLeaves,
* EventActivated,
* EventTextChanged,
* EventAlphaChanged,
* EventSized

Just to name a few. There is a Huge listing of events which all windows inherit in CEGUIWindow.h

==== Conclusion ====

hopefully this tutorial showed you how to implement events in cegui. They really are the mechanism which all things happen. Once you master how to use events, the rest of the GUI becomes so easy to use, as most user interactions are event driven. While you may not use them all, there are even events for Rotating windows and dropping windows on other windows! Just think of the possibilities. Until next time Happy Clicking!

[[Category:Tutorials]]

CEGUI In Practice - A Game Console

2011-03-06T01:36:42Z

Capek: because references rule

DialogPositions

2011-03-05T12:55:21Z

Capek: Bot: Fixing double redirect to Dialog Configurations

#REDIRECT [[Dialog Configurations]]

CEGUI In Practice - A Game Console

2011-03-04T20:09:20Z

Capek: Robot: Cosmetic changes

Dynamic Fonts

2011-03-04T17:39:39Z

Capek: Robot: Cosmetic changes

{{VersionBadge|0.5}} {{VersionBadge|0.6}}

=== Introduction ===
The datafiles\fonts folder contains static font definitions such as Commonwealth-10.font. The XML contents of that file specify one particular font, mainly a logical name (Commonwealth-10), a filename (Commonv2c.ttf), and a size (10). To load this static font definition you'd write the following line of code:
<source lang="cpp">
CEGUI::FontManager::getSingleton().createFont("Commonwealth-10.font");
</source>

This works well, but sometimes you need to display a same font in various sizes. One approach is to create multiple .font files, one per font size. But there is a better approach, a way to dynamically create fonts.

Please post comments or questions on the message board thread for the [http://www.cegui.org.uk/phpBB2/viewtopic.php?p=13350 DynamicFont]

=== Files ===

==== DynamicFont.h ====
<source lang="cpp">
#ifndef _DynamicFont_h_
#define _DynamicFont_h_

#include "CEGuiSample.h"
#include "CEGUI.h"
#include "CEGUIXMLAttributes.h"

class DemoSample : public CEGuiSample
{
public:
bool initialiseSample()
{
using namespace CEGUI;
try
{
// Retrieve the window manager
WindowManager& winMgr = WindowManager::getSingleton();

// Load the TaharezLook scheme and set up the default mouse cursor and font
SchemeManager::getSingleton().loadScheme("TaharezLook.scheme");
System::getSingleton().setDefaultMouseCursor("TaharezLook", "MouseArrow");
if(!FontManager::getSingleton().isFontPresent("Commonwealth-10"))
FontManager::getSingleton().createFont("Commonwealth-10.font");

// Set the GUI Sheet
Window* sheet = winMgr.createWindow("DefaultWindow", "root_wnd");
System::getSingleton().setGUISheet(sheet);

// Load a layout
Window* guiLayout = winMgr.loadWindowLayout("DynamicFont.layout");
sheet->addChildWindow(guiLayout);

// Configure the event for the list of created fonts
CEGUI::Combobox* existingFonts = static_cast<CEGUI::Combobox*>(winMgr.getWindow("DynamicFont/Fonts"));
existingFonts->subscribeEvent(CEGUI::Combobox::EventListSelectionAccepted, CEGUI::Event::Subscriber(&DemoSample::eventSelectExistingFont, this));

// Configure the event for the add button
CEGUI::PushButton* add = static_cast<CEGUI::PushButton*>(winMgr.getWindow("DynamicFont/Add"));
add->subscribeEvent(CEGUI::PushButton::EventMouseClick, CEGUI::Event::Subscriber(&DemoSample::eventAddFont, this));

// Add the font previously created
addExistingFont("Commonwealth-10");
}
catch(Exception &e)
{
#if defined( __WIN32__ ) || defined( _WIN32 )
MessageBox(NULL, e.getMessage().c_str(), "Error initializing the demo", MB_OK | MB_ICONERROR | MB_TASKMODAL);
#else
std::cerr << "Error initializing the demo:" << e.getMessage().c_str() << "\n";
#endif
}

return true;
}

void cleanupSample(void)
{
}

bool eventAddFont(const CEGUI::EventArgs& args)
{
// Add a font from the specified parameters
using namespace CEGUI;

WindowManager& winMgr = WindowManager::getSingleton();
Window* nameText = winMgr.getWindow("DynamicFont/Name");
Window* filenameText = winMgr.getWindow("DynamicFont/Filename");
Window* sizeText = winMgr.getWindow("DynamicFont/Size");

setFont(nameText->getText(), filenameText->getText(), sizeText->getText());
return true;
}

void addExistingFont(const CEGUI::String& pName)
{
// Once a font has been created we add it to the combobox of fonts
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();

Combobox* existingFonts = static_cast<CEGUI::Combobox*>(winMgr.getWindow("DynamicFont/Fonts"));
ListboxTextItem* itemCombobox = new ListboxTextItem(pName);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
itemCombobox->setSelected(true);
existingFonts->addItem(itemCombobox);
}

bool eventSelectExistingFont(const CEGUI::EventArgs& args)
{
// Use an already created font
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
Combobox* existingFonts = static_cast<CEGUI::Combobox*>(winMgr.getWindow("DynamicFont/Fonts"));
setFont(existingFonts->getText(), "", "");
return true;
}

void setFont(const CEGUI::String& pName, const CEGUI::String& pFilename, const CEGUI::String& pSize)
{
// Set the font displayed within the multiline editbox
using namespace CEGUI;

String sampleText(pName);

WindowManager& winMgr = WindowManager::getSingleton();
CEGUI::Window* text = winMgr.getWindow("DynamicFont/Text");
Font* font;

if(FontManager::getSingleton().isFontPresent(pName))
{
// Select a previously created font
font = FontManager::getSingleton().getFont(pName);
}
else
{
// Dynamically create a new font
XMLAttributes xmlAttributes;

// Attributes specified within CEGUIFont.cpp
xmlAttributes.add("Name", pName);
xmlAttributes.add("Filename", pFilename);
xmlAttributes.add("ResourceGroup", "");
xmlAttributes.add("AutoScaled", "true");
xmlAttributes.add("NativeHorzRes", "800");
xmlAttributes.add("NativeVertRes", "600");

// Attributes specified within CEGUIXMLAttributes.cpp
xmlAttributes.add("Size", pSize);
xmlAttributes.add("AntiAlias", "true");

try
{
font = FontManager::getSingleton().createFont("FreeType", xmlAttributes);
if(font)
{
font->load(); // This function must be used
addExistingFont(pName);
}
}
catch(Exception &e)
{
// Display the error message
sampleText = e.getMessage();
}
}

text->setFont(font);
text->setText(sampleText);
}

private:
};

#endif // _DynamicFont_h_
</source>

==== main.cpp ====
<source lang="cpp">
#if defined( __WIN32__ ) || defined( _WIN32 )
#define WIN32_LEAN_AND_MEAN
#define NOMINMAX
#include "windows.h"
#endif

#include "DynamicFont.h"

#if defined( __WIN32__ ) || defined( _WIN32 )
int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine,int nCmdShow)
#else
int main(int argc, char *argv[])
#endif
{
DemoSample app;
return app.run();
}
</source>

==== DynamicFont.layout ====
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="DynamicFont" >
<Property Name="Text" Value="Dynamic Font" />
<Property Name="TitlebarFont" Value="Commonwealth-10" />
<Property Name="InheritsAlpha" Value="False" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.02,0},{0.054167,0},{0.98,0},{0.781251,0}}" />
<Window Type="TaharezLook/MultiLineEditbox" Name="DynamicFont/Text" >
<Property Name="Text" >
</Property>
<Property Name="ReadOnly" Value="True" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.01,0},{0.075,0},{0.99,0},{0.715617,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="DynamicFont/NameLabel" >
<Property Name="Text" Value="Name:" />
<Property Name="HorzFormatting" Value="RightAligned" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.018409,0},{0.881661,0},{0.0809004,0},{0.968338,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="DynamicFont/Name" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.0809,0},{0.881661,0},{0.328819,0},{0.968338,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="DynamicFont/FilenameLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Filename:" />
<Property Name="HorzFormatting" Value="RightAligned" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.347544,0},{0.881661,0},{0.438807,0},{0.968338,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="DynamicFont/Filename" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.438807,0},{0.881661,0},{0.713682,0},{0.968338,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="DynamicFont/SizeLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Size:" />
<Property Name="HorzFormatting" Value="RightAligned" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.731982,0},{0.881661,0},{0.793499,0},{0.968338,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="DynamicFont/Size" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.793499,0},{0.881661,0},{0.858294,0},{0.968338,0}}" />
</Window>
<Window Type="TaharezLook/Button" Name="DynamicFont/Add" >
<Property Name="Text" Value="Add" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.867109,0},{0.881661,0},{0.974324,0},{0.968338,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="DynamicFont/FontsLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Fonts:" />
<Property Name="HorzFormatting" Value="RightAligned" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.018409,0},{0.768338,0},{0.0859395,0},{0.855015,0}}" />
</Window>
<Window Type="TaharezLook/Combobox" Name="DynamicFont/Fonts" >
<Property Name="ReadOnly" Value="True" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.085939,0},{0.768338,0},{0.974324,0},{0.994412,0}}" />
<Property Name="MaxEditTextLength" Value="1073741823" />
</Window>
</Window>
</GUILayout>
</source>

[[Category:HowTo]]

CELayout Editor - Getting Started / Building

2011-03-04T16:12:27Z

Capek: Robot: Cosmetic changes

{{VersionBadge|0.6}}

== Abstract ==

This page tries to get you up and running with the layout editor. It will explain both the use of a distribution, and downloading from SVN. If you have problems, don't hesitate to visit the forums. And besides, you may alter this page with any information you think will be helpful to future readers of this page.
Some parts might be a little too verbose, but better safe then sorry ;-) If you're done reading, don't forget to read the [http://www.cegui.org.uk/wiki/index.php/Manual manual].

== Using a distribution ==

This is the recommended way. The distributions are stable and compatible with official CEGUI library releases. For example the 0.4.1 editor will work fine ("proven") with the 0.4.1 CEGUI release. Visit the [http://www.cegui.org.uk/wiki/index.php/Downloads download page] for Windows installer(s) and Linux source distribution(s). Before installing a new version, it is recommeded that you uninstall a previous version first, because files might get removed in newer versions and such.
On windows you can stop reading now. Linux and/or SVN users must read on for a bit more.

== Compiling yourself ==
If you are a non-windows user, or prefer SVN access over distributions, you must follow the steps mentioned in this topic.

=== Setup CEGUI ===
Please see the [http://www.cegui.org.uk/wiki/index.php/HOWTO:_Obtain_the_library_source_from_subversion CEGUI download info] for downloading and compiling the cegui library.

= Compile WxWidgets =

This topic explains how to get and setup this cross-platform application framework.

Distributions for many platforms can be found [http://www.wxwidgets.org/downld2.htm here].

== On Windows ==

=== Recommended: WxWidgets (2.8.11) ===

* [http://prdownloads.sourceforge.net/wxwindows/wxWidgets-2.8.11.zip Download as .zip]
* I recommend applying the following change manually in the file '''wxWidgets-2.8.11\src\msw\stdpaths.cpp''' :
In the function '''wxString wxStandardPaths::GetAppDir()''' ( starting at line 249 ) delete the lines 253 - 263 which should be equal to the following code snippet:
<source lang="cpp">
// allow running the apps directly from build directory in debug builds
#ifdef __WXDEBUG__
wxString lastdir;
if ( fn.GetDirCount() )
{
lastdir = fn.GetDirs().Last();
lastdir.MakeLower();
if ( lastdir.Matches(_T("debug*")) || lastdir.Matches(_T("vc_msw*")) )
fn.RemoveLastDir();
}
#endif // __WXDEBUG__
</source>
Deleting those lines will fix a bug leading to inconsistency between debug and release and allows you to load the splash screen png-file directly from the debug directory, same as it is the case for release. Otherwise, for the debug configuration the splash screen will be loaded from the bin directory (one level above).
* For compiling you have two options:
** Option 1 (fast): Compile using Visual Studio command line
*** Open the VS command line ( Start->All Programs->Microsoft Visual Studio->Visual Studio Tools->Visual Studio command line )
*** In the command line change to the build directory '''wxWidgets-2.8.11\build\msw''' (example: "'''cd C:\wxWidgets-2.8.11\build\msw'''")
*** To compile the debug configuration enter '''nmake -f makefile.vc BUILD=debug UNICODE=1 USE_OPENGL=1'''
*** To compile the release configuration enter '''nmake -f makefile.vc BUILD=release UNICODE=1 USE_OPENGL=1'''
** Option 2: Compile using the Visual Studio solution:
*** Change the lines '''#define wxUSE_GLCANVAS 0''' to '''#define wxUSE_GLCANVAS 1''' in the following files:
*** '''wxWidgets-2.8.11\include\wx\msw\setup.h'''
*** '''wxWidgets-2.8.11\include\wx\msw\setup0.h'''
*** '''wxWidgets-2.8.11\include\wx\univ\setup.h'''
*** Start '''wxWidgets-2.8.11\build\msw\wx.dsw''' (if saving the project afterwards, you can open wx.sln for later use cases)
*** Build all projects in "Unicode Debug" and "Unicode Release" configurations

=== WxWidgets (2.9.0) ===
* '''NOTE:''' Appearently this release doesn't work well with the editor yet. Please use 2.8.10 as latest 'safe' release.
* Download [http://www.wxwidgets.org/downloads/ wxAll].
* Edit '''wxWidgets-2.9.0\include\wx\msw\setup.h''', '''wxWidgets-2.9.0\include\wx\msw\setup0.h''' and '''wxWidgets-2.9.0\include\wx\univ\setup.h''' to change from '''#define wxUSE_GLCANVAS 0''' to '''#define wxUSE_GLCANVAS 1'''.
* Build '''wxWidgets-2.9.0\build\msw\wx.dsw''' (Appearently recent wx releases include solutions for vc7, 8 and 9 too).
* More unknown changes???

=== WxWidgets (2.8.3 - 2.8.10) ===

* Download [http://www.wxwidgets.org/downloads/ wxAll].
* Edit '''wxWidgets-2.8.3\include\wx\msw\setup0.h''' and '''wxWidgets-2.8.3\include\wx\univ\setup.h''' to change from '''#define wxUSE_GLCANVAS 0''' to '''#define wxUSE_GLCANVAS 1'''.
* Build '''wxWidgets-2.8.3\build\msw\wx.dsw'''
* More unknown changes???

=== WxWidgets (2.6.4) ===

* Download [http://www.wxwidgets.org/downloads/ wxAll].
* Edit '''wxWidgets-2.6.4\include\wx\msw\setup.h''' and '''wxWidgets-2.6.4\include\wx\univ\setup.h''' to change from '''#define wxUSE_GLCANVAS 0''' to '''#define wxUSE_GLCANVAS 1'''.
* Build '''wxWidgets-2.6.4\build\msw\wx.dsw'''

'''Note: '''I (scriptkid) always use the regular 'unicode debug' and 'unicode release' builds. But i assume that the DLLs will work fine too. If it hasn't been done so already, add 'include/msvc' and include to the include build paths and 'lib/vc_lib' to the library paths in Visual Studio.

=== WxWidgets (less than 2.6.4) ===

Because of issues I had compiling wxWidgets properly, I'm going to go into more depth for using Visual Studio 7.1 or 8.0 to do so. (Jouninkomiko 05-20-2006)

* Because the editor uses the wxGLCanvas, open include/msvc/wx/setup.h, and change the define for wxUSE_GLCANVAS from 0 to 1.
** Within the src/wxWindows.dsw solution you'll find this setting inside the wxWindows project, under Headers/Setup/setup.h

'''NOTE:''' Another Windows specific step-by-step guide was posted in the forums by [[User:fjeronimo|fjeronimo]] and can be read here: http://www.cegui.org.uk/phpBB2/viewtopic.php?t=2760

== On Linux ==
* Enter ./configure --with-opengl --enable-unicode
* Enter make
* Enter make install

=== Setup the editor ===
This topic explains how to get and setup the editor from sources.

==== Checkout ====
If you use a non-command line utility such as TortoiseSVN, you can choose one of these URLs to respectively checkout the HEAD or one of the stable branches.
http'''s'''://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk
http'''s'''://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/branches/v-0-4-1
http'''s'''://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/branches/before_wxwidgets

Or, from the command line (same order):
svn co http'''s'''://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk MyEditorFolder
svn co http'''s'''://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/branches/v-0-4-1 MyEditorFolder
svn co http'''s'''://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/branches/before_wxwidgets MyEditorFolder

Retreiving is always "anonymous", so it should work immediately.

==== Compile ====

On windows:
* Open vc++6/CELayoutEditor.dsw (VS6) or vc++6/CELayoutEditor.sln (VS7.1). Conversions should happen automatically when opening on newer versions. Make sure that you add the directories 'wxWidgets-x.x.x\include' and 'wxWidgets-x.x.x\include\msvc' to your Include Directories, and 'wxWidgets-x.x.x\lib\vc_lib' to your Library Directories.
* Also add CEGUI-0.5.0 to the project include folders.
* Also add CEGUI-0.5.0\include to the project include folders.
* Build either Debug or Release.

On Linux:
* Enter ./bootstrap
* Enter ./configure
* Enter make
* Enter make install
* Optionally set the CELAYOUTEDITOR_DATAPATH environment variable to point the editor to the correct 'datafiles' directory. If you do not set this variable, the editor will default to the location where it thinks the datafiles were installed (this will be typically be something like /usr/local/share/CELayoutEditor/datafiles). See the configuration file for additional details.

Hopefully, we will have a mac-compatible project or makefile in the future as well, so watch this space! :-)

== Setup CELayoutEditor ==

* If using the Visual Studio solution: go to the '''Project Settings''' and under '''Debugging''' set '''$(TargetDir)''' as the '''working directory''' for your configurations ('''Debug''' and '''Release''').

* Get all the '''CEGUI dll s''' you need and place them in your working directories. ( e.g. in '''C:\CELayoutEditor\bin\debug''' and '''C:\CELayoutEditor\bin\release''' if "C:\CELayoutEditor" is your checkout directory). You will also need '''SILLY.dll''' and '''SILLY_d.dll''' from the CEGUI dependencies respectively placed in the release and debug directories.

* Now after compiling, the CELayoutEditor should be ready to start and working. Everything regarding the .ini files and handling the editor should be covered in the manual.

[[Category:Tutorials]]

Changes and Porting Tips for 0.5.0

2011-03-04T14:37:03Z

Capek: SILLY interlinks

{{VersionBadge|0.4}}

Note that this is incomplete, work in progress, documentation.

= Release =

* 0.5.0 stable Released on November the 6th 2006: [[CEGUI Downloads 0.5.0|goto download page]]
* 0.5.0 RC1 Released on June the 20th 2006: [[Downloads 0.5.0-RC1|goto download page]]
* 0.5.0 RC2 Released on August the 13th 2006: [[Downloads 0.5.0-RC2|goto download page]]

= ChangeLog =
<pre>
Release 0.5.0 (Final)
=====================
Added: TaharezLook was missing ItemListbox and ListboxItem windows & skin
definitions.
Added: Partial CEGUI support for MingW. It is now possible to build CEGUI under
mingw with support for OpenGL renderer. This approach is going to be generalized
later to the other renderer and wiki page explaining the process will follows.
Added: Missing functions in WindowFactoryManager Lua bindings. Incomplete
FalagardWindowMapping binding as well.
Added: Lua binding for OutStream: FileStream (minimal std::ofstream).
Added: XML writing function in Lua bindings.
Added: --enable-debug in configure script instead of using CPPFLAGS=-DDEBUG
./configure ...
Added: premake files for Minesweeper sample and minor fixes to make it run in
windows.
Added: the minesweeper demo
Added: missing doxyfile in order to be in make dist
Added: ScrollablePane sample

Removed: Empty Font 'implData' header files we no longer use.
Removed: [[Falagard]] skinning manual is now a part of the CEGUI manuals
sub-project, so is no longer included here as a pdf.

Modified: Changed Demo7 to use the layout XML file instead of hard-coded window
creation.
Modified: Demo7Window.layout now uses the new ItemListbox, with items defined
within the layout, as the Listbox as opposed to the old style list with
hard-coded items.
Modified: Win32CEGuiRendererSelector:
- It is now possible to navigate to the Combobox via keyboard.
- First available renderer is pre-selected into the dialog.
- With a single renderer available, it is auto-selected and dialog is not shown.
Modified: Changed compile order under autotools so CEGUIBase is made before
things that use it - related to forthcoming cross-compile support.
Modified Added some missing bits and a whole load of other stuff to 'make dist'
to ease a more unified approach to creating packages for the various platforms.
Modified: Renamed tolua++bin/remake_pkg..bat to remove extra period
Modified: Changed Russian text in FontDemo sample - the old text apparently
potentially offensive. Thanks to 'Sanya' for the updated text.
Modified: The RefCounted template now has the CEGUIEXPORT macro as it avoids
warnings in client code when using MSVC.
Modified: Promote Expat to be the second prefered parser under linux in order to
act the same under linux and Win32. Note that the prefered parser is still
Xerces. The parser order is now the following : Xerces, Expat, Libxml, TinyXML.
Modified: WidgetComponent had a nasty misspelling of 'Alignemnt'.
Modified: MSVC no longer uses CEGUIConfig.h and CEGUISamplesConfig.h for
anything
Modified: Premake scripts are now much more flexible.

Coding Standards: Removed various occurrences of the NULL macro.

Docs: Added note to docs for Spinner regarding the lame state of floating point
support.

Bug Fix: ListHeader settings for sizing, moving, and clicking were not properly
set on newly created segments.
Bug Fix: Resolved issue where the algorithm that ensured font textures were
filled would actually end up trying to render every glyph within a font.
Bug Fix: ItemListBase::insertItem was not setting the ItemEntry::d_ownerList
member correctly.
Bug Fix: Added another 'special case' to Spinner::getValueFromText to support
typing an initial decimal point.
Bug Fix: Sometimes compound widgets did not get their components layed out
properly when adding the widget to its parent.
Bug Fix: The way in which properties would set a window to use the DefaultFont
was incorrect; it explicitly set it to the name of the current default, as
opposed to a 'floating default'.
Bug Fix: FontDim did not work correctly since re-calculation of the layout was
not triggered in response to the font being changed. Added this code to
Window::onFontChanged - although more elegant / selective solutions might be
considered later on.
Bug Fix: Added code so that all windows using default font get notified of a
change in the default via the normal channel (Window::onFontChanged).
Bug Fix: There was an issue regarding auto-repeat of mouse button down events
not getting their state reset if the mouse button was released outside of the
window getting the auto-repeat events.
Bug Fix: CEGuiSample.cpp did not get all required includes with certain renderer
combinations.
Bug Fix: Range emplyed by FreeTypeFont::rasterize was exclusive of the start
element; first glyph of every page loaded was missed!
Bug Fix: CEGUI::Window did not properly clean-up a custom tooltip if it created
one.
Bug Fix: Calculation of number of glyph pages in Font::setMaxCodepoint was
incorrect.
Bug Fix: When the OpenGL renderer was disabled by ./configure, the [[SILLY]] codec
was still being built.
Bug Fix: When the OpenGL renderer was disabled by ./configure, the requirement
for a default ImageCodec was still enforced.
Bug Fix: case of included file in Win32CEGuiRendererSelector.cpp changed ready
to support cross-compiling in post 0.5.0 versions.
Bug Fix: Support was broken in the Samples framework for newer versions of Ogre.
Bug Fix: The cegui_reldim and cegui_absdim macros were missing the CEGUI
namespace qualifier.
Bug Fix: When a glyph failed to load in FreeTypeFont, although we logged the
error we did not work around the issue of the missing glyph image, so a seg
fault was generated upon attempted use of those missing images. This addresses
the issue by creating dummy images for missing font glyphs which use a zero
size. Mantis #0000125.
Bug Fix: RefCounted would call AddRef when the wrapped pointer and its counter
were null.
Bug Fix: Event::ScopedConnection would call members of BoundSlot using a
potentially null RefCounted pointer.
Bug Fix: In C++ a namespace does not have a semicolon after the closing brace.
Bug Fix: Nasty memory leak in DevIL image codec. thanx to mafm on IRC.
Bug Fix: fixed a small error in the comment of CEGUI_DECLARE_WINDOW_FACTORY
Bug Fix: Tab control did not require to hear about multi-clicks on the
TabControl scroll buttons. Patch from zap. Mantis #0000117.
Bug Fix: Issue with utf8 missing conversion in TinyXML and libXML
Bug Fix: Added missing public visibility specifier to ScopedConnection class
members.
Bug Fix: premake files were not enabling Xerces correctly in the samples.
Bug Fix: TabControlDemo layout split up. We dont allow multiple root windows in
a layout when using a validating XML parser.
Bug Fix: Falagard.xsd was missing new type attribute for PropertyDim.
Bug Fix: PropertyLinkDefinition was not writing XML properly (no base class
writing).
Bug Fix: Bugs in [[Falagard]] XML writing.
Bug Fix: Spinner would throw an exception when a lone minus sign was entered.
Mantis ticket #110.
Bug Fix: Input capture bug that broke Combobx - introduced by patch #82.
Bug Fix: ScrollablePane would cause exceptions on destruction. Mantis ticket
#83.
Bug Fix: a bug in the premake improvements where samples would not generate
properly.
Bug Fix: A number of CEGUI exceptions were being caught by value instead of
reference.
Bug Fix: OpenGL renderer now also disables texture coordinate generation.
Bug Fix: Irrlicht sample driver now quits on the escape key like the rest.
Bug Fix: Updates and fixes to resolve the NPOT texture source data issue (mantis
#45) in a relatively consistent way - at least for the 0.5.x releases.

Release 0.5.0-RC2
=================
Added: single colour support to PropertyHelper::stringToColourRect
Added: missing support to Irrlicht renderer for creating a texture with a given size.
Added: Updates to renderers for D3D8.1 and D3D9 to report correct values for 'original' size and actual texture size. (Related to Mantis ticket #45).
Added: Support for using user defined image codec by name (using dso) or directly throught a pointer to an existing image codec.
Added: Long property export (allows for properties containing multiple lines).
Added: Helper methods to Window to return EventSet::Iterator and PropertySet::Iterator objects.
Added: Reworked TabControl by zap. Mantis #82.
Added: TabControlDemo sample. Mantis #82.
Added: Danish language in the FontDemo sample.
Added: Output of summary of configure results (for configure based builds)
Added: Texture extra size information to CEGUI::Texture in order to be able to handle scaled/stretched textures within Imageset.
Added: Texture Scaling support in IrrlichRenderer

Removed: Empty source file CEGUIVector.cpp
Removed: TabPane files.

Modified: Behaviour of Editbox so that EventCharacterKey events are only marked as handled if the key press actually resulted in a change to the Editbox text string. (Related to Mantis #59)
Modified: Replaced all getWindow<something> with get<something>
Modified: Replaced all setWindow<something> with set<something>
Modified: EventSet::EventIterator now known as EventSet::Iterator
Modified: PropertySet::PropertyIterator now known as PropertySet::Iterator
Modified: ImageCodec modules are now DynamicModule
Modified: [[Falagard]] PropertyDim now supports a type attribute for UDim properties. Mantis #82.
Modified: Improved TabControl imagery. Mantis #82.
Modified: autotools makefiles now symlink the sample binaries (to avoid having to do 'make install'). Mantis #82.
Modified: PropertyHelper now uses snprintf instead of std::ostringstream again. Mantis #82.
Modified: Removed static Makefile for tolua++cegui generator tool and switched to autotools style build, with enable/disable configure option, for tolua++cegui generator tool
Modified: Moved tolua++ into its own dir, removed lua_and_tolua++
Modified: Externalised our use of the Lua library
Modified: premake updates
Modified: Updated AUTHORS file.
Modified: Remove exec file attribute on Falagard.xsd
Modified: XMLRefSchema/Font.xsd for font rewrite
Modified: LuaScriptModule public headers no longer need include lua.h included.
Modified: Made a bunch of warnings go away in MSVC in the new font code.
Modified: Deleted the remaining old msvc project files.

Bug Fix: Clean the XMLSerialization code: remove empty autowindow
Bug Fix: Added missing glDisable(GL_FOG); in gl renderer
Bug Fix: Irrlicht and D3D8.1 renderer modules would keep live pointers to Texture objects that failed to fully initialise (file or size errors for example) Mantis #43.
Bug Fix: Disable texture stages we do not use in Direct3D renderers. (Mantis #95)
Bug Fix: Mouse cursor z value. Mantis #49
Bug Fix: Imagset XML attribute for image file name is 'Imagefile' and not 'Filename'.
Bug Fix: normal attributes use 'true', only properties sometimes use 'True'.
Bug Fix: Global default resource group was not being used by DefaultResourceProvider.
Bug Fix: XML output from CEGUI::Image class.
Bug Fix: Imageset scaling issue when renderer automatically scales the image #45 (this is currently a partial fix)
Bug Fix: IrrlichtRenderer - Mouse event error. Mantis #98.
Bug Fix: IrrlichtRenderer - size error in addQuad. Mantis #99.
Bug Fix: IrrlichtRenderer - Sample driver had linker lib name wrong for renderer module. Mantis #100.
Bug Fix: TinyXMLParser bug. Mantis Tracker #57
Bug Fix: a bug in the openglrenderer cleanup related to image codec.
Bug Fix: Install renderer module includes at the same place as in Win32 (linux / mac autotools)
Bug Fix: OpenGL sample driver did not inject middle mouse up (injected it as down). Mantis #82.
Bug Fix: Corrected some mistakes in the [[Falagard]] Lua bindings
Bug Fix: Apparently in some cases OpenGLRenderer needs NOMINMAX in Win32 (Mantis #63)
Bug Fix: FreeTypeFont did not free the font data properly, also fixes a potential infinite loop in FreeTypeFont (Mantis #60)
Bug Fix: FairChar font texture was not power of 2 (Mantis #64)
Bug Fix: SliderThumb incorrectly mapped in some schemes (mantis #88)
Bug Fix: Updated Irrlicht renderer to work with 0.5.0 codebase.
Bug Fix: some missing data
Bug Fix: DirectX 8.1 sample driver
Bug Fix: some missing files in the make dist command (Mantis #89)
Bug Fix: Change the name of an enumeration value in schema Font.xsd.
Bug Fix: Memory leak in Font.
Bug Fix: Lua bindings was missing ImagesetManager::createImagesetFromImageFile + some missing tolua_throws modifiers

== Release 0.5.0-RC1 ==
Various internal code cleanups:
- Removal of unrequired utf8* casts on string literals.
- Removed use of NULL macro from the library code.
- Code refactorings to Font class. Removes some instances of repeated code, and makes
some methods shorter / cleaner.
- Split large methods in Scheme into smaller, more managable, chunks.
- Removed all the System constructor overloads and replaced with a single method.
- Removed string literals for component widget names which were scattered throughout t
he widget code.
- Replaced virtually all member fields holding pointers to component widgets with gett
er methods (which basically allows those widgets to be replaced without the parent kno
wing or caring).
- Refactoring of XML handler to remove huge if/else if/else construct.
- Refectored large if / else if / else constructs in all non-falagard XML handlers to
use a member function for each element type (rather than having all code in one huge f
unction).
- Event system has been rewritten from scratch.
- Font system has been rewritten.

Added "PushedOff" rendering state for button based widgets and MenuItem.
Added: Ability to rename windows.
Added: CEGUISamplesConfig.h file to allow configuration of samples framework independe
ntly of the main config (saves recompiling everything just to change some sample setti
ng).
Added: FPS readout to OpenGL base app in the samples framework.
Added: "PropertyLinkDefinition" element for [[Falagard]] system.
Added: "controlPropery" attribute to SectionSpecififations under falagard to enable re
nering of section imagery to be controled via a named boolean property.
Added: mouse pass through feature in Window, to ignore mouse events. Nice for making a
DefaultWindow transparent to the mouse regarding picking windows behind it.
Added: MSVC++ auto-linking for Ogre base app in samples framework.
Added: grab/restoreTextures in the OpenGL renderer to cache texture image data, and la
ter restore it.
Added: Abstracted Logger interface to support user created custom loggers. (SF patch #
1414121 by zap)
Added: DefaultLogger implementation (SF patch #1414121 by zap)
Added: page up/down key functionality to MultiLineEditbox (SF patch #1347376 by Dalfy)
Added: small script to recreate the binding generator for tolua++
Added: customized tolua++ binary. For exception handling support in generated binding
code.
Added: missing exception definitions file needed to generate the bindings.
Added: README with instructions on how to generate the bindings.
Added: Documentation for some of the new features in the bundled tolua++ generator.
Added: When subscribing to events from "inside" Lua a self object can be registered as
well to be passed along with the EventArgs.
Added: New WindowRenderer system, replacing previous system where the Window sub-class
controlled the rendering process.
Added: Major update of the LuaScriptModule to support anonymous functions.
Added: Exception handling has been added for some functions.
Added: [[Falagard]] derivatives of DefaultWindow, DragContainer and ItemEntry with minimal
StateImagery.
Added: executeEventHandler now accepts functions that are table fields.
Added: Text node support to both parser (Xerces and TinyXML)
Added: AutoWindow tag to xml layouts to fetch a window created by the look'n'feel or t
he base widget itself.
Added: Window::isAutoWindow member that returns true if the window has "__auto_" in it
s name. (a flag is set in the constructor). It's faster than checking the actual strin
g.
Added: A setting to Window to specify that it should never write XML no matter what if
activated. Tooltips get this set by default by System.
Added: A property ban list to provide a system for mapping which properties should (no
t) be written to XML. In the respective addProperties member functions checks have bee
n added and some properties are banned if we are an auto window.
Added: Default resource group support to Xerces for use when loading schema files.
Added: Default resource group support to ScriptingModule, and implemented its use in
the CEGUILua module.
Added: DynamicModule class to wrap access to a dynamically linked / loaded module.
Added: New dynamic libraries for Xerces, Expat TinyXMLParser, and libxml Parsers.
Added: TextProperty and FontProperty elements for [[Falagard]] text components.
Added: New ItemListBase based ItemListbox widget. For Window based listbox items.
Added: XML Serialization class for all XML writing.
Added: Recursive versions of Window::getChild and isChild by ID. They are called getCh
ildRecursive and isChildRecursive. Reason for the explicit naming is that it's a pretty expensive operation and should not be used unless necessary.
Added: Lots of missing members in the Lua bindings.
Added: setlocale(LC_NUMERIC, "C"); to the System constructor as we depend on this beha
viour.
Added: setVisible member to CEGUI::MouseCursor.
Added: bat files to make it easier for Windows users to regenerate the Lua bindings an
d tolua++cegui.
Added: ImageCodec support to the OpenGL renderer. This allows users to easily write a
custom image loader. TGA, [[SILLY]], DevIL, Corona and FreeImage codecs are supplied.
Added: const version of getDataPtr in RawDataContainer.
Added: premake scripts to generate MSVC solutions.
Added: ClippedContainer for situations where more specialized clipping is required.

Modified: Placed the integrated TinyXML into its own namespace (CEGUITinyXML) to preve
nt clashes in projects using another copy of TinyXML. (Patch #1294002).
Modified: Changed EventSet to operate without needing events to be pre-added, much lik
e GlabalEventSet always did.
Modified: Removal of mass pre-specification of events for all classes using events.
Modified: Cflags to add include dir for CEGUI in CEGUI.pc.in (allows use of <CEGUI/...
> form of include statement).
Modified: The "Lua and tolua++" module has been made a DLL on Windows machines.
Modified: Renamed System::setTooltip to System::setDefaultTooltip (Mantis #1Cool.
Modified: In the lua module, updated Window with casting helpers as member functions.
eg. w:toFrameWindow()
Modified: Removed the Static,StaticText and StaticImage from CEGUIBase and implemented
them in FalagardBase instead.
Modified: Updated to tolua++ 1.0.92
Modified: Moved LuaFunctor into its own files
Modified: Reimplemented the "late binding" effect from the v04 Lua module. In v04 the
function is always looked up by name. In CVS HEAD the actual Lua function is reference
d, but now this will only occur the first time the event is triggered. This means that it's no longer necessary to have a function defined to subscribe it to an event. As l
ong as the function has been created before the event occurs everything will be good S
mile
Modified: Moved subscribeScriptedEvent into ScriptModule to allow more customized scri
pt subscription functionality.
Modified: Made the layout XML handler use subscribeScriptedEvent for Event tags instea
d of subscribeEvent with ScriptFunctor
Modified: Removal of "tolua_outside" stuff that was no longer needed.
Modified: Moved the declaration/definition of base window factories into its own files
.
Modified: Removal of WidgetSets folder, and its contents.
Modified: Removed unnecessary getSingleton and getSingletonPtr from manager classes.
Modified: The script module now throws ScriptException.
Modified: Removal of TextItem as falagard now handles that exclusively.
Modified: Moved all rendering member functions out of base classes an into [[Falagard]] re
ndering classes.
Modified: Removal of virtually all rendering and layout related Window properties from
CEGUIBase - a few are moved to FalagardBase, the rest must be implemented via XML.
Modified: Removal of TaharezLook and WindowsLook modules from the system.
Modified: Removal of MetricsMode system, and all non-unified interface and properties
from Window (and related fixes to other classes).
Modified: Elimination of RenderableElement and derived classes.
Modified: Moved to a C preprocessor macro system for widget module creation.
Modified: Removal of abstract createXXX methods from widget base classes - the looknfe
el system now auto-creates these widgets when specified within the XML.
Modified: Updated to TinyXML 2.4.3 in order to allow CDATA section in XML text node (v
erbatim text)
Modified: GUILayout handler in order to support long value in properties.
Modified: Made the XML writing system aware of falagard when determining property defa
ult values.
Modified: Switched PropertyHelper to use std::ostringstream as the output is much nice
r. Changed property default values to the new format where needed.
Modified: Better error reporting for dynamic module load failures.
Modified: Switched to using external pcre library. Removed embedded copy of pcre.
Modified: Switched system to use dynamic libs for XML parsers with programatically con
figurable default.
Modified: FactoryModule to use DynamicModule.
Modified: Resolved issue with unneeded member qualification (Patch #1454773).
Modified: Made String::ptr a public member.
Modified: The bundled tolua++cegui binding generator will now generate a lua_CEGUI.cpp
that compiles out-of-the-box on Windows
Modified: Removed the DataContainer template class, and made it into just RawDataConta
iner, non templated.
Modified: Optimized FalagardMultiLineEditbox to only cache visible lines when renderin
g.
Modified: Optimized ButtonBase and MenuItem updateInternalState. Mantis #44
Modified: Moved the renderers to their own folder named RendererModules.
Modified: Optimized picking and rendering by caching screen space rectangles.
Modified: Applied zap's rewrite of the Font system. Patch #1508321
Modified: Texture::loadFromMemory now takes a Texture::PixelFormat parameter. RGB and
RGBA are currently required. Fixes Patch #1455523 as well. 3rd party renderer modules
needs to be updated.

Bug fix: OpenGLRenderer was producing errors and not cleaning up state changes properl
y (thanx muhkuh25)
Bug fix: OpenGLRenderer was broken when compiled for x86-64.
Bug Fix: ListboxItem::getOwnerWindow should be const
Bug Fix: ListboxItem::getOwnerWindow should not take a Window* argument.
Bug Fix: Scheme::resourcesLoaded was always returning true.
Bug Fix: PropertyHelper::stringToImage was not handling empty string case.
Bug Fix: Editbox::onCharacter was setting the event as handled even if nothing was don
e.
Bug Fix: Added shift/ctrl/alt support to the OpenGL sample driver (injects LeftXXX)
Bug Fix: The command line renderer selector does no longer ask if there is only one re
nderer available.
Bug Fix: Fixed window resizing for the OpenGL Sample driver.
Bug Fix: fixed const correctness for "String::utf8_stream_len" SF patch #1367423
Bug Fix: Detect "window->addChildWindow(window);" and do nothing instead of actually t
rying.
Bug Fix: Added missing performChildWindowLayout to Scrollbar::onScrollConfigChanged to
allow making a look'n'feel with a thumb that sizes to indicate document size.
Bug fix: const correctness for Window::getLookNFeel
Bug fix: FrameWindow, isTitlebarEnabled and isCloseButtonEnabled were return the oppos
ite of what they should.
Bug Fix: FrameWindow should do relayout if text changes to allow using a fontdim in th
e titlebar dimensions.
Bug Fix: Changing the default mouse cursor in the System object will now update the cu
rsor immediately where appropriate. (Ticket #17).
Bug Fix: Fixed case in StaticText where default text area was always used if frame was
disabled.
Bug Fix: Image offsets were'nt being properly handled for the corners in FrameComponen
t.
Bug Fix: MultiColumnList would always use item string when sorting, instead of vitual
operators on users custom items.
Bug Fix: System::getWindowContainingMouse would return incorrect Window if called from
within Window::EventMouseLeaves handlers.
Bug Fix: Order of static data creation in C++ is unspecified; we can't have globally d
efined static data that relies on other such static data within the same module.
Bug Fix: Falagard/ProgressBar was broken when vertical or reversed-horizontal.
Bug Fix: Corruption of window registry when rename failed (Patch #1450623).
Bug Fix: Initialisation issue with TabControl trying to access child widgets before th
ey are created. (Patch #1391727).
Buf Fix: CEGUI::Window::setModalState(true) removes the modal state from a modal windo
w. Mantis #42
Bug Fix: MultiColumnList getNextSelection bug. Mantis #47
Bug Fix: System subscriber to renderer event but does not unsubscribe on destruction.
Mantis #48
Bug Fix: OpenGL and DirectX9 renderers were not handling error correctly when creating
textures.
Bug Fix: Bug in LuaScriptModule where executeScriptFile did not unload the file data b
uffer correctly in case of an exception (thanks gcarlton).
Bug Fix: A bug in ItemListBase::resetList_impl where calling resetList would crash (th
anks Turtle).
Bug Fix: Typo in TabPane::testClassName_impl ("Tabpane" instead of "TabPane").
Bug Fix: Big Endian inconsistency in CEGUI::colour.
Bug Fix: CEGUI::Window was not detaching the tooltip during destruction. Mantis #38
Bug Fix: FrameWindow was consuming all LeftButton up events. Down events were affected
as well, and now only consume if the event started drag sizing.
Bug Fix: DragContainer would overwrite any new position applied to the DragContainer d
uring the DragDropItemDropped event. Mantis #53
Bug Fix: The OpenGL sample driver could cause a stack overflow. Patch #1507826
</pre>

= Porting Notes =

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

== CELayoutUpgrader ==

[[CELayoutUpgrader]] is a python script that can upgrade XML layout files to the Unified Coordinate System. It should help to ease the porting process.

== 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 co-ordinate types: UDim, UVector2 and URect.

{| cellpadding=2px cellspacing=0
| style="color: #ffffff; background-color: #ff5555; border: solid 1px #000000;" | '''The information in the following section has been updated again since RC1 was issued - early adopters will need to update their code again to use SVN trunk code and the upcoming RC2.'''
|}

* getXPosition, getWindowXPosition, getRelativeXPosition and getAbsoluteXPosition members are replaced with a single getXPosition member returning a UDim.
* getYPosition, getWindowYPosition, getRelativeYPosition and getAbsoluteYPosition members are replaced with a single getYPosition member returning a UDim.
* getPosition, getWindowPosition, getRelativePosition and getAbsolutePosition members are replaced with a single getPosition member returning a UVector2.
* getWidth, getWindowWidth, getRelativeWidth and getAbsoluteWidth members are replaced with a single getWidth member returning a Udim.
* getHeight, getWindowHeight, getRelativeHeight and getAbsoluteHeight members are replaced with a single getHeight member returning a UDim.
* getSize, getWindowSize, getRelativeSize and getAbsoluteSize members are replaced with a single getSize member returning a UVector2
* getRect, getWindowArea, getRelativeRect and getAbsoluteRect members are replaced with a single getArea member returning a URect.
* getMaximumSize and getWindowMaxSize members are replaced with a single getMaxSize member returning a UVector2.
* getMinimumSize and getWindowMinSize members are replaced with a single getMinSize member returnung a UVector2.

* setWidth and setWindowWidth members are replaced with a single setWidth member taking a UDim.
* setHeight and setWindowHeight members are replaced with a single setHeight member taking a UDim.
* setSize and setWindowSize members are replaced with a single setSize member taking a UVector2.
* setXPosition and setWindowXPosition members are replaced with a single setXPosition member taking a UDim.
* setYPosition and setWindowYPosition members are replaced with a single setYPosition member taking a UDim.
* setPosition and setWindowPosition members are replaced with a single setPosition member taking a UVector2.
* setAreaRect, setRect and setWindowArea members are replaced with setArea members accepting the following options:
** Four UDims; specifying x position, y position, width and height.
** Two UVector2s; specifying position and size.
** A single URect defining the area.
* setMaximumSize and setWindowMaxSize members are replaced with a single setMaxSize member taking a UVector2.
* setMinimumSize and setWindowMinSize members are replaced with a single setMinSize member taking a UVector2.

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

=== Font system changes ===

* There's no notion of '''StartCodepoint''' and '''EndCodepoint''', or '''glyph set''' anymore. Font render glyphs on the fly as required: if you ask to display "A" it renders a small subset of glyphs (256 codepoints surrounding the missing glyph usually, but can render extra glyphs out of the range to conserve texture space).
* The Font class is now an abstract class and there are two implementations: FreeTypeFont and PixmapFont.
** FreeTypeFont uses the FreeType library and can display TTF, FON, PCF/BDF, PS fonts (and possibly others). I have ensured that bitmap fonts work, since bitmap fonts should be handled a little different from outline fonts.
** PixmapFont uses an Imageset with the glyphs and can display colorful glyphs (which FreeType cannot due to its grayscale nature). However, it's more primitive, but can be useful for things like logos, loading messages etc.
* The Font class is now a PropertySet, so specialized classes derived from Font can add their own properties (such as PointSize for FreeType fonts which don't have sense for Imageset-based fonts). Here's a list of available properties:
** All font classes: Name, FileName, NativeRes, ResourceGroup, AutoScaled
** FreeTypeFont: PointSize, Antialiased
** PixmapFont: Imageset, Mapping
* Fixed a number of (vertical) font positioning errors: the font wasn't properly centered within its LineAdvance range.
* Added several new fonts: DejaVuSans (taken from the DejaVu project, http://dejavu.sf.net), fkp (a X11 bitmap font from http://artwizaleczapka.sf.net), FairChar (a Imageset-based font which I made from some old GIF file I found on my HD :-).
* A FontDemo sample which shows several properties of the new Font class.

The above changes resulted in some slight changes to the format of the XML .font files:

* GlyphSet, GlyphRange, Glyph sections of the Font are gone
* The possible values of the Type attribute are now:
** FreeType (instead of Dynamic)
** Pixmap (instead of Static)
* The FirstCodepoint and LastCodepoint attributes of the Font section were removed

After you change your .font files as mentioned above, they should work without problems.

=== Iterator Changes ===
* EventSet::EventIterator is changed to EventSet::Iterator
* PropertySet::PropertyIterator is changed to PropertySet::Iterator

=== Convert Point to UVector2 ===

<source lang="cpp">CEGUI::Point(_x, _y)</source>
becomes
<source lang="cpp">CEGUI::UVector2(CEGUI::UDim(_x,0), CEGUI::UDim(_y,0))</source>

To be continued...

[[Category:Manuals]]

News Archive

2011-03-04T14:34:38Z

Capek: SILLY interlinks

=== CEGUI Version 0.7.5 released! by ''' [[User:Crazyeddie|Crazyeddie]] 20th November 2010 ===
Read all the details in the [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=6&t=5280 official announcement].

=== CEGUI Version 0.7.4 released! by ''' [[User:Crazyeddie|Crazyeddie]] 11th October 2010 ===
Emergency fix for 0.7.3 release! [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=6&t=5182 official announcement].

=== CEGUI Version 0.7.3 released! by ''' [[User:Crazyeddie|Crazyeddie]] 8th October 2010 ===
Read all the details in the [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=6&t=5182 official announcement].

=== CEGUI Version 0.7.2 released! by ''' [[User:Crazyeddie|Crazyeddie]] 29th August 2010 ===
Read all the details in the [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=6&t=5096 official announcement].

=== CELayoutEditor 0.7.1 released for Windows! by ''' [[User:scriptkid|scriptkid]] 1th January 2010 ===
See the [[CELayoutEditor Downloads 0.7.1]] page for the link.

=== "Pirate Princess" (game) released! by ''' [[User:scriptkid|scriptkid]] 25th November 2009 ===
Pirate Princess is a semi-casual word game based adventure, just finished and on sale. Of course it uses CEGUI (a lot!). Check out the website:
[http://www.moonpod.com/English/about_pirateprincess.php Pirate Princess - A word game based adventure!].

=== CEGUI 0.7.1 is Released! by ''' [[User:scriptkid|scriptkid]] 26th October 2009 ===
See the [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=6&t=4443 details here]

=== "Cube Combat" (game) released! by ''' [[User:scriptkid|scriptkid]] 20th October 2009 ===
Cube Combat is a bomberman remake game, which uses CEGUI. It looks & feels nice and polished. Check out the website:
[http://www.cubecombat.net Cube Combat - A 3D bomberman remake!].

=== CEGUI 0.7.0 is Released! by ''' [[User:CrazyEddie|CrazyEddie]] 20th September 2009 ===
See the [http://www.cegui.org.uk/phpBB2/viewtopic.php?f=6&t=4340 details here]

=== CEGUI 0.6.3 release of the Layout Editor! by ''' [[User:scriptkid|scriptkid]] 9th June 2009 ===

=== "Snakeworlds" (game) released! by ''' [[User:scriptkid|scriptkid]] 3rd April 2009 ===
Snakeworlds is a snake remake game, which uses CEGUI. Check out the website:
[http://www.snakeworldsgame.com Snakeworlds - A spherical snake game!].

=== CEGUI 0.6.2 Released! by ''' [[User:CrazyEddie|CrazyEddie]] 3rd December 2008 ===

Read the [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=3712/ buzz]

=== New 0.6.x in-progress LayoutEditor! by ''' [[User:scriptkid|scriptkid]] 2th August 2008 ===

See the [[CELayoutEditor Downloads 0.6.x]] page for the link (bottom of the page!).

=== New 0.6.x in-progress LayoutEditor! by ''' [[User:scriptkid|scriptkid]] 7th May 2008 ===

See the [[CELayoutEditor Downloads 0.6.0]] page for the link (bottom of the page!).

=== New 0.6.0 Release of CEGUI and tools! by ''' The CEGUI Development Team 27th March 2008 ===
The Crazy Eddie's GUI System project (crayzedsgui on sourceforge.net) is pleased to announce the release of version 0.6.0 of the Crazy Eddie's GUI System library and associated CELayoutEditor and CEImagesetEditor tools.

Founded in 2003, Crazy Eddie's GUI System has consistently been one of the favourite choices for the serious game or multimedia developer needing a mature, stable and flexible rendered GUI solution. The library is open source, highly configurable and offers virtually unrivalled skinning opportunities via its "Falagard" XML skinning system. Crazy Eddie's GUI System library is released under the MIT license, thus offering the ultimate flexibility for all usage scenarios.

The 0.6.0 release comes some 16 months after the previous release, and marks the official return of Paul D Turner (CrazyEddie) as project leader and as a permanent member on the development team.

For more information about Crazy Eddie's GUI System see the project website at http://www.cegui.org.uk. Support requests for the library and associated tools, in the first instance, should be directed at the Crazy Eddie's GUI System project forums at http://forums.cegui.org.uk.

You can get the files at the [[Downloads|CEGUI Downloads page]].

See also this forum thread: http://www.cegui.org.uk/phpBB2/viewtopic.php?p=13973

=== New MSVC++ 9 binary packages for CEGUI and [[SILLY]] by ''' [[User:CrazyEddie|CrazyEddie]] 3rd February 2008 ===
We have released binary dependency packages and pre-built SDK packages for both [[SILLY]] 0.1.0 and CEGUI 0.5.0b for use with Microsoft's Visual C++ 9 (2008 edition) compiler.

See the [[Downloads]] page and the announcement on the [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=2965 forums] for additional information.

=== New CELayoutEditor SVN trunk update by ''' [[User:fjeronimo|fjeronimo]] 18th December 2007 ===
A new update that adds new features to the property grid, improves exception handling, adds version information and more misc stuff has been committed to the CELayoutEditor SVN trunk.

More details can be found in the following [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=2825/ forum entry].

=== New CEImagesetEditor SVN trunk update by ''' [[User:fjeronimo|fjeronimo]] 10th December 2007 ===
A new update that adds VS2003 & VS2005 solutions and modifies configuration settings has been
committed to the CEImagesetEditor SVN trunk.

More details can be found in the following [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=2822/ forum entry].

=== New CELayoutEditor SVN trunk update by ''' [[User:fjeronimo|fjeronimo]] 06th December 2007 ===
A new update that adds Vectored Exception Handling (VEH) support, stack trace info to all thrown exceptions and
other misc stuff has been committed to the CELayoutEditor SVN trunk.

More details can be found in the following [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=2821/ forum entry].

=== New Widget: GroupBox ''' [[User:Scriptkid|Scriptkid]] 02th December 2007 ===
A new update adds Levia's GroupBox to the trunk. Thanks to Levia!

=== New CEGUI SVN trunk update by ''' [[User:fjeronimo|fjeronimo]] 30th November 2007 ===
A new update that adds RTTI info to debug builds and performs some logger modifications has been committed to the CEGUI SVN trunk.

More details can be found in the following [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=2816/ forum entry].

=== New CELayoutEditor SVN trunk update by ''' [[User:fjeronimo|fjeronimo]] 22th November 2007 ===
A new update that includes important bug fixes and internal changes that increase performance and code quality has been committed to the CELayoutEditor SVN trunk.

More details can be found in the following [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=2811/ forum entry].

=== New CEGUI SVN trunk update by ''' [[User:fjeronimo|fjeronimo]] 10th November 2007 ===
A new update that adds type, file name and line number to all thrown exceptions has been committed to the CEGUI SVN trunk.

More details can be found in the following [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=2799/ forum entry].

=== New developments by ''' [[User:Scriptkid|Scriptkid]] 06th November 2007 ===
Starting a few weeks ago, new development is being done on CEGUI, mainly on its tools. User [[User:fjeronimo|fjeronimo]] has made some valuable modifications already. Besides that, we are moving through the Mantis list and verifying+fixing bugs. We will keep you up-to-date regarding these matters.

=== Release of 0.5.0b source packages by [[User:CrazyEddie|CrazyEddie]] 28th November 2006 ===
We have issued new versions of the 0.5.0 source packages - the previous ones were missing the files for the Microsoft Direct3D based renderer modules, the packages contain no other changes Thanks go to dmail for raising this issue.

=== Release of 0.5.0b binary packages for Win32 by [[User:CrazyEddie|CrazyEddie]] 14th November 2006 ===
The Win32 binary dependency and SDK packages released on the 6th contained an inconsistency related to the [[SILLY]] library. Today I have issued a new set of binary packages which have been fixed - the new version is known as 0.5.0b, and contains no other changes. Many thanks to forum member vasmann for alerting me to the issue.

=== Release of 0.5.0 stable by [[User:CrazyEddie|CrazyEddie]] 6th November 2006 ===
It has been almost a year in the making, but it is finally here! The CEGUI development team is immensely proud to announce the release of Crazy Eddie's GUI System 0.5.0 - the first stable release of code in the 0.5.x series.

There are pretty vast changes in this release from the previous stable (0.4.1) - many of these changes are breaking, so please agian review [[Changes and Porting Tips for 0.5.0|Release Notes 0.5.X]] to see details of most of these changes.

This release consists of various files that you may need, depending on your usage of the system. We are providing source packages, documentation packages, dependency packages, and binary SDK packages (for VC7.1 and VC8).

To coincide with this release, we are also happy to announce a stable 0.1.0 release of Simple Image Loading LibrarY (SILLY), and the 0.5.0 release of the CELayoutEditor. Please see the [[Downloads|downloads page]] for full details.

=== CEGUI 0.5.0 Release Candidate 2 by [[User:Dalfy|Dalfy]] 13 august 2006 ===
We are pleased to announce the second release candidate of the 0.5 branches of CEGUI. There has been a lot of changes between 0.4.1 and 0.5.0. They are listed in [[Changes and Porting Tips for 0.5.0|Release Notes 0.5.X]]. Please have a try at it and help us get a final release soon. Check the download page.

=== CEGUI 0.5.0 Release Candidate 1 by [[User:Dalfy|Dalfy]] 20 June 2006 ===
We are pleased to announce the first release candidate of the 0.5 branches of CEGUI. There has been a lot of changes between 0.4.1 and 0.5.0. They are listed in [[Changes and Porting Tips for 0.5.0|Release Notes 0.5.X]]. Please have a try at it and help us get a final release soon by sending a lot of bug report in Mantis bug tracker. The download page for CEGUI-0.5.0-RC1 contains some typos but most link are already valid and mirrored on sourceforge. The link on the download page are going to be fixed during the day.

For any question regarding this release you can use either the forum either irc.

=== Migration to Subversion by [[User:CrazyEddie|CrazyEddie]] 11:13, 3 April 2006 (PDT) ===
We have taken the decision to migrate the code for main CEGUI Mk-2 library and the CELayoutEditor tool from using the CVS revision control system, over to Subversion (SVN). If you're using the stable releases, this will not affect you at all. If you're using code out of some branch of CVS, then you will need to switch to SVN instead - we will not be maintaining both repositories. You will find that for general usage, CVS and SVN are similar, and have similar commands. For Windows users, we heartily recommend the use of [http://tortoisesvn.tigris.org/ TortoiseSVN].

For full details of how to obtain the source code from the subversion repository, please see the page [[Obtaining the library source from Subversion|HOWTO: Obtain the library source from subversion]]

All 'ceguiaddons' projects will continue to use CVS for revision control.

=== Site Moved (again) ===
We have now moved the site back to the sourceforge servers, and made a few changes as to the way the site is handled in general - as you have probably noticed!

Basically the main 'content' areas of the site are now entirely wiki based, and we also have a few other bits installed to handle certain requirements where the wiki is less suited to the task.

The features of the new site are:
* Wiki based system for all main site content
* phpBB2 being used for community forums
* Coppermine based gallery
* Mantis for all bug and feature tracking
* Single, unified, log-in for all site areas

Changes and Porting Tips for 0.5.0

2011-03-04T14:34:29Z

Capek: SILLY interlinks

{{VersionBadge|0.4}}

Note that this is incomplete, work in progress, documentation.

= Release =

* 0.5.0 stable Released on November the 6th 2006: [[CEGUI Downloads 0.5.0|goto download page]]
* 0.5.0 RC1 Released on June the 20th 2006: [[Downloads 0.5.0-RC1|goto download page]]
* 0.5.0 RC2 Released on August the 13th 2006: [[Downloads 0.5.0-RC2|goto download page]]

= ChangeLog =
<pre>
Release 0.5.0 (Final)
=====================
Added: TaharezLook was missing ItemListbox and ListboxItem windows & skin
definitions.
Added: Partial CEGUI support for MingW. It is now possible to build CEGUI under
mingw with support for OpenGL renderer. This approach is going to be generalized
later to the other renderer and wiki page explaining the process will follows.
Added: Missing functions in WindowFactoryManager Lua bindings. Incomplete
FalagardWindowMapping binding as well.
Added: Lua binding for OutStream: FileStream (minimal std::ofstream).
Added: XML writing function in Lua bindings.
Added: --enable-debug in configure script instead of using CPPFLAGS=-DDEBUG
./configure ...
Added: premake files for Minesweeper sample and minor fixes to make it run in
windows.
Added: the minesweeper demo
Added: missing doxyfile in order to be in make dist
Added: ScrollablePane sample

Removed: Empty Font 'implData' header files we no longer use.
Removed: [[Falagard]] skinning manual is now a part of the CEGUI manuals
sub-project, so is no longer included here as a pdf.

Modified: Changed Demo7 to use the layout XML file instead of hard-coded window
creation.
Modified: Demo7Window.layout now uses the new ItemListbox, with items defined
within the layout, as the Listbox as opposed to the old style list with
hard-coded items.
Modified: Win32CEGuiRendererSelector:
- It is now possible to navigate to the Combobox via keyboard.
- First available renderer is pre-selected into the dialog.
- With a single renderer available, it is auto-selected and dialog is not shown.
Modified: Changed compile order under autotools so CEGUIBase is made before
things that use it - related to forthcoming cross-compile support.
Modified Added some missing bits and a whole load of other stuff to 'make dist'
to ease a more unified approach to creating packages for the various platforms.
Modified: Renamed tolua++bin/remake_pkg..bat to remove extra period
Modified: Changed Russian text in FontDemo sample - the old text apparently
potentially offensive. Thanks to 'Sanya' for the updated text.
Modified: The RefCounted template now has the CEGUIEXPORT macro as it avoids
warnings in client code when using MSVC.
Modified: Promote Expat to be the second prefered parser under linux in order to
act the same under linux and Win32. Note that the prefered parser is still
Xerces. The parser order is now the following : Xerces, Expat, Libxml, TinyXML.
Modified: WidgetComponent had a nasty misspelling of 'Alignemnt'.
Modified: MSVC no longer uses CEGUIConfig.h and CEGUISamplesConfig.h for
anything
Modified: Premake scripts are now much more flexible.

Coding Standards: Removed various occurrences of the NULL macro.

Docs: Added note to docs for Spinner regarding the lame state of floating point
support.

Bug Fix: ListHeader settings for sizing, moving, and clicking were not properly
set on newly created segments.
Bug Fix: Resolved issue where the algorithm that ensured font textures were
filled would actually end up trying to render every glyph within a font.
Bug Fix: ItemListBase::insertItem was not setting the ItemEntry::d_ownerList
member correctly.
Bug Fix: Added another 'special case' to Spinner::getValueFromText to support
typing an initial decimal point.
Bug Fix: Sometimes compound widgets did not get their components layed out
properly when adding the widget to its parent.
Bug Fix: The way in which properties would set a window to use the DefaultFont
was incorrect; it explicitly set it to the name of the current default, as
opposed to a 'floating default'.
Bug Fix: FontDim did not work correctly since re-calculation of the layout was
not triggered in response to the font being changed. Added this code to
Window::onFontChanged - although more elegant / selective solutions might be
considered later on.
Bug Fix: Added code so that all windows using default font get notified of a
change in the default via the normal channel (Window::onFontChanged).
Bug Fix: There was an issue regarding auto-repeat of mouse button down events
not getting their state reset if the mouse button was released outside of the
window getting the auto-repeat events.
Bug Fix: CEGuiSample.cpp did not get all required includes with certain renderer
combinations.
Bug Fix: Range emplyed by FreeTypeFont::rasterize was exclusive of the start
element; first glyph of every page loaded was missed!
Bug Fix: CEGUI::Window did not properly clean-up a custom tooltip if it created
one.
Bug Fix: Calculation of number of glyph pages in Font::setMaxCodepoint was
incorrect.
Bug Fix: When the OpenGL renderer was disabled by ./configure, the [[SILLY]] codec
was still being built.
Bug Fix: When the OpenGL renderer was disabled by ./configure, the requirement
for a default ImageCodec was still enforced.
Bug Fix: case of included file in Win32CEGuiRendererSelector.cpp changed ready
to support cross-compiling in post 0.5.0 versions.
Bug Fix: Support was broken in the Samples framework for newer versions of Ogre.
Bug Fix: The cegui_reldim and cegui_absdim macros were missing the CEGUI
namespace qualifier.
Bug Fix: When a glyph failed to load in FreeTypeFont, although we logged the
error we did not work around the issue of the missing glyph image, so a seg
fault was generated upon attempted use of those missing images. This addresses
the issue by creating dummy images for missing font glyphs which use a zero
size. Mantis #0000125.
Bug Fix: RefCounted would call AddRef when the wrapped pointer and its counter
were null.
Bug Fix: Event::ScopedConnection would call members of BoundSlot using a
potentially null RefCounted pointer.
Bug Fix: In C++ a namespace does not have a semicolon after the closing brace.
Bug Fix: Nasty memory leak in DevIL image codec. thanx to mafm on IRC.
Bug Fix: fixed a small error in the comment of CEGUI_DECLARE_WINDOW_FACTORY
Bug Fix: Tab control did not require to hear about multi-clicks on the
TabControl scroll buttons. Patch from zap. Mantis #0000117.
Bug Fix: Issue with utf8 missing conversion in TinyXML and libXML
Bug Fix: Added missing public visibility specifier to ScopedConnection class
members.
Bug Fix: premake files were not enabling Xerces correctly in the samples.
Bug Fix: TabControlDemo layout split up. We dont allow multiple root windows in
a layout when using a validating XML parser.
Bug Fix: Falagard.xsd was missing new type attribute for PropertyDim.
Bug Fix: PropertyLinkDefinition was not writing XML properly (no base class
writing).
Bug Fix: Bugs in [[Falagard]] XML writing.
Bug Fix: Spinner would throw an exception when a lone minus sign was entered.
Mantis ticket #110.
Bug Fix: Input capture bug that broke Combobx - introduced by patch #82.
Bug Fix: ScrollablePane would cause exceptions on destruction. Mantis ticket
#83.
Bug Fix: a bug in the premake improvements where samples would not generate
properly.
Bug Fix: A number of CEGUI exceptions were being caught by value instead of
reference.
Bug Fix: OpenGL renderer now also disables texture coordinate generation.
Bug Fix: Irrlicht sample driver now quits on the escape key like the rest.
Bug Fix: Updates and fixes to resolve the NPOT texture source data issue (mantis
#45) in a relatively consistent way - at least for the 0.5.x releases.

Release 0.5.0-RC2
=================
Added: single colour support to PropertyHelper::stringToColourRect
Added: missing support to Irrlicht renderer for creating a texture with a given size.
Added: Updates to renderers for D3D8.1 and D3D9 to report correct values for 'original' size and actual texture size. (Related to Mantis ticket #45).
Added: Support for using user defined image codec by name (using dso) or directly throught a pointer to an existing image codec.
Added: Long property export (allows for properties containing multiple lines).
Added: Helper methods to Window to return EventSet::Iterator and PropertySet::Iterator objects.
Added: Reworked TabControl by zap. Mantis #82.
Added: TabControlDemo sample. Mantis #82.
Added: Danish language in the FontDemo sample.
Added: Output of summary of configure results (for configure based builds)
Added: Texture extra size information to CEGUI::Texture in order to be able to handle scaled/stretched textures within Imageset.
Added: Texture Scaling support in IrrlichRenderer

Removed: Empty source file CEGUIVector.cpp
Removed: TabPane files.

Modified: Behaviour of Editbox so that EventCharacterKey events are only marked as handled if the key press actually resulted in a change to the Editbox text string. (Related to Mantis #59)
Modified: Replaced all getWindow<something> with get<something>
Modified: Replaced all setWindow<something> with set<something>
Modified: EventSet::EventIterator now known as EventSet::Iterator
Modified: PropertySet::PropertyIterator now known as PropertySet::Iterator
Modified: ImageCodec modules are now DynamicModule
Modified: [[Falagard]] PropertyDim now supports a type attribute for UDim properties. Mantis #82.
Modified: Improved TabControl imagery. Mantis #82.
Modified: autotools makefiles now symlink the sample binaries (to avoid having to do 'make install'). Mantis #82.
Modified: PropertyHelper now uses snprintf instead of std::ostringstream again. Mantis #82.
Modified: Removed static Makefile for tolua++cegui generator tool and switched to autotools style build, with enable/disable configure option, for tolua++cegui generator tool
Modified: Moved tolua++ into its own dir, removed lua_and_tolua++
Modified: Externalised our use of the Lua library
Modified: premake updates
Modified: Updated AUTHORS file.
Modified: Remove exec file attribute on Falagard.xsd
Modified: XMLRefSchema/Font.xsd for font rewrite
Modified: LuaScriptModule public headers no longer need include lua.h included.
Modified: Made a bunch of warnings go away in MSVC in the new font code.
Modified: Deleted the remaining old msvc project files.

Bug Fix: Clean the XMLSerialization code: remove empty autowindow
Bug Fix: Added missing glDisable(GL_FOG); in gl renderer
Bug Fix: Irrlicht and D3D8.1 renderer modules would keep live pointers to Texture objects that failed to fully initialise (file or size errors for example) Mantis #43.
Bug Fix: Disable texture stages we do not use in Direct3D renderers. (Mantis #95)
Bug Fix: Mouse cursor z value. Mantis #49
Bug Fix: Imagset XML attribute for image file name is 'Imagefile' and not 'Filename'.
Bug Fix: normal attributes use 'true', only properties sometimes use 'True'.
Bug Fix: Global default resource group was not being used by DefaultResourceProvider.
Bug Fix: XML output from CEGUI::Image class.
Bug Fix: Imageset scaling issue when renderer automatically scales the image #45 (this is currently a partial fix)
Bug Fix: IrrlichtRenderer - Mouse event error. Mantis #98.
Bug Fix: IrrlichtRenderer - size error in addQuad. Mantis #99.
Bug Fix: IrrlichtRenderer - Sample driver had linker lib name wrong for renderer module. Mantis #100.
Bug Fix: TinyXMLParser bug. Mantis Tracker #57
Bug Fix: a bug in the openglrenderer cleanup related to image codec.
Bug Fix: Install renderer module includes at the same place as in Win32 (linux / mac autotools)
Bug Fix: OpenGL sample driver did not inject middle mouse up (injected it as down). Mantis #82.
Bug Fix: Corrected some mistakes in the [[Falagard]] Lua bindings
Bug Fix: Apparently in some cases OpenGLRenderer needs NOMINMAX in Win32 (Mantis #63)
Bug Fix: FreeTypeFont did not free the font data properly, also fixes a potential infinite loop in FreeTypeFont (Mantis #60)
Bug Fix: FairChar font texture was not power of 2 (Mantis #64)
Bug Fix: SliderThumb incorrectly mapped in some schemes (mantis #88)
Bug Fix: Updated Irrlicht renderer to work with 0.5.0 codebase.
Bug Fix: some missing data
Bug Fix: DirectX 8.1 sample driver
Bug Fix: some missing files in the make dist command (Mantis #89)
Bug Fix: Change the name of an enumeration value in schema Font.xsd.
Bug Fix: Memory leak in Font.
Bug Fix: Lua bindings was missing ImagesetManager::createImagesetFromImageFile + some missing tolua_throws modifiers

== Release 0.5.0-RC1 ==
Various internal code cleanups:
- Removal of unrequired utf8* casts on string literals.
- Removed use of NULL macro from the library code.
- Code refactorings to Font class. Removes some instances of repeated code, and makes
some methods shorter / cleaner.
- Split large methods in Scheme into smaller, more managable, chunks.
- Removed all the System constructor overloads and replaced with a single method.
- Removed string literals for component widget names which were scattered throughout t
he widget code.
- Replaced virtually all member fields holding pointers to component widgets with gett
er methods (which basically allows those widgets to be replaced without the parent kno
wing or caring).
- Refactoring of XML handler to remove huge if/else if/else construct.
- Refectored large if / else if / else constructs in all non-falagard XML handlers to
use a member function for each element type (rather than having all code in one huge f
unction).
- Event system has been rewritten from scratch.
- Font system has been rewritten.

Added "PushedOff" rendering state for button based widgets and MenuItem.
Added: Ability to rename windows.
Added: CEGUISamplesConfig.h file to allow configuration of samples framework independe
ntly of the main config (saves recompiling everything just to change some sample setti
ng).
Added: FPS readout to OpenGL base app in the samples framework.
Added: "PropertyLinkDefinition" element for [[Falagard]] system.
Added: "controlPropery" attribute to SectionSpecififations under falagard to enable re
nering of section imagery to be controled via a named boolean property.
Added: mouse pass through feature in Window, to ignore mouse events. Nice for making a
DefaultWindow transparent to the mouse regarding picking windows behind it.
Added: MSVC++ auto-linking for Ogre base app in samples framework.
Added: grab/restoreTextures in the OpenGL renderer to cache texture image data, and la
ter restore it.
Added: Abstracted Logger interface to support user created custom loggers. (SF patch #
1414121 by zap)
Added: DefaultLogger implementation (SF patch #1414121 by zap)
Added: page up/down key functionality to MultiLineEditbox (SF patch #1347376 by Dalfy)
Added: small script to recreate the binding generator for tolua++
Added: customized tolua++ binary. For exception handling support in generated binding
code.
Added: missing exception definitions file needed to generate the bindings.
Added: README with instructions on how to generate the bindings.
Added: Documentation for some of the new features in the bundled tolua++ generator.
Added: When subscribing to events from "inside" Lua a self object can be registered as
well to be passed along with the EventArgs.
Added: New WindowRenderer system, replacing previous system where the Window sub-class
controlled the rendering process.
Added: Major update of the LuaScriptModule to support anonymous functions.
Added: Exception handling has been added for some functions.
Added: [[Falagard]] derivatives of DefaultWindow, DragContainer and ItemEntry with minimal
StateImagery.
Added: executeEventHandler now accepts functions that are table fields.
Added: Text node support to both parser (Xerces and TinyXML)
Added: AutoWindow tag to xml layouts to fetch a window created by the look'n'feel or t
he base widget itself.
Added: Window::isAutoWindow member that returns true if the window has "__auto_" in it
s name. (a flag is set in the constructor). It's faster than checking the actual strin
g.
Added: A setting to Window to specify that it should never write XML no matter what if
activated. Tooltips get this set by default by System.
Added: A property ban list to provide a system for mapping which properties should (no
t) be written to XML. In the respective addProperties member functions checks have bee
n added and some properties are banned if we are an auto window.
Added: Default resource group support to Xerces for use when loading schema files.
Added: Default resource group support to ScriptingModule, and implemented its use in
the CEGUILua module.
Added: DynamicModule class to wrap access to a dynamically linked / loaded module.
Added: New dynamic libraries for Xerces, Expat TinyXMLParser, and libxml Parsers.
Added: TextProperty and FontProperty elements for [[Falagard]] text components.
Added: New ItemListBase based ItemListbox widget. For Window based listbox items.
Added: XML Serialization class for all XML writing.
Added: Recursive versions of Window::getChild and isChild by ID. They are called getCh
ildRecursive and isChildRecursive. Reason for the explicit naming is that it's a pretty expensive operation and should not be used unless necessary.
Added: Lots of missing members in the Lua bindings.
Added: setlocale(LC_NUMERIC, "C"); to the System constructor as we depend on this beha
viour.
Added: setVisible member to CEGUI::MouseCursor.
Added: bat files to make it easier for Windows users to regenerate the Lua bindings an
d tolua++cegui.
Added: ImageCodec support to the OpenGL renderer. This allows users to easily write a
custom image loader. TGA, SILLY, DevIL, Corona and FreeImage codecs are supplied.
Added: const version of getDataPtr in RawDataContainer.
Added: premake scripts to generate MSVC solutions.
Added: ClippedContainer for situations where more specialized clipping is required.

Modified: Placed the integrated TinyXML into its own namespace (CEGUITinyXML) to preve
nt clashes in projects using another copy of TinyXML. (Patch #1294002).
Modified: Changed EventSet to operate without needing events to be pre-added, much lik
e GlabalEventSet always did.
Modified: Removal of mass pre-specification of events for all classes using events.
Modified: Cflags to add include dir for CEGUI in CEGUI.pc.in (allows use of <CEGUI/...
> form of include statement).
Modified: The "Lua and tolua++" module has been made a DLL on Windows machines.
Modified: Renamed System::setTooltip to System::setDefaultTooltip (Mantis #1Cool.
Modified: In the lua module, updated Window with casting helpers as member functions.
eg. w:toFrameWindow()
Modified: Removed the Static,StaticText and StaticImage from CEGUIBase and implemented
them in FalagardBase instead.
Modified: Updated to tolua++ 1.0.92
Modified: Moved LuaFunctor into its own files
Modified: Reimplemented the "late binding" effect from the v04 Lua module. In v04 the
function is always looked up by name. In CVS HEAD the actual Lua function is reference
d, but now this will only occur the first time the event is triggered. This means that it's no longer necessary to have a function defined to subscribe it to an event. As l
ong as the function has been created before the event occurs everything will be good S
mile
Modified: Moved subscribeScriptedEvent into ScriptModule to allow more customized scri
pt subscription functionality.
Modified: Made the layout XML handler use subscribeScriptedEvent for Event tags instea
d of subscribeEvent with ScriptFunctor
Modified: Removal of "tolua_outside" stuff that was no longer needed.
Modified: Moved the declaration/definition of base window factories into its own files
.
Modified: Removal of WidgetSets folder, and its contents.
Modified: Removed unnecessary getSingleton and getSingletonPtr from manager classes.
Modified: The script module now throws ScriptException.
Modified: Removal of TextItem as falagard now handles that exclusively.
Modified: Moved all rendering member functions out of base classes an into [[Falagard]] re
ndering classes.
Modified: Removal of virtually all rendering and layout related Window properties from
CEGUIBase - a few are moved to FalagardBase, the rest must be implemented via XML.
Modified: Removal of TaharezLook and WindowsLook modules from the system.
Modified: Removal of MetricsMode system, and all non-unified interface and properties
from Window (and related fixes to other classes).
Modified: Elimination of RenderableElement and derived classes.
Modified: Moved to a C preprocessor macro system for widget module creation.
Modified: Removal of abstract createXXX methods from widget base classes - the looknfe
el system now auto-creates these widgets when specified within the XML.
Modified: Updated to TinyXML 2.4.3 in order to allow CDATA section in XML text node (v
erbatim text)
Modified: GUILayout handler in order to support long value in properties.
Modified: Made the XML writing system aware of falagard when determining property defa
ult values.
Modified: Switched PropertyHelper to use std::ostringstream as the output is much nice
r. Changed property default values to the new format where needed.
Modified: Better error reporting for dynamic module load failures.
Modified: Switched to using external pcre library. Removed embedded copy of pcre.
Modified: Switched system to use dynamic libs for XML parsers with programatically con
figurable default.
Modified: FactoryModule to use DynamicModule.
Modified: Resolved issue with unneeded member qualification (Patch #1454773).
Modified: Made String::ptr a public member.
Modified: The bundled tolua++cegui binding generator will now generate a lua_CEGUI.cpp
that compiles out-of-the-box on Windows
Modified: Removed the DataContainer template class, and made it into just RawDataConta
iner, non templated.
Modified: Optimized FalagardMultiLineEditbox to only cache visible lines when renderin
g.
Modified: Optimized ButtonBase and MenuItem updateInternalState. Mantis #44
Modified: Moved the renderers to their own folder named RendererModules.
Modified: Optimized picking and rendering by caching screen space rectangles.
Modified: Applied zap's rewrite of the Font system. Patch #1508321
Modified: Texture::loadFromMemory now takes a Texture::PixelFormat parameter. RGB and
RGBA are currently required. Fixes Patch #1455523 as well. 3rd party renderer modules
needs to be updated.

Bug fix: OpenGLRenderer was producing errors and not cleaning up state changes properl
y (thanx muhkuh25)
Bug fix: OpenGLRenderer was broken when compiled for x86-64.
Bug Fix: ListboxItem::getOwnerWindow should be const
Bug Fix: ListboxItem::getOwnerWindow should not take a Window* argument.
Bug Fix: Scheme::resourcesLoaded was always returning true.
Bug Fix: PropertyHelper::stringToImage was not handling empty string case.
Bug Fix: Editbox::onCharacter was setting the event as handled even if nothing was don
e.
Bug Fix: Added shift/ctrl/alt support to the OpenGL sample driver (injects LeftXXX)
Bug Fix: The command line renderer selector does no longer ask if there is only one re
nderer available.
Bug Fix: Fixed window resizing for the OpenGL Sample driver.
Bug Fix: fixed const correctness for "String::utf8_stream_len" SF patch #1367423
Bug Fix: Detect "window->addChildWindow(window);" and do nothing instead of actually t
rying.
Bug Fix: Added missing performChildWindowLayout to Scrollbar::onScrollConfigChanged to
allow making a look'n'feel with a thumb that sizes to indicate document size.
Bug fix: const correctness for Window::getLookNFeel
Bug fix: FrameWindow, isTitlebarEnabled and isCloseButtonEnabled were return the oppos
ite of what they should.
Bug Fix: FrameWindow should do relayout if text changes to allow using a fontdim in th
e titlebar dimensions.
Bug Fix: Changing the default mouse cursor in the System object will now update the cu
rsor immediately where appropriate. (Ticket #17).
Bug Fix: Fixed case in StaticText where default text area was always used if frame was
disabled.
Bug Fix: Image offsets were'nt being properly handled for the corners in FrameComponen
t.
Bug Fix: MultiColumnList would always use item string when sorting, instead of vitual
operators on users custom items.
Bug Fix: System::getWindowContainingMouse would return incorrect Window if called from
within Window::EventMouseLeaves handlers.
Bug Fix: Order of static data creation in C++ is unspecified; we can't have globally d
efined static data that relies on other such static data within the same module.
Bug Fix: Falagard/ProgressBar was broken when vertical or reversed-horizontal.
Bug Fix: Corruption of window registry when rename failed (Patch #1450623).
Bug Fix: Initialisation issue with TabControl trying to access child widgets before th
ey are created. (Patch #1391727).
Buf Fix: CEGUI::Window::setModalState(true) removes the modal state from a modal windo
w. Mantis #42
Bug Fix: MultiColumnList getNextSelection bug. Mantis #47
Bug Fix: System subscriber to renderer event but does not unsubscribe on destruction.
Mantis #48
Bug Fix: OpenGL and DirectX9 renderers were not handling error correctly when creating
textures.
Bug Fix: Bug in LuaScriptModule where executeScriptFile did not unload the file data b
uffer correctly in case of an exception (thanks gcarlton).
Bug Fix: A bug in ItemListBase::resetList_impl where calling resetList would crash (th
anks Turtle).
Bug Fix: Typo in TabPane::testClassName_impl ("Tabpane" instead of "TabPane").
Bug Fix: Big Endian inconsistency in CEGUI::colour.
Bug Fix: CEGUI::Window was not detaching the tooltip during destruction. Mantis #38
Bug Fix: FrameWindow was consuming all LeftButton up events. Down events were affected
as well, and now only consume if the event started drag sizing.
Bug Fix: DragContainer would overwrite any new position applied to the DragContainer d
uring the DragDropItemDropped event. Mantis #53
Bug Fix: The OpenGL sample driver could cause a stack overflow. Patch #1507826
</pre>

= Porting Notes =

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

== CELayoutUpgrader ==

[[CELayoutUpgrader]] is a python script that can upgrade XML layout files to the Unified Coordinate System. It should help to ease the porting process.

== 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 co-ordinate types: UDim, UVector2 and URect.

{| cellpadding=2px cellspacing=0
| style="color: #ffffff; background-color: #ff5555; border: solid 1px #000000;" | '''The information in the following section has been updated again since RC1 was issued - early adopters will need to update their code again to use SVN trunk code and the upcoming RC2.'''
|}

* getXPosition, getWindowXPosition, getRelativeXPosition and getAbsoluteXPosition members are replaced with a single getXPosition member returning a UDim.
* getYPosition, getWindowYPosition, getRelativeYPosition and getAbsoluteYPosition members are replaced with a single getYPosition member returning a UDim.
* getPosition, getWindowPosition, getRelativePosition and getAbsolutePosition members are replaced with a single getPosition member returning a UVector2.
* getWidth, getWindowWidth, getRelativeWidth and getAbsoluteWidth members are replaced with a single getWidth member returning a Udim.
* getHeight, getWindowHeight, getRelativeHeight and getAbsoluteHeight members are replaced with a single getHeight member returning a UDim.
* getSize, getWindowSize, getRelativeSize and getAbsoluteSize members are replaced with a single getSize member returning a UVector2
* getRect, getWindowArea, getRelativeRect and getAbsoluteRect members are replaced with a single getArea member returning a URect.
* getMaximumSize and getWindowMaxSize members are replaced with a single getMaxSize member returning a UVector2.
* getMinimumSize and getWindowMinSize members are replaced with a single getMinSize member returnung a UVector2.

* setWidth and setWindowWidth members are replaced with a single setWidth member taking a UDim.
* setHeight and setWindowHeight members are replaced with a single setHeight member taking a UDim.
* setSize and setWindowSize members are replaced with a single setSize member taking a UVector2.
* setXPosition and setWindowXPosition members are replaced with a single setXPosition member taking a UDim.
* setYPosition and setWindowYPosition members are replaced with a single setYPosition member taking a UDim.
* setPosition and setWindowPosition members are replaced with a single setPosition member taking a UVector2.
* setAreaRect, setRect and setWindowArea members are replaced with setArea members accepting the following options:
** Four UDims; specifying x position, y position, width and height.
** Two UVector2s; specifying position and size.
** A single URect defining the area.
* setMaximumSize and setWindowMaxSize members are replaced with a single setMaxSize member taking a UVector2.
* setMinimumSize and setWindowMinSize members are replaced with a single setMinSize member taking a UVector2.

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

=== Font system changes ===

* There's no notion of '''StartCodepoint''' and '''EndCodepoint''', or '''glyph set''' anymore. Font render glyphs on the fly as required: if you ask to display "A" it renders a small subset of glyphs (256 codepoints surrounding the missing glyph usually, but can render extra glyphs out of the range to conserve texture space).
* The Font class is now an abstract class and there are two implementations: FreeTypeFont and PixmapFont.
** FreeTypeFont uses the FreeType library and can display TTF, FON, PCF/BDF, PS fonts (and possibly others). I have ensured that bitmap fonts work, since bitmap fonts should be handled a little different from outline fonts.
** PixmapFont uses an Imageset with the glyphs and can display colorful glyphs (which FreeType cannot due to its grayscale nature). However, it's more primitive, but can be useful for things like logos, loading messages etc.
* The Font class is now a PropertySet, so specialized classes derived from Font can add their own properties (such as PointSize for FreeType fonts which don't have sense for Imageset-based fonts). Here's a list of available properties:
** All font classes: Name, FileName, NativeRes, ResourceGroup, AutoScaled
** FreeTypeFont: PointSize, Antialiased
** PixmapFont: Imageset, Mapping
* Fixed a number of (vertical) font positioning errors: the font wasn't properly centered within its LineAdvance range.
* Added several new fonts: DejaVuSans (taken from the DejaVu project, http://dejavu.sf.net), fkp (a X11 bitmap font from http://artwizaleczapka.sf.net), FairChar (a Imageset-based font which I made from some old GIF file I found on my HD :-).
* A FontDemo sample which shows several properties of the new Font class.

The above changes resulted in some slight changes to the format of the XML .font files:

* GlyphSet, GlyphRange, Glyph sections of the Font are gone
* The possible values of the Type attribute are now:
** FreeType (instead of Dynamic)
** Pixmap (instead of Static)
* The FirstCodepoint and LastCodepoint attributes of the Font section were removed

After you change your .font files as mentioned above, they should work without problems.

=== Iterator Changes ===
* EventSet::EventIterator is changed to EventSet::Iterator
* PropertySet::PropertyIterator is changed to PropertySet::Iterator

=== Convert Point to UVector2 ===

<source lang="cpp">CEGUI::Point(_x, _y)</source>
becomes
<source lang="cpp">CEGUI::UVector2(CEGUI::UDim(_x,0), CEGUI::UDim(_y,0))</source>

To be continued...

[[Category:Manuals]]

Build from source for Linux

2011-03-04T14:34:18Z

Capek: SILLY interlinks

{{VersionBadge|0.5}}

I happened to notice that this article needed to be written and I was about to install CEGUI from source right now, so I thought I'd document the steps I used, in hopes that they may be useful to somebody.

I'm on ubuntu 6.06 (Dapper)<br />

You need:<br />
- A C++ compiler (g++ in my case)<br />
- Linux Makefile<br />

First you need to download the latest source tarball. I think it's a good idea to keep all the libraries you install from source in a directory, so you can re-compile later with different options if you wish. /home/user/Installs in my case.
Move the downloaded tar to your "installs directory" and extract it with:<br />
tar xzf CEGUI-0.5.0b.tar.gz<br />

Enter the CEGUI file:<br />
cd CEGUI-0.5.0/<br />
and type <br />
./configure --help<br />
Scroll up a bit and take a look at the available compile options. Pay special attention to the optional ones, so you can make sure that you get all the features you need.
then type<br />
./configure<br />
If everything worked you should get a summary of the build you are going to make. If you don't get the summary, it's probably because you don't have the libraries CEGUI needs to compile. Make sure you have the _DEVELOPMENT_ libraries installed. If you are not happy with the summary, run configure again and use the options from the help section to tweak it.<br />
Here is what I got.<br />

----

************************************************
* Crazy Eddie's GUI System - Configuration Results Summary
************************************************

* Library Release Version: 0.5.0
*
* Code options:
* Building CEGUI in debug mode: no
*
* Renderer Modules:
* Building OpenGL Renderer: yes
* Building Irrlict Renderer: no
*
* Image Loading Codec Modules (currently for OpenGL Renderer only):
* Building Corona Image Codec: no
* Building DevIL Image Codec: no
* Building FreeImage Image Codec: no
* Building [[SILLY]] Image Codec: no
* Building TGA Image Codec: yes
*
* Default Image Codec will be: TGAImageCodec
*
* XML Parser Modules:
* Building TinyXMLParser: yes
* Building ExpatParser: no
* Building LibXMLParser: no
* Building XercesParser: no
*
* Default XML Parser is: TinyXMLParser
*
* Scripting:
* Building Lua scripting module: no
* Building tolua++cegui generator: no
*
* Samples Framework:
* Building Samples: yes
* GTK2 based dialog for renderer selection: no
* OpenGL Renderer available in samples: yes
* Irrlict Renderer available in samples: no
* Ogre3D Renderer available in samples: no
************************************************

----
the next part is easy, just type 'make' then 'make install'.<br />
In practice you'll need root privileges to install the files, so with ubuntu:<br />
sudo make install<br />
or in gentoo for example:<br />
su<br />
make install<br />
Hope this helps.

Note: If you're in Gentoo or Saboyan, configure might incorrectly detect your C++ preprocessor as "gcc -E", which will cause Irrlicht to fail. If you need Irrlicht, try:
$ CC="g++" ./configure
Enjoy!

[[Category:HowTo]]

Adding ImageSets to the CEGUI LayoutEditor 0.6.X

2011-03-04T00:17:54Z

Capek: Bot-aided spell checker

{{VersionBadge|0.6}}

If you have made your own [[Imageset files|ImageSet]] which you'd like to access from the CELayoutEditor, you need to place it in your corresponding datafiles directory.

To find your directory, open your CELayoutEditor.ini file and look for this line:
<pre>
ImagesetsPath=C:\Program Files\CELayoutEditor 0.6.3b\datafiles/imagesets/
</pre>

(If you don't have an INI file yet, launch the editor at least once. More details can be found in the editor's [[CELayoutEditor Manual|manual]]).

Copy your own Imageset file (including the actual image which it uses!) to that directory and restart the editor. Now it will 'pick it up' automatically, like it does for fonts as well.

Finally, to use an image in the editor, goto the property grid (in the dialog) and use the following format:
<pre>
"set:setName image:imgName"
</pre>
Where 'setName' is equal to the 'name=xxx' part in your XML file, and the image is one of the defined images by name. Just like you'd do in a layout file directly or in code via the 'setProperty' method for images.

[[Category:HowTo]]

Sample code for all Widgets

2011-03-03T23:57:26Z

Capek: Spelling fix

{{VersionBadge|0.5}} {{VersionBadge|0.6}}

This code goes through every widget and demonstrates how to retrieve and set their data as well as some of their particularities. Please post comments or questions on the message board thread for the [http://www.cegui.org.uk/phpBB2/viewtopic.php?p=7967#7967 Widget Galore]

=== Widgets ===

==== General ====
A widget can be enabled/disabled via setEnabled(). Disabling a widget prevents the user from activating it and manipulating its contents. A widget can be hidden/shown via setVisible().

==== Tooltip ====
A Tooltip widget displays text when the mouse has been hovering over a widget for a certain amount of time. This widget requires that time be injected within CEGUI via injectTimePulse().

The graphical aspect (the scheme) of the tooltip can be specified via setTooltip(). The amount of hovering time required to activate the tooltip can be specified via setHoverTime(). The amount of time the tooltip is displayed can be specified via setDisplayTime(). And the fade transition time can be specified via setFadeTime(); this affects both the fade in and the fade out times. The tooltip text of a widget can be specified via setTooltipText(). Please note that some complex widgets are composed of several widgets. In order to have a tooltip text displayed while hovering over any region of the complex widget then every component widget needs to have a tooltip text specified. For example a Spinner widget is composed of an Editbox widget and two Button widgets.

==== StaticText ====
There is no StaticText within CEGUI but type of widget can be obtained via the DefaultWindow class.

The currently displayed text can be specified via setText(). The colour of this text can be specified via the "TextColours" property. The value of this property contains 4 colour definitions: top left, top right, bottom left, and bottom right. Each colour is specified as a two-digit hexadecimal value of the format AARRGGBB (alpha, red, green, blue). The text is aligned vertically via the "VertFormatting" property with a value of TopAligned, BottomAligned, or VertCentred. The text is aligned horizontally via the "HorzFormatting" property with a value of LeftAligned, RightAligned, HorzCentred, HorzJustified, WordWrapLeftAligned, WordWrapRightAligned, WordWrapCentred, or WordWrapJustified.

==== StaticImage ====
There is no StaticImage within CEGUI but type of widget can be obtained via the DefaultWindow class.

The currently displayed image can be specified via the "Image" property. This property takes two parameters, the imageset ("set") and the image name ("image").

==== ProgressBar ====
A ProgressBar widget displays a progression; it does not receive inputs from a user.

The current progress can be specified via setProgress(). Progress can be advanced through steps. The step size can be specified via setStepSize() and a step performed via step(). Progress can be adjusted by a delta value via adjustProgress(). The current progress value can be obtained via getProgress().

==== Button ====
A Button widget displays a text and receives an activation instruction from the user.

The text can be specified via setText().

==== ScrollablePane ====
A ScrollablePane widget displays contents that can be scrolled. Contents can be added via addChildWindow(). When that content exceeds the dimensions of the ScrollablePane then scrollbars appear to allow the use to view and interact with that hidden content.

==== Checkbox ====
A Checkbox widget controls a boolean value; true when checked and false when unchecked. This value can be obtained via isSelected() and specified via setSelected(true) to check or setSelected(false) to uncheck.

==== Spinner ====
A Spinner widget controls a numerical values (float) through an editbox or the use of the increment or decrement buttons.

This value is bounded within a minimum and a maximum by calling setMinimumValue() and setMaximumValue(). The arrow buttons increment or decrement the value by the amount specified with setStepSize(). The numerical value can be displayed in four formats: FloatingPoint, Integer, Hexadecimal, Octal.

The current value is obtained via getCurrentValue() and specified via setCurrentValue().

==== Editbox ====
An Editbox widget controls printable character values; letters, numbers, punctuations, and symbols.

The maximal number of characters that can be specified is bound by setMaxTextLength(). The value can be set to readable only (modifications by users are not allowed) via setReadOnly(true). The value can be masked via setTextMasked() and the default value of * can be modified via setMaskCodePoint().

The current value can be obtained via getText() and specified via setText().

==== Slider ====
A Slider widget controls a numerical value (float) through the position of a "thumb".

This value is bounded within a maximum by setMaxValue(); the minimum value is set to 0.0f. The thumb can be dragged to the desired position or moved by clicking on either side of the thumb. The increment or decrement value is set by setClickStep().

The current value can be obtained via getCurrentValue() and specified via setCurrentValue().

==== Scrollbar ====
A Scrollbar widget controls a numerical value (float) through the position of a "thumb".

This value is bounded within a maximum by setDocumentSize(); the minimum value is set to 0.0f. The thumb can be dragged to the desired position or moved by clicking on either side of the thumb. The increment or decrement value is set by setPageSize(). The arrow buttons increment or decrement the value by the amount specified with setStepSize().

The current value can be obtained via getScrollPosition() and specified via setScrollPosition(). Note that the actual maximum value that the scrollbar will return is set by the following formula: document_size - page_size. Thus, a document of size 100 and a page size of 10 will have a value from 0 to 90.

==== MultiLineEditbox ====
A MultiLineEditbox widget controls printable character values; letters, numbers, punctuations, and symbols.

Unlike the Editbox widget there is no maximal number of characters that can be specified. The value can be set to readable only (modifications by users are not allowed) via setReadOnly(true). Text can be automatically wrapped via a call to setWordWrapping(true).

The current value can be obtained via getText() and specified via setText().

==== RadioButton ====
A RadioButton widget controls a single selection among many choices.

The choices are grouped by calling setGroupID(). Only one RadioButton per group ID can be selected; this widget does not support multiple selection. However it is possible for a choice to possess no decision; initially every RadioButton of a group is unselected.

The currently selected RadioButton can be obtained via getSelectedButtonInGroup(). This RadioButton pointer can then be used to query the ID via getID(), the text (visible label of the RadioButton) via getText(), or user data via getUserData(). A RadioButton can be selected via setSelected(true). Passing false will deselect the RadioButton, potentially making every RadioButton of the group unselected.

==== Listbox ====
A Listbox widget controls either a single selection or multiple selections among many choices. Multiple selections are enabled via setMultiselectEnabled().

The choices are listbox text items (ListboxTextItem) added to the listbox via addItem(). These do not possess a selection indicator by default; one must be specified via setSelectionBrushImage(). The call to ensureItemIsVisible() ensures that the item is visible; the listbox will automatically scroll down if necessary. The text of the ListboxTextItem can be changed via the setText() function. However this new text will not be displayed until you call the Listbox's handleUpdatedItemData() function.

The selected ListboxItem can be obtained via getFirstSelectedItem() and subsequent selections through getNextSelected(). A selection can be specified via setItemSelectState().

It is possible for a Listbox to contain list items that are not simply composed of text. [http://www.cegui.org.uk/wiki/index.php/Create_a_CheckListboxItem CheckListboxItem] demonstrates this advanced feature. Another approach would be to simulate the behavior of a listbox such that each row is composed of various widgets. [[PseudoListbox]] demonstrates this.

==== Combobox ====
A Combobox widget controls a single selection among many choices.

The choices are listbox text items (ListboxTextItem) added to the combobox via addItem(). These do not possess a selection indicator by default; one must be specified via setSelectionBrushImage().

The value of the text within the Editbox can be obtained via getText() and the last selected ListboxItem can be obtained via getSelectedItem(). However there is no guarantee that both are synchronized; typing text within the Editbox will not automatically select the corresponding ListboxItem. Fortunately the reverse is not true; selecting a ListboxItem will place that text within the Editbox. Placing the Editbox in read-only mode with setReadOnly(true) can avoid problems. The current value can be specified via listboxTextItem->setSelected(true) and a setText(itemCombobox->getText()).

==== MultiColumnList ====
A MultiColumnList widget controls controls either a single selection or multiple selections among many choices. Multiple selections are enabled via setSelectionMode(MultiColumnList::RowMultiple).

A MultiColumnList widget may contain a single column or multiple columns. Columns are added via addColumn(), specifying a label, a column ID, and a column width.

Three steps are required to add a row. The first step is to add a new row with addRow(). The second step is to create a ListboxTextItem for each cell of the row and specify the selection indicator via setSelectionBrushImage(). The third step is to add the newly created ListboxTextItem to the MultiColumnList via setItem(), specifying the ListboxTextItem, the column ID, and the row ID.

The selected row can be obtained via getFirstSelectedItem() and subsequent selections through getNextSelected(). This will iterate through every selected cell, returning each selected ListboxTextItem . A selection can be specified via setItemSelectState(); by setting the selection mode to rows (either RowSingle or RowMultiple) you actually only need to select the ListboxTextItem of the first column.

==== TabControl ====
A TabControl widget allows multiple windows to be displayed one at a time, via tab buttons.

Two objects must be created within the Layout Editor to generate a functional tab control. The first is a window of type "TabControl". This will be the parent window of the tab buttons as well as the pages. The second is a window of type "DefaultWindow". This window will be placed within the TabControl (in code via addTab(), not through the Layout Editor) and will specify the contents of a page. Widgets are to be placed within these TabPane via the Layout Editor. The "TabButton" windows are not to be specified via the Layout Editor since they will be automatically created when a TabPane is added to the TabControl.

In this demo the TabControl widget was placed within a FrameWindow. This is not a requirement. It could have just easily been placed alongside the widgets of the other window.

==== Menu & Popup Menu ====

See [[Menu and Popup]]

=== Files ===

==== WidgetGalore.h ====
<source lang="cpp">
#ifndef _WidgetGalore_h_
#define _WidgetGalore_h_

#include "CEGuiSample.h"
#include "CEGUI.h"

class DemoSample : public CEGuiSample
{
public:
bool initialiseSample()
{
using namespace CEGUI;
try
{
// Retrieve the window manager
WindowManager& winMgr = WindowManager::getSingleton();

// Load the TaharezLook scheme and set up the default mouse cursor and font
SchemeManager::getSingleton().loadScheme("TaharezLook.scheme");
System::getSingleton().setDefaultMouseCursor("TaharezLook", "MouseArrow");
if(!FontManager::getSingleton().isFontPresent("Commonwealth-10"))
FontManager::getSingleton().createFont("Commonwealth-10.font");

// Set the GUI Sheet
Window* sheet = winMgr.createWindow("DefaultWindow", "root_wnd");
System::getSingleton().setGUISheet(sheet);

// Load a layout
Window* guiLayout = winMgr.loadWindowLayout("WidgetGalore.layout");
sheet->addChildWindow(guiLayout);

/* Tooltip */
System::getSingleton().setDefaultTooltip("TaharezLook/Tooltip"); // Set the name of the default tooltip
Tooltip* tooltip = System::getSingleton().getDefaultTooltip();
tooltip->setHoverTime(0.5f); // Display the tooltip after the mouse has been hovering over the widget for half a second
tooltip->setDisplayTime(10.0f); // Display for 15 seconds then disappear
tooltip->setFadeTime(1.0f); // Duration of the transition between fully visible and fully invisible
// To set the tooltip text for a window simply call setTooltipText() see staticText for an example

/* StaticText */
DefaultWindow* staticText = static_cast<DefaultWindow*>(winMgr.getWindow("StaticText"));
staticText->setText("Red Static Text");
// Colours are specified as aarrggbb in Hexadecimal
// Where aa is alpha, rr is red, gg is green, and bb is blue
// tl: top left, tr: top right, bl: bottom left, br: bottom right
staticText->setProperty("TextColours", "tl:FFFF0000 tr:FFFF0000 bl:FFFF0000 br:FFFF0000");
staticText->setProperty("VertFormatting", "VertCentred"); // TopAligned, BottomAligned, VertCentred
staticText->setProperty("HorzFormatting", "HorzCentred"); // LeftAligned, RightAligned, HorzCentred
// HorzJustified, WordWrapLeftAligned, WordWrapRightAligned, WordWrapCentred, WordWrapJustified
staticText->setTooltipText("This is a StaticText widget");

/* StaticImage */
ImagesetManager::getSingleton().createImagesetFromImageFile("ImageForStaticImage", "GPN-2000-001437.tga");
DefaultWindow* staticImage = static_cast<DefaultWindow*>(winMgr.getWindow("StaticImage"));
staticImage->setProperty("Image", "set:ImageForStaticImage image:full_image"); // "full_image" is a default name from CEGUIImageset::Imageset()

/* ProgressBar */
ProgressBar* progressBar = static_cast<ProgressBar*>(winMgr.getWindow("ProgressBar"));
progressBar->setProgress(0.25f); // Initial progress of 25%
progressBar->setStepSize(0.10f); // Calling step() will increase the progress by 10%
progressBar->step(); // Advance the progress by the size specified in setStepSize()
progressBar->adjustProgress(-0.05f); // Adjust the progress by a delta value rather than setting a new value through setProgress
float valueProgressBar = progressBar->getProgress(); // initial 0.25f + step 0.10f - adjustment 0.05f = 0.30f

/* Button */
PushButton* btnClose = static_cast<PushButton*>(winMgr.getWindow("btnClose"));
btnClose->setText("Exit");

/* ScrollablePane */
ScrollablePane* scrollablePane = static_cast<ScrollablePane*>(winMgr.getWindow("ScrollablePane"));
ImagesetManager::getSingleton().createImagesetFromImageFile("ImageForScrollablePane", "GPN-2000-001437.tga");
DefaultWindow* staticImageInScrollablePane = static_cast<DefaultWindow*>(winMgr.createWindow("TaharezLook/StaticImage", "StaticImageInScrollablePane"));
staticImageInScrollablePane->setProperty("Image", "set:ImageForScrollablePane image:full_image"); // "full_image" is a default name from CEGUIImageset::Imageset()
staticImageInScrollablePane->setPosition(UVector2(UDim(0.0f, 0.0f), UDim(0.0f, 0.0f))); // Start in the upper left corner
staticImageInScrollablePane->setWidth(UDim(2.0f, 0.0f)); // Twice the width of the parent, the ScrollablePane
staticImageInScrollablePane->setHeight(UDim(2.0f, 0.0f)); // Twice the height of the parent, the ScrollablePane
scrollablePane->addChildWindow(staticImageInScrollablePane); // Add the image to the // Twice the width of the parent, the ScrollablePane
Editbox* editboxInScrollablePane = static_cast<Editbox*>(winMgr.createWindow("TaharezLook/Editbox", "EditboxInScrollablePane"));
editboxInScrollablePane->setPosition(UVector2(UDim(0.0f, 0.0f), UDim(2.1f, 0.0f))); // Start below the image
editboxInScrollablePane->setWidth(UDim(2.0f, 0.0f));
editboxInScrollablePane->setHeight(UDim(0.3f, 0.0f));
scrollablePane->addChildWindow(editboxInScrollablePane);

/* Check box */
Checkbox* checkbox = static_cast<Checkbox*>(winMgr.getWindow("Checkbox"));
checkbox->setSelected( true );
bool valueCheckbox = checkbox->isSelected(); // Retrieve whether it is checked

/* Spinner */
Spinner* spinner = static_cast<Spinner*>(winMgr.getWindow("Spinner"));
spinner->setTextInputMode(Spinner::FloatingPoint); // FloatingPoint, Integer, Hexadecimal, Octal
spinner->setMinimumValue(-10.0f);
spinner->setMaximumValue(10.0f);
spinner->setStepSize(0.2f);
spinner->setCurrentValue(5.2f);
float valueSpinner = spinner->getCurrentValue(); // Retrieve the value

/* Editbox */
Editbox* editbox = static_cast<Editbox*>(winMgr.getWindow("Editbox"));
editbox->setText("Editbox values");
editbox->setMaxTextLength(13); // The trailing 's' will not be displayed
editbox->setReadOnly(false);
editbox->setTextMasked(false);
editbox->setMaskCodePoint(0x002A); // *
String valueEditbox = editbox->getText(); // Retrieve the text

/* Slider */
Slider* slider = static_cast<Slider*>(winMgr.getWindow("Slider"));
slider->setMaxValue(100.0f);
slider->setClickStep(10.0f);
slider->setCurrentValue(20.0f);
float valueSlider = slider->getCurrentValue(); // Retrieve the value

/* Scrollbar (Horizontal) */
Scrollbar* scrollbarHorizontal = static_cast<Scrollbar*>(winMgr.getWindow("HorizontalScrollbar"));
scrollbarHorizontal->setDocumentSize(100.0f);
scrollbarHorizontal->setPageSize(10.0f);
scrollbarHorizontal->setStepSize(1.0f);
scrollbarHorizontal->setScrollPosition(75.0f);
float valueScrollbarHorizontal = scrollbarHorizontal->getScrollPosition(); // Retrieve the scroll position

/* Scrollbar (Vertical) */
Scrollbar* scrollbarVertical = static_cast<Scrollbar*>(winMgr.getWindow("VerticalScrollbar"));
scrollbarVertical->setDocumentSize(100.0f);
scrollbarVertical->setPageSize(10.0f);
scrollbarVertical->setStepSize(1.0f);
scrollbarVertical->setScrollPosition(25.0f);
float valueScrollbarVertical = scrollbarVertical->getScrollPosition(); // Retrieve the scroll position

/* MultiLineEditbox */
MultiLineEditbox* multiLineEditbox = static_cast<MultiLineEditbox*>(winMgr.getWindow("MultiLineEditbox"));
multiLineEditbox->setText("MultiLineEditbox value");
multiLineEditbox->setReadOnly(false);
multiLineEditbox->setWordWrapping(true);
String valueMultiLineEditbox = multiLineEditbox->getText(); // Retrieve the text

/* RadioButton */
RadioButton* radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_A"));
radioButton->setGroupID(1);
radioButton->setID(101);
radioButton->setSelected(true);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_B"));
radioButton->setGroupID(1);
radioButton->setID(102);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_C"));
radioButton->setGroupID(1);
radioButton->setID(103);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_1"));
radioButton->setGroupID(2);
radioButton->setID(201);
radioButton->setSelected(true);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_2"));
radioButton->setGroupID(2);
radioButton->setID(202);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_3"));
radioButton->setGroupID(2);
radioButton->setID(203);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_A")); // Get handle of one radio button from the group
uint valueRadioButtonLetters = radioButton->getSelectedButtonInGroup()->getID(); // Get selected ID
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_3")); // Can obtain the handle of any radio button in the group
uint valueRadioButtonNumbers = radioButton->getSelectedButtonInGroup()->getID();
radioButton->setSelected(true); // Specify which button should appear selected by default

/* Listbox */
Listbox* listbox = static_cast<Listbox*>(winMgr.getWindow("Listbox"));
listbox->setMultiselectEnabled(false);
ListboxTextItem* itemListbox = new ListboxTextItem("Value A", 1);
itemListbox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listbox->addItem(itemListbox);
itemListbox = new ListboxTextItem("Value B", 2);
itemListbox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listbox->addItem(itemListbox);
itemListbox = new ListboxTextItem("Value C", 3);
itemListbox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listbox->addItem(itemListbox);
itemListbox = new ListboxTextItem("Value D", 4);
itemListbox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listbox->addItem(itemListbox);
listbox->setItemSelectState(itemListbox, true);
listbox->ensureItemIsVisible(itemListbox);
uint valueListbox = listbox->getFirstSelectedItem()->getID(); // Retrieve the ID of the selected listbox item

/* Combobox */
Combobox* combobox = static_cast<Combobox*>(winMgr.getWindow("Combobox"));
combobox->setReadOnly(true);
ListboxTextItem* itemCombobox = new ListboxTextItem("Value 1", 1);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
combobox->addItem(itemCombobox);
itemCombobox = new ListboxTextItem("Value 2", 2);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
combobox->addItem(itemCombobox);
itemCombobox->setSelected(true); // Select this item
combobox->setText(itemCombobox->getText()); // Copy the item's text into the Editbox
itemCombobox = new ListboxTextItem("Value 3", 3);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
combobox->addItem(itemCombobox);
itemCombobox = new ListboxTextItem("Value 4", 4);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
combobox->addItem(itemCombobox);
String valueCombobox = combobox->getText(); // Retrieve the displayed text
uint idCombobox = combobox->getSelectedItem()->getID(); // Retrieve the ID of the selected combobox item

/* MultiColumnList */
MultiColumnList* multiColumnList = static_cast<MultiColumnList*>(winMgr.getWindow("MultiColumnList"));\
multiColumnList->addColumn("Col A", 0, UDim(0.32f, 0));
multiColumnList->addColumn("Col B", 1, UDim(0.32f, 0));
multiColumnList->addColumn("Col C", 2, UDim(0.32f, 0));
multiColumnList->setSelectionMode(MultiColumnList::RowSingle); // MultiColumnList::RowMultiple
ListboxTextItem* itemMultiColumnList;
multiColumnList->addRow();
itemMultiColumnList = new ListboxTextItem("A1", 101);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 0, 0); // ColumnID, RowID
itemMultiColumnList = new ListboxTextItem("B1", 102);
//itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
// By commenting the line above a cell does not specify a selection indicator
// selecting that line will show a "gap" in the selection.
multiColumnList->setItem(itemMultiColumnList, 1, 0); // ColumnID, RowID
itemMultiColumnList = new ListboxTextItem("C1", 103);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 2, 0); // ColumnID, RowID
multiColumnList->addRow();
itemMultiColumnList = new ListboxTextItem("A2", 201);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 0, 1); // ColumnID, RowID
itemMultiColumnList = new ListboxTextItem("B2", 202);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 1, 1); // ColumnID, RowID
itemMultiColumnList = new ListboxTextItem("C2", 203);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 2, 1); // ColumnID, RowID
MCLGridRef grid_ref(1, 0); // Select according to a grid reference; second row
multiColumnList->setItemSelectState(grid_ref, true);
ListboxItem* listboxItem = multiColumnList->getFirstSelectedItem();
uint valueColumnA = listboxItem->getID(); // Retrieve the value of the selected item from column A
listboxItem = multiColumnList->getNextSelected(listboxItem);
uint valueColumnB = listboxItem->getID(); // Retrieve the value of the selected item from column B
listboxItem = multiColumnList->getNextSelected(listboxItem);
uint valueColumnC = listboxItem->getID(); // Retrieve the value of the selected item from column C

/* TabControl */
TabControl* winTabControl = static_cast<TabControl*>(winMgr.getWindow("TabControl"));
winTabControl->setTabHeight(UDim(0.15f, 0.0f)); // Make the tab buttons a little bigger
Window* tabPage = winMgr.getWindow("TabPane1");
tabPage->setText("Page 1");
tabPage->setSize(UVector2(UDim(1.0f, 0.0f), UDim(1.0f, 0.0f))); // Size to 100% of its parent, the TabControl
tabPage->setPosition(UVector2(UDim(0.0f, 0.0f), UDim(0.0f, 0.0f))); // Move to the upper left corner of its parent
winTabControl->addTab(tabPage);
tabPage = winMgr.getWindow("TabPane2");
tabPage->setText("Page 2");
tabPage->setSize(UVector2(UDim(1.0f, 0.0f), UDim(1.0f, 0.0f)));
tabPage->setPosition(UVector2(UDim(0.0f, 0.0f), UDim(0.0f, 0.0f)));
winTabControl->addTab(tabPage);

}
catch(Exception &e)
{
#if defined( __WIN32__ ) || defined( _WIN32 )
MessageBox(NULL, e.getMessage().c_str(), "Error initializing the demo", MB_OK | MB_ICONERROR | MB_TASKMODAL);
#else
std::cerr << "Error initializing the demo:" << e.getMessage().c_str() << "\n";
#endif
}

return true;
}

void cleanupSample(void)
{
}
};

#endif // _WidgetGalore_h_
</source>

==== main.cpp ====
<source lang="cpp">
#if defined( __WIN32__ ) || defined( _WIN32 )
#define WIN32_LEAN_AND_MEAN
#define NOMINMAX
#include "windows.h"
#endif

#include "WidgetGalore.h"

#if defined( __WIN32__ ) || defined( _WIN32 )
int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine,int nCmdShow)
#else
int main(int argc, char *argv[])
#endif
{
DemoSample app;
return app.run();
}
</source>

==== WidgetGalore.layout ====
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<GUILayout >
<Window Type="DefaultWindow" Name="Root" >
<Property Name="Text" >1</Property>
<Property Name="InheritsAlpha" Value="False" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0,0},{0,0},{1,0},{1,0}}" />
<Window Type="DefaultWindow" Name="TabPane2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.72875,0},{0.7185,0},{0.97875,0},{0.9685,0}}" />
<Window Type="TaharezLook/StaticText" Name="StaticTextPage2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >In Page 2:</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.06,0},{0.226667,0},{0.415,0},{0.476667,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="EditBoxPage2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.420001,0},{0.22,0},{0.99,0},{0.47,0}}" />
</Window>
</Window>
<Window Type="TaharezLook/FrameWindow" Name="winTabControl" >
<Property Name="Text" >Tab Control Window</Property>
<Property Name="TitlebarFont" Value="Commonwealth-10" />
<Property Name="CaptionColour" Value="00FFFFFF" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.695627,0},{0.2725,0},{0.993122,0},{0.704167,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
<Window Type="TaharezLook/TabControl" Name="TabControl" >
<Property Name="TabHeight" Value="{0,0}" />
<Property Name="TabTextPadding" Value="{0,0}" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.088566,0},{0.174378,0},{0.931404,0},{0.804637,0}}" />
</Window>
<Window Type="TaharezLook/Button" Name="btnOk" >
<Property Name="Text" >Ok</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.128412,0},{0.841464,0},{0.365583,0},{0.926003,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Button" Name="btnCancel" >
<Property Name="Text" >Cancel</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.400429,0},{0.841464,0},{0.637601,0},{0.926003,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Button" Name="btnApply" >
<Property Name="Text" >Apply</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.668224,0},{0.843977,0},{0.905394,0},{0.928516,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
</Window>
<Window Type="DefaultWindow" Name="TabPane1" >
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="ClippedByParent" Value="False" />
<Property Name="UnifiedAreaRect" Value="{{0.72875,0},{0.012178,0},{0.97875,0},{0.262178,0}}" />
<Window Type="TaharezLook/StaticText" Name="StaticTextPage1" >
<Property Name="Text" >In Page 1:</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.06,0},{0.226667,0},{0.415,0},{0.476667,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="EditBoxPage1" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.420001,0},{0.22,0},{0.99,0},{0.47,0}}" />
</Window>
</Window>
<Window Type="TaharezLook/FrameWindow" Name="winWidgets" >
<Property Name="Text" >Dave, it's full of widgets!</Property>
<Property Name="TitlebarFont" Value="Commonwealth-10" />
<Property Name="CaptionColour" Value="00FFFFFF" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.00375,0},{0.143333,0},{0.751248,0},{0.806665,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
<Window Type="TaharezLook/Button" Name="btnClose" >
<Property Name="Text" >Close</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.732397,0},{0.895137,0},{0.976465,0},{0.975697,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Editbox" Name="Editbox" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.62442,0},{0.090471,0},{0.969776,0},{0.153443,0}}" />
</Window>
<Window Type="TaharezLook/Checkbox" Name="Checkbox" >
<Property Name="Text" >Check</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.396859,0},{0.944201,0},{0.453147,0}}" />
</Window>
<Window Type="TaharezLook/Combobox" Name="Combobox" >
<Property Name="Text" >Combo Box</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.090471,0},{0.613522,0},{0.413287,0}}" />
<Property Name="MaxEditTextLength" Value="1073741823" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_A" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >A</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.652856,0},{0.189876,0},{0.704964,0},{0.246164,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_B" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >B</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.707569,0},{0.189876,0},{0.759678,0},{0.246164,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_C" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >C</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.761542,0},{0.189876,0},{0.813651,0},{0.246164,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_1" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >1</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.189876,0},{0.897272,0},{0.246164,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >2</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.245152,0},{0.897272,0},{0.30144,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_3" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >3</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.300429,0},{0.897272,0},{0.356717,0}}" />
</Window>
<Window Type="TaharezLook/HorizontalScrollbar" Name="HorizontalScrollbar" >
<Property Name="PageSize" Value="0" />
<Property Name="StepSize" Value="1" />
<Property Name="OverlapSize" Value="0" />
<Property Name="DocumentSize" Value="1" />
<Property Name="ScrollPosition" Value="0" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.185427,0},{0.613522,0},{0.26206,0}}" />
</Window>
<Window Type="TaharezLook/VerticalScrollbar" Name="VerticalScrollbar" >
<Property Name="PageSize" Value="0" />
<Property Name="StepSize" Value="1" />
<Property Name="OverlapSize" Value="0" />
<Property Name="DocumentSize" Value="1" />
<Property Name="ScrollPosition" Value="0" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.026087,0},{0.090471,0},{0.082106,0},{0.606802,0}}" />
</Window>
<Window Type="TaharezLook/Listbox" Name="Listbox" >
<Property Name="Text" >List Box</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.626634,0},{0.427903,0},{0.876634,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
</Window>
<Window Type="TaharezLook/MultiColumnList" Name="MultiColumnList" >
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.271357,0},{0.816779,0},{0.551507,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
</Window>
<Window Type="TaharezLook/MultiLineEditbox" Name="MultiLineEditbox" >
<Property Name="Text" >
</Property>
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.462498,0},{0.626634,0},{0.706566,0},{0.876634,0}}" />
</Window>
<Window Type="TaharezLook/ProgressBar" Name="ProgressBar" >
<Property Name="StepSize" Value="0.01" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="CurrentProgress" Value="0" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.559296,0},{0.816779,0},{0.608291,0}}" />
</Window>
<Window Type="TaharezLook/Slider" Name="Slider" >
<Property Name="CurrentValue" Value="0" />
<Property Name="MaximumValue" Value="1" />
<Property Name="ClickStepSize" Value="0.01" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.099415,0},{0.090471,0},{0.155434,0},{0.606802,0}}" />
</Window>
<Window Type="TaharezLook/Spinner" Name="Spinner" >
<Property Name="StepSize" Value="1" />
<Property Name="CurrentValue" Value="0" />
<Property Name="MaximumValue" Value="32767" />
<Property Name="MinimumValue" Value="-32768" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.48995,0},{0.944201,0},{0.551507,0}}" />
</Window>
<Window Type="TaharezLook/StaticImage" Name="StaticImage" >
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.732397,0},{0.626634,0},{0.976465,0},{0.876634,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="StaticText" >
<Property Name="Text" >Static Text</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.462498,0},{0.895137,0},{0.706566,0},{0.975697,0}}" />
</Window>
<Window Type="TaharezLook/ScrollablePane" Name="ScrollablePane" >
<Property Name="ContentArea" Value="l:0 t:0 r:0 b:0" />
<Property Name="HorzStepSize" Value="0.1" />
<Property Name="VertStepSize" Value="0.1" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="HorzOverlapSize" Value="0.01" />
<Property Name="UnifiedAreaRect" Value="{{0.019063,0},{0.629399,0},{0.157023,0},{0.879399,0}}" />
<Property Name="VertOverlapSize" Value="0.01" />
<Property Name="HorzScrollPosition" Value="0" />
<Property Name="VertScrollPosition" Value="0" />
</Window>
</Window>
</Window>
</GUILayout>
</source>

[[Category:Manuals]]
[[Category:Update requested]]

File Selection Dialog

2011-03-03T23:56:53Z

Capek: Spelling fix

== Introduction ==
This page list all user contributed dialog. Dialog that can appear in this section includes :
Colour Selection, File Selection and whatever dialog pleased you. Some of this dialog might later became part of CEGUI but since they are user contribution feel free to add your own work here.

== File Selection Dialog ==
[http://www.ogre3d.org/wiki/index.php/CEGUICommonFileDialog File Selection Dialog] on ogre Wiki

[[Category:Uncategorised]]

Create a CheckListboxItem

2011-03-03T23:56:44Z

Capek: Spelling fix

Sometimes you need a list where the items are checkable. The ItemListbox introduced in CEGUI 0.5 accepts all sorts of items, as long as they inherit ItemEntry. I'm going to teach you how to create a CheckListboxItem to put in your list.

== Getting started! ==
I'm assuming you are just using a standard imageset, with a standard scheme (currently TaharezLook and WindowsLook are supported).

We are first going to get started by writing the looknfeel entry. This is the most important part of this tutorial, as its basically 70% of what we need to do to achieve our goal. First of all, this entry has a few states:

# Enabled: How the item looks when the item is enabled.
# Disabled: How the item looks when the item is disabled.
# SelectedEnabled: How the item looks when the item is selected and is enabled.
# SelectedDisabled: How the item looks when the item is selected and is disabled.

== Writing the requirements ==

Open the appriopiate looknfeel file (WindowsLook.looknfeel or TaharezLook.looknfeel), and place this at the bottom (inside the [[Falagard]] tags though!)

''' Our start '''
<WidgetLook name="WindowsLook/CheckListboxItem">
</WidgetLook>

We first need to define a WidgetLook, this is where all the action happens in. It takes one attribute, name. This is simply the name of the widget you are defining. Now we are going to add the states. These states are necessary for the item to respond to certain events. For example, when the item is disabled, the state Disabled is used.

<WidgetLook name="WindowsLook/CheckListboxItem">
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

We define a state via StateImagery. It requires the attribute name which specifies what state its in. Don't worry about Layer for now. Section is always used. This part takes care of actually changing the look. It requires a attribute section, this is actually WHAT to change, in this case the label. TextColour is a simple colour (black), we will define it below. Now as you can see the Enabled state just sets the text colour to black, thats all it does. Same goes for Disabled (remember this is an item, items are not commonly disabled).

Now we are going to take a look at the other two states.

<WidgetLook name="WindowsLook/CheckListboxItem">
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedEnabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedDisabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

These states pretty much speak for themselves altough there are more sections listed. Section not only defines what to change, also defines what needs to be shown. In the Enabled state we dont want it to look like its selected, so there is no selection section. Note that the order of which you put the Sections are also the Z order. In this case we are putting the selection image first, and then text. If we would do it the other way around, we wouldn't see the text.

Now we are going to add the definitions of some colours and property's.

<WidgetLook name="WindowsLook/CheckListboxItem">
<PropertyDefinition name="TextColour" initialValue="FF000000" redrawOnWrite="true" />
<PropertyDefinition name="SelectedTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="SelectionBrush" initialValue="set:WindowsLook image:Background" redrawOnWrite="true" />
<PropertyDefinition name="SelectionColour" initialValue="FF3030FF" redrawOnWrite="true" />
<Property name="Selectable" value="True" />
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedEnabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedDisabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

Our first PropertyDefinition just defines a text for a colour used in the StateImagery sections. Same goes for the other PropertyDefinitions except the SelectionBrush. Instead of defining a colour, it defines a image. In this case it uses the WindowsLook Background image defined in the imageset. Then we got a Property, which simply implies some sort of setting. In this case, we make it a item by adding the Property 'Selectable' and setting it to true as we want it to act like an item.

== Writing the functional parts ==

We now need to add the parts where the background, text and the selection gets drawn. This seems hard, but isn't actually. We are going to start off with a NamedArea. This is required for a listbox item as the listbox needs to know how big the item is to fit it into the list.

<WidgetLook name="WindowsLook/CheckListboxItem">
<PropertyDefinition name="TextColour" initialValue="FF000000" redrawOnWrite="true" />
<PropertyDefinition name="SelectedTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="SelectionBrush" initialValue="set:WindowsLook image:Background" redrawOnWrite="true" />
<PropertyDefinition name="SelectionColour" initialValue="FF3030FF" redrawOnWrite="true" />
<Property name="Selectable" value="True" />
<b><NamedArea name="ContentSize">
<Area>
<Dim type="LeftEdge" >
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge" >
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width" >
<FontDim type="HorzExtent" padding="6" />
</Dim>
<Dim type="Height" >
<FontDim type="LineSpacing" />
</Dim>
</Area>
</NamedArea></b>
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedEnabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedDisabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

I am assuming you know what the basics like the Area, Dim and such. Though FontDim is used to change the size of the item depending on a label. The part we just added now defines the size of the item.
Instead of adding the whole code here again, I'm only showing the additions from now on.

Ok! Now we are going to add the actual Checkbox. This is crucial for our goal, as it allows the item to be checked upon click. We dont have to write the states and all that for the Checkbox, we just use Child! Just place this under our NamedArea and above the first StateImagery.

<Child type ="WindowsLook/Checkbox" nameSuffix="__auto__checkbox">
<Area>
<Dim type="LeftEdge">
<UnifiedDim scale="0" type="LeftEdge" />
<AbsoluteDim value="3" />
</Dim>
<Dim type="TopEdge">
<UnifiedDim scale="0" type="TopEdge" />
</Dim>
<Dim type="Width">
<UnifiedDim scale="1" type="Width" />
</Dim>
<Dim type="Height">
<UnifiedDim scale="1" type="Height"/>
</Dim>
</Area>
</Child>

This adds a WindowsLook/Checkbox to our item. The suffix is necessary to make the name unique. the rest is pretty straight forward - it adds the checkbox on the left side of the item, starting from 3 pixels to make it look smooth.

Now we need a label, this part is simple and I will not spend as much time on clarifying it, it basically explains itself.

<ImagerySection name="label">
<TextComponent>
<Area>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="LeftEdge">
<AbsoluteDim value="18" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="-3" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
</TextComponent>
</ImagerySection>

The TextComponent simply states this this can contain text. The Dim's are just positioning. Note the LeftEdge, the label starts at 18 pixels from the left. This is because the first ~15 pixels are occupied by the checkbox.

Now something important! The selection image.

<ImagerySection name="selection">
<ImageryComponent>
<Area>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
<ImageProperty name="SelectionBrush" />
<ColourProperty name="SelectionColour" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>

Note that we give it the name selection, as used in the StateImagery. The Area part is just positioning and fitting again. The Dim's used there simply make sure the whole item is filled. ImageProperty defines the image to use. We have defined SelectionBrush at the top of our WidgetLook. It simply fills the Area with that image now. ColourProperty colours the image, we have also defined SelectionColour at the top of the WidgetLook. VertFormat and HorzFormat are stretched, if its not stretched, it will only draw one pixel of the image, making it near invisible. Stretching it just makes sure the whole area is covered.

That was it! We wrote our looknfeel entry!!

<WidgetLook name="WindowsLook/CheckListboxItem">
<PropertyDefinition name="TextColour" initialValue="FF000000" redrawOnWrite="true" />
<PropertyDefinition name="SelectedTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="SelectionBrush" initialValue="set:WindowsLook image:Background" redrawOnWrite="true" />
<PropertyDefinition name="SelectionColour" initialValue="FF3030FF" redrawOnWrite="true" />
<Property name="Selectable" value="True" />
<NamedArea name="ContentSize">
<Area>
<Dim type="LeftEdge" >
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge" >
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width" >
<FontDim type="HorzExtent" padding="6" />
</Dim>
<Dim type="Height" >
<FontDim type="LineSpacing" />
</Dim>
</Area>
</NamedArea>
<Child type ="WindowsLook/Checkbox" nameSuffix="__auto__checkbox">
<Area>
<Dim type="LeftEdge">
<UnifiedDim scale="0" type="LeftEdge" />
<AbsoluteDim value="3" />
</Dim>
<Dim type="TopEdge">
<UnifiedDim scale="0" type="TopEdge" />
</Dim>
<Dim type="Width">
<UnifiedDim scale="1" type="Width" />
</Dim>
<Dim type="Height">
<UnifiedDim scale="1" type="Height"/>
</Dim>
</Area>
</Child>
<ImagerySection name="label">
<TextComponent>
<Area>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="LeftEdge">
<AbsoluteDim value="18" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="-3" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
</TextComponent>
</ImagerySection>
<ImagerySection name="selection">
<ImageryComponent>
<Area>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
<ImageProperty name="SelectionBrush" />
<ColourProperty name="SelectionColour" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<StateImagery name="Enabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="label">
<ColourProperty name="TextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedEnabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="SelectedDisabled">
<Layer>
<Section section="selection" />
<Section section="label">
<ColourProperty name="SelectedTextColour" />
</Section>
</Layer>
</StateImagery>
</WidgetLook>

Pfew am I glad thats done.

== Coding our item ==

We have come to the part where we actually try out our new item. We need to do a few things to call this one finished. First, we need to create the CheckListboxItem class. Then we are going to add the window factory to the system. Last but not least is adding the [[Falagard]] mapping. We'll start with the CheckListboxItem class.

==== CheckListItem.h ====
#ifndef _CHECKLISTITEM_
#define _CHECKLISTITEM_
#include <stdio.h>
#include <stdlib.h>
#include <CEGUI.h>
<br />
namespace CEGUI
{
class CheckListboxItem : public ItemEntry
{
protected:
public:
CheckListboxItem(const String &type, const String &name);
virtual ~CheckListboxItem();
static const String WidgetTypeName;
};
CEGUI_DECLARE_WINDOW_FACTORY(CheckListboxItem)
}
#endif

As you can see, this class inherits ItemEntry. This is necessary as its THE thing that makes this item working properly. Pay special attention to '''CEGUI_DECLARE_WINDOW_FACTORY(CheckListboxItem)'''. This tells CEGUI that we are declarating the window.

==== CheckListItem.cpp ====
#include "CheckListItem.h"
<br />
namespace CEGUI
{
CEGUI_DEFINE_WINDOW_FACTORY(CheckListboxItem)
const String CheckListboxItem::WidgetTypeName("CEGUI/CheckListboxItem");
CheckListboxItem::CheckListboxItem(const String &type, const String &name) :
ItemEntry(type, name)
{
}
CheckListboxItem::~CheckListboxItem()
{
}
}

'''CEGUI_DEFINE_WINDOW_FACTORY(CheckListboxItem)''' is quite important here. It tells CEGUI where we are placing the code that comes with the window. As you can see this class is quite empty, you are, of course, free to add anything you like to this class - these are just the mere basics.

Now, there is one more important thing to do. Register this window properly in CEGUI.

namespace CEGUI
{
void bindCEGUI()
{
CEGUI::WindowFactoryManager& wfMgr = CEGUI::WindowFactoryManager::getSingleton();
wfMgr.addFactory(&CEGUI_WINDOW_FACTORY(CheckListboxItem));
wfMgr.addFalagardWindowMapping("WindowsLook/CheckListboxItem", "CEGUI/ItemEntry", "WindowsLook/CheckListboxItem", "Falagard/ItemEntry");
}
}

addFalagardWindowMappings parameters are as follows: Name, Type, LooknFeel, WindowRenderer. Just put this code somewhere in your main file or on another place that you are sure is executed before using our new item. Also note, in order to use '''CEGUI_WINDOW_FACTORY()''' you need to be in the CEGUI namespace.

'''Example'''

==== main.cpp ====
#include <stdio.h>
#include <stdlib.h>
#include "SDLLoader.h"
#include "CheckListItem.h"
void doStuff();
<br />
namespace CEGUI
{
void bindCEGUI()
{
CEGUI::WindowFactoryManager& wfMgr = CEGUI::WindowFactoryManager::getSingleton();
wfMgr.addFactory(&CEGUI_WINDOW_FACTORY(CheckListboxItem));
wfMgr.addFalagardWindowMapping("WindowsLook/CheckListboxItem", "CEGUI/ItemEntry", "WindowsLook/CheckListboxItem", "Falagard/ItemEntry");
}
}
int main (int argc, char **argv)
{
SDLLoader sdl;
sdl.init();
CEGUI::bindCEGUI();
doStuff();
sdl.main_loop();
return 0;
}
<br />
void doStuff()
{
CEGUI::System * m_System = CEGUI::System::getSingletonPtr();
CEGUI::Logger::getSingletonPtr()->setLoggingLevel(CEGUI::Insane);
CEGUI::WindowManager * m_WndMgr = CEGUI::WindowManager::getSingletonPtr();
CEGUI::Window * m_Root = m_System->getGUISheet();
<br />
CEGUI::ItemListbox * lb = (CEGUI::ItemListbox*)m_WndMgr->createWindow("WindowsLook/ItemListbox", "Lol");
lb->setSize(CEGUI::UVector2(CEGUI::UDim(0.3f, 0.0f), CEGUI::UDim(0.3f, 0.0f)));
lb->setPosition(CEGUI::UVector2(CEGUI::UDim(0.1f, 0.0f), CEGUI::UDim(0.1f, 0.0f)));
m_Root->addChildWindow(lb);
<br />
CEGUI::CheckListboxItem * check = (CEGUI::CheckListboxItem*)m_WndMgr->createWindow("WindowsLook/CheckListboxItem", "Test");
check->setText("Test");
lb->addChildWindow(check);
}

As you can see in the main function, the function that registers the window is called before actually creating it. Dont pay any attention to the sdl initiation - it's just my personal test environment.

Congratulations! You have just created a CheckListboxItem. This was a very good practice because you also learned the technique required to write a completely new widget.

Please contact me if you have any question, comments, feedback - anything, email me at [mailto:levia@openfrag.org levia at openfrag dot com].

--[[User:Levia]] 21:10, 5 April 2007 (GMT+1)

[[Category:Tutorials]]

Subversion

2011-03-03T23:55:47Z

Capek: Spelling fix

This page introduce the use of subversion. If you're only intent is to get the files from subversion you should start with [[Obtaining the library source from Subversion]] which help you in getting the file and compiling CEGUI. This page dive deeper in the use of subversion as a standard user as well as a developer of the library itself. This page presents the use of subversion with the command line tool available for windows, mac and linux.

First of all here is some urls to get started with subersion usage :
* Repository url: [https://svn.sourceforge.net/svnroot/crayzedsgui/ https://svn.sourceforge.net/svnroot/crayzedsgui/]
** CEGUI library latest development files url: [https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk]
** CEGUI Layout Editor latest version url: [https://svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk https://svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk]
** Repository browser: [http://svn.sourceforge.net/viewcvs.cgi/crayzedsgui/cegui_mk2/ http://svn.sourceforge.net/viewcvs.cgi/crayzedsgui/cegui_mk2/]

== Glossary ==
* Repository: That's the place storing all the files and revisions. It's hosted by sourceforge. In Subversion respository are identified using urls.
* Working Copy: A working copy is a local view of part of the repository. You can retrieve a local copy using the checkout command. A working copy contains the file as well as a lot of additional information. The size of the working copy is more than twice the size of the file of the project.
* Branches: Subversion does not provides branches concept, however it's possible to organize the project in several branches. The current development branch is known as trunk. The other branches are stored in a folder named .... branches. So a branch in Subversion is just a folder in branches.
* Tags: Subversion does not provides tags concept. Like branches tags are only subfolder of the tags folder.
* Revision: Snapshot of the tree at a given time. Each modification on the tree create a new revision.

== Layout of the repository ==
At this moment there are two projects in the CEGUI repository. The CEGUI library and the layout editor. The repository is organised as follows:
* cegui_mk2 : The cegui library itself
** trunk : The main development stream
** branches : Branches (features testing are prefix with pre-)
** tags: Release of the CEGUI library
* CELayoutEditor : The editor files
** trunk : The main development stream
** branches : Branches
** tags: Release of the editor

== Getting a working copy of the project ==
In order to get the files from the Sourceforge server one can use two commands. Both commands retrieve the files, however the second command excludes you from staying up-to-date or create patches. If you plan to get the sources, create your library, install it and remove them, the second solution is the best for you.
svn checkout url [dest_dir]
svn co url [dest_dir]
or
svn export url [dest_dir]

Using each of these commands you will get you the latest version of any file with url as root tree. You can get files at a particular revision using an additional parameter:
svn checkout/export [-r number] url [dest_dir]. It useful to test older version. There is no named revision in subversion but it's easy to create tags which provides the same features.

== Updating your working copy ==
When you choose 'checkout', you now have a working copy of the library or the editor. You can keep it in sync with the repository at Sourceforge with the following command:
svn update [folder|file]
svn up [folder|file]

== Getting history of modifications ==
In order to get a kind of changelog you can use subversion. Each modification of the repository comes with a text message explaining the last modification. You can get the history of any file or directory of your working copy using:
svn log [url] (remote repository)
svn log [path] (working copy)

== Making change to your working copy ==
There is several change that can be made on subversion repository : adding, removing, renamming and modifying files, adding, removing and renamming directory. A standard work session consists in the following operation.
# Update your working copy
# Make your change
# commit your change

This section focus on the second step of a work session. Files and directory are not handled automatically by subversion you must first explain to subversion that those file must be manage d. This is done using the add command:
svn add source.cpp // Add source.cpp to your local subversion copy
svn add subdir // Add subdir to your local subversion copy as well as all file contained in the repository itself
One of the improvement of subversion compared to CVS is its ability to remove file as well as folder this done by the rm or delete command
svn del source.cpp
Finally you can rename file or directory using the mv command. This command does not allow mass moving like the standard mv command of unix system. rename is an alias of this command.
svn mv source dest

You can use any text editor to edit your files. Subversion will do its best to send on the network only the change you've made to your working copy.

''Must talk about loking facilities here''

== Branching, Tagging, Merging ==
In subversion a branch or a tag is just a folder in the corresponding folders. In order to create a branch one needs to use the copy operation. Copying a complete tree in subversion is cheap. In order to create a branch or tag use the following operation :
svn copy url_source url_dest
I suggest using url of the repository directly. In order to create a branch of CEGUI use :
svn copy https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/branches/v0-5
To create a tag use :
svn copy https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/branches/v0-5 https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/tags/v0-5-0

A final notes on TAG. Nothing prevents someone to make changes on a tag. It's up to the developer to do changes only on trunk and branches.

If you have fixed a lot of bug in a subsystem or want to apply some of the change made to trunk to a specific branch you have to merge. Merging requires a working copy.
svn merge url_from url_to working_copy_path

'' Merging need some improvement ''
'' Need to add some information on conflict''

== Properties ==
Subversion allows one to attach meta information to any file and folder in the repository. Those information are called properties. The table bellow list most interesting properties:

{| border="1"
|-
||'''Name'''||'''Values'''||'''Description'''||'''Files||Directories
|-
||svn:executable||set/unset||Tel whether the file should be made executable or not||yes||no
|-
||svn:mime-type||mime of the file||Tel the mime type of the file. This is use to select the diff algorithm used||yes||no
|-
||svn:ignore||*.o *.lo ...||List file to be ignore by svn command||no||yes
|-
||svn:keywords||Date,Revision,Author,HeadURL,Id||It allows subversion to automatically substitue some field in the file on check out or update||yes||no
|-
||svn:eol-style||native*,CRLF,CR,LF||It allows automatic conversion from one eol style to another||yes||no
|-
||svn:externals||svn url||It allows to create soft link between to subversion repository||no||yes
|-
||svn:needs-lock||set/unset||Tel whether the file must be locked before editing or not||yes||yes
|}
You can also defines your own properties for whatever use you might need them. When one adds a file to subversion it must add the svn:eol-style property to the value native for all text file. It can be made automatically using autoprops facilities of svn.

In order to manipulate properties you can use
svn propset name value url/file
svn proplist url/file
svn propget name url/file
svn propdel url/file
svn propedit name url/file

== Pitfalls ==

== Configuring subversion ==

== External Links ==
* [http://subversion.tigris.org/ Subversion home] (to get the software)
* [http://svnbook.red-bean.com/ Subversion book] (to learn a lot more than what you read in this page)
* [http://tortoisesvn.tigris.org/ TortoiseSVN] (Win32 client, a must)

[[Category:CEGUI Developer Team]]

Features

2011-03-03T23:55:36Z

Capek: Spelling fix

CEGUI's main features are:

* Mature codebase, CEGUI has been around since 2003!
* Multi-platform support - Windows, Linux and Mac OS projects/solutions are available
* Support for both 32bit and 64bit architectures
* Heavily data-driven by using XML files, a generic property system and powerful skinning abilities
* Very flexible, you can code your own widget renderers, use your chosen XML parser, script module, etc...
* UNICODE support - utf8 and utf32 (check the Fonts sample)
* Renderers for OpenGL, DirectX 9, DirectX 10, DirectX 11, Irrlicht, Ogre3D, Crystal Space (provided by the Crystal Space team) and Open Scene Graph (provided by the Open Scene Graph team), DirectFB (experimental). A null renderer is provided as well.
* Clear interface in case you want to write your own renderer
* Several tools, including a Layout- and Imageset editors
* Many wiki pages and useful sample projects
* Commercial products have been developed with CEGUI already. Check the [[Projects Using CEGUI]].

Most important events

2011-03-03T23:55:28Z

Capek: Spelling fix

This article is going to show you the most important and useful events of each widget.

=== Getting started ===
I'm only going to change the initialiseSample function for each widget + adding some others.
==== EventGalore.h ====
<source lang="cpp">
#ifndef _EventGalore_h_
#define _EventGalore_h_

#include "CEGuiSample.h"
#include "CEGUI.h"

class EventGalore : public CEGuiSample
{
public:
bool initialiseSample()
{
try
{
using namespace CEGUI;

WindowManager& winMgr = WindowManager::getSingleton();

// Load the TaharezLook scheme and set up the default mouse cursor and font
SchemeManager::getSingleton().loadScheme("TaharezLook.scheme");
System::getSingleton().setDefaultMouseCursor("TaharezLook", "MouseArrow");
if(!FontManager::getSingleton().isFontPresent("Commonwealth-10"))
FontManager::getSingleton().createFont("Commonwealth-10.font");

// Set the GUI Sheet
Window* sheet = winMgr.createWindow("DefaultWindow", "root_wnd");
System::getSingleton().setGUISheet(sheet);

// Place here the code from the widgets, place functions below this function.

}
catch(CEGUI::Exception &e)
{
#if defined( __WIN32__ ) || defined( _WIN32 )
MessageBox(NULL, e.getMessage().c_str(), "Error initializing the demo", MB_OK | MB_ICONERROR | MB_TASKMODAL);
#else
std::cerr << "Error initializing the demo:" << e.getMessage().c_str() << "\n";
#endif
}
return true;
}
void cleanupSample(void)
{
}
};
#endif // _EventGalore_h_
</source>

==== main.cpp ====
<source lang="cpp">
#if defined( __WIN32__ ) || defined( _WIN32 )
#define WIN32_LEAN_AND_MEAN
#define NOMINMAX
#include "windows.h"
#endif

#include "EventGalore.h"

#if defined( __WIN32__ ) || defined( _WIN32 )
int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine,int nCmdShow)
#else
int main(int argc, char *argv[])
#endif
{
EventGalore app;
return app.run();
}
</source>

=== Widgets ===

==== Window ====

The Window widget is a important baseclass, all widgets inherit this class. It has lots 'n lots of events, where a few are introduced by other widgets, and where many are unimportant. If a event is taken from this Window class, it is mentioned.

* EventDragDropItemEnters - Fired when a drag and drop item floats over the window.
* EventDragDropItemLeaves - Fired when a drag and drop item floats out of the window.
* EventDragDropItemDropped - Fired when the item has been dropped on the window.

==== PushButton ====

The button is a simple, expected widget. It contains only one important event, but we are going to add a few more.

* EventClicked - Fired when the button has been clicked.
* EventMouseEnters - Fired when the mouse enters the widget. Inherited from Window.
* EventMouseLeaves - Fired when the mouse leaves the widget. Inherited from Window.

<source lang="cpp">
PushButton * pushButton = static_cast<PushButton*>(winMgr.createWindow("TaharezLook/Button", "Button1"));
sheet->addChildWindow(pb);
pushButton->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
pushButton->setSize(UVector2(cegui_reldim(0.2f), cegui_reldim(0.08f)));
pushButton->setText("Hey! Come here!");

pushButton->subscribeEvent(PushButton::EventClicked, Event::Subscriber(&EventGalore::onPushButtonClicked, this));
pushButton->subscribeEvent(PushButton::EventMouseEnters, Event::Subscriber(&EventGalore::onMouseEnters, this));
pushButton->subscribeEvent(PushButton::EventMouseLeaves, Event::Subscriber(&EventGalore::onMouseLeaves, this));
</source>
<source lang="cpp">
bool onPushButtonClicked(const CEGUI::EventArgs &e)
{
// Our button has been clicked!
CEGUI::PushButton * pushButton = static_cast<CEGUI::PushButton*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("Button1"));
pushButton->setText("We got clicked!");
return true;
}

bool onMouseEnters(const CEGUI::EventArgs &e)
{
// Mouse has entered the button. (Hover)
CEGUI::PushButton * pushButton = static_cast<CEGUI::PushButton*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("Button1"));
pushButton->setText("Now click!");
return true;
}

bool onMouseLeaves(const CEGUI::EventArgs &e)
{
// Mouse has left the button.
CEGUI::PushButton * pushButton = static_cast<CEGUI::PushButton*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("Button1"));
// Back to its original state!
pushButton->setText("Hey! Come here!");
return true;
}
</source>

==== Listbox ====

The listbox is a very useful listing widget. Only has one important event.

* EventSelectionChanged - Fired when a or another item has been selected.

<source lang="cpp">
Listbox * listBox = static_cast<Listbox*>(winMgr.createWindow("TaharezLook/Listbox", "Listbox1"));
sheet->addChildWindow(listBox);

listBox->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
listBox->setSize(UVector2(cegui_reldim(0.4f), cegui_reldim(0.4f)));

ListboxTextItem * listBoxItem = new ListboxTextItem("Our very first item.", 1);
listBoxItem->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listBox->addItem(listBoxItem);

listBoxItem = new ListboxTextItem("Our second item.", 2);
listBoxItem->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listBox->addItem(listBoxItem);

listBox->subscribeEvent(Listbox::EventSelectionChanged, Event::Subscriber(&EventGalore::onSelectionChanged, this));
</source>
<source lang="cpp">
bool onSelectionChanged(const CEGUI::EventArgs &e)
{
// The selection has changed.
CEGUI::Listbox * listBox = static_cast<CEGUI::Listbox*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("Listbox1"));
// Get the item we selected
CEGUI::ListboxItem * selectedItem = listBox->getFirstSelectedItem();
selectedItem->setText("Oh we got selected!");

return true;
}
</source>

==== Checkbox ====

A checkable item useful for boolean(true or false) 'questions'.

* EventCheckStateChanged - Fired when the checkbox got checked or un-checked.
* EventMouseEnters - Fired when the mouse hovers over the checkbox. Inherited from Window.
* EventMouseLeaves - Fired when the mouse moves out of the checkbox. Inherited from Window.

<source lang="cpp">
Checkbox * checkBox = static_cast<Checkbox*>(winMgr.createWindow("TaharezLook/Checkbox", "Checkbox1"));
sheet->addChildWindow(checkBox);
checkBox->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
checkBox->setSize(UVector2(cegui_reldim(0.4f), cegui_reldim(0.1f)));

// A question where people can only answer yes or no (true or false)
checkBox->setText("Hey! Do you want to be rich?");

checkBox->subscribeEvent(Checkbox::EventCheckStateChanged, Event::Subscriber(&EventGalore::onCheckStateChanged, this));
checkBox->subscribeEvent(Checkbox::EventMouseEnters, Event::Subscriber(&EventGalore::onMouseEnters, this));
checkBox->subscribeEvent(Checkbox::EventMouseLeaves, Event::Subscriber(&EventGalore::onMouseLeaves, this));
</source>
<source lang="cpp">
bool onCheckStateChanged(const CEGUI::EventArgs &e)
{
// Our item has been checked or unchecked, update our item accordingly.
updateCheckbox();
return true;
}

bool onMouseEnters(const CEGUI::EventArgs &e)
{
// The mouse has entered, update the checkbox accordingly.
updateCheckbox();
return true;
}

bool onMouseLeaves(const CEGUI::EventArgs &e)
{
CEGUI::Checkbox * checkBox = static_cast<CEGUI::Checkbox*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("Checkbox1"));
// Reset
checkBox->setText("Hey! Do you want to be rich?");
return true;
}

void updateCheckbox()
{
CEGUI::Checkbox * checkBox = static_cast<CEGUI::Checkbox*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("Checkbox1"));

if (checkBox->isSelected())
{
// Our checkbox is selected, so someone has previously said 'yes'.
checkBox->setText("Click to choose no!");
}
else
{
// Our item is not selected, so someone hasn't done anything yet, or it has been previously
// unchecked.
checkBox->setText("Click to choose yes!");
}
}
</source>
This might confuse at first sight. Let me go through this here, in steps.
* First, our checkbox is created and our mouse remains still.
* Second, the mouse enters the checkbox, updateCheckbox is called. In this case, our checkbox isn't selected by default, so the text becomes 'Click to choose yes!'.
* Third, we click. The onCheckStateChanged function is called, and that function calls updateCheckbox again to instantly change the text again. We have clicked the checkbox, while it wasn't previously checked, this means its checked now. Text becomes 'Click to choose no!'.
* Fourth, we move our mouse away from the checkbox. The onMouseLeaves function is called, where we reset the text to our question.

==== RadioButton ====

Similar to Checkbox, only it can be grouped, and once selected, it cannot be unselected (except when another button has been selected). Note, in this case, both functions are called when you click the unselected radiobutton. This is because one is unselected and one is selected.

* EventSelectStateChanged - Fired when the radiobutton has been selected.

<source lang="cpp">
RadioButton * radioButton = static_cast<RadioButton*>(winMgr.createWindow("TaharezLook/RadioButton", "RadioButton1"));
sheet->addChildWindow(radioButton);

radioButton->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
radioButton->setSize(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
radioButton->setText("Yes");
radioButton->setGroupID(0);

radioButton->subscribeEvent(RadioButton::EventSelectStateChanged, Event::Subscriber(&EventGalore::onButton1SelectChanged, this));
// To make sure the event is fired.
radioButton->setSelected(true);

radioButton = static_cast<RadioButton*>(winMgr.createWindow("TaharezLook/RadioButton", "RadioButton2"));
sheet->addChildWindow(radioButton);

radioButton->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.2f)));
radioButton->setSize(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
radioButton->setText("No");
radioButton->setGroupID(0);

radioButton->subscribeEvent(RadioButton::EventSelectStateChanged, Event::Subscriber(&EventGalore::onButton2SelectChanged, this));
</source>
<source lang="cpp">
bool onButton1SelectChanged(const CEGUI::EventArgs &e)
{
CEGUI::RadioButton * radioButton1 = static_cast<CEGUI::RadioButton*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("RadioButton1"));

if (radioButton1->isSelected())
{
// This one just got selected.
radioButton1->setText("Ok then. Yes it is.");
}
else
{
// This one got unselected. Reset it.
radioButton1->setText("Yes");
}
return true;
}

bool onButton2SelectChanged(const CEGUI::EventArgs &e)
{
// We have chosen no.
CEGUI::RadioButton * radioButton2 = static_cast<CEGUI::RadioButton*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("RadioButton2"));

if (radioButton2->isSelected())
{
// This one just got selected.
radioButton2->setText("Ok then. No it is.");
}
else
{
// This one got unselected. Reset it.
radioButton2->setText("No");
}
return true;
}
</source>

==== Editbox ====

A simple editable box where text can be entered.

* EventTextAccepted - Fired when someone has pressed TAB or RETURN, or when someone has clicked another window.

<source lang="cpp">
Editbox * editBox = static_cast<Editbox*>(winMgr.createWindow("TaharezLook/Editbox", "Editbox1"));
sheet->addChildWindow(editBox);

editBox->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
editBox->setSize(UVector2(cegui_reldim(0.4f), cegui_reldim(0.1f)));
editBox->setText("Edit me!");

editBox->subscribeEvent(Editbox::EventTextAccepted, Event::Subscriber(&EventGalore::onTextAccepted, this));
</source>
<source lang="cpp">
bool onTextAccepted(const CEGUI::EventArgs &e)
{
// Our text has been accepted by either deactivating it or pressing tab or enter.
CEGUI::Editbox * editBox = static_cast<CEGUI::Editbox*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("Editbox1"));
// So we got the text here, do something with it. Lets just..put the text back in reverse order.
CEGUI::String currentText = editBox->getText();

std::string finalString;

CEGUI::String::reverse_iterator ppkNode = currentText.rbegin();
CEGUI::String::reverse_iterator ppkEnd = currentText.rend();

for (; ppkNode != ppkEnd; ++ppkNode)
{
finalString.push_back((*ppkNode));
}
editBox->setText(finalString);
return true;
}
</source>

==== MultiLineEditbox ====

This widget is pretty much the same as editbox, but allows more lines.

* EventTextChanged - Fired when text has been changed. Inherited from window.

This widget doesn't have the event TextAccepted, so you'll need to 'apply' the input by a button for example.

<source lang="cpp">
MultiLineEditbox * multiLineEditbox = static_cast<MultiLineEditbox*>(winMgr.createWindow("TaharezLook/MultiLineEditbox", "MultiEditbox1"));
sheet->addChildWindow(multiLineEditbox);
multiLineEditbox->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
multiLineEditbox->setSize(UVector2(cegui_reldim(0.3f), cegui_reldim(0.3f)));
multiLineEditbox->setText("Now edit me!");

multiLineEditbox->subscribeEvent(MultiLineEditbox::EventTextChanged, Event::Subscriber(&EventGalore::onTextChanged, this));

// This text is going to show the result.
Window * textWindow = winMgr.createWindow("TaharezLook/StaticText", "StaticText1");
sheet->addChildWindow(textWindow);
textWindow->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.5f)));
textWindow->setSize(UVector2(cegui_reldim(0.6f), cegui_reldim(0.1f)));
textWindow->setText("Now edit me!");
</source>
<source lang="cpp">
bool onTextChanged(const CEGUI::EventArgs &e)
{
CEGUI::WindowManager * winMgr = CEGUI::WindowManager::getSingletonPtr();
CEGUI::MultiLineEditbox * multiLineEditbox = static_cast<CEGUI::MultiLineEditbox*>(winMgr->getWindow("MultiEditbox1"));
CEGUI::Window * textWindow = winMgr->getWindow("StaticText1");

textWindow->setText(multiLineEditbox->getText());
return true;
}
</source>
Notice what happens when you enter text on another line though :)

==== FrameWindow ====

This is a window where you usually put your widgets on.

* EventCloseClicked - Fired when the 'X' in the upper right corner is clicked (of the Framewindow).
* EventRollupToggled - Fired when the window gets rolled up, or rolled down.

<source lang="cpp">
FrameWindow * frameWindow = static_cast<FrameWindow*>(winMgr.createWindow("TaharezLook/FrameWindow", "FrameWindow1"));
sheet->addChildWindow(frameWindow)
frameWindow->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
frameWindow->setSize(UVector2(cegui_reldim(0.4f), cegui_reldim(0.4f)));
frameWindow->setText("Our window");

frameWindow->subscribeEvent(FrameWindow::EventCloseClicked, Event::Subscriber(&EventGalore::onCloseClicked, this));
frameWindow->subscribeEvent(FrameWindow::EventRollupToggled, Event::Subscriber(&EventGalore::onRollupToggled, this));
</source>
<source lang="cpp">
bool onCloseClicked(const CEGUI::EventArgs &e)
{
// Someone has clicked the upper right 'X'.

// We don't HAVE to cast to FrameWindow, as the method we are going to use to close the window
// is available in Window, but for the sake of clarity...
CEGUI::FrameWindow * frameWindow = static_cast<CEGUI::FrameWindow*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("FrameWindow1"));
frameWindow->destroy();
// Note: Dont try to delete the pointer.
return true;
}

bool onRollupToggled(const CEGUI::EventArgs &e)
{
CEGUI::FrameWindow * frameWindow = static_cast<CEGUI::FrameWindow*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("FrameWindow1"));

if (frameWindow->isRolledup())
{
frameWindow->setText("Rolled up");
}
else
{
frameWindow->setText("Our window");
}
return true;
}
</source>

==== ProgressBar ====

A progress widget.

* EventProgressDone - Fired when the progress bar reaches 100%(1.0f).
* EventProgressChanged - Fired when the progress changes.
* EventMouseClick - Fired when someone clicked on the window. Inherited from Window.

<source lang="cpp">
ProgressBar * progressBar = static_cast<ProgressBar*>(winMgr.createWindow("TaharezLook/ProgressBar", "ProgressBar1"));
sheet->addChildWindow(progressBar);
progressBar->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
progressBar->setSize(UVector2(cegui_reldim(0.5f), cegui_reldim(0.04f)));

progressBar->subscribeEvent(ProgressBar::EventProgressDone, Event::Subscriber(&EventGalore::onProgressDone, this));
progressBar->subscribeEvent(ProgressBar::EventProgressChanged, Event::Subscriber(&EventGalore::onProgressChanged, this));
progressBar->subscribeEvent(ProgressBar::EventMouseClick, Event::Subscriber(&EventGalore::onMouseClick, this));

Window * resultWindow = winMgr.createWindow("TaharezLook/StaticText", "StaticText1");
sheet->addChildWindow(resultWindow);
resultWindow->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.05f)));
resultWindow->setSize(UVector2(cegui_reldim(0.5f), cegui_reldim(0.06f)));
resultWindow->setText("Lets start progressing!");
resultWindow->setProperty("FrameEnabled", "false");
resultWindow->setProperty("BackgroundEnabled", "false");
</source>
<source lang="cpp">
bool onProgressDone(const CEGUI::EventArgs &e)
{
// The progress bar is full.
CEGUI::Window * resultWindow = CEGUI::WindowManager::getSingletonPtr()->getWindow("StaticText1");

resultWindow->setText("We are done!");
return true;
}

bool onProgressChanged(const CEGUI::EventArgs &e)
{
// The progress changed.
CEGUI::WindowManager * winMgr = CEGUI::WindowManager::getSingletonPtr();
CEGUI::ProgressBar * progressBar = static_cast<CEGUI::ProgressBar*>(winMgr->getWindow("ProgressBar1"));
CEGUI::Window * resultWindow = winMgr->getWindow("StaticText1");

float progress = progressBar->getProgress();
int finalProgress = static_cast<int>(progress*100);
std::stringstream resultStr;
resultStr << "Progress: " << finalProgress << "%";

resultWindow->setText(resultStr.str());
return true;
}

bool onMouseClick(const CEGUI::EventArgs &e)
{
CEGUI::ProgressBar * progressBar = static_cast<CEGUI::ProgressBar*>(CEGUI::WindowManager::getSingletonPtr()->getWindow("ProgressBar1"));
progressBar->setProgress(progressBar->getProgress() + 0.05f);
return true;
}
</source>

==== Slider ====

A widget which accepts input though moving a 'thumb' between a range.

* EventValueChanged - Fired when the slider's thumb has moved one step left or right.
* EventThumbTrackEnded - Fired when the user stops moving the slider's thumb. Handy when a change causes an CPU expensive operation, because now you only catch the 'final' change.

<source lang="cpp">
Slider * slider = static_cast<Slider*>(winMgr.createWindow("TaharezLook/Slider", "Slider1"));
sheet->addChildWindow(slider);
slider->setPosition(UVector2(cegui_reldim(0.1f), cegui_reldim(0.1f)));
slider->setSize(UVector2(cegui_reldim(0.5f), cegui_reldim(0.04f)));
slider->setMaxValue(1.0f);
slider->setClickStep(0.1f);
slider->setCurrentValue(0.5f); // Start half way

slider->subscribeEvent(Slider::EventValueChanged, Event::Subscriber(&EventGalore::onSliderValueChanged, this));
slider->subscribeEvent(Slider::EventProgressChanged, Event::Subscriber(&EventGalore::onSliderChangeEnded, this));

</source>
<source lang="cpp">
bool onSliderValueChanged(const CEGUI::EventArgs &e)
{
// The slider moved.
CEGUI::WindowManager * winMgr = CEGUI::WindowManager::getSingletonPtr();
CEGUI::Slider * slider = static_cast<CEGUI::Slider*>(winMgr->getWindow("Slider1"));
CEGUI::Window * resultWindow = winMgr->getWindow("StaticText1");

std::stringstream resultStr;
resultStr << "Moved to: " << slider->getCurrentValue();

resultWindow->setText(resultStr);
return true;
}

bool onSliderChangeEnded(const CEGUI::EventArgs &e)
{
// The slider stopped moving (user released mouse)
CEGUI::WindowManager * winMgr = CEGUI::WindowManager::getSingletonPtr();
CEGUI::Slider * slider = static_cast<CEGUI::Slider*>(winMgr->getWindow("Slider1"));
CEGUI::Window * resultWindow = winMgr->getWindow("StaticText1");

std::stringstream resultStr;
resultStr << "Moving stopped at: " << slider->getCurrentValue();

resultWindow->setText(resultStr);
return true;
}

</source>

==== Spinner ====

==== MultiColumnList ====

[[Category:Uncategorised]]

Creating a sub image

2011-03-03T23:55:17Z

Capek: Spelling fix

{{VersionBadge|0.5}} {{VersionBadge|0.6}} {{VersionBadge|0.7}}

I found that it might be useful to be able to create a subimage from an image. Say for instance u have a minimap created from a file, and you want to be able to zoom it. For this purpose it's best to use a subimage from the map. Basically this code can be used to complete that task:

<source lang="cpp">
//this function is just called to show the imageloading from a file, and selecting a subpart of the image
void GUIHud::createMMap()
{
//load in a file, replace with your own file
CEGUI::Texture* texture = mGUIRenderer->createTexture("Ground1.bmp");

//create a new imageset with an image that spans the entire texture
CEGUI::Imageset* set = CEGUI::ImagesetManager::getSingleton().createImageset((CEGUI::utf8*)"ExampleImageSet",texture);
set->defineImage("Base",CEGUI::Point(0.0f,0.0f),CEGUI::Size(texture->getWidth(),texture->getHeight()),CEGUI::Point(0.0f,0.0f));

//create a new window for this stuff and link the created image to it
CEGUI::StaticImage* renderTarget = (CEGUI::StaticImage*)CEGUI::WindowManager::getSingleton().createWindow((CEGUI::utf8*)"SEM/StaticImage", (CEGUI::utf8*)"BaseWindow");
renderTarget->setSize(CEGUI::Size(0.3f, 0.4f));
CEGUI::WindowManager::getSingleton().getWindow((CEGUI::utf8*)topElement)->addChildWindow(renderTarget);
renderTarget->setPosition(CEGUI::Point(0.6, 0.6));
renderTarget->setImage(&set->getImage((CEGUI::utf8*)"Base"));

/*this function replaces the image with the new coordinates passed with it, which selects a subimage,
and replaces the given image with the newly created one */
createSubImage("ExampleImageSet","Base",CEGUI::Point(0.0f,0.0f),CEGUI::Size(texture->getWidth()-512,texture->getHeight()-512),CEGUI::Point(0.0f,0.0f));

//should not be necessary, if anything weird appears try redrawing the image
//renderTarget->requestRedraw();
}
//this function replaces the image in the given imageset with the new coordinates that are passed with this function
void GUIHud::createSubImage(CEGUI::String imageSetName,CEGUI::String imageName, CEGUI::Point start, CEGUI::Size size,CEGUI::Point offset)
{
CEGUI::Imageset* curr_imageset = CEGUI::ImagesetManager::getSingleton().getImageset(imageSetName);
CEGUI::Texture* texture = curr_imageset->getTexture();
curr_imageset->undefineImage(imageName);
curr_imageset->defineImage(imageName,start,size,offset);
}
</source>

this code was written with Ogre, but the main lines of it should be clear i think.

[[Category:HowTo]]

XML File formats

2011-03-03T23:53:30Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

* [[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.

[[Category:Manuals]]

Writing CEGUI scripts

2011-03-03T23:53:20Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.4}}
The code on this page is Lua script using the CEGUILua bindings available in CEGUI 0.4.
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]] 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(0.5,0.5)
local pos = CEGUI.Point(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 ==
-- we'll be using the window manager quite alot
local wmgr = CEGUI.WindowManager:getSingleton()

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

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

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

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

item = wmgr: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.

[[Category:HowTo]]

Using CEGUI with SDL and OpenGL

2011-03-03T23:53:11Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.6}} {{VersionBadge|0.5}}
[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:

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

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:

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

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

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

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:

<source lang="cpp">
glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(45.0, 800.0/600.0, 0.1,100.0);
glMatrixMode(GL_MODELVIEW);
glLoadIdentity();
</source>

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

<source lang="cpp">
#include "renderers/OpenGLGUIRenderer/openglrenderer.h"
</source>

It must be created before starting CEGUI.

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

Then the CEGUI::System must be initialised:

<source lang="cpp">
new CEGUI::System(renderer);
</source>

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:

<source lang="cpp">
SDL_ShowCursor(SDL_DISABLE);
</source>

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

<source lang="cpp">
SDL_EnableUNICODE(1);
</source>

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:

<source lang="cpp">
SDL_EnableKeyRepeat(SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);
</source>

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:

<source lang="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();
}
}
</source>

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 and injecting change of window size ===
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''. We also have to tell

Here is what our inject_input function looks like:

<source lang="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 != 0)
{
CEGUI::System::getSingleton().injectChar(e.key.keysym.unicode);
}
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;

}

}

}
</source>

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

'''Mouse Motion''':

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

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.

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

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

<source lang="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);
}
</source>

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

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

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

<source lang="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;
}
}
</source>

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:

<source lang="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;
}
}
</source>

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

<source lang="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;
}
</source>

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

=== Change of window size ===
If the window size changes (e.g. switching to fullscreen mode), we have to tell the openGlRenderer what's the new window size. Otherwise e.g. the Fonts aren't scaled properly. Therefore we add an SDL Event Handler for SDL_VIDEORESIZE and submit the new window size to the openGlRenderer of CEGUI. Also, on a resize the OpenGL context is lost, meaning textures must be reloaded. The OpenGLRenderer provides functions to do this, grabTextures and restoreTextures.

<source lang="cpp">
...
case SDL_VIDEORESIZE:
renderer->grabTextures();
//your resize code here, including the SDL_SetVideoMode call
renderer->restoreTextures();
renderer->setDisplaySize(CEGUI::Size(e.resize.w, e.resize.h));
break;

...
</source>

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

<source lang="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();
}
</source>

The line:

<source lang="cpp">
CEGUI::System::getSingleton().renderGUI();
</source>

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:

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

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

=== The Code ===
To compile under linux:
<code>gcc teste.cpp -I/usr/include/CEGUI/ -lSDL -lGL -lGLU -lCEGUIBase -lCEGUIOpenGLRenderer</code>

This code uses release 0.5.0 of CEGUI.
<source lang="cpp">
/*
* Adapted by: Johnny Souza - johnnysouza.js@gmail.com
* Date: 19/01/07 17:00
* Description: Using CEGUI with SDL and OpenGL
*/

#include <stdio.h>
#include <stdlib.h>

#include <SDL/SDL.h>

#include <CEGUI.h>
/* for release 0.4.X use:
* #include <renderers/OpenGLGUIRenderer/openglrenderer.h>
*/
#include <RendererModules/OpenGLGUIRenderer/openglrenderer.h>

#include <GL/gl.h>
#include <GL/glu.h>

CEGUI::OpenGLRenderer *renderer;

void handle_mouse_down(Uint8 button)
{
switch ( button ) {
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;

case SDL_BUTTON_WHEELDOWN:
CEGUI::System::getSingleton().injectMouseWheelChange( -1 );
break;
case SDL_BUTTON_WHEELUP:
CEGUI::System::getSingleton().injectMouseWheelChange( +1 );
break;
}
}

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

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;

case SDL_VIDEORESIZE:
renderer->setDisplaySize(CEGUI::Size(e.resize.w, e.resize.h));
break;
}
}
}

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

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

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

int main (int argc, char **argv)
{
SDL_Surface * screen;
atexit (SDL_Quit);
SDL_Init (SDL_INIT_VIDEO);
screen = SDL_SetVideoMode (600, 480, 0, SDL_OPENGL);
if (screen == NULL) {
/* Se ainda não der, desiste! */
fprintf (stderr, "Impossível ajustar ao vídeo: %s\n", SDL_GetError ());
exit (1);
}
renderer = new CEGUI::OpenGLRenderer (0, 600, 480);
new CEGUI::System (renderer);
SDL_ShowCursor (SDL_DISABLE);
SDL_EnableUNICODE (1);
SDL_EnableKeyRepeat (SDL_DEFAULT_REPEAT_DELAY, SDL_DEFAULT_REPEAT_INTERVAL);
main_loop();
}
</source>

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

[[Category:Tutorials]]

The Beginners Guide to Falagard skinning - Part II

2011-03-03T23:53:01Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.4}}
{{Series|The Beginners Guide to Falagard|2}}

== Introduction ==
Last time we looked at the essential basics to get something running with Falagard. This is great, but a simplistic look'n'feel for a button is a bit boring. So lets step forward and learn something new.

In this tutorial we will create a look'n'feel for the ''Editbox'' window type. This widget is interactive and uses new parts of the Falagard system, making it an excellent target for another tutorial.

So let's get started...

== Requirements ==
We'll start out by looking at the requirements for the ''Editbox'' window type. Like always, the information we're looking for can be found in the [[Falagard System base widgets reference]].

In there we'll see that the ''Editbox'' is a bit more complex than the ''Button''. But fear not - we'll get through every part of it ;-)

Let's start out with the ''StateImagery'' needed for this widget:
* Enabled
* Disabled
* ReadOnly
* ActiveSelection
* InactiveSelection

Unlike the ''Button'' we don't have any optional states. ''Enabled'' and ''Disabled'' should speak for themselves. ''ReadOnly'' is used when the ''Editbox'' is in read-only mode (easy huh?).

The ''ActiveSelection'' state is somewhat special. It should define what imagery to render for the selection graphics itself when the window is in an activated state (has focus).
''InactiveSelection'' is the same, except it is used when the window is '''not''' active (does'nt have focus).

Besides the ''StateImagery'' needed, a ''Editbox'' also requires a ''NamedArea'' called '''TextArea''' and a ''ImagerySection'' named '''Carat''' (yes, car'''a'''t).
We'll have a much closer look at these later on.

The initial XML (with the parts we know about) looks like this:

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<ImagerySection name="Carat">
</ImagerySection>
<StateImagery name="Enabled">
</StateImagery>
<StateImagery name="Disabled">
</StateImagery>
<StateImagery name="ReadOnly">
</StateImagery>
<StateImagery name="ActiveSelection">
</StateImagery>
<StateImagery name="InactiveSelection">
</StateImagery>
</Falagard>
</source>

We'll fill it out as we go...

== Imagery ==
This look'n'feel will use a frame consisting of 8 different images from our favorite imageset ''MyImages''. Furthermore we'll have a single image stretched to fill the hole in this frame. The images will have names that are easy to interpret:
{| cellpadding="15" border="1"
|+ Frame setup
| TL || align="center" | T || TR
|-
| align="center" | L || Bg|| align="center" |R
|-
| BL || align="center" | B || BR
|}

Each prefixed with '''Editbox'''. Forming imagenames like '''EditboxTL''' etc.

The ''FrameComponent'' tag may only occur inside an ''ImagerySection''. Just like the ''ImageryComponent'' and ''TextComponent'' that we used in part I.

Using the ''FrameComponent'' is very much like using the ''ImageryComponent'' all the tags allowed are the same, but a ''FrameComponent'' allows up to nine images to be specified. It's purpose is to make making frames easy :-)
A ''FrameComponent'' is special in the way it handles formatting compared to ''ImageryComponent'' though. Any formatting options are only applied to the background image - if it's specified. Yes. We don't have to set all nine of them. We can just choose the image "positions" we need. In our case we'll use all of them tough...

Let's look at the XML for this ''FrameComponent'':
<source lang="xml">
<FrameComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image type="TopLeftCorner" imageset="MyImages" image="EditboxTL" />
<Image type="TopEdge" imageset="MyImages" image="EditboxT" />
<Image type="TopRightCorner" imageset="MyImages" image="EditboxTR" />
<Image type="RightEdge" imageset="MyImages" image="EditboxR" />
<Image type="BottomRightCorner" imageset="MyImages" image="EditboxBR" />
<Image type="BottomEdge" imageset="MyImages" image="EditboxB" />
<Image type="BottomLeftCorner" imageset="MyImages" image="EditboxBL" />
<Image type="LeftEdge" imageset="MyImages" image="EditboxL" />
<Image type="Background" imageset="MyImages" image="EditboxBg" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</FrameComponent>
</source>

You should recognise the area. It's the full area of the window, exactly like the areas we used in part I.
Reason: We want the frame and background to cover the entire window. Simple :-)

Nine images are specifed. The order does not matter.
But note that compared to the ''ImageryComponent'' used last time, we must specify a type attribute for the images.
This is so Falagard knows where to place this image in the frame.
These are of course listed in the [[Falagard System XML Enumerations reference]].

The format both horizontally and vertically is ''Stretched''. This ensures that the background image is stretched to fill as much as possible of the "hole" created by the border images (TL,T,TR etc.).

We'll use this frame for all the 3 states (''Enabled'', ''Disabled'', ''ReadOnly''), but we want the colours to be a little different in each state. In part I we created a new property to hold the colour of the Text. To show a different approach, we'll "hard-code" the frame colours into this look'n'feel.

CEGUI supports using a colour rectangle to modulate the colours of anything it renders. This makes it possible to "apply" nice colour gradients to our frame imagery.

The ''Normal'' state will use the colours, unmodified from the image file.

The ''Disabled'' state will use gray to darken the frame imagery

In the ''ReadOnly'' state we'll create a gradient that is white in the top-left corner, and slightly grayish for the three other corners. When applied to the imagery this will result in the top-left corner using exactly the same colours as in the image file, and the three other corners being slightly darkened.

To use this frame component we must - like stated earlier - fit it in a ''ImagerySection''. We'll call this new imagery section "frame".

This is all the we need to write up the xml for this frame, and use it in our states, so now the XML looks like this:

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<b><ImagerySection name="frame">
<FrameComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image type="TopLeftCorner" imageset="MyImages" image="EditboxTL" />
<Image type="TopEdge" imageset="MyImages" image="EditboxT" />
<Image type="TopRightCorner" imageset="MyImages" image="EditboxTR" />
<Image type="RightEdge" imageset="MyImages" image="EditboxR" />
<Image type="BottomRightCorner" imageset="MyImages" image="EditboxBR" />
<Image type="BottomEdge" imageset="MyImages" image="EditboxB" />
<Image type="BottomLeftCorner" imageset="MyImages" image="EditboxBL" />
<Image type="LeftEdge" imageset="MyImages" image="EditboxL" />
<Image type="Background" imageset="MyImages" image="EditboxBg" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</FrameComponent>
</ImagerySection></b>
<ImagerySection name="Carat">
</ImagerySection>
<StateImagery name="Enabled">
<b><Layer>
<Section section="frame" />
</Layer></b>
</StateImagery>
<StateImagery name="Disabled">
<b><Layer>
<Section section="frame">
<Colours topLeft="FF7F7F7F" topRight="FF7F7F7F" bottomLeft="FF7F7F7F" bottomRight="FF7F7F7F" />
</Section>
</Layer></b>
</StateImagery>
<StateImagery name="ReadOnly">
<b><Layer>
<Section section="frame">
<Colours topLeft="FFFFFFFF" topRight="FFDFDFDF" bottomLeft="FFDFDFDF" bottomRight="FFDFDFDF" />
</Section>
</Layer></b>
</StateImagery>
<StateImagery name="ActiveSelection">
</StateImagery>
<StateImagery name="InactiveSelection">
</StateImagery>
</Falagard>
</source>

The frame component has been added, and the ''Enabled'', ''Disabled'' and ''ReadOnly'' states have been set up to use them. The only new thing is really the ''Colours'' tag inside the ''Section'' tags for "frame".

It behaves just like the ''ColourProperty'' tag we used in part I, except you can specify a colour to use for each corner.
It's attributes
* topLeft
* topRight
* bottomLeft
* bottomRight
Each specify a single colour of the same format we used for ''ColourProperty'' (AARRGGBB in hex).

== Text ==
Remeber something about a ''NamedArea''? Either way we're going to look at it now. The ''Editbox'' widget requires us to define a named area so it knows where to render, the text we type in, the caret (the marker that shows us where the characters we type will be inserted) and our selection.

In this look'n'feel, we want the text to be rendered inside our frame. That is we dont want the text to cover the frame imagery itself, only the background of it. Falagard provides a ''ImageDim'' tag that we can use to extract the width and height from the images we used for the frame. Falagard also provides a ''DimOperator'' tag that we can use to do a little math on our dimensions. These features will be the core of our ''NamedArea'' which will be named '''TextArea''' (Stated in the requirements... Remember?)

The only thing we must (and may) specify in a ''NamedArea'' is a ''Area''.

If we take a look back at the ''Area'' tag, we know that it must specify four dimensions. ''LeftEdge'', ''TopEdge'', ''RightEdge'' and ''BottomEdge''. You might remember that we can specify ''Width'' instead of ''RightEdge'', and ''Height'' instead of ''BottomEdge''. But we're not going to do that. Just so you know (and don't forget) ;-)

We start out with a "empty" XML and fill it out as we go. For now it looks like this:

<source lang="xml">
<NamedArea name="TextArea">
<Area>
<Dim type="LeftEdge">
</Dim>
<Dim type="TopEdge">
</Dim>
<Dim type="RightEdge">
</Dim>
<Dim type="BottomEdge">
</Dim>
</Area>
</NamedArea>
</source>

We start out with the left edge. In the frame we used the image named '''EditboxL''' for the left edge. And as the area we want to define is to lie inside the frame, we'll use the width of this specific image as the left edge of our area.
The XML for this ''ImageDim'' is like so:

<source lang="xml">
<ImageDim imageset="MyImages" image="EditboxL" dimension="Width" />
</source>

The top edge is very similar except we'll use the height of the image named '''EditboxT''' instead.

<source lang="xml">
<ImageDim imageset="MyImages" image="EditboxT" dimension="Height" />
</source>

The right edge is a bit more tricky. To start out we'll use a ''UnifiedDim'' that gives us the right edge of our widget.

<source lang="xml">
<UnifiedDim scale="1" offset="0" type="RightEdge">
</Unified>
</source>

We use a seperate tag to close it, as by itself this ''UnifiedDim'' is not good enough. We still need the take the frame into accout. The image dimension we're after is the width of the image '''EditboxR'''. We must subtract this width from the right edge to ensure that the frame imagery is not overwritten by a long text string in the ''Editbox''.

The ''DimOperator'' can do this for us with XML like this:

<source lang="xml">
<UnifiedDim scale="1" offset="0" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxR" dimension="Width" />
</DimOperator>
</Unified>
</source>

The ''DimOperator'' tag requires us to specify the attribute ''op'' with the name of the operation we want to perform as the value. The operations supported by Falagard are:
* Add
* Subtract
* Multiply
* Divide
We used ''Subtract'' to "move back" a little from our right edge to make sure we leave the frame imagery for the right edge alone.

The bottom edge of the area is very similar to the right. There are two differences. First we want the ''UnifiedDim'' to take the bottom edge of our window and not the right edge. Second we want to subtract the height of the image named '''EditboxB''' instead too.

This gives us this XML:

<source lang="xml">
<UnifiedDim scale="1" offset="0" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxB" dimension="Height" />
</DimOperator>
</Unified>
</source>

If we put these four dimensions into our ''NamedArea'' it looks like this:

<source lang="xml">
<NamedArea name="TextArea">
<Area>
<Dim type="LeftEdge">
<b><ImageDim imageset="MyImages" image="EditboxL" dimension="Width" /></b>
</Dim>
<Dim type="TopEdge">
<b><ImageDim imageset="MyImages" image="EditboxT" dimension="Height" /></b>
</Dim>
<Dim type="RightEdge">
<b><UnifiedDim scale="1" offset="0" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxR" dimension="Width" />
</DimOperator>
</Unified></b>
</Dim>
<Dim type="BottomEdge">
<b><UnifiedDim scale="1" offset="0" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxB" dimension="Height" />
</DimOperator>
</Unified></b>
</Dim>
</Area>
</NamedArea>
</source>

This is the complete ''NamedArea'' for our ''Editbox'' look'n'feel. If we fit it inside our full look'n'feel it will look like the XML below. Notice that the ''NamedArea'' is specifed before the ''ImagerySection''. This is required by Falagard.

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<b><NamedArea name="TextArea">
<Area>
<Dim type="LeftEdge">
<ImageDim imageset="MyImages" image="EditboxL" dimension="Width" />
</Dim>
<Dim type="TopEdge">
<ImageDim imageset="MyImages" image="EditboxT" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxR" dimension="Width" />
</DimOperator>
</Unified>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxB" dimension="Height" />
</DimOperator>
</Unified>
</Dim>
</Area>
</NamedArea></b>
<ImagerySection name="frame">
...
... saving space ...
...
</ImagerySection>
<ImagerySection name="Carat">
</ImagerySection>
<StateImagery name="Enabled">
<Layer>
<Section section="frame" />
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="frame">
<Colours topLeft="FF7F7F7F" topRight="FF7F7F7F" bottomLeft="FF7F7F7F" bottomRight="FF7F7F7F" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ReadOnly">
<Layer>
<Section section="frame">
<Colours topLeft="FFFFFFFF" topRight="FFDFDFDF" bottomLeft="FFDFDFDF" bottomRight="FFDFDFDF" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ActiveSelection">
</StateImagery>
<StateImagery name="InactiveSelection">
</StateImagery>
</Falagard>
</source>

We don't reference '''TextArea''' anywhere. Just specifying it is all that is required according to the [[Falagard System base widgets reference]].

== Caret ==
The ''Editbox'' has a caret. This is a marker that shows us where we are typing and allows us to tell if we are inserting in the middle of the text or at the end etc. The text is split around it by CEGUI so we don't draw over the text rendering the point we're editing unreadable. All this is currently handled internally and all you need to do is create a ''ImagerySection'' name '''Carat'''.

note by Pompei2: You're reading right, the ''ImagerySection'' is named '''Carat''' although the right word is a caret.

When CEGUI needs render the caret (and the text) it will fetch this ''ImagerySection'' and render it at the appropriate position in the text.
We do not need to make a ''TextComponent'' in a ''Editbox'' to get the text to render. Because of the pecularities of the caret (and selection which we will handle later) it's all done automatically, by using the ''NamedArea'' '''TextArea''' we just specified along with the real pixel area of the window, to confine rendering to right rectangle on the screen.

Enough details. We just want to render a single image named '''EditboxCaret''' stretched vertically inside the '''TextArea'''.

Creating the ''ImagerySection'' is very much like creating the background for the ''Button'' in part I, the only real difference being the ''Area'' used. We'll look at the XML for this area, it's all made up by stuff we've already seen.

<source lang="xml">
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width">
<ImageDim imageset="MyImages" image="EditboxCaret" dimension="Width" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
</source>

The first and second (left/top edges) ''Dim''s have the familiar ''AbsoluteDim'' with a value of zero. Nothing new here.

The third ''Dim'' on the other hand is new. It's now specified as "Width" and not "RightEdge" like we have done so far. Inside we have a ''ImageDim'' for the width of the caret image we're using. If we had used the regular ''UnifiedDim'', the caret itself would have the width our textarea (because the caret resides in the text area) and would have been very ugly...

The fourth dimension is the familiar ''UnifiedDim'' we have used in all the earlier areas.

We know from part I how to make a ''ImagerySection'' with a ''ImageryComponent''. This is all we need to render this single-image caret. The XML for our look'n'feel is nearing completion.

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<NamedArea name="TextArea">
...
... saving space ...
...
</NamedArea>
<ImagerySection name="frame">
...
... saving space ...
...
</ImagerySection>
<ImagerySection name="Carat">
<b><ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width">
<ImageDim imageset="MyImages" image="EditboxCaret" dimension="Width" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="EditboxCaret" />
<VertFormat type="Stretched" />
</ImageryComponent></b>
</ImagerySection>
<StateImagery name="Enabled">
<Layer>
<Section section="frame" />
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="frame">
<Colours topLeft="FF7F7F7F" topRight="FF7F7F7F" bottomLeft="FF7F7F7F" bottomRight="FF7F7F7F" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ReadOnly">
<Layer>
<Section section="frame">
<Colours topLeft="FFFFFFFF" topRight="FFDFDFDF" bottomLeft="FFDFDFDF" bottomRight="FFDFDFDF" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ActiveSelection">
</StateImagery>
<StateImagery name="InactiveSelection">
</StateImagery>
</Falagard>
</source>

We only specify the vertical formatting for the new ''ImageryComponent'' because we are specifying the area to exactly match the width of the image, and thus any formatting would have no effect. ''LeftAligned'' (the default) is just fine.

Now we just need to do something in the ''ActiveSelection'' and ''InactiveSelection'' states...

== Selection ==
When the user has selected text in the ''Editbox'', either with the mouse or the keyboard, CEGUI render the selection using the two additional states '''ActiveSelection''' and '''InactiveSelection'''.

The the window is active (has focus) it will use the state '''ActiveSelection''', if if does not have focus (inactive) yet still has a selection '''InactiveSelection''' will be used.

For the selection in this look'n'feel, we'll use a single image stretched over the selection area. This image will contain plain white in the image file so we can apply any colour(s) we choose to the selection imagery.
Let's call it '''White'''.

For '''ActiveSelection''' we'll use a classic blue colour, for inactive the same, except we'll make it 50% transparent.
We can avoid a colour tag in the '''ActiveSelection''' state if we specify the colours to use directly in the ''ImageryComponent''. We'll do that to show how it works.

We'll create a new ''ImagerySection'' for this "selection brush" named '''selection'''. XML follows:

<source lang="xml">
<ImagerySection name="selection">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="White" />
<Colours topLeft="FF26458A" topRight="FF26458A" bottomLeft="FF26458A" bottomRight="FF26458A" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
</source>

We use a default area that you should recognise by now. CEGUI will automatically use the right size for the selection.
The image we use is the one called '''White''' from our favorite imageset '''MyImages'''. Like always ;-)
A colour tag has been added as well to make our selection some kind of blue...
The vertical and horizontal formatting is ''Stretched'' which is generally what you would want to do in a situation like this.

We'll "call" this ''ImagerySection'' from the '''ActiveSelection''' and '''InactiveSelection''' states. In the '''InactiveSelection''' state we'll further modulate the colours used by passing a 50% transparent white. This will have the effect of using the same colour as in the active state, but make that colour 50% transparent. We could have just specified the full colour to use in each state and remove the ''Colours'' tag from the ''ImageryComponent'', but I wanted to show that multiple modulations are possible with Falagard.

The states are the last thing missing from the look'n'feel, so let's take a look at the final XML (yay :-P ).

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<NamedArea name="TextArea">
<Area>
<Dim type="LeftEdge">
<ImageDim imageset="MyImages" image="EditboxL" dimension="Width" />
</Dim>
<Dim type="TopEdge">
<ImageDim imageset="MyImages" image="EditboxT" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxR" dimension="Width" />
</DimOperator>
</Unified>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="MyImages" image="EditboxB" dimension="Height" />
</DimOperator>
</Unified>
</Dim>
</Area>
</NamedArea>
<ImagerySection name="frame">
<FrameComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image type="TopLeftCorner" imageset="MyImages" image="EditboxTL" />
<Image type="TopEdge" imageset="MyImages" image="EditboxT" />
<Image type="TopRightCorner" imageset="MyImages" image="EditboxTR" />
<Image type="RightEdge" imageset="MyImages" image="EditboxR" />
<Image type="BottomRightCorner" imageset="MyImages" image="EditboxBR" />
<Image type="BottomEdge" imageset="MyImages" image="EditboxB" />
<Image type="BottomLeftCorner" imageset="MyImages" image="EditboxBL" />
<Image type="LeftEdge" imageset="MyImages" image="EditboxL" />
<Image type="Background" imageset="MyImages" image="EditboxBg" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</FrameComponent>
</ImagerySection>
<ImagerySection name="Carat">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="Width">
<ImageDim imageset="MyImages" image="EditboxCaret" dimension="Width" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="EditboxCaret" />
<VertFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<ImagerySection name="selection">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="White" />
<Colours topLeft="FF26458A" topRight="FF26458A" bottomLeft="FF26458A" bottomRight="FF26458A" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<StateImagery name="Enabled">
<Layer>
<Section section="frame" />
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="frame">
<Colours topLeft="FF7F7F7F" topRight="FF7F7F7F" bottomLeft="FF7F7F7F" bottomRight="FF7F7F7F" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ReadOnly">
<Layer>
<Section section="frame">
<Colours topLeft="FFFFFFFF" topRight="FFDFDFDF" bottomLeft="FFDFDFDF" bottomRight="FFDFDFDF" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="ActiveSelection">
<Layer>
<Section section="selection" />
</Layer>
</StateImagery>
<StateImagery name="InactiveSelection">
<Layer>
<Section section="selection">
<Colours topLeft="7FFFFFFF" topRight="7FFFFFFF" bottomLeft="7FFFFFFF" bottomRight="7FFFFFFF" />
</Section>
</Layer>
</StateImagery>
</Falagard>
</source>

That's it folks. The look'n'feel is done. Hopefully you're starting to play around with the XML and making the look'n'feel suit you (or your artist ;-) ).
Again, feel free to add comments in the discussion page.

Stay tuned for part III...

--[[User:lindquist]] 00:41, 14 Dec 2005 (CET)

[[Category:Tutorials]]

The Beginners Guide to Falagard skinning - Part I

2011-03-03T23:52:51Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.4}}
{{Series|The Beginners Guide to Falagard|1}}

== Introduction ==
The Falagard system in CEGUI 0.4 and up is a powerful tool.
By using it you can make your GUI elements look like you want and not how some coder thought looked cool.
Use Falagard to your advantage and you can do alot of nice things from XML that you might think needed real code.

Falagard allows you not only to define how the rendering of a window proceeds, you can create new representational features as well by creating new properties for the window and using them in your imagery configurations.

Before I go too far glorifying Falagard, we'll just jump right into it :-)

== Basics ==
Falagard is a part of the CEGUI core and is implemented in C++. It is completely possible to write a skin in C++, but it's is not very practical. You have to recompile every time you change something. Fortunately CEGUI supports creating a Falagard skin from a custom XML format.

This Falagard XML format is what we're going to be looking at throughout this tutorial. As I think learning by doing is the way to go, we'll try to produce something useful with this tutorial - a fully working look'n'feel for a regular button.

The beginning:

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
</WidgetLook>
</Falagard>
</source>

This is the truely minimal XML that defines a widget look. A widget look contains all the information needed to render a specific type of window, a widget look is also what we would define as a look'n'feel.
The first line tells the parser that this is really a XML document. This must always be the first line of a Falagard XML skin.
The second line opens the ''Falagard'' tag. This is always the first thing we do after the ''<?xml ... ?>'' tag.
I hope you're somewhat familiar with XML or at least HTML as this tutorial might be a little difficult to understand if you're not. Now you're warned.
The third line opens a ''WidgetLook'' tag. This is where we cram all the details about our look'n'feel.
The fourth line closes the ''WidgetLook'' tag. We must always remember to close our tags.
The fifth line closes the ''Falagard'' tag. Again - always remember to close your tags.

While this simple XML snippet is good for showing you how to start out, it is completely useless as it does nothing.

To make our look'n'feel interesting we need to tell it what to do. So let's have a look at the Falagard data structure:

* WidgetLook
** Property definitions
** Properties
** Named areas
** Child components
** Imagery sections
** State imagery

This might be overwhelming. It might not. Either way it's the how it is. Falagard is a complex system...
But it's really not that hard once you get down the basics.

The look'n'feel we are going to produce is for a ''Falagard/Button'' type window. This window type is simple, and we don't have to know about all of the parts of a look'n'feel. We only need to know what we'll be using. Furthermore we'll keep it very simple which leaves us at a point where we can make something work with very little.

I'm still going to give a short description of each item in the list though:

* WidgetLook - This is where we add all the other components for our look'n'feel. Consider it '''the''' look'n'feel.

* Property definitions - A property definition is the creation of a new property in the window that gets the look'n'feel assigned.

* Properties - A property in CEGUI is a window variable that we can access from anywhere. Even outside C++ (think XML window layouts). We often assign default values to properties from a look'n'feel.

* Named areas - A named area defines a rectangle, inside the window we are skinning, with a distinct name. Often used to define where to draw some specific piece of imagery that needs special handling by CEGUI as thus cannot be completely defined in the look'n'feel.

* Child components - Some window types need child windows. This could be scrollbar, a titlebar etc. We specify what type of window this child will be customize it for the situation from the look'n'feel.

* Imagery sections - An imagery section is a collection of imagery components tagged with a name. We use imagery sections to split the renderable parts of our look'n'feel into sections which can be drawn independently. Like for example having the frame in one section and the background in another.

* State imagery - Tells CEGUI what to draw when. In a state imagery we draw all the different imagery sections we need for a specific window "situation". For our button we will have: Normal, Hover, Pushed, Disabled.

Ok. I hope this clarifies it a bit. We'll go into more detil about the different parts as we need them.

== Requirements ==
Every time you write a look'n'feel you need to make find out what the requirements are for the type of window you want to skin. To get this information you either look at the header files in the Falagard module source directory, or you reference the manual. This is available both online, here on the wiki, and in the documentation directory in the SDK as a PDF.

The online version is available on the page [[falagard Skinning System Documentation]]. For the list of these requirements I'm talking about the [[Falagard System base widgets reference]] is what you're looking for.
If we look in there we'll see that ''Falagard/Button'' only require 1 ''StateImagery'' definition to be present. ''Normal''.

It allows up to four ''StateImagery'' definitions to cover all its possible states: ''Normal'', ''Hover'', ''Pushed'' and ''Disabled''.

We'll start out the easy way and just make the ''Normal'' state ;-) So now our XML looks like this:

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<b><StateImagery name="Normal">
</StateImagery></b>
</WidgetLook>
</Falagard>
</source>

If you compare to the last XML piece, the only difference is the addition of a ''StateImagery'' tag with its name attribute set to "Normal". This makes sure that we live up to the requirement of a "Normal" state definition.
As I said earlier the ''WidgetLook'' is '''the''' look'n'feel so it is - of course - inside it we add the ''StateImagery'' tag.

This still extremely simple look'n'feel is actually a fully valid look'n'feel. It implements what is required by the manual. Though as you might have guessed it still does nothing.
To get it to render anything we have to define the imagery sections mentioned earlier.

== Imagery ==
For our look'n'feel we'll just want a single image to be stretched over the entire window area. That is each corner from the image mapped to each corner of the window.

To acheive this the first thing we need to do is to add a ''ImagerySection'' to our look'n'feel.

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<b><ImagerySection name="bg">
</ImagerySection></b>
<StateImagery name="Normal">
<b><Layer>
<Section section="bg" />
</Layer></b>
</StateImagery>
</WidgetLook>
</Falagard>
</source>

Now we have added the imagery section, and named it "bg". This name is just something we choose.

Inside the state imagery for the "Normal" state a layer has been added.
The ''Layer'' tag allow you to control the z-ordering of layers inside in a ''StateImagery'', but we only need one layer for this look'n'feel so let's not worry too much about that.

In the layer a ''Section'' has been added. This tag tells the layer its in that we want the ''ImagerySection'' named "bg" to be rendered as part of this layer.

This is nice. The look'n'feel is all ready and hooked up to render the imagery section "bg" as the imagery for the "Normal" state. But our imagery section is still empty, and this means our look'n'feel really is no better than the previous. It still does nothing (at least visually).

Now that we're over the really basic and boring stuff, let's make it draw that image...

To draw a single image we use the tag ''ImageryComponent''. This tag requires us to define the area in which we want the image to be drawn, as well as the image to draw.

The area is the most complex part of practically all look'n'feels. It is designed to be flexible and uses an extended version of the unified coordinate system of CEGUI 0.4 and up.
Besides the regular two numbers containing the relative and absolute component of the coordinate or size Falagard also allows us to use the dimensions of images, windows, text and even properties.
We can also perform arithmetic operations on these dimensions to a certain extent.

Any area needs to define 4 dimensions to fully describe the area. There is some flexibility in how you define the dimensions though.
Probably the most common is to use one of "LeftEdge", "TopEdge", "RightEdge" or "BottomEdge". These map to edges of the window that recieves the look'n'feel, but you can specify "Width" and "Height" instead of "RightEdge" and "BottomEdge".

The look'n'feel we're creating only needs a simple area that covers the entire widget. We'll take the XML required for that in two steps.

<source lang="xml">
<Area>
<Dim type="LeftEdge">
</Dim>
<Dim type="TopEdge">
</Dim>
<Dim type="RightEdge">
</Dim>
<Dim type="BottomEdge">
</Dim>
</Area>
</source>

The area itself is created with the ''Area'' tag. Inside it we have the 4 dimensions. We must explicitly state the type of dimension for each one. The order is important:

* LeftEdge
* TopEdge
* RightEdge / Width
* BottomEdge / Height

You don't have to use '''both''' width and height. For example using "RightEdge" and "Height" is fine.

This tells the area how to interpret the dimensions that we are now going to add:

<source lang="xml">
<Area>
<Dim type="LeftEdge">
'''<AbsoluteDim value="0" />'''
</Dim>
<Dim type="TopEdge">
'''<AbsoluteDim value="0" />'''
</Dim>
<Dim type="RightEdge">
'''<UnifiedDim scale="1" offset="0" type="RightEdge" />'''
</Dim>
<Dim type="BottomEdge">
'''<UnifiedDim scale="1" offset="0" type="BottomEdge" />'''
</Dim>
</Area>
</source>

Inside each ''Dim'' tag we have added a dimension. Let's take them one at a time.

# <AbsoluteDim value="0" /> - This tell it to put our "LeftEdge" ''Dim'' at pixel position 0. All dimensions are always relative to window that has the look'n'feel, so 0 will in this case be the left edge of our widget as we planned.

# <AbsoluteDim value="0" /> - Just the same as before. But this time we're in a "TopEdge" ''Dim'' so it will result in the top edge of our window.

# <UnifiedDim scale="1" offset="0" type="RightEdge" /> - A unified dimension. This one has a scale (relative) component of exactly one. And a offset (absolute) value of zero. As type we've set "RightEdge". This is what the scale component get multiplied by to get some thing useful (pixel values). One times RightEdge will equal RightEdge, which is exactly the window dimension we want.

# <UnifiedDim scale="1" offset="0" type="BottomEdge" /> - Same as before but the bottom edge of our window as the dimension.

Now the area to span our entire is worked out, let's add that ''ImageryComponent'' and give it its area.

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<ImagerySection name="bg">
<b><ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
</ImageryComponent></b>
</ImagerySection>
<StateImagery name="Normal">
<Layer>
<Section section="bg" />
</Layer>
</StateImagery>
</WidgetLook>
</Falagard>
</source>

Now the area is in place.
The ''ImageryComponent'' tag has been added to our ''ImagerySection'' and inside it we have out the area we just created.
All thats missing now is the image!

We'll assume we have a imageset loaded called "MyImages". And inside this imageset we have the image "ButtonBG" defined.
This is the image we'll use for our button.

The XML looks like this

<source lang="xml">
<Image imageset="MyImages" image="ButtonBG" />
</source>

Simple eh?

We also wanted the image to be stretched across the whole area of the ''ImageryComponent''. The default formatting in top/left alignment. Not good enough...

We add the formatting tags

<source lang="xml">
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</source>

Vertical format must come first. Both sets stretching as the formatting. Which is what we need.
That's all we wanted in the look'n'feel so let's have a look at the XML for this extremely simple button skin.

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<ImagerySection name="bg">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<b><Image imageset="MyImages" image="ButtonBG" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" /></b>
</ImageryComponent>
</ImagerySection>
<StateImagery name="Normal">
<Layer>
<Section section="bg" />
</Layer>
</StateImagery>
</WidgetLook>
</Falagard>
</source>

The three new tags just got added after the area in the ''ImageryComponent'', and we're done :)

== Label ==
You might have noticed that I have'nt talked about the label until now.
We'll need to take a look at it now or we won't get any text on our button.
With Falagard you have full control of how the text is rendered.

For our look'n'feel we want the text to be centered both vertically and horizontally in the widget. We also want the text to wrap (word wrap) if it's too long to render as one line without being clipped.

We'll make a new ''ImagerySection'' for our label. This gives us a nice seperation of parts to render. "bg" being the background, and a new section called "label" to represent the - You guessed it - label.
Inside this new ''ImagerySection'' we add a ''TextComponent'' which we'll set up to render the text like we want.

<source lang="xml">
<ImagerySection name="label">
<TextComponent>
</TextComponent>
</ImagerySection>
</source>

Like a ''ImageryComponent'' a ''TextComponent'' must have an area. For our button we'll allow text to span the entire window. This means that we can reuse the ''Area'' from before.

A ''TextComponent'' by default renders the text of the window that has the look'n'feel assigned.
This is exactly what we want for our button.

The formatting we wanted is easily made by using the same tag we used before (to format the background image) but with another type. The formattings supported are different for ''TextComponent'' and ''ImageryComponent''.

Let's look at the XML for this new ''ImagerySection'' "label":

<source lang="xml">
<ImagerySection name="label">
<TextComponent>
<b><Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<VertFormat type="CentreAligned" />
<HorzFormat type="WordWrapCentreAligned" /></b>
</TextComponent>
</ImagerySection>
</source>

We added the same area as in the "bg" ''ImagerySection'', and added the formattings we wanted. Take a look at [[Falagard System XML Enumerations reference]] for the complete listing of supported formattings (and lots of other stuff).

This ''ImagerySection'' is done. It will render the label with the correct formatting using a white colour. By not specifying a colour we always choose white, which is useful as we can modulate it into any colour we choose later on. Which we of course will :-)

To actually use this new "label" section we must add it to our state imagery like we did with the "bg" section earlier. So here's what the XML looks like so far:

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<b><ImagerySection name="label">
<TextComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<VertFormat type="CentreAligned" />
<HorzFormat type="WordWrapCentreAligned" />
</TextComponent>
</ImagerySection></b>
<ImagerySection name="bg">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="ButtonBG" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<StateImagery name="Normal">
<Layer>
<Section section="bg" />
'''<Section section="label" />'''
</Layer>
</StateImagery>
</WidgetLook>
</Falagard>
</source>

This look'n'feel adds the fully working label (still white) to our button skin. This is starting to become a useful look'n'feel, so let's give it the final touch by adding handling of the three other states ''Hover'', ''Pushed'' and ''Disabled'' that we left out before.

== Colours ==
We want to use different text colours for each of these states. We also want to able to customize those colours on a per widget basis.
This is made possible by the property definition.

A ''PropertyDefinition'' creates a new property in the window that gets the look'n'feel assigned. The property we create is a simple string value, but '''we''' choose what it's used for. '''Not''' CEGUI.

In total we have 4 states for our button counting the new ones, so we'll add 4 new properties to store the text colour for each state. The XML is like so:

<source lang="xml">
<PropertyDefinition name="NormalTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="HoverTextColour" initialValue="FFFF0000" redrawOnWrite="true" />
<PropertyDefinition name="PushedTextColour" initialValue="FF00FF00" redrawOnWrite="true" />
<PropertyDefinition name="DisabledTextColour" initialValue="7F888888" redrawOnWrite="true" />
</source>

* ''name'' is the name the new property will be available under.
* ''initialValue'' is the default value for the property.
* ''redrawOnWrite'' when set to true the window will be redrawn when the value of the property changes.

These properties will be available from both C++ code and in XML window layouts. So choosing a good name is a good idea.
You can create properties that you don't use for anything inside the look'n'feel. These will still become available which can be a good way of creating new variables for windows that you might need in your application.

The default values represent colours in the format CEGUI would expect a colour for a built-in property.
Colours for CEGUI are always written in hexadecimal.

The format is: "AARRGGBB" where:
* AA = Alpha
* RR = Red
* GG = Green
* BB = Blue

This gives our properties the values of
* white for ''Normal''
* red for ''Hover''
* green for ''Pushed''
* 50% tranparent grey for ''Disabled''

Setting a new value for any of these properties will make sure the button is re-rendered to show the new colour.

The only places in the look'n'feel that know which state we are in are the ''StateImagery'' tags. The ''Section'' tags inside these allow for colours to be specified. The XML for the label in the ''Normal'' state looks like this:

<source lang="xml">
<Section name="label">
<ColourProperty name="NormalTextColour" />
</Section>
</source>

The ''ColourProperty'' tag inside our ''Section'' ensures that all imagery in the imagery section "label" has its colour modulated by the value of the property "NormalTextColour". The imagery section "label" render only white text, so by doing this we ensure that the colour rendered is exactly that of the value of the property "NormalTextColour".

We now know what to do so lets look at the XML so far for this look'n'feel:

<source lang="xml">
<?xml version="1.0" ?>
<Falagard>
<WidgetLook name="MyButton">
<b><PropertyDefinition name="NormalTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
<PropertyDefinition name="HoverTextColour" initialValue="FFFF0000" redrawOnWrite="true" />
<PropertyDefinition name="PushedTextColour" initialValue="FF00FF00" redrawOnWrite="true" />
<PropertyDefinition name="DisabledTextColour" initialValue="7F888888" redrawOnWrite="true" /></b>
<ImagerySection name="label">
<TextComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<VertFormat type="CentreAligned" />
<HorzFormat type="WordWrapCentreAligned" />
</TextComponent>
</ImagerySection>
<ImagerySection name="bg">
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" offset="0" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" offset="0" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="MyImages" image="ButtonBG" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<StateImagery name="Normal">
<Layer>
<Section section="bg" />
<b><Section section="label">
<ColourProperty name="NormalTextColour" />
</Section></b>
</Layer>
</StateImagery>
<b><StateImagery name="Hover">
<Layer>
<Section section="bg" />
<Section section="label">
<ColourProperty name="HoverTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Pushed">
<Layer>
<Section section="bg" />
<Section section="label">
<ColourProperty name="PushedTextColour" />
</Section>
</Layer>
</StateImagery>
<StateImagery name="Disabled">
<Layer>
<Section section="bg" />
<Section section="label">
<ColourProperty name="DisabledTextColour" />
</Section>
</Layer>
</StateImagery></b>
</WidgetLook>
</Falagard>
</source>

Not too hard was it? The look'n'feel reached a whole new level with these changes, as state is reflected in the text colour.

To sum up what we've made:
* A look'n'feel for the ''Falagard/Button'' window type.
* Static background image.
* Formatted label.
* Label colour dependent on current state.

----

That will be enough for this time. It's getting early ;-)

I hope this tutorial is useful and that it will help expose Falagard more broadly.

Please give feedback in the discussion page so I can improve the tutorial where needed.

--[[User:lindquist]] 06:10, 6 Dec 2005 (CET)

[[Category:Tutorials]]

The Beginner Guide to Resource Groups

2011-03-03T23:52:40Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.6}}
{{Series|The Beginner Guide|2}}

{{notice|message=This tutorial is for CEGUI versions up to 0.6.2. For later releases, see the tutorials in the main documentation.}}

If you have read [[The Beginner Guide to Getting CEGUI Rendering]], you probably have your application set-up to perform the basic CEGUI initialisation steps and to call the System::renderGUI method, which is all very nice; but lets face it, you still can't get anything to draw!

The next stage in this quest for the 'holy grail' (that is, to actually get CEGUI to work) is to setup resource provider groups that will later enable us to load some files so that CEGUI has some source materials to use when rendering.

== What is a ResourceProvider? ==
CEGUI makes use of a helper object which we call the ResourceProvider. This object provides an interface between the core CEGUI library and any external file loading system.

For example, the Ogre and Irrlicht engines have their own resource manager / file loading sub-systems, by implementing and supplying a specialised ResourceProvider object, the renderer modules for these engines allow seamless integration with these systems so that CEGUI data files are loaded via these systems. The lower level Direct3D and OpenGL libraries do not have their own resource systems as such, so for these you can use the CEGUI default resource provider.

=== DefaultResourceProvider Explained ===
CEGUI's default resource provider, CEGUI::DefaultResourceProvider, supplies some basic functionality for those who do not yet have, or do not need, a more sophisticated alternative. As well as supplying the functions required by CEGUI for actually loading files and data, DefaultResourceProvider also has some rudimentary support for 'resource groups'. Here, a resource group is basically a label given to a directory or path on the system. This allows us to have logical grouping of files within directories and then to be able to refer to those location via a simple label rather than hard coded paths. In the simplest case this means that you just need to update the resource group location instead of updating path information throughout your code and in the XML files when you change the location of the data files.

Before you can use the CEGUI::DefaultResourceProvider, you need to ensure you have included the correct header (usually at the start of your source file), for example:
<code>
# include <CEGUIDefaultResourceProvider.h>
</code>
==== Specifying Resource Groups and Directories ====
The DefaultResourceProvider allows you to define any number of named resource groups and to specify a directory to be used for each group. What this means is that you can create a resource group, say “imagesets” and assign a directory to that, for example “./mygame/datafiles/gui/imagesets/”. Then when loading an Imageset through the ImagesetManager, you could specify the resource group to be used as “imagesets” and the system will look in the predefined location.
At present each resource group may only have a single directory assigned to it.

A small code example is in order to clarify what has been said. Where as previously, without the use of resource groups, you might have done this:
<source lang="cpp">
Imageset* wlis = ImagesetManager::getSingleton().createImageset(
"./mygame/datafiles/gui/imagesets/WindowsLook.imageset");
</source>

Using resource groups, at initialisation time, you create the resource groups in the default resource provider, like this:
<source lang="cpp">
DefaultResourceProvider* rp = static_cast<DefaultResourceProvider*>(
CEGUI::System::getSingleton().getResourceProvider());

rp->setResourceGroupDirectory("imagesets", "./mygame/datafiles/gui/imagesets/");
</source>

Then later on in the code, when you need to load the imageset, you can reference the resource group to be used, like this:
<source lang="cpp">
Imageset* wlis = ImagesetManager::getSingleton().createImageset(
"WindowsLook.imageset", "imagesets");
</source>

Note how you do not need to specify any path information; the path information is obtained from the resource group specified, in the example this is "imagesets". We will later show you how you set default resource groups for each of the resource types – then you do not have to specify the group when you load a resource (unless you're loading it from a group that is not the default, of course).

Another important thing to consider is that using this approach, the data files should not contain relative path information – they should, in general, just have the actual file name.

== Default Resource Groups ==
Each of the system classes that represents a loadable resource has static members to set and get a default resource group. This resource group will be used when loading the specific data files needed by a given class – in the case of the Imageset class, the default resource group should reference a directory holding the imageset xml and texture image files.

For each of the resource consuming classes, the static members are named the same (special exception is xerces – see below):
<source lang="cpp">
const String& getDefaultResourceGroup();
void setDefaultResourceGroup(const String& groupname);
</source>

The following is a list of the core resource loading classes and the resources that they load:

CEGUI::Imageset - Imageset xml and texture image files.
CEGUI::Font - Font xml and ttf font files.
CEGUI::Scheme - Scheme xml files.
CEGUI::WindowManager - Window layout xml files.
CEGUI::WidgetLookManager - LookNFeel xml files
CEGUI::ScriptModule - Script files in whichever scripted langauge.

There is one special exception, as mentioned above – that is the Xerces-C based XML parser. For this there is a special resource group setting to specify where the schema files can be found (these are the .xsd files used for xml validation). For this special case, the static members are:
<source lang="cpp">
const String& XercesParser::getSchemaDefaultResourceGroup();
void XercesParser::setSchemaDefaultResourceGroup(const String& groupname);
</source>

One final thing to consider, is that the resource provider class also has a default group. This should be considered a 'global' default – it is used whenever a specific resource loading class has no default of its own specified. This could be useful if you have all your data in a single directory.

== DefaultResourceProvider Setup: A Complete Example ==
To close, we will show how the CEGUI samples framework does the initialisation of resource groups and their target directories, and how we assign the default groups to be used for all of the resource types.

After initialising the core CEGUI::System object as usual, we then specify a set of resource groups and their target directories:
<source lang="cpp">
// initialise the required dirs for the DefaultResourceProvider
CEGUI::DefaultResourceProvider* rp = static_cast<CEGUI::DefaultResourceProvider*>
(CEGUI::System::getSingleton().getResourceProvider());

rp->setResourceGroupDirectory("schemes", "../datafiles/schemes/");
rp->setResourceGroupDirectory("imagesets", "../datafiles/imagesets/");
rp->setResourceGroupDirectory("fonts", "../datafiles/fonts/");
rp->setResourceGroupDirectory("layouts", "../datafiles/layouts/");
rp->setResourceGroupDirectory("looknfeels", "../datafiles/looknfeel/");
rp->setResourceGroupDirectory("lua_scripts", "../datafiles/lua_scripts/");

// This is only needed if you are using Xerces and need to
// specify the schemas location
rp->setResourceGroupDirectory("schemas", "../../XMLRefSchema/");
</source>
Now that is done, we have a nice set of resource groups defined with their target directories set. Finally, to get the system to use these new directories, we set the default resource groups to be used:
<source lang="cpp">
// set the default resource groups to be used
CEGUI::Imageset::setDefaultResourceGroup("imagesets");
CEGUI::Font::setDefaultResourceGroup("fonts");
CEGUI::Scheme::setDefaultResourceGroup("schemes");
CEGUI::WidgetLookManager::setDefaultResourceGroup("looknfeels");
CEGUI::WindowManager::setDefaultResourceGroup("layouts");
CEGUI::ScriptModule::setDefaultResourceGroup("lua_scripts");

// Again, you only need to this one if you are using xerces and have
// defined a group for schemas.
CEGUI::XercesParser::setSchemaDefaultResourceGroup("schemas");
</source>

== Conclusion ==
Here you have had a brief introduction to the DefaultResourceProvider class, you have seen how to create resource groups and assign directory locations to them, and you have also seen how to specify default resource groups for each resource type CEGUI uses.

[[User:CrazyEddie]]

[[Category:Tutorials]]

The Beginner Guide to Loading Data Files and Initialisation

2011-03-03T23:52:30Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.6}}
{{Series|The Beginner Guide|3}}

{{notice|message=This tutorial is for CEGUI versions up to 0.6.2. For later releases, see the tutorials in the main documentation.}}

Ok. Now you have read [[The Beginner Guide to Getting CEGUI Rendering]] and [[The Beginner Guide to Resource Groups]], the next rung on the ladder to success is to actually load in the files that CEGUI will be using to produce some output!

== Overview: Data Files ==
CEGUI uses a variety of data files and initially there may be some confusion over what these are, how they relate to each other and how they get loaded. So before we get started with the meat of all this, I will introduce the data files, what they are, what they're used for, and how they get loaded into CEGUI.

=== XML, XSD? It's all XML! ===
With the notable exceptions of graphical image files and loadable modules (DLL and so files, etc), the majority of the data files used by CEGUI are actually XML. This leads us to the first obstacle that people run into; the .xsd schema files.

Although the Expat XML parsing library is now becoming CEGUI's default library, the previous long time default, and CrazyEddie's own preferred XML parsing library is the [http://xerces.apache.org/xerces-c Xerces-C++] library from the [http://www.apache.org Apache Software Foundation]. The advantage of using this particular library to handle parsing XML is that it provides ''schema validation''. Schema validation is a means by which we can check, at parse time, whether the input file contains the expected data and that the data is correctly specified. To do this, the system requires some additional files which are known as schema files, which have the .xsd file extension - the master copies of CEGUI's schema files are currently found in the ''cegui_mk2/XMLRefSchema/'' directory. Anyway, the only thing you need to know about these .xsd files for now is that, when using Xerces-C++ as a parser, they must be available to the ResourceProvider system; this is best achieved by setting up a resource group to a directory containing the schema files and setting that group as the default to be used by CEGUI::XercesParser when loading schema files ([[The Beginner Guide to Resource Groups]] shows how to do this).

=== The Data Files ===
As mentioned above, with a couple of exceptions, all data files in CEGUI are XML. Rather than using the generic '.xml' file extension, the data files are named according to what the files actually represent; so .imageset for an Imageset and .font for a Font, etc. Below is a very brief overview of each file type; more advanced discussion of the files and their capabilities can be found elsewhere.

==== Imageset ====
Effectively, an Imageset is just a collection of defined regions upon the source image / texture file (which is also specified in the Imageset definition). Each of these defined regions has a unique name and is known within the system as an Image. An Image as defined in an Imageset is the basic level of imagery used by CEGUI. By modifying the source image / texture file and also the position and size of the defined regions within the Imageset files you can easily change the appearance of what gets drawn by CEGUI.

==== Font ====
A Font file, unsurprisingly, defines a font for use in CEGUI. There are two types of font which can be defined:
; FreeType Font : This is a font based upon a true-type (.ttf) font file. It is denoted with Type="FreeType" in the .font file starting with version 0.5.0 of CEGUI. In previous versions it was known as "Dynamic".
; Pixmap Font : Also known as a bitmapped font, this type of font is based upon an Imageset which defines Images for the font glyphs. It is denoted with Type="Pixmap" in the .font file starting with version 0.5.0 of CEGUI. In previous versions it was known as "Static".

==== Scheme ====
A Scheme is a largely means to group other data files together, it's also the most convenient way to load and register widget types. A Scheme can contain one or more of the following (which will be loaded and initialised when the scheme is loaded):
* Imageset (either a full Imageset via XML, or a single image via an image file)
* Font
* Window Set
* Window Renderer Set
* Window Alias
* [[Falagard]] Mapping

===== Imageset and Font =====
These have already been mentioned above. The specifications here just get them to load as part of the scheme.

===== Window Set =====
Basically specifies the name of a loadable module (.dll / .so, etc), and a set of widget names contained within that module that you wish to register with the system. If no names are listed, all available types in the module are registered.

===== Window Renderer Set =====
Specifies the name of a loadable module (.dll / .so, etc), and a set of window renderer names contained within that module that you wish to register with the system. If no names are listed, all available types in the module are registered. A 'Window Renderer' is an object that can control rendering for some base window type(s), all the window renderer objects supplied with CEGUI perform rendering by making use of the 'Falagard' skinning system (though this is not a strict requirement).

===== Window Alias =====
Provides a means to refer to a window / widget type by alternative names, it can also be used to 'hide' an already registered widget type with another widget type (so that other widget type gets used instead).

===== [[Falagard]] Mapping =====
Used to create a usable ''Window Type'' type from a ''Target Type'' which names the base type containing the functionality, a ''Renderer'' which names a Window Renderer that can control rendering for the specified target type, and a ''LookNFeel'' which names a skin to be applied (these are normally specified via XML looknfeel files).

==== Layout ====
A layout file contains an XML representation of a window layout. Each nested 'Window' element defines a window or widget to be created, the 'Property' elements define the desired settings and property values for each window defined.

==== Config ====
CEGUI Supports the use of a config file. This file allows you to specify some defaults, such as a Scheme to load, a layout to load, initialisation and termination script files (when using a ScriptModule), and some other things which are not discussed here.

== Loading the Basic Files ==
In order to get things up and running you need to load in some files. The minimal set of files required are:
* Imageset
* Font
* Scheme

The good thing about the Scheme file is that it can be used to load the other two automatically. For the purposes of this tutorial, we will load a scheme file and a font file - it is assumed the scheme automatically loads an Imageset for us. This is done as follows:

<code>// load in the scheme file, which auto-loads the TaharezLook imageset
CEGUI::SchemeManager::getSingleton().loadScheme( "TaharezLook.scheme" );

// load in a font. The first font loaded automatically becomes the default font.
if(! CEGUI::FontManager::getSingleton().isFontPresent( "Commonwealth-10" ) )
CEGUI::FontManager::getSingleton().createFont( "Commonwealth-10.font" );</code>

In the above code snippet (and in the sample files) it is assumed that the resource group locations and the default groups have all been set up as described in [[The Beginner Guide to Resource Groups]].

== Simple Defaults Initialisation ==
Finally, you need to specify some defaults. This is to ensure that the system always has a font and mouse cursor available for when a window or widget specifies no preference of its own.

In reality, we no longer need to specify a default font, since the FontManager will now automatically set the first loaded font as the default. Although if this is not the default font you require, you can set a different one as you desire. The code to set a default font is as follows:

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

The other default object you need to set is the mouse cursor. This is to ensure that when you move the mouse over any element that does not set a cursor of its own the cursor does not disappear. The code to set the default mouse cursor is as follows (NB: This uses the TaharezLook imageset which was loaded with the scheme above).

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

If you intend to use tool tips, usually you specify the name of the ToolTip based widget type that you want used. It is actually possible to set this on a per-window basis, though that is not normally required, and is beyond the scope of this little introduction. Anyway, to specify the tool tip window type:

System::getSingleton().setDefaultTooltip( "TaharezLook/Tooltip" );

== Conclusion ==
Here we have discovered the very basics of what the various data files used by CEGUI are, how they are loaded, and the minimal initialisation needed for CEGUI applications. Other articles will discuss each of the data files types in greater detail allowing advanced uses to be discovered.

[[User:CrazyEddie]]

[[Category:Tutorials]]

The Beginner Guide to Getting CEGUI Rendering

2011-03-03T23:52:20Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.6}}
{{Series|The Beginner Guide|1}}

{{notice|message=This tutorial is for CEGUI versions up to 0.6.2. For later releases, see the tutorials in [http://www.cegui.org.uk/docs/current/ the main documentation].}}

In order to get CEGUI to render, no matter what your target engine is, there are basically three steps that must be done.

# Create an instance of a CEGUI::Renderer based object.
# Create the CEGUI::System object.
# Call the method to render the GUI.

Obviously you also need to load some data and perform very basic initialisation, which is covered in [[The Beginner Guide to Loading Data Files and Initialisation]], and also you need to get your inputs into the system which is covered in [[The Beginner Guide to Injecting Inputs]].

=== Create an instance of a CEGUI::Renderer based object ===
This is fairly straight forward and should pose no major obstacles for any of the supported renderers. You must of course remember to include the header file for the renderer that you will be using, also remember that for Ogre3D the renderer module now comes with CEGUI and not Ogre (Huh? Since when? As of 23/02/2010 (CEGUI 0.7.1, OGRE 1.7) the module is called CEGUIOgreRenderer, and is in CEGUI's sources, not Ogre's). (Note that you need to delete the Renderer object when you are cleaning up the program.)

The basic renderer creation code is:

'''Direct3D 8.1'''
CEGUI::DirectX81Renderer* myRenderer =
new CEGUI::DirectX81Renderer( myD3D8Device );

'''Direct3D 9'''
CEGUI::DirectX9Renderer* myRenderer =
new CEGUI::DirectX9Renderer( myD3D9Device, 0 );

'''OpenGL'''
CEGUI::OpenGLRenderer* myRenderer =
new CEGUI::OpenGLRenderer( 0 );

'''Ogre3D'''
CEGUI::OgreCEGUIRenderer* myRenderer =
new CEGUI::OgreCEGUIRenderer( myRenderWindow );
''Note:'' Using Ogre 1.4.9 with CEGUI 0.6.2 binding the renderer to the scene manager seems to be required (in my case the GUI was not displayed while the mouse events were properly processed). To bind a scene manager to the renderer, use the ''setTargetSceneManager'' method:
myRenderer->setTargetSceneManager(mySceneManager);

'''Irrlicht Engine'''
CEGUI::IrrlichtRenderer* myRenderer =
new CEGUI::IrrlichtRenderer( myIrrlichtDevice, true );

=== Create the CEGUI::System object to initialise the system ===
Another extremely simple step. Just instantiate the CEGUI::System object by using 'new' and passing in a pointer to the CEGUI::Renderer that you created in the previous step. This will cause the entire system to initialise itself.

new CEGUI::System( myRenderer );

=== Call the method to render the GUI ===
This is the only step that, depending upon your target engine, can be done differently. Basically what you need to do call the CEGUI::System::renderGUI method at the end of your rendering loop. For lucky users of the Ogre3D engine, this step is taken care of automatically. For everybody else, some simple example code can be seen below

'''Direct3D 8.1 / 9'''
// Start the scene
myD3DDevice->BeginScene();<br />
// clear display
myD3DDevice->Clear(0, 0, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0, 0, 0), 1.0f, 0);<br />
// user function to draw 3D scene
draw3DScene();<br />
// draw GUI
'''CEGUI::System::getSingleton().renderGUI();'''<br />
// end the scene
myD3DDevice->EndScene();<br />
// finally present the frame.
myD3DDevice->Present(0, 0, 0, 0);

'''OpenGL'''
// user function to draw 3D scene
draw3DScene();<br />
// draw GUI (should not be between glBegin/glEnd pair)
'''CEGUI::System::getSingleton().renderGUI();'''

'''Irrlicht'''
// start the scene
myIrrlichtDriver->beginScene(true, true, irr::video::SColor(150,50,50,50));<br />
// draw main scene
myIrrlichtSceneManager->drawAll();<br />
// draw gui
'''CEGUI::System::getSingleton().renderGUI();'''<br />
// end the scene
myIrrlichtDriver->endScene();

=== Conclusion ===
This is the ''most basic'' introduction to setting up CEGUI to render. There are things not covered here, such as using different scene managers in Ogre and advanced options such as user specified resource providers, and so on.

[[User:CrazyEddie]] 03:34, 9 February 2008 (PST)

[[Category:Tutorials]]

The "official" layout editor

2011-03-03T23:52:10Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

The Official layout editor for CEGUI is CELayoutEditor.

== Documentation ==
* [[CELayout Editor - Getting Started / Building]]
* [[CELayoutEditor Manual]]

== Design ==
* [[User Interface]]

[[Category:CELayoutEditor]]

Subversion

2011-03-03T23:52:00Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

This page introduce the use of subversion. If you're only intent is to get the files from subversion you should start with [[Obtaining the library source from Subversion]] which help you in getting the file and compiling CEGUI. This page dive deeper in the use of subversion as a standard user as well as a developer of the library itself. This page presents the use of subversion with the command line tool available for windows, mac and linux.

First of all here is some urls to get started with subersion usage :
* Repository url: [https://svn.sourceforge.net/svnroot/crayzedsgui/ https://svn.sourceforge.net/svnroot/crayzedsgui/]
** CEGUI library latest development files url: [https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk]
** CEGUI Layout Editor latest version url: [https://svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk https://svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk]
** Repository browser: [http://svn.sourceforge.net/viewcvs.cgi/crayzedsgui/cegui_mk2/ http://svn.sourceforge.net/viewcvs.cgi/crayzedsgui/cegui_mk2/]

== Glossary ==
* Repository: That's the place storing all the files and revisions. It's hosted by sourceforge. In Subversion respository are identified using urls.
* Working Copy: A working copy is a local view of part of the repository. You can retrieve a local copy using the checkout command. A working copy contains the file as well as a lot of additional information. The size of the working copy is more than twice the size of the file of the project.
* Branches: Subversion does not provides branches concept, however it's possible to organize the project in several branches. The current development branch is known as trunk. The other branches are stored in a folder named .... branches. So a branch in Subversion is just a folder in branches.
* Tags: Subversion does not provides tags concept. Like branches tags are only subfolder of the tags folder.
* Revision: Snapshot of the tree at a given time. Each modification on the tree create a new revision.

== Layout of the repository ==
At this moment there are two projects in the CEGUI repository. The CEGUI library and the layout editor. The repository is organised as follows:
* cegui_mk2 : The cegui library itself
** trunk : The main development stream
** branches : Branches (features testing are prefix with pre-)
** tags: Release of the CEGUI library
* CELayoutEditor : The editor files
** trunk : The main development stream
** branches : Branches
** tags: Release of the editor

== Getting a working copy of the project ==
In order to get the files from the Sourceforge server one can use two commands. Both commands retrieve the files, however the second command excludes you from staying up-to-date or create patches. If you plan to get the sources, create your library, install it and remove them, the second solution is the best for you.
svn checkout url [dest_dir]
svn co url [dest_dir]
or
svn export url [dest_dir]

Using each of these commands you will get you the latest version of any file with url as root tree. You can get files at a particular revision using an additional parameter:
svn checkout/export [-r number] url [dest_dir]. It usefull to test older version. There is no named revision in subversion but it's easy to create tags which provides the same features.

== Updating your working copy ==
When you choose 'checkout', you now have a working copy of the library or the editor. You can keep it in sync with the repository at Sourceforge with the following command:
svn update [folder|file]
svn up [folder|file]

== Getting history of modifications ==
In order to get a kind of changelog you can use subversion. Each modification of the repository comes with a text message explaining the last modification. You can get the history of any file or directory of your working copy using:
svn log [url] (remote repository)
svn log [path] (working copy)

== Making change to your working copy ==
There is several change that can be made on subversion repository : adding, removing, renamming and modifying files, adding, removing and renamming directory. A standard work session consists in the following operation.
# Update your working copy
# Make your change
# commit your change

This section focus on the second step of a work session. Files and directory are not handled automatically by subversion you must first explain to subversion that those file must be manage d. This is done using the add command:
svn add source.cpp // Add source.cpp to your local subversion copy
svn add subdir // Add subdir to your local subversion copy as well as all file contained in the repository itself
One of the improvement of subversion compared to CVS is its ability to remove file as well as folder this done by the rm or delete command
svn del source.cpp
Finally you can rename file or directory using the mv command. This command does not allow mass moving like the standard mv command of unix system. rename is an alias of this command.
svn mv source dest

You can use any text editor to edit your files. Subversion will do its best to send on the network only the change you've made to your working copy.

''Must talk about loking facilities here''

== Branching, Tagging, Merging ==
In subversion a branch or a tag is just a folder in the corresponding folders. In order to create a branch one needs to use the copy operation. Copying a complete tree in subversion is cheap. In order to create a branch or tag use the following operation :
svn copy url_source url_dest
I suggest using url of the repository directly. In order to create a branch of CEGUI use :
svn copy https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/branches/v0-5
To create a tag use :
svn copy https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/branches/v0-5 https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/tags/v0-5-0

A final notes on TAG. Nothing prevents someone to make changes on a tag. It's up to the developer to do changes only on trunk and branches.

If you have fixed a lot of bug in a subsystem or want to apply some of the change made to trunk to a specific branch you have to merge. Merging requires a working copy.
svn merge url_from url_to working_copy_path

'' Merging need some improvement ''
'' Need to add some information on conflict''

== Properties ==
Subversion allows one to attach meta information to any file and folder in the repository. Those information are called properties. The table bellow list most interesting properties:

{| border="1"
|-
||'''Name'''||'''Values'''||'''Description'''||'''Files||Directories
|-
||svn:executable||set/unset||Tel whether the file should be made executable or not||yes||no
|-
||svn:mime-type||mime of the file||Tel the mime type of the file. This is use to select the diff algorithm used||yes||no
|-
||svn:ignore||*.o *.lo ...||List file to be ignore by svn command||no||yes
|-
||svn:keywords||Date,Revision,Author,HeadURL,Id||It allows subversion to automatically substitue some field in the file on check out or update||yes||no
|-
||svn:eol-style||native*,CRLF,CR,LF||It allows automatic conversion from one eol style to another||yes||no
|-
||svn:externals||svn url||It allows to create soft link between to subversion repository||no||yes
|-
||svn:needs-lock||set/unset||Tel whether the file must be locked before editing or not||yes||yes
|}
You can also defines your own properties for whatever use you might need them. When one adds a file to subversion it must add the svn:eol-style property to the value native for all text file. It can be made automatically using autoprops facilities of svn.

In order to manipulate properties you can use
svn propset name value url/file
svn proplist url/file
svn propget name url/file
svn propdel url/file
svn propedit name url/file

== Pitfalls ==

== Configuring subversion ==

== External Links ==
* [http://subversion.tigris.org/ Subversion home] (to get the software)
* [http://svnbook.red-bean.com/ Subversion book] (to learn a lot more than what you read in this page)
* [http://tortoisesvn.tigris.org/ TortoiseSVN] (Win32 client, a must)

[[Category:CEGUI Developer Team]]

Scheme files

2011-03-03T23:51:50Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

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

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

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

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

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

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

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

Each element will be described individually below.

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

Attributes:
* '''Name''' - Specifies the name that the scheme will use within the system. ''Required''.

''GUIScheme'' is the root element and is the only "global" tag.
<source lang="xml">
<?xml version="1.0" ?>
<GUIScheme Name="MyScheme">
...
... resources ...
...
</GUIScheme>
</source>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Attributes:
* '''Filename''' - Specifies the name of the loadable module (dll / .so / etc). ''Required''.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:Manuals]]

Sample code for all Widgets

2011-03-03T23:51:41Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.5}} {{VersionBadge|0.6}}

This code goes through every widget and demonstrates how to retrieve and set their data as well as some of their particularities. Please post comments or questions on the message board thread for the [http://www.cegui.org.uk/phpBB2/viewtopic.php?p=7967#7967 Widget Galore]

=== Widgets ===

==== General ====
A widget can be enabled/disabled via setEnabled(). Disabling a widget prevents the user from activating it and manipulating its contents. A widget can be hidden/shown via setVisible().

==== Tooltip ====
A Tooltip widget displays text when the mouse has been hovering over a widget for a certain amount of time. This widget requires that time be injected within CEGUI via injectTimePulse().

The graphical aspect (the scheme) of the tooltip can be specified via setTooltip(). The amount of hovering time required to activate the tooltip can be specified via setHoverTime(). The amount of time the tooltip is displayed can be specified via setDisplayTime(). And the fade transition time can be specified via setFadeTime(); this affects both the fade in and the fade out times. The tooltip text of a widget can be specified via setTooltipText(). Please note that some complex widgets are composed of several widgets. In order to have a tooltip text displayed while hovering over any region of the complex widget then every component widget needs to have a tooltip text specified. For example a Spinner widget is composed of an Editbox widget and two Button widgets.

==== StaticText ====
There is no StaticText within CEGUI but type of widget can be obtained via the DefaultWindow class.

The currently displayed text can be specified via setText(). The color of this text can be specified via the "TextColours" property. The value of this property contains 4 color definitions: top left, top right, bottom left, and bottom right. Each color is specified as a two-digit hexadecimal value of the format AARRGGBB (alpha, red, green, blue). The text is aligned vertically via the "VertFormatting" property with a value of TopAligned, BottomAligned, or VertCentred. The text is aligned horizontally via the "HorzFormatting" property with a value of LeftAligned, RightAligned, HorzCentred, HorzJustified, WordWrapLeftAligned, WordWrapRightAligned, WordWrapCentred, or WordWrapJustified.

==== StaticImage ====
There is no StaticImage within CEGUI but type of widget can be obtained via the DefaultWindow class.

The currently displayed image can be specified via the "Image" property. This property takes two parameters, the imageset ("set") and the image name ("image").

==== ProgressBar ====
A ProgressBar widget displays a progression; it does not receive inputs from a user.

The current progress can be specified via setProgress(). Progress can be advanced through steps. The step size can be specified via setStepSize() and a step performed via step(). Progress can be adjusted by a delta value via adjustProgress(). The current progress value can be obtained via getProgress().

==== Button ====
A Button widget displays a text and receives an activation instruction from the user.

The text can be specified via setText().

==== ScrollablePane ====
A ScrollablePane widget displays contents that can be scrolled. Contents can be added via addChildWindow(). When that content exceeds the dimensions of the ScrollablePane then scrollbars appear to allow the use to view and interact with that hidden content.

==== Checkbox ====
A Checkbox widget controls a boolean value; true when checked and false when unchecked. This value can be obtained via isSelected() and specified via setSelected(true) to check or setSelected(false) to uncheck.

==== Spinner ====
A Spinner widget controls a numerical values (float) through an editbox or the use of the increment or decrement buttons.

This value is bounded within a minimum and a maximum by calling setMinimumValue() and setMaximumValue(). The arrow buttons increment or decrement the value by the amount specified with setStepSize(). The numerical value can be displayed in four formats: FloatingPoint, Integer, Hexadecimal, Octal.

The current value is obtained via getCurrentValue() and specified via setCurrentValue().

==== Editbox ====
An Editbox widget controls printable character values; letters, numbers, punctuations, and symbols.

The maximal number of characters that can be specified is bound by setMaxTextLength(). The value can be set to readable only (modifications by users are not allowed) via setReadOnly(true). The value can be masked via setTextMasked() and the default value of * can be modified via setMaskCodePoint().

The current value can be obtained via getText() and specified via setText().

==== Slider ====
A Slider widget controls a numerical value (float) through the position of a "thumb".

This value is bounded within a maximum by setMaxValue(); the minimum value is set to 0.0f. The thumb can be dragged to the desired position or moved by clicking on either side of the thumb. The increment or decrement value is set by setClickStep().

The current value can be obtained via getCurrentValue() and specified via setCurrentValue().

==== Scrollbar ====
A Scrollbar widget controls a numerical value (float) through the position of a "thumb".

This value is bounded within a maximum by setDocumentSize(); the minimum value is set to 0.0f. The thumb can be dragged to the desired position or moved by clicking on either side of the thumb. The increment or decrement value is set by setPageSize(). The arrow buttons increment or decrement the value by the amount specified with setStepSize().

The current value can be obtained via getScrollPosition() and specified via setScrollPosition(). Note that the actual maximum value that the scrollbar will return is set by the following formula: document_size - page_size. Thus, a document of size 100 and a page size of 10 will have a value from 0 to 90.

==== MultiLineEditbox ====
A MultiLineEditbox widget controls printable character values; letters, numbers, punctuations, and symbols.

Unlike the Editbox widget there is no maximal number of characters that can be specified. The value can be set to readable only (modifications by users are not allowed) via setReadOnly(true). Text can be automatically wrapped via a call to setWordWrapping(true).

The current value can be obtained via getText() and specified via setText().

==== RadioButton ====
A RadioButton widget controls a single selection among many choices.

The choices are grouped by calling setGroupID(). Only one RadioButton per group ID can be selected; this widget does not support multiple selection. However it is possible for a choice to possess no decision; initially every RadioButton of a group is unselected.

The currently selected RadioButton can be obtained via getSelectedButtonInGroup(). This RadioButton pointer can then be used to query the ID via getID(), the text (visible label of the RadioButton) via getText(), or user data via getUserData(). A RadioButton can be selected via setSelected(true). Passing false will deselect the RadioButton, potentially making every RadioButton of the group unselected.

==== Listbox ====
A Listbox widget controls either a single selection or multiple selections among many choices. Multiple selections are enabled via setMultiselectEnabled().

The choices are listbox text items (ListboxTextItem) added to the listbox via addItem(). These do not possess a selection indicator by default; one must be specified via setSelectionBrushImage(). The call to ensureItemIsVisible() ensures that the item is visible; the listbox will automatically scroll down if necessary. The text of the ListboxTextItem can be changed via the setText() function. However this new text will not be displayed until you call the Listbox's handleUpdatedItemData() function.

The selected ListboxItem can be obtained via getFirstSelectedItem() and subsequent selections through getNextSelected(). A selection can be specified via setItemSelectState().

It is possible for a Listbox to contain list items that are not simply composed of text. [http://www.cegui.org.uk/wiki/index.php/Create_a_CheckListboxItem CheckListboxItem] demonstrates this advanced feature. Another approach would be to simulate the behavior of a listbox such that each row is composed of various widgets. [[PseudoListbox]] demonstrates this.

==== Combobox ====
A Combobox widget controls a single selection among many choices.

The choices are listbox text items (ListboxTextItem) added to the combobox via addItem(). These do not possess a selection indicator by default; one must be specified via setSelectionBrushImage().

The value of the text within the Editbox can be obtained via getText() and the last selected ListboxItem can be obtained via getSelectedItem(). However there is no guarantee that both are synchronized; typing text within the Editbox will not automatically select the corresponding ListboxItem. Fortunately the reverse is not true; selecting a ListboxItem will place that text within the Editbox. Placing the Editbox in read-only mode with setReadOnly(true) can avoid problems. The current value can be specified via listboxTextItem->setSelected(true) and a setText(itemCombobox->getText()).

==== MultiColumnList ====
A MultiColumnList widget controls controls either a single selection or multiple selections among many choices. Multiple selections are enabled via setSelectionMode(MultiColumnList::RowMultiple).

A MultiColumnList widget may contain a single column or multiple columns. Columns are added via addColumn(), specifying a label, a column ID, and a column width.

Three steps are required to add a row. The first step is to add a new row with addRow(). The second step is to create a ListboxTextItem for each cell of the row and specify the selection indicator via setSelectionBrushImage(). The third step is to add the newly created ListboxTextItem to the MultiColumnList via setItem(), specifying the ListboxTextItem, the column ID, and the row ID.

The selected row can be obtained via getFirstSelectedItem() and subsequent selections through getNextSelected(). This will iterate through every selected cell, returning each selected ListboxTextItem . A selection can be specified via setItemSelectState(); by setting the selection mode to rows (either RowSingle or RowMultiple) you actually only need to select the ListboxTextItem of the first column.

==== TabControl ====
A TabControl widget allows multiple windows to be displayed one at a time, via tab buttons.

Two objects must be created within the Layout Editor to generate a functional tab control. The first is a window of type "TabControl". This will be the parent window of the tab buttons as well as the pages. The second is a window of type "DefaultWindow". This window will be placed within the TabControl (in code via addTab(), not through the Layout Editor) and will specify the contents of a page. Widgets are to be placed within these TabPane via the Layout Editor. The "TabButton" windows are not to be specified via the Layout Editor since they will be automatically created when a TabPane is added to the TabControl.

In this demo the TabControl widget was placed within a FrameWindow. This is not a requirement. It could have just easily been placed alongside the widgets of the other window.

==== Menu & Popup Menu ====

See [[Menu and Popup]]

=== Files ===

==== WidgetGalore.h ====
<source lang="cpp">
#ifndef _WidgetGalore_h_
#define _WidgetGalore_h_

#include "CEGuiSample.h"
#include "CEGUI.h"

class DemoSample : public CEGuiSample
{
public:
bool initialiseSample()
{
using namespace CEGUI;
try
{
// Retrieve the window manager
WindowManager& winMgr = WindowManager::getSingleton();

// Load the TaharezLook scheme and set up the default mouse cursor and font
SchemeManager::getSingleton().loadScheme("TaharezLook.scheme");
System::getSingleton().setDefaultMouseCursor("TaharezLook", "MouseArrow");
if(!FontManager::getSingleton().isFontPresent("Commonwealth-10"))
FontManager::getSingleton().createFont("Commonwealth-10.font");

// Set the GUI Sheet
Window* sheet = winMgr.createWindow("DefaultWindow", "root_wnd");
System::getSingleton().setGUISheet(sheet);

// Load a layout
Window* guiLayout = winMgr.loadWindowLayout("WidgetGalore.layout");
sheet->addChildWindow(guiLayout);

/* Tooltip */
System::getSingleton().setDefaultTooltip("TaharezLook/Tooltip"); // Set the name of the default tooltip
Tooltip* tooltip = System::getSingleton().getDefaultTooltip();
tooltip->setHoverTime(0.5f); // Display the tooltip after the mouse has been hovering over the widget for half a second
tooltip->setDisplayTime(10.0f); // Display for 15 seconds then disappear
tooltip->setFadeTime(1.0f); // Duration of the transition between fully visible and fully invisible
// To set the tooltip text for a window simply call setTooltipText() see staticText for an example

/* StaticText */
DefaultWindow* staticText = static_cast<DefaultWindow*>(winMgr.getWindow("StaticText"));
staticText->setText("Red Static Text");
// Colors are specified as aarrggbb in Hexadecimal
// Where aa is alpha, rr is red, gg is green, and bb is blue
// tl: top left, tr: top right, bl: bottom left, br: bottom right
staticText->setProperty("TextColours", "tl:FFFF0000 tr:FFFF0000 bl:FFFF0000 br:FFFF0000");
staticText->setProperty("VertFormatting", "VertCentred"); // TopAligned, BottomAligned, VertCentred
staticText->setProperty("HorzFormatting", "HorzCentred"); // LeftAligned, RightAligned, HorzCentred
// HorzJustified, WordWrapLeftAligned, WordWrapRightAligned, WordWrapCentred, WordWrapJustified
staticText->setTooltipText("This is a StaticText widget");

/* StaticImage */
ImagesetManager::getSingleton().createImagesetFromImageFile("ImageForStaticImage", "GPN-2000-001437.tga");
DefaultWindow* staticImage = static_cast<DefaultWindow*>(winMgr.getWindow("StaticImage"));
staticImage->setProperty("Image", "set:ImageForStaticImage image:full_image"); // "full_image" is a default name from CEGUIImageset::Imageset()

/* ProgressBar */
ProgressBar* progressBar = static_cast<ProgressBar*>(winMgr.getWindow("ProgressBar"));
progressBar->setProgress(0.25f); // Initial progress of 25%
progressBar->setStepSize(0.10f); // Calling step() will increase the progress by 10%
progressBar->step(); // Advance the progress by the size specified in setStepSize()
progressBar->adjustProgress(-0.05f); // Adjust the progress by a delta value rather than setting a new value through setProgress
float valueProgressBar = progressBar->getProgress(); // initial 0.25f + step 0.10f - adjustment 0.05f = 0.30f

/* Button */
PushButton* btnClose = static_cast<PushButton*>(winMgr.getWindow("btnClose"));
btnClose->setText("Exit");

/* ScrollablePane */
ScrollablePane* scrollablePane = static_cast<ScrollablePane*>(winMgr.getWindow("ScrollablePane"));
ImagesetManager::getSingleton().createImagesetFromImageFile("ImageForScrollablePane", "GPN-2000-001437.tga");
DefaultWindow* staticImageInScrollablePane = static_cast<DefaultWindow*>(winMgr.createWindow("TaharezLook/StaticImage", "StaticImageInScrollablePane"));
staticImageInScrollablePane->setProperty("Image", "set:ImageForScrollablePane image:full_image"); // "full_image" is a default name from CEGUIImageset::Imageset()
staticImageInScrollablePane->setPosition(UVector2(UDim(0.0f, 0.0f), UDim(0.0f, 0.0f))); // Start in the upper left corner
staticImageInScrollablePane->setWidth(UDim(2.0f, 0.0f)); // Twice the width of the parent, the ScrollablePane
staticImageInScrollablePane->setHeight(UDim(2.0f, 0.0f)); // Twice the height of the parent, the ScrollablePane
scrollablePane->addChildWindow(staticImageInScrollablePane); // Add the image to the // Twice the width of the parent, the ScrollablePane
Editbox* editboxInScrollablePane = static_cast<Editbox*>(winMgr.createWindow("TaharezLook/Editbox", "EditboxInScrollablePane"));
editboxInScrollablePane->setPosition(UVector2(UDim(0.0f, 0.0f), UDim(2.1f, 0.0f))); // Start below the image
editboxInScrollablePane->setWidth(UDim(2.0f, 0.0f));
editboxInScrollablePane->setHeight(UDim(0.3f, 0.0f));
scrollablePane->addChildWindow(editboxInScrollablePane);

/* Check box */
Checkbox* checkbox = static_cast<Checkbox*>(winMgr.getWindow("Checkbox"));
checkbox->setSelected( true );
bool valueCheckbox = checkbox->isSelected(); // Retrieve whether it is checked

/* Spinner */
Spinner* spinner = static_cast<Spinner*>(winMgr.getWindow("Spinner"));
spinner->setTextInputMode(Spinner::FloatingPoint); // FloatingPoint, Integer, Hexadecimal, Octal
spinner->setMinimumValue(-10.0f);
spinner->setMaximumValue(10.0f);
spinner->setStepSize(0.2f);
spinner->setCurrentValue(5.2f);
float valueSpinner = spinner->getCurrentValue(); // Retrieve the value

/* Editbox */
Editbox* editbox = static_cast<Editbox*>(winMgr.getWindow("Editbox"));
editbox->setText("Editbox values");
editbox->setMaxTextLength(13); // The trailing 's' will not be displayed
editbox->setReadOnly(false);
editbox->setTextMasked(false);
editbox->setMaskCodePoint(0x002A); // *
String valueEditbox = editbox->getText(); // Retrieve the text

/* Slider */
Slider* slider = static_cast<Slider*>(winMgr.getWindow("Slider"));
slider->setMaxValue(100.0f);
slider->setClickStep(10.0f);
slider->setCurrentValue(20.0f);
float valueSlider = slider->getCurrentValue(); // Retrieve the value

/* Scrollbar (Horizontal) */
Scrollbar* scrollbarHorizontal = static_cast<Scrollbar*>(winMgr.getWindow("HorizontalScrollbar"));
scrollbarHorizontal->setDocumentSize(100.0f);
scrollbarHorizontal->setPageSize(10.0f);
scrollbarHorizontal->setStepSize(1.0f);
scrollbarHorizontal->setScrollPosition(75.0f);
float valueScrollbarHorizontal = scrollbarHorizontal->getScrollPosition(); // Retrieve the scroll position

/* Scrollbar (Vertical) */
Scrollbar* scrollbarVertical = static_cast<Scrollbar*>(winMgr.getWindow("VerticalScrollbar"));
scrollbarVertical->setDocumentSize(100.0f);
scrollbarVertical->setPageSize(10.0f);
scrollbarVertical->setStepSize(1.0f);
scrollbarVertical->setScrollPosition(25.0f);
float valueScrollbarVertical = scrollbarVertical->getScrollPosition(); // Retrieve the scroll position

/* MultiLineEditbox */
MultiLineEditbox* multiLineEditbox = static_cast<MultiLineEditbox*>(winMgr.getWindow("MultiLineEditbox"));
multiLineEditbox->setText("MultiLineEditbox value");
multiLineEditbox->setReadOnly(false);
multiLineEditbox->setWordWrapping(true);
String valueMultiLineEditbox = multiLineEditbox->getText(); // Retrieve the text

/* RadioButton */
RadioButton* radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_A"));
radioButton->setGroupID(1);
radioButton->setID(101);
radioButton->setSelected(true);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_B"));
radioButton->setGroupID(1);
radioButton->setID(102);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_C"));
radioButton->setGroupID(1);
radioButton->setID(103);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_1"));
radioButton->setGroupID(2);
radioButton->setID(201);
radioButton->setSelected(true);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_2"));
radioButton->setGroupID(2);
radioButton->setID(202);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_3"));
radioButton->setGroupID(2);
radioButton->setID(203);
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_A")); // Get handle of one radio button from the group
uint valueRadioButtonLetters = radioButton->getSelectedButtonInGroup()->getID(); // Get selected ID
radioButton = static_cast<RadioButton*>(winMgr.getWindow("RadioButton_3")); // Can obtain the handle of any radio button in the group
uint valueRadioButtonNumbers = radioButton->getSelectedButtonInGroup()->getID();
radioButton->setSelected(true); // Specify which button should appear selected by default

/* Listbox */
Listbox* listbox = static_cast<Listbox*>(winMgr.getWindow("Listbox"));
listbox->setMultiselectEnabled(false);
ListboxTextItem* itemListbox = new ListboxTextItem("Value A", 1);
itemListbox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listbox->addItem(itemListbox);
itemListbox = new ListboxTextItem("Value B", 2);
itemListbox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listbox->addItem(itemListbox);
itemListbox = new ListboxTextItem("Value C", 3);
itemListbox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listbox->addItem(itemListbox);
itemListbox = new ListboxTextItem("Value D", 4);
itemListbox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
listbox->addItem(itemListbox);
listbox->setItemSelectState(itemListbox, true);
listbox->ensureItemIsVisible(itemListbox);
uint valueListbox = listbox->getFirstSelectedItem()->getID(); // Retrieve the ID of the selected listbox item

/* Combobox */
Combobox* combobox = static_cast<Combobox*>(winMgr.getWindow("Combobox"));
combobox->setReadOnly(true);
ListboxTextItem* itemCombobox = new ListboxTextItem("Value 1", 1);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
combobox->addItem(itemCombobox);
itemCombobox = new ListboxTextItem("Value 2", 2);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
combobox->addItem(itemCombobox);
itemCombobox->setSelected(true); // Select this item
combobox->setText(itemCombobox->getText()); // Copy the item's text into the Editbox
itemCombobox = new ListboxTextItem("Value 3", 3);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
combobox->addItem(itemCombobox);
itemCombobox = new ListboxTextItem("Value 4", 4);
itemCombobox->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
combobox->addItem(itemCombobox);
String valueCombobox = combobox->getText(); // Retrieve the displayed text
uint idCombobox = combobox->getSelectedItem()->getID(); // Retrieve the ID of the selected combobox item

/* MultiColumnList */
MultiColumnList* multiColumnList = static_cast<MultiColumnList*>(winMgr.getWindow("MultiColumnList"));\
multiColumnList->addColumn("Col A", 0, UDim(0.32f, 0));
multiColumnList->addColumn("Col B", 1, UDim(0.32f, 0));
multiColumnList->addColumn("Col C", 2, UDim(0.32f, 0));
multiColumnList->setSelectionMode(MultiColumnList::RowSingle); // MultiColumnList::RowMultiple
ListboxTextItem* itemMultiColumnList;
multiColumnList->addRow();
itemMultiColumnList = new ListboxTextItem("A1", 101);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 0, 0); // ColumnID, RowID
itemMultiColumnList = new ListboxTextItem("B1", 102);
//itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
// By commenting the line above a cell does not specify a selection indicator
// selecting that line will show a "gap" in the selection.
multiColumnList->setItem(itemMultiColumnList, 1, 0); // ColumnID, RowID
itemMultiColumnList = new ListboxTextItem("C1", 103);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 2, 0); // ColumnID, RowID
multiColumnList->addRow();
itemMultiColumnList = new ListboxTextItem("A2", 201);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 0, 1); // ColumnID, RowID
itemMultiColumnList = new ListboxTextItem("B2", 202);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 1, 1); // ColumnID, RowID
itemMultiColumnList = new ListboxTextItem("C2", 203);
itemMultiColumnList->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
multiColumnList->setItem(itemMultiColumnList, 2, 1); // ColumnID, RowID
MCLGridRef grid_ref(1, 0); // Select according to a grid reference; second row
multiColumnList->setItemSelectState(grid_ref, true);
ListboxItem* listboxItem = multiColumnList->getFirstSelectedItem();
uint valueColumnA = listboxItem->getID(); // Retrieve the value of the selected item from column A
listboxItem = multiColumnList->getNextSelected(listboxItem);
uint valueColumnB = listboxItem->getID(); // Retrieve the value of the selected item from column B
listboxItem = multiColumnList->getNextSelected(listboxItem);
uint valueColumnC = listboxItem->getID(); // Retrieve the value of the selected item from column C

/* TabControl */
TabControl* winTabControl = static_cast<TabControl*>(winMgr.getWindow("TabControl"));
winTabControl->setTabHeight(UDim(0.15f, 0.0f)); // Make the tab buttons a little bigger
Window* tabPage = winMgr.getWindow("TabPane1");
tabPage->setText("Page 1");
tabPage->setSize(UVector2(UDim(1.0f, 0.0f), UDim(1.0f, 0.0f))); // Size to 100% of its parent, the TabControl
tabPage->setPosition(UVector2(UDim(0.0f, 0.0f), UDim(0.0f, 0.0f))); // Move to the upper left corner of its parent
winTabControl->addTab(tabPage);
tabPage = winMgr.getWindow("TabPane2");
tabPage->setText("Page 2");
tabPage->setSize(UVector2(UDim(1.0f, 0.0f), UDim(1.0f, 0.0f)));
tabPage->setPosition(UVector2(UDim(0.0f, 0.0f), UDim(0.0f, 0.0f)));
winTabControl->addTab(tabPage);

}
catch(Exception &e)
{
#if defined( __WIN32__ ) || defined( _WIN32 )
MessageBox(NULL, e.getMessage().c_str(), "Error initializing the demo", MB_OK | MB_ICONERROR | MB_TASKMODAL);
#else
std::cerr << "Error initializing the demo:" << e.getMessage().c_str() << "\n";
#endif
}

return true;
}

void cleanupSample(void)
{
}
};

#endif // _WidgetGalore_h_
</source>

==== main.cpp ====
<source lang="cpp">
#if defined( __WIN32__ ) || defined( _WIN32 )
#define WIN32_LEAN_AND_MEAN
#define NOMINMAX
#include "windows.h"
#endif

#include "WidgetGalore.h"

#if defined( __WIN32__ ) || defined( _WIN32 )
int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine,int nCmdShow)
#else
int main(int argc, char *argv[])
#endif
{
DemoSample app;
return app.run();
}
</source>

==== WidgetGalore.layout ====
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<GUILayout >
<Window Type="DefaultWindow" Name="Root" >
<Property Name="Text" >1</Property>
<Property Name="InheritsAlpha" Value="False" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0,0},{0,0},{1,0},{1,0}}" />
<Window Type="DefaultWindow" Name="TabPane2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.72875,0},{0.7185,0},{0.97875,0},{0.9685,0}}" />
<Window Type="TaharezLook/StaticText" Name="StaticTextPage2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >In Page 2:</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.06,0},{0.226667,0},{0.415,0},{0.476667,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="EditBoxPage2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.420001,0},{0.22,0},{0.99,0},{0.47,0}}" />
</Window>
</Window>
<Window Type="TaharezLook/FrameWindow" Name="winTabControl" >
<Property Name="Text" >Tab Control Window</Property>
<Property Name="TitlebarFont" Value="Commonwealth-10" />
<Property Name="CaptionColour" Value="00FFFFFF" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.695627,0},{0.2725,0},{0.993122,0},{0.704167,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
<Window Type="TaharezLook/TabControl" Name="TabControl" >
<Property Name="TabHeight" Value="{0,0}" />
<Property Name="TabTextPadding" Value="{0,0}" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.088566,0},{0.174378,0},{0.931404,0},{0.804637,0}}" />
</Window>
<Window Type="TaharezLook/Button" Name="btnOk" >
<Property Name="Text" >Ok</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.128412,0},{0.841464,0},{0.365583,0},{0.926003,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Button" Name="btnCancel" >
<Property Name="Text" >Cancel</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.400429,0},{0.841464,0},{0.637601,0},{0.926003,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Button" Name="btnApply" >
<Property Name="Text" >Apply</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.668224,0},{0.843977,0},{0.905394,0},{0.928516,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
</Window>
<Window Type="DefaultWindow" Name="TabPane1" >
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="ClippedByParent" Value="False" />
<Property Name="UnifiedAreaRect" Value="{{0.72875,0},{0.012178,0},{0.97875,0},{0.262178,0}}" />
<Window Type="TaharezLook/StaticText" Name="StaticTextPage1" >
<Property Name="Text" >In Page 1:</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.06,0},{0.226667,0},{0.415,0},{0.476667,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="EditBoxPage1" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.420001,0},{0.22,0},{0.99,0},{0.47,0}}" />
</Window>
</Window>
<Window Type="TaharezLook/FrameWindow" Name="winWidgets" >
<Property Name="Text" >Dave, it's full of widgets!</Property>
<Property Name="TitlebarFont" Value="Commonwealth-10" />
<Property Name="CaptionColour" Value="00FFFFFF" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="TitlebarEnabled" Value="True" />
<Property Name="UnifiedAreaRect" Value="{{0.00375,0},{0.143333,0},{0.751248,0},{0.806665,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
<Window Type="TaharezLook/Button" Name="btnClose" >
<Property Name="Text" >Close</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.732397,0},{0.895137,0},{0.976465,0},{0.975697,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Editbox" Name="Editbox" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.62442,0},{0.090471,0},{0.969776,0},{0.153443,0}}" />
</Window>
<Window Type="TaharezLook/Checkbox" Name="Checkbox" >
<Property Name="Text" >Check</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.396859,0},{0.944201,0},{0.453147,0}}" />
</Window>
<Window Type="TaharezLook/Combobox" Name="Combobox" >
<Property Name="Text" >Combo Box</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.090471,0},{0.613522,0},{0.413287,0}}" />
<Property Name="MaxEditTextLength" Value="1073741823" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_A" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >A</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.652856,0},{0.189876,0},{0.704964,0},{0.246164,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_B" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >B</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.707569,0},{0.189876,0},{0.759678,0},{0.246164,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_C" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >C</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.761542,0},{0.189876,0},{0.813651,0},{0.246164,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_1" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >1</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.189876,0},{0.897272,0},{0.246164,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >2</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.245152,0},{0.897272,0},{0.30144,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioButton_3" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" >3</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.300429,0},{0.897272,0},{0.356717,0}}" />
</Window>
<Window Type="TaharezLook/HorizontalScrollbar" Name="HorizontalScrollbar" >
<Property Name="PageSize" Value="0" />
<Property Name="StepSize" Value="1" />
<Property Name="OverlapSize" Value="0" />
<Property Name="DocumentSize" Value="1" />
<Property Name="ScrollPosition" Value="0" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.185427,0},{0.613522,0},{0.26206,0}}" />
</Window>
<Window Type="TaharezLook/VerticalScrollbar" Name="VerticalScrollbar" >
<Property Name="PageSize" Value="0" />
<Property Name="StepSize" Value="1" />
<Property Name="OverlapSize" Value="0" />
<Property Name="DocumentSize" Value="1" />
<Property Name="ScrollPosition" Value="0" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.026087,0},{0.090471,0},{0.082106,0},{0.606802,0}}" />
</Window>
<Window Type="TaharezLook/Listbox" Name="Listbox" >
<Property Name="Text" >List Box</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.626634,0},{0.427903,0},{0.876634,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
</Window>
<Window Type="TaharezLook/MultiColumnList" Name="MultiColumnList" >
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.271357,0},{0.816779,0},{0.551507,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
</Window>
<Window Type="TaharezLook/MultiLineEditbox" Name="MultiLineEditbox" >
<Property Name="Text" >
</Property>
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.462498,0},{0.626634,0},{0.706566,0},{0.876634,0}}" />
</Window>
<Window Type="TaharezLook/ProgressBar" Name="ProgressBar" >
<Property Name="StepSize" Value="0.01" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="CurrentProgress" Value="0" />
<Property Name="UnifiedAreaRect" Value="{{0.183835,0},{0.559296,0},{0.816779,0},{0.608291,0}}" />
</Window>
<Window Type="TaharezLook/Slider" Name="Slider" >
<Property Name="CurrentValue" Value="0" />
<Property Name="MaximumValue" Value="1" />
<Property Name="ClickStepSize" Value="0.01" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.099415,0},{0.090471,0},{0.155434,0},{0.606802,0}}" />
</Window>
<Window Type="TaharezLook/Spinner" Name="Spinner" >
<Property Name="StepSize" Value="1" />
<Property Name="CurrentValue" Value="0" />
<Property Name="MaximumValue" Value="32767" />
<Property Name="MinimumValue" Value="-32768" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.845164,0},{0.48995,0},{0.944201,0},{0.551507,0}}" />
</Window>
<Window Type="TaharezLook/StaticImage" Name="StaticImage" >
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.732397,0},{0.626634,0},{0.976465,0},{0.876634,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="StaticText" >
<Property Name="Text" >Static Text</Property>
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.462498,0},{0.895137,0},{0.706566,0},{0.975697,0}}" />
</Window>
<Window Type="TaharezLook/ScrollablePane" Name="ScrollablePane" >
<Property Name="ContentArea" Value="l:0 t:0 r:0 b:0" />
<Property Name="HorzStepSize" Value="0.1" />
<Property Name="VertStepSize" Value="0.1" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="HorzOverlapSize" Value="0.01" />
<Property Name="UnifiedAreaRect" Value="{{0.019063,0},{0.629399,0},{0.157023,0},{0.879399,0}}" />
<Property Name="VertOverlapSize" Value="0.01" />
<Property Name="HorzScrollPosition" Value="0" />
<Property Name="VertScrollPosition" Value="0" />
</Window>
</Window>
</Window>
</GUILayout>
</source>

[[Category:Manuals]]
[[Category:Update requested]]

SDL to CEGUI keytable

2011-03-03T23:51:30Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.4}} {{VersionBadge|0.5}} {{VersionBadge|0.6}} {{VersionBadge|0.7}}

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.

<source lang="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;
}
</source>

Usage is like so:

<source lang="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);
}
}
</source>

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

[[Category:HowTo]]

Overview of GUI files

2011-03-03T23:51:20Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

There are a lot of files that go into creating a GUI with CEGUI. Here is an overview (thanks to lindquist for the original version). An expanded version of this brief overview would be quite useful.

== Overview of CEGUI resource files ==
=== '''.imageset Files''' ===
An imageset is an xml file describing a set of images contained in an image file.
When an imageset is loaded, images from that file become available to the application via the [http://www.cegui.org.uk/api_reference/classCEGUI_1_1ImagesetManager.html ImagesetManager].

Editor: [http://www.cegui.org.uk/phpBB2/viewtopic.php?t=1346 CEImagesetEditor in the works by Martignasse.]

=== '''[[Scheme files]]''' ===
A scheme file is an xml file describing the binding of widgets defined in a looknfeel file and the base Falagard widget set. Once loaded the components in the scheme file are available via the [http://www.cegui.org.uk/api_reference/classCEGUI_1_1WindowManager.html WindowManager]. A detailed description of [[Scheme files]] is also available.

Editor: none

=== '''.looknfeel Files''' ===
These are also xml files, which define the visual aspect of widgets declared in the scheme file.

Editor: none

=== '''.layout Files''' ===
A layout file is also in xml format. It describes a set of widgets to create and their positions, sizes, and other attributes. Basically this describes the final on-screen layout of your GUI, hence the name.

Editor: [[The "official" layout editor]]

=== '''.font Files''' ===
These simple xml files give the location of a font file (like a TrueType .ttf file) and define a few extra properties about how CEGUI should use that font.

Editor:

== About [[Falagard Skinning System Documentation]] ==
Falagard is the part of the API that makes it possible to create a completly new set of widgets (at the visual level) from xml files.

You can, with a looknfeel, describe a widget and make it appear as you want (by using images defined in some imageset) and finally bind it to one of the widgets from a Falagard Base widget set in a scheme file.

Link: [[Falagard Skinning System Documentation]]

== Related Documents ==
* [[XML File formats]] - Detailed documentation of the various XML file formats.

[[Category:Manuals]]

Obtaining the library source from Subversion

2011-03-03T23:51:10Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

{{VersionBadge|0.7}} {{VersionBadge|0.6}} {{VersionBadge|0.5}} {{VersionBadge|0.4}}

{{notice|message=We now use Mercurial so this page can be considered obsolete for versions >= 0.7}}

{{notice|message=Much of this information has been incorporated into the official developer documentation, see [http://www.cegui.org.uk/docs/current/downloading.html Obtaining the code] and [http://www.cegui.org.uk/docs/current/compiling.html Supported systems and compilation]}}

== Abstract ==

PLEASE note: if you'd rather use precreated releases (tarballs or SDKs), please follow [[Downloads]].

All the code for CrazyEddie's GUI System (and its tools) is kept in a revision control system known as [[Subversion]](SVN). This is a tool that allows us to easily track changes to the code (who did what, and when), to maintain multiple different versions (branches) for the code, and, where necessary, undo, revert, or merge code changes. This page explains the URLs of these repositories.

== Branches and trunks ==

Generally speaking, each stable release series has a seperate branch, and any changes made on those branches are largely bug-fixes and non-breaking (where possible) changes. The main 'trunk', or HEAD, code is where the latest and greatest code can be found, although this version of the code is generally to be considered as unstable / testing code. On the whole, we maintain two branches at once; whichever is the latest 'stable' branch, and the main trunk code. When a new release is made, previous release branches are generally considered obsolete (this will continue at least until we reach version 1.0.0 - at this stage we may consider maintaining support for multiple released versions).

== Accessing Subversion ==

It is possible to browse the SVN repository online by visiting http://crayzedsgui.svn.sourceforge.net/viewvc/crayzedsgui/cegui_mk2/
However, in order to actually compile the code you need to get the sources on your machine. On Linux you'd use the 'svn' command, and on Windows we'd suggest the [http://tortoisesvn.tigris.org/ Tortoise SVN Client] utility, which nicely integrates with your Explorer. Note that the 'svn' command expects the local target directory in the command, where TortoiseSVN expects it in an editbox of its interface. Either way, the URLs mentioned next will be the same. Note the '''s''''s; the repository has a secure URL. Retreiving is always "anonymous", so it should work immediately.

== The URLs ==

'''From the commandline'''
* ''CEGUI itself'':
** For the current stable version code:<br /><pre>svn co https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/branches/v0-7 cegui_mk2-0-7</pre>
** For the cutting edge, unstable development version code:<br /><pre>svn co <nowiki>https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk</nowiki> cegui_mk2-trunk</pre>

* ''CEGUI Layout Editor:''
** For the current stable version code:<br /><pre>svn co https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/branches/v0-6-1 LayoutEditor</pre>
** For the cutting edge, unstable development version code:<br /><pre>svn co https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk LayoutEditor</pre>

* ''CEGUI Imageset Editor:''
** For the current stable version code:<br /><pre>svn co https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CEImagesetEditor/tags/v0-6-1 ImagesetEditor</pre>
** For the cutting edge, unstable development version code:<br /><pre>svn co https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CEImagesetEditor/trunk ImagesetEditor</pre>

'''From TortoiseSVN'''
* ''CEGUI itself:''
** For the current stable version code:<br /><pre>https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/branches/v0-7</pre>
** For the cutting edge, unstable development version code:<br /><pre>https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk</pre>
* ''CEGUI Layout Editor:''
** For the current stable version code:<br /><pre>https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/branches/v-0-6-1</pre>
** For the cutting edge, unstable development version code:<br /><pre>https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk</pre>
* ''CEGUI Imageset Editor:''
** For the current stable version code:<br /><pre>https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CEImagesetEditor/tags/v0-6-1</pre>
** For the cutting edge, unstable development version code:<br /><pre>https://crayzedsgui.svn.sourceforge.net/svnroot/crayzedsgui/CEImagesetEditor/trunk</pre>

== TODO: What's next ==
Now that you have the sources locally available, it's time to compile them. Depending on your OS, please follow one of the following links:
* For Windows, click here: <link here>
* For Linux, click here: <link here>
* For Mac OS, click here: <link here>

= Compiling on Windows =
Now that you have the code, you probably want to compile it :)

On windows, Premake is used to create project and solution files for different versions of Visual Studio. These files can be found in the directory 'makefiles/premake'. Per supported Visual Studio version there is one batch file for CEGUI itself, and one for the samples. After running a batch file, a corresponding .sln file is written in the same directory, which you can open.

= Compiling on Linux =

The first thing to do is to run bootstrap, which will run automake, autoconf, and various other tools to initialise the build environment and create the main configure script. If you have problems with bootstrap, make sure you're using a recent version of automake (1.9 is known to work).

./bootstrap

Now you should be on familiar territorty. To configure the build, run configure:

./configure

There are various things you can change about the way the system is built, to get information about these options, pass the --help option to configure like so:

./configure --help

Once configure has run successfully, you need to run make as usual:

make

And finall, install as root:

su <and enter password ;) >
make install

= Compiling for the Ogre3D Engine / Compiling the OgreRenderer =

[[Building CEGUI for Ogre / OgreRenderer]]

= Documentation =
Since you are using the library from SVN instead of using the precreated packages, you need to get the documentation by yourself. Please follow [[Documentation]].

[[Category:HowTo]]

Layout files

2011-03-03T23:51:00Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

For the time being, this has been copy-and-pasted directly from "readme.txt" in the XMLRefSchema directory of the CEGUI source code. Some prettier formatting along the lines of '''[[Scheme files]]''' would be nice.

<pre>
A GUI Layout defines a hierachy of Window based objects to be created and a property settings for each window.
The root element is GUILayout.

GUILayout Element
=================
GUILayout is the root element.
The GUILayout must contain a single Window element only.

GUILayout attributes
--------------------
Parent - Specifies the name of an existing window that this gui layout should be attached to (optional).

Window Element
==============
The Window element is used to specify a new window object to be created.
The Window element has attributes as described below and may contain any number of nested Window elements, any number of Property elements,
any number of LayoutImport elements, and any number of Event elements.

Window attributes
-----------------
Type - Specifies the type of Window object to be created (required).
Name - Specifies the unique name for the Window. If this is ommitted a name will be generated. If a window with the name already exists, an exception will be thrown. (optional).

Property Element
================
The Property element is used to set properties on the Window created by the containing Window element.
Property has no sub-elements, but has attributes as described below.

Property attributes
-------------------
Name - The name of the property to be set. If no such property exists for the target window, an exception may be thrown. (required).
Value - The value to be assigned to the property. This must be in a format expected by the property or an exception may be thrown. (required).

LayoutImport Element
====================
The LayoutImport element is used to reference (import) a layout file into another. The root window of the imported layout is attached to the Window where the import occurrs.
The LayoutImport element has attributes but no sub-elements.

LayoutImport attributes
-----------------------
Filename - Specifies the filename of the layout XML file to be imported.
ResourceGroup - The resource group identifier to pass to the resource provider when loading the file.

Event Element
=============
The Event element is used to create bindings between Gui elements and script functions.
The Event element has attributes but no sub-elements.

Event attributes
----------------
Name - Specifies the name of the target event.
Function - Specifies the name of the script function that is to be bound to the event.
</pre>

[[Category:Manuals]]
[[Category:NeedsRefinement]]

Introduction To Auto Windows

2011-03-03T23:50:51Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

=== Introduction ===
The purpose of this article is to highlight the "Auto Window" and demonstrate a couple of the advanced possibilities that they enable within Crazy Eddie's GUI System. The article will introduce the concept of the auto window, show where it is used in the unmodified system, and then go on to demonstrate how the developer can make use of the same ideas to solve certain problems.

=== What is an Auto Window? ===
If you have used CEGUI at all, chances are that you have already used auto windows without knowing it; combo boxes, all the list widgets, and even the scroll bar and frame window are all compound widgets made up of multiple component widgets - those component widgets are classed as auto windows.

An auto window is basically a widget that is created as a child component of another widget type, as defined in the LookNFeel skin by the use of the <Child> tag. Many of the core widgets have requirements for auto windows that must be specified - the frame window for example requires that a titlebar and close button be specified.

It is possible that there may be confusion in relation to LookNFeel specifications and window Layout specifications. It appears there is some crossover of functionality since both provide a means for setting properties, specifying child widgets, and so on; be assured there actually isn't any crossover. The parts of the system that deal with LookNFeel and Layouts are operating at totally different levels. One potentially useful way to look at these two parts of the system is to consider the LookNFeel to specify a class (or maybe a template) for a widget, whilst the Layouts define and specify actual instances of those classes.

=== An Existing Example ===
The first thing we will do is take a look at an existing example. Here is how the titlebar is specified for the WindowsLook frame window:

...
<Child type="WindowsLook/Titlebar" nameSuffix="__auto_titlebar__">
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="Height">
<FontDim type="LineSpacing">
<DimOperator op="Multiply">
<AbsoluteDim value="1.5" />
</DimOperator>
</FontDim>
</Dim>
</Area>
<Property name="AlwaysOnTop" value="False" />
</Child>
...

Since this whole concept may be new to many readers, lets take this first example one part at a time.

To open the definition we use the <Child> tag. Here we need to supply two attributes to specify the type of window to be created and a name suffix to be used. This is telling the system that whenever a widget using this WidgetLook (in this case "WindowsLook/FrameWindow") is created, it should create and attach a child window of the specified type ("WindowsLook/Titlebar") and name that child by appending the given suffix ("__auto_titlebar__") to the base widget name.

In this example, if you create a "WindowsLook/Framewindow" with the name "myWindow", the system will automatically have created a "WindowsLook/Titlebar" named "myWindow__auto_titlebar__" and added it as a child to "myWindow".

Next we can see an <Area> tag. The content in here defines the area that this child is to occupy within its parent (meaning all positions are relative to the parent's position, and scale co-ordinate components are fractions of the size of the parent).

In this example the the title bar is positioned at absolute location (0,0) - so is at the top left of the parent. The right edge is is specified as being a scale value of 1, which means the right edge will always be attached to the right edge of the parent. The height is specified as being 1.5 times the linespacing value of the current font.

Finally we see a <Property> tag. We can list properties here to specify 'defaults' to be used for the component widget in instances of the widget being defined. This provides a means to override default settings that may previously have been specified either in the core system code, or in the WidgetLook for the type being embedded.

In this example we are ensuring that the titlebar is used with the always on top setting disabled.

Note that we have skimmed over some of the specifics of this definition - this article is not intended as a tutorial on the [[Falagard]] system itself, just one specific capability of it.

=== Accessing Auto Windows ===
Now we know what an auto window is and generally how they are created, you may be able to see that it is possible to access these windows directly - afterall they are actually the same as any other child window, just automatically created by the system.

Sticking with the the FrameWindow, you might want to hear about mouse clicks on the title bar and assign a scripted event handler. Your code could look something similar to this:

<source lang="cpp">
...
// get access to the titlebar attached to the frame window "myFrameWindow"
Window* titlebar = WindowManager::getSingleton().getWindow("myFrameWindow__auto_titlebar__");

// attach a scripted event handler to process mouse clicks
titlebar->subscribeScriptedEvent("MouseClick", "handleTitlebarClick");
...
</source>

This is very nice, but requires some code compilation so could be hard to play with and tweak. What we really want to be doing is attaching our event handler from within the layout file like we would in the case of a "normal" window. The CEGUI layout system provides a means for us to target auto windows within the layout file with the <AutoWindow> tag.

The AutoWindow tag takes a single attribute "NameSuffix" which specifies the name suffix of the auto window we wish to target (if we continue our example, this would be "__auto_titlebar__" to target the titlebar of a FrameWindow). The AutoWindow tag may then then contain LayoutImport (yes, you really can import an entire layout as content for an auto window), Property, Event, and other Window and AutoWindow (to target auto windows of auto windows!) tags.

Thus, to attach a scripted event handler to the title bar of a frame window in a layout you could do this:

...
<Window Type="WindowsLook/FrameWindow" Name="myFrameWindow" >
<Property Name="Text" Value="Auto Window Example" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.25,0},{0.25,0},{0.8,0},{0.8,0}}" />

<AutoWindow NameSuffix="__auto_titlebar__" >
<Event Name="MouseClick" Function="handleTitlebarClick" />
</AutoWindow>

</Window>
...

Reiterating, along with the Event tag you could just as easily have specified Property tags to modify the options set for the title bar, or even Window tags to add an extra button for example. The AutoWindow tag effectively allows us to do an auto window anything we can do with a normal window.

=== Making Your Own Auto Windows ===
As already mentioned, various compound widgets in the system have specified requirements for auto windows that must be supplied within the LookNFeel. What you need to consider is that these requirements are a minimum and not an absolute. This affords us the possibility of specifying, via the <Child> tag, additional auto windows of our choosing in the LookNFeel. Effectively this unties our hands and gives total freedom to create any number of new widgets by combining other widgets in various ways. Obviously there will be cases where supporting systems and code are required, but the basic composition and layout of these widgets can be entirely specified in XML.

One of the weaknesses of the FrameWindow as it stands at the moment is that developer added content, that is your buttons and other widgets, are added to the frame window relative to the top-left corner and on an equal standing to the title bar. This can lead to situations where your content is sometimes partially obscured by the titlebar, this can especially be the case if the user may re-size the frame window - things may look fine at the initial size, but quickly go awry when the window is made smaller.

One work around to the frame window issue is to add an absolutely positioned container window in the layout and have the content added to that. On the surface this seems like an ideal solution, but in reality has more issues of its own since it does not allow your layout to remain resolution neutral (2 pixels at 640 x 480 are much larger physically than they are at, say, 1024 x 768). Additionally, changing the size of the titlebar font would not automatically re-size the 'content pane' and so you would need additional processing for that. Ultimately the whole concept breaks down as being not worth the cost.

What is needed is a solution that can remain resolution independent, have some kind of absolute positioning, but also react to changes in the parent window. All of these criteria are met by the basic provisions of the [[Falagard]] system and the auto window approach will give us a reasonable solution.

The rest of the article will develop a frame window type that has a separate client area or content window. Note that the solution developed is not a panacea; there are still potential issues surrounding enabling and disabling of the title bar and window frame, though generally the solution presented will be useful to many.

=== Example Project - NewFrameWindow ===
Basically what we are going to do is to create a new FrameWindow type that uses the auto window system to add a DefaultWindow which covers what is commonly known as the 'client area' of the frame window; that is the area within the window frame and title bar. We can then target content into this client area auto window within layout files.

First let us define a couple of criteria that this new auto window must meet as far as position and size:
* The top edge needs to be glued to the bottom edge of the title bar at all times.
* The other edges need to be within the window sizing frame at all times.

Ok, that seems fairly straight forwards, lets make a start. We'll define the new auto window and its parts outside of any WidgetLook to begin with, this will enable us to focus on the important aspects of what we are doing. At the end the final thing is presented in full along with other supporting material.

First provide the Child tag structure:
<Child type="DefaultWindow" nameSuffix="__auto_clientarea__">
</Child>

Note that the suffix could, in reality, be anything you choose; the use "__auto_<whatever>__" is just the established idiom used within CEGUI itself - so we just continue that here.

Now we need to establish the area to be used by the client area window according to our specifications above. In order to do what is needed we need two pieces of information; the location of the bottom edge of the title bar, and the size of the sizing border. Both are easily obtained. The WidgetDim element in [[Falagard]] allows us to extract information about the location of another widget, and the PropertyDim allows us to extract a setting from the parent window.

We now define the area for the client area window as follows:
<Area>
<Dim type="LeftEdge">
<PropertyDim name="SizingBorderThickness" />
</Dim>
<Dim type="TopEdge">
<WidgetDim widget="__auto_titlebar__" dimension="BottomEdge" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge">
<DimOperator op="Subtract">
<PropertyDim name="SizingBorderThickness" />
</DimOperator>
</UnifiedDim>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge">
<DimOperator op="Subtract">
<PropertyDim name="SizingBorderThickness" />
</DimOperator>
</UnifiedDim>
</Dim>
</Area>

We require no additional settings or options for this window.

To utilise the client area in a layout we now can use XML such as:
<AutoWindow NameSuffix="__auto_clientarea__" >
<Window Type="WindowsLook/Button" Name="myButton">
<Property Name="UnifiedAreaRect" Value="{{0.02,0},{0.01,0},{0.98,0},{0.2,0}}" />
<Property Name="Text" Value="Engage!" />
</Window>
</AutoWindow>

=== Putting It Together ===
In order that you can make use of such a new frame window it all needs to be presented to the system in some way. You could just modify the existing WindowsLook.looknfeel XML file and that would be fine. However, in this section we present the solution in such a way it can be used as an 'add-in' widget which can be used in addition to the existing WindowsLook widgets. This is just one way of doing it, various possibilities exist for the advanced user.

We have the following two files:
* NewFrameWindow.scheme - specifies the required binding to make the widget available in the system
* NewFrameWindow.looknfeel - specifies the LookNFeel specification for the new frame window type

This code snippet shows how you might load in the schemes:
<source lang="cpp">
...
// Note that in order for this to work you need to have loaded the normal
// WindowsLook.scheme.
SchemeManager::getSingleton().loadScheme("WindowsLook.scheme");

// Load in a scheme to setup our new frame window type
SchemeManager::getSingleton().loadScheme("NewFrameWindow.scheme");
...
</source>

==== NewFrameWindow.scheme ====
<?xml version="1.0" ?>
<GUIScheme Name="WindowsLookAdditions">
<LookNFeel Filename="NewFrameWindow.looknfeel" />
<WindowSet Filename="CEGUIFalagardWRBase" />

<FalagardMapping WindowType="WindowsLook/NewFrameWindow"
TargetType="CEGUI/FrameWindow"
Renderer="Falagard/FrameWindow"
LookNFeel="WindowsLook/NewFrameWindow" />

</GUIScheme>

==== NewFrameWindow.looknfeel ====
<?xml version="1.0" ?>
<Falagard>

<WidgetLook name="WindowsLook/NewFrameWindow">
<PropertyLinkDefinition name="CaptionColour" widget="__auto_titlebar__" targetProperty="CaptionColour" initialValue="FF000000" />
<PropertyLinkDefinition name="TitlebarFont" widget="__auto_titlebar__" targetProperty="Font" />
<Property name="NSSizingCursorImage" value="set:WindowsLook image:MouseNoSoCursor" />
<Property name="EWSizingCursorImage" value="set:WindowsLook image:MouseEsWeCursor" />
<Property name="NWSESizingCursorImage" value="set:WindowsLook image:MouseNwSeCursor" />
<Property name="NESWSizingCursorImage" value="set:WindowsLook image:MouseNeSwCursor" />
<NamedArea name="ClientWithTitleWithFrame">
<Area>
<Dim type="LeftEdge">
<ImageDim imageset="WindowsLook" image="WindowFrameLeft" dimension="Width" />
</Dim>
<Dim type="TopEdge">
<WidgetDim widget="__auto_titlebar__" dimension="BottomEdge" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="WindowsLook" image="WindowFrameRight" dimension="Width" />
</DimOperator>
</UnifiedDim>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="WindowsLook" image="WindowFrameBottom" dimension="Height" />
</DimOperator>
</UnifiedDim>
</Dim>
</Area>
</NamedArea>
<NamedArea name="ClientWithTitleNoFrame">
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<WidgetDim widget="__auto_titlebar__" dimension="BottomEdge" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
</NamedArea>
<NamedArea name="ClientNoTitleWithFrame">
<Area>
<Dim type="LeftEdge">
<ImageDim imageset="WindowsLook" image="WindowFrameLeft" dimension="Width" />
</Dim>
<Dim type="TopEdge">
<ImageDim imageset="WindowsLook" image="WindowFrameTop" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="WindowsLook" image="WindowFrameRight" dimension="Width" />
</DimOperator>
</UnifiedDim>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="WindowsLook" image="WindowFrameBottom" dimension="Height" />
</DimOperator>
</UnifiedDim>
</Dim>
</Area>
</NamedArea>
<NamedArea name="ClientNoTitleNoFrame">
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
</NamedArea>
<Child type="DefaultWindow" nameSuffix="__auto_clientarea__">
<Area>
<Dim type="LeftEdge">
<PropertyDim name="SizingBorderThickness" />
</Dim>
<Dim type="TopEdge">
<WidgetDim widget="__auto_titlebar__" dimension="BottomEdge" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge">
<DimOperator op="Subtract">
<PropertyDim name="SizingBorderThickness" />
</DimOperator>
</UnifiedDim>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge">
<DimOperator op="Subtract">
<PropertyDim name="SizingBorderThickness" />
</DimOperator>
</UnifiedDim>
</Dim>
</Area>
</Child>
<Child type="WindowsLook/Titlebar" nameSuffix="__auto_titlebar__">
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="Height">
<FontDim widget="__auto_titlebar__" type="LineSpacing">
<DimOperator op="Multiply">
<AbsoluteDim value="1.5" />
</DimOperator>
</FontDim>
</Dim>
</Area>
<Property name="AlwaysOnTop" value="False" />
</Child>
<Child type="WindowsLook/SystemButton" nameSuffix="__auto_closebutton__">
<Area>
<Dim type="LeftEdge">
<UnifiedDim scale="1" type="LeftEdge">
<DimOperator op="Subtract">
<AbsoluteDim value="0.5">
<DimOperator op="Multiply">
<ImageDim imageset="WindowsLook" image="CloseButtonNormal" dimension="Width">
<DimOperator op="Add">
<WidgetDim widget="__auto_titlebar__" dimension="Height" />
</DimOperator>
</ImageDim>
</DimOperator>
</AbsoluteDim>
</DimOperator>
</UnifiedDim>
</Dim>
<Dim type="TopEdge">
<WidgetDim widget="__auto_titlebar__" dimension="Height">
<DimOperator op="Subtract">
<AbsoluteDim value="0.5">
<DimOperator op="Multiply">
<WidgetDim widget="__auto_titlebar__" dimension="Height">
<DimOperator op="Add">
<ImageDim imageset="WindowsLook" image="CloseButtonNormal" dimension="Height" />
</DimOperator>
</WidgetDim>
</DimOperator>
</AbsoluteDim>
</DimOperator>
</WidgetDim>
</Dim>
<Dim type="Width">
<ImageDim imageset="WindowsLook" image="CloseButtonNormal" dimension="Width" />
</Dim>
<Dim type="Height">
<ImageDim imageset="WindowsLook" image="CloseButtonNormal" dimension="Height" />
</Dim>
</Area>
<Property name="AlwaysOnTop" value="True" />
<Property name="NormalImage" value="set:WindowsLook image:CloseButtonNormal" />
<Property name="HoverImage" value="set:WindowsLook image:CloseButtonHover" />
<Property name="PushedImage" value="set:WindowsLook image:CloseButtonPushed" />
</Child>
<ImagerySection name="withtitle_frame">
<FrameComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<WidgetDim widget="__auto_titlebar__" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
<Image type="BottomLeftCorner" imageset="WindowsLook" image="WindowFrameBottomLeft" />
<Image type="BottomRightCorner" imageset="WindowsLook" image="WindowFrameBottomRight" />
<Image type="LeftEdge" imageset="WindowsLook" image="WindowFrameLeft" />
<Image type="RightEdge" imageset="WindowsLook" image="WindowFrameRight" />
<Image type="BottomEdge" imageset="WindowsLook" image="WindowFrameBottom" />
</FrameComponent>
</ImagerySection>
<ImagerySection name="notitle_frame">
<FrameComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
<Image type="TopLeftCorner" imageset="WindowsLook" image="WindowFrameTopLeft" />
<Image type="TopRightCorner" imageset="WindowsLook" image="WindowFrameTopRight" />
<Image type="BottomLeftCorner" imageset="WindowsLook" image="WindowFrameBottomLeft" />
<Image type="BottomRightCorner" imageset="WindowsLook" image="WindowFrameBottomRight" />
<Image type="LeftEdge" imageset="WindowsLook" image="WindowFrameLeft" />
<Image type="TopEdge" imageset="WindowsLook" image="WindowFrameTop" />
<Image type="RightEdge" imageset="WindowsLook" image="WindowFrameRight" />
<Image type="BottomEdge" imageset="WindowsLook" image="WindowFrameBottom" />
</FrameComponent>
</ImagerySection>
<ImagerySection name="withtitle_withframe_client_area">
<Colours topLeft="FFDFDFF5" topRight="FFDFEFF5" bottomLeft="FFF4F3F5" bottomRight="FFF0F0F5" />
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<ImageDim imageset="WindowsLook" image="WindowFrameLeft" dimension="Width" />
</Dim>
<Dim type="TopEdge">
<WidgetDim widget="__auto_titlebar__" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="WindowsLook" image="WindowFrameRight" dimension="Width" />
</DimOperator>
</UnifiedDim>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="WindowsLook" image="WindowFrameBottom" dimension="Height" />
</DimOperator>
</UnifiedDim>
</Dim>
</Area>
<Image imageset="WindowsLook" image="Background" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<ImagerySection name="notitle_withframe_client_area">
<Colours topLeft="FFDFDFF5" topRight="FFDFEFF5" bottomLeft="FFF4F3F5" bottomRight="FFF0F0F5" />
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<ImageDim imageset="WindowsLook" image="WindowFrameLeft" dimension="Width" />
</Dim>
<Dim type="TopEdge">
<ImageDim imageset="WindowsLook" image="WindowFrameTop" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge">
<DimOperator op="Subtract">
<ImageDim imageset="WindowsLook" image="WindowFrameRight" dimension="Width" />
</DimOperator>
</UnifiedDim>
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge">
<DimOperator op="Subtract">
<ImageDim imageset="WindowsLook" image="WindowFrameBottom" dimension="Height" />
</DimOperator>
</UnifiedDim>
</Dim>
</Area>
<Image imageset="WindowsLook" image="Background" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<ImagerySection name="withtitle_noframe_client_area">
<Colours topLeft="FFDFDFF5" topRight="FFDFEFF5" bottomLeft="FFF4F3F5" bottomRight="FFF0F0F5" />
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<WidgetDim widget="__auto_titlebar__" dimension="Height" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="WindowsLook" image="Background" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<ImagerySection name="notitle_noframe_client_area">
<Colours topLeft="FFDFDFF5" topRight="FFDFEFF5" bottomLeft="FFF4F3F5" bottomRight="FFF0F0F5" />
<ImageryComponent>
<Area>
<Dim type="LeftEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="TopEdge">
<AbsoluteDim value="0" />
</Dim>
<Dim type="RightEdge">
<UnifiedDim scale="1" type="RightEdge" />
</Dim>
<Dim type="BottomEdge">
<UnifiedDim scale="1" type="BottomEdge" />
</Dim>
</Area>
<Image imageset="WindowsLook" image="Background" />
<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />
</ImageryComponent>
</ImagerySection>
<StateImagery name="ActiveWithTitleWithFrame">
<Layer>
<Section section="withtitle_frame">
<Colours topLeft="FFA7C7FF" topRight="FFA7C7FF" bottomLeft="FFA7C7FF" bottomRight="FFA7C7FF" />
</Section>
<Section section="withtitle_withframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="InactiveWithTitleWithFrame">
<Layer>
<Section section="withtitle_frame">
<Colours topLeft="FFEFEFEF" topRight="FFEFEFEF" bottomLeft="FFEFEFEF" bottomRight="FFEFEFEF" />
</Section>
<Section section="withtitle_withframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="DisabledWithTitleWithFrame">
<Layer>
<Section section="withtitle_frame">
<Colours topLeft="FFEFEFEF" topRight="FFEFEFEF" bottomLeft="FFEFEFEF" bottomRight="FFEFEFEF" />
</Section>
<Section section="withtitle_withframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="ActiveWithTitleNoFrame">
<Layer>
<Section section="withtitle_noframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="InactiveWithTitleNoFrame">
<Layer>
<Section section="withtitle_noframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="DisabledWithTitleNoFrame">
<Layer>
<Section section="withtitle_noframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="ActiveNoTitleWithFrame">
<Layer>
<Section section="notitle_frame">
<Colours topLeft="FFA7C7FF" topRight="FFA7C7FF" bottomLeft="FFA7C7FF" bottomRight="FFA7C7FF" />
</Section>
<Section section="notitle_withframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="InactiveNoTitleWithFrame">
<Layer>
<Section section="notitle_frame">
<Colours topLeft="FFEFEFEF" topRight="FFEFEFEF" bottomLeft="FFEFEFEF" bottomRight="FFEFEFEF" />
</Section>
<Section section="notitle_withframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="DisabledNoTitleWithFrame">
<Layer>
<Section section="notitle_frame">
<Colours topLeft="FFEFEFEF" topRight="FFEFEFEF" bottomLeft="FFEFEFEF" bottomRight="FFEFEFEF" />
</Section>
<Section section="notitle_withframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="ActiveNoTitleNoFrame">
<Layer>
<Section section="notitle_noframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="InactiveNoTitleNoFrame">
<Layer>
<Section section="notitle_noframe_client_area" />
</Layer>
</StateImagery>
<StateImagery name="DisabledNoTitleNoFrame">
<Layer>
<Section section="notitle_noframe_client_area" />
</Layer>
</StateImagery>
</WidgetLook>
</Falagard>

==== Test layout file ====
<?xml version="1.0" encoding="UTF-8"?>
<GUILayout>
<Window Type="DefaultGUISheet" Name="root">

<Window Type="WindowsLook/NewFrameWindow" Name="myFrameWindow">
<Property Name="UnifiedPosition" Value="{{0.1,0},{0.1,0}}" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedMinSize" Value="{{0,128},{0,128}}" />
<Property Name="UnifiedSize" Value="{{0.4,0},{0.5,0}}" />
<Property Name="Text" Value="Demo of seperate client area." />


<AutoWindow NameSuffix="__auto_clientarea__" >
<Window Type="WindowsLook/Button" Name="myFrameWindow/Button1">
<Property Name="UnifiedAreaRect" Value="{{0.02,0},{0.01,0},{0.98,0},{0.15,0}}" />
<Property Name="Text" Value="A Button" />
</Window>
<Window Type="WindowsLook/Button" Name="myFrameWindow/Button2">
<Property Name="UnifiedAreaRect" Value="{{0.04,0},{0.6,0},{0.96,0},{0.75,0}}" />
<Property Name="Text" Value="Another Button" />
</Window>
</AutoWindow>

</Window>
</Window>
</GUILayout>

=== Conclusion ===
In this article you have seen what an auto window is, how the system uses them "out of the box", and how you can utilise the same system to extend widgets to perform differently. You have also seen how to target these auto windows from c++ code and also from layout XML files.

[[User:CrazyEddie]]

[[Category:Uncategorised]]

Imageset files

2011-03-03T23:50:40Z

Capek: Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1)

For the time being, this has been copy-and-pasted directly from "readme.txt" in the XMLRefSchema directory of the CEGUI source code. Some prettier formatting along the lines of '''[[Scheme files]]''' would be nice.

<pre>
Imagesets define one or more images on a larger image (texture).
The root element must be Imageset.

Imageset Element
================
Has attributes and a collection of one or more Image elements.

Imageset attributes
-------------------
Imagefile - path to the image file containing the graphics (required).
ResourceGroup - The resource group identifier to pass to the resource provider when loading the file.
Name - the name that will be assigned to the Imageset in the GUI system (required).
NativeHorzRes - The horizontal screen resolution that the images were are intended to be displayed at (optional, default=640).
NativeVertRes - The vertical screen resolution that the images were are intended to be displayed at (optional, default=480).
AutoScaled - Boolean, states whether to scale imagery so it appears the same size as any resolution (optional, default=false).

Image Element
=============
Has attributes defining an sub-image area. Can have no sub-elements.

Image attributes
----------------
Name - The name that will be used to identify the image within the Imageset. (required).
XPos - X pixel co-ordinate of the top-left corner of the image on the texture. (required).
YPos - Y pixel co-ordinate of the top-left corner of the image on the texture. (required).
Width - Width of this image in pixels. (required).
Height - Height of this image in pixels. (required).
XOffset - Horizontal offset to apply when rendering. (optional, default=0)
YOffset - Vertical offset to apply when rendering. (optional, default=0)

</pre>

[[Category:Uncategorised]]