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

Cool window effects

2011-01-07T09:56:02Z

Makofierce:

= Inactive windows become transparent =
'''WARNING ! As for now (02.07.2007), this code does make all your tooltips transparent, I'm working on a solution.'''

'''Problem solved (02.07.2007). If you used the old code, please replace by the new.'''

Please discuss this snippet within the [[http://www.cegui.org.uk/phpBB2/viewtopic.php?p=11786 cool window effects - Inactive windows become trans.]] thread.

Do you know about the [http://vizzzion.org/images/blog/composite.png cool effects that the composite extension can create] on linux ? There are many. I wanted to implement one into my game: make the [http://img337.imageshack.us/img337/9398/windowtransparencyue1.png inactive windows become transparent] and only the active one be 100% opaque. (see the links in this sentence for screenshots.) This effect can be interesting if you want your users to concentrate 100% on the active window and the inactive ones aren't important at this moment. But what if the user has to see two windows or more at the same time (and with full opacity) ? We'll see how to handle this.

== The theory ==
There is more then one way to achieve this, but I'll only present the one I chose. CEGUI has something that is called global events. These are events that are fired independently on the widget they apply to. I'll try with an example: sometimes you need to know when a button is clicked, no matter what button it is, you want to know it for EVERY button. This is what global events are for.

We'll subscribe to two global events: "a window gets activated" and "a window gets closed". When a window gets activated, we add it to a stack which we use to keep track of the windows and the order they where activated. We also make the last active window become transparent. When a window gets closed, we remove it from the stack and activate the one that is on the top of the stack now. (that is the window that was active just before the one we just closed.)

We keep the root window away from it, that means we never make the root window transparent, because this would make the tooltips become transparent. You need to have an empty root window that is a container for your other windows.

== The praxis (code) ==
Now let's go ! First, we need to register callback functions to the two global events:
<code><cpp/>
CEGUI::GlobalEventSet::getSingleton( ).subscribeEvent( CEGUI::Window::EventNamespace + "/" + CEGUI::Window::EventActivated,
CEGUI::Event::Subscriber(&onWindowActivated) );
CEGUI::GlobalEventSet::getSingleton( ).subscribeEvent( CEGUI::Window::EventNamespace + "/" + CEGUI::Window::EventDestructionStarted,
CEGUI::Event::Subscriber(&onWindowClosed) );</code>

We also need a stack to keep track of the windows. I chose to use the std::list type instead of the std::stack, because we need to be able to either delete all references of one element or to search the stack. So here it is:
<code><cpp/>std::list<CEGUI::Window *> pWinHistory;</code>

Also, don't forget to put your root window just before setting it as the root window:
<code><cpp/>pWinHistory.push_back(pMyRootWindow);
CEGUI::System::getSingleton().setGUISheet(pMyRootWindow);
</code>

One thing you need to know about the root window is that you need an empty root window, containing one or more child windows that contain all GUI items. Your root window will never become transparent, thus you need an empty "container" root window.

And now we implement our two callback functions. I excessively commented the functions.

onWindowActivated:
<code><cpp/>/// Called everytime a window gets activated.
/** This function is called by CEGUI every time that a window gets the focus.
*
* Currently, we use this function to keep track of the order that windows where
* active, so when closing a window we can activate the last one, as this isn't
* done automatically by CEGUI.
*
* \param e The event arguments.
*
* \return Always true.
*
* \author Pompei2
*/
bool onWindowActivated( const CEGUI::EventArgs &ea )
{
try {
const CEGUI::WindowEventArgs& we = static_cast<const CEGUI::WindowEventArgs&>(ea);
CEGUI::Window *pLastWin = pWinHistory.back( );

// We only work with FrameWindows.
if( !we.window->testClassName( CEGUI::FrameWindow::EventNamespace ) )
return true;

// If it is the same window as before, ignore it.
if( pLastWin == we.window )
return true;

if( pLastWin != CEGUI::System::getSingleton().getGUISheet() ) {
// If every time a window gets activated we make the last active window become
// transparent, this will result in all inactive windows being transparent.
pLastWin->setProperty( "Alpha", "0.25" );

// But we never make the root window transparent, as this would make all tooltips
// become transparent, and we don't want this !
}

// We need the active window to not inherit the transparence of its parents.
we.window->setProperty( "InheritsAlpha", "false" );

// Finally, we add the new window to the stack.

// One could also check if it's already present in the stack and if yes, just put it on the top.
// You would have to do this if you want to set the transparency depending on the window's position
// in the stack (see "Extending the effect").
pWinHistory.push_back( we.window );
} catch( CEGUI::Exception& e ) {
fprintf( stderr, "CEGUI error: %s\n", e.getMessage( ).c_str( ) );
return true;
}

return true;
}</code>

And onWindowClosed:
<code><cpp/>/// Called everytime a window gets closed.
/** This function is called by CEGUI just before a window gets closed.
*
* Currently, we use this function to activate the previous window
* when closing this one, as it's not done automatically by CEGUI.
*
* \param e The event arguments.
*
* \return Always true.
*
* \author Pompei2
*/
bool onWindowClosed( const CEGUI::EventArgs &ea )
{
try {
const CEGUI::WindowEventArgs& we = static_cast<const CEGUI::WindowEventArgs&>(ea);
CEGUI::Window *pLastWin = NULL;

// We only work with FrameWindows.
if( !we.window->testClassName( CEGUI::FrameWindow::EventNamespace ) )
return true;

// Delete the current window from the stack.
// CARE: std::list::remove removes ALL occurences of we.window from the stack !
// This is VERY important to know, as if you activate window A, then window B and then A again,
// the stack will contain A twice: {A,B,A}.
pWinHistory.remove( we.window );

// Now we get the window that was active before the current one:
pLastWin = m_pWinHistory.back( );

// re-activate it (like windos, linux, .. all do).
pLastWin->activate( );

// And set it to be opaque again.
// You could either do this here or you do this in the onWindowActivate function, the result is the same,
// as the call to CEGUI::Window::activate above results in onWindowActivate to be called.
pLastWin->setProperty( "Alpha", "1.0" );
} catch( CEGUI::Exception& e ) {
fprintf( stderr, "CEGUI error: %s\n", e.getMessage( ).c_str( ) );
return true;
}

return true;
}</code>

That's all.

One important thing you might not know yet, is that CEGUI DOESN'T activate a window that gets shown. you have to manually activate a window when you create it (and want it to be active, of course).

== Extending the effect ==
* You could also automatically activate a window as soon as it's shown. for this you could subscribe to the "a window gets shown" global event and then just call ea.window->activate( );
Edit: Hmm I tried this one but wasn't able to get it to work. If someone has success, please tell us how you did it in the forums.

* You could try to make the window's transparency degree dependent on its position in the stack. That means the most recent windows get less transparent while the "oldest" windows get very transparent. To do this, just loop trough the stack - that would be a list - and set every window's transparency accordingly. Do this when a window gets active AND when a window gets closed. You would also need to never have the same window twice in the stack, as it would screw your results up.

--[[User:Pompei2|Pompei2]] 06:00, 6 May 2007 (PDT)

----
----
you can add more cool effects here.

Formatted Numeric Data

2011-01-07T09:54:26Z

Makofierce:

International Components for Unicode (ICU) is a toolkit to internationalise applications. Initially developed for Java it has been ported to C/C++. There is a Java version of ICU called ICU4J, and there is a C/C++ version of ICU called ICU4C. Now ICU4C has been partially ported to CEGUI. Please use this [http://www.cegui.org.uk/phpBB2/viewtopic.php?p=8097#8097 thread] for discussion.

==International Components for Unicode==
===Useful Links===
*[http://www.icu-project.org/ Home page]
*[http://source.icu-project.org/repos/icu/icu/trunk/license.html Licence]
*[http://www.icu-project.org/userguide/ Documentation]
*[http://www.icu-project.org/apiref/icu4c/ ICU4C API Reference]
*[http://www.loc.gov/standards/iso639-2/ ISO 639 Language Codes]
*[http://unicode.org/iso15924/iso15924-codes.html ISO 15924 Script Codes]
*[http://www.iso.org/iso/country_codes ISO 3166 Country Codes]
*[http://www.iso.org/iso/currency_codes ISO 4217 Currency Codes]
*[http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html#_details ICU Decimal Format Syntax]
*[http://www.icu-project.org/userguide/formatDateTime.html ICU Date/Time Format Syntax]

===Getting started===
Download these [http://www.icu-project.org/download/ files from the ICU web site]
*Source: icu-3.4.1.zip for Windows OR icu-3.4.1.tgz for Unix
*Documentation: icu-3.4-docs.zip
*User Guide: icu-3.4-userguide.zip

Files of interest:
*Solution to compile: icu/source/allinone/allinone.sln
*Instructions to compile and use ICU: icu/readme.html#HowToBuildWindows
*ICU4C samples: icu/source/samples/

The instructions for building and setting up ICU are contained in the readme.html. If you have any problems, contact the icu-support mailing list or submit a bug report.
*[http://www.icu-project.org/contacts.html icu-support mailing list]
*[http://www.icu-project.org/bugs.html ICU bug tracking tool]

===Incorporating ICU4C within an existing project===

Additional include directories:
*$(ICU)\include

Additional library directories:
*$(ICU)\lib

Link with:
*debug: icuucd.lib icuind.lib
*release: icuuc.lib icuin.lib

Make certain these DLLs are present with your executable or in your PATH:
*debug: icuuc34d.dll icuin34d.dll icudt34.dll
*release: icuuc34.dll icuin34.dll icudt34.dll

==CEGUI's ICU==
ICU4C provides many features to support internationalisation. The class I've created encapsulates some (not all) of these features.

===Locale===
A Locale is an identifier that describes the rules in effect within a country for a specific language. These rules specify the formatting of currencies, numeric values, dates, and others. Unfortunately these rules do not take into consideration the modifications that may have been applied within the Regional Settings of Window's Control Panel, unless the "@compat=host" locale is used, which is available in ICU 3.6 and later. However most functions accept a formatting mask. This allows applications to recreate some of the features of the control panel, allowing users to specify their desired formats. The setLocale() and setCurrency() functions will configure the class to adopt the rules specified by the specified language, country, and currency.

===formatNumber===
The formatNumber() function formats a numeric value given the specified mask. Three versions are available. The versions accepting a CEGUI::String has been customised to allow large numbers to be formatted: numbers having up to 18 integers and 7 decimals. The current implementation of this function is limited to accepting a single format for positive numbers. If the numeric value to be formatted is negative then a negative sign will precede the formatted value. However it is impossible to format a negative value within parentheses: formatting -1234.56 to (1,234.56).

===numberToText===
The numberToText() function converts a numeric value into a textual representation. For example the numeric value 123 is converted into "one hundred twenty-three" in English and "cent vingt-trois" in French.

===numberToOrdinal===
The numberToOrdinal() function converts a numeric value into an ordinal representation. For example the numeric value 1 is converted into "1st" in english. Support for other languages is either buggy or lacking (or I have improperly coded this feature).

===formatText===
The formatText() function will parse a numeric value and sprinkle digits into the slots specified by the formatting mask. A North American telephone number of "12223334444" can be formatted into "1 (222) 333-4444" with the mask "0 (000) 000-0000". This non-localised function accepts three format specifier. A "0" represents a forced digit. If the numerical value possesses a digit at that position then the digit will be displayed, otherwise the place holder character(s) will be used. A "#" represents a potential digit. If the numerical value possesses a digit at that position the the digit will be displayed, otherwise nothing is displayed. Finally the apostrophe "'" allows the mask to specify the characters "0", "#", or "'", rather than using them as format specifiers.

===formatCurrency===
The formatCurrency() function will format a numerical value according to the currently configured locale and currency. It will NOT convert the monetary value of one currency to another.

===formatDateTime===
The formatDateTime() function will format a date, time, or date/time given the specified mask. The UDate variable type is a double. According to [http://www.icu-project.org/userguide/dateCalendar.html ICU's documentation] <i>A UDate value is stored as UTC time in milliseconds, which means it is calendar and time zone independent. UDate is the most compact and portable way to store and transmit a date and time.</i>

===localToGmt and gmtToLocal===
The localToGmt() and the gmtToLocal() functions convert a date and a time between a local and a GMT value.

===CeguiStringToDateTime===
The CeguiStringToDateTime() function will parse a string specifying a date or a time into its corresponding UDate value. Although it is possible to parse a string containing both a date and a time the resulting UDate value will be inaccurate, varying from its intended value by up to 1 minute 47 seconds. A better approach is to keep the date and time separated.

==Source Code==

===icu.h===
<pre>
#ifndef _ICU_h_
#define _ICU_h_

#include "unicode/utypes.h"
#include "unicode/unistr.h"
#include "unicode/numfmt.h"
#include "unicode/dcfmtsym.h"
#include "unicode/decimfmt.h"
#include "unicode/locid.h"
#include "unicode/uclean.h"
#include "unicode/calendar.h"
#include "unicode/datefmt.h"
#include "unicode/smpdtfmt.h"
#include "unicode/rbnf.h"
#include "CEGUI.h"

class ICU
{
public:
ICU(bool cleanupICU = true);
~ICU();
bool setLocale(const CEGUI::String& language, const CEGUI::String& country);
const Locale& getLocale();
bool setCurrency(const char *currency);

bool formatNumber(const CEGUI::String& rawValue, const CEGUI::String& mask, CEGUI::String& formattedValue);
bool formatNumber(const double rawValue, const CEGUI::String& mask, CEGUI::String& formattedValue);
bool formatNumber(const int32_t rawValue, const CEGUI::String& mask, CEGUI::String& formattedValue);

bool numberToText(const double rawValue, CEGUI::String& formattedValue);
bool numberToText(const int32_t rawValue, CEGUI::String& formattedValue);

bool numberToOrdinal(const double rawValue, CEGUI::String& formattedValue);
bool numberToOrdinal(const int32_t rawValue, CEGUI::String& formattedValue);

bool formatText(const CEGUI::String& rawValue, const CEGUI::String& mask, const CEGUI::String& zeroPlaceHolder, CEGUI::String& formattedValue);

bool formatCurrency(const double& currency, CEGUI::String& formattedValue);

bool formatDateTime(UDate rawDateTime, const CEGUI::String& mask, CEGUI::String& formattedDateTime);
bool localToGmt(const UDate& localDate, const UDate& localTime, UDate& gmtDate, UDate& gmtTime);
bool gmtToLocal(const UDate& gmtDate, const UDate& gmtTime, UDate& localDate, UDate& localTime);

bool CeguiStringToDateTime(const CEGUI::String& stringDateTime, const CEGUI::String& mask, UDate& unicodeDateTime);
bool CeguiStringToInt32(const CEGUI::String& stringValue, int32_t& int32Value);
void UnicodeToCeguiString(const UnicodeString& unicodeString, CEGUI::String& ceguiString);
private:
void _splitIntegerDecimal(const CEGUI::String& combined, CEGUI::String& integerPart, CEGUI::String& decimalPart);
bool _convertLocalAndGmt(const UDate& localDate, const UDate& localTime, UDate& gmtDate, UDate& gmtTime, bool fromLocalToGMT);
bool _ruleBasedNumberFormat(const double rawValue, URBNFRuleSetTag tag, CEGUI::String& formattedValue);
bool _ruleBasedNumberFormat(const int32_t rawValue, URBNFRuleSetTag tag, CEGUI::String& formattedValue);
Locale m_locale; // Current locale of the computer
UChar m_currency[4]; // Currency code
bool m_cleanupICU; // Whether to call ICU's cleanup function
};

#endif // _ICU_h_
</pre>

===icu.cpp===

<pre>
#include "ICU.h"
#include <vector>

ICU::ICU(bool cleanupICU)
{
m_cleanupICU = cleanupICU;
}

ICU::~ICU()
{
// http://www.icu-project.org/userguide/design.html#Init_and_Termination
// The paragraph "ICU Initialization and Termination" mentions that this function
// can be called to force the ICU library to release any allocated heap storage
// otherwise memory leak checking tools will falsely report leaks.
// My thinking with this m_cleanupICU variable is that the library should not release
// its memory allocation if it is also used outside of this class. This
// implementation grants you some control over when this cleanup occurs.
// You are not required to call u_cleanup(). It's dangerous if called at the wrong time.
if(m_cleanupICU)
u_cleanup();
}

bool ICU::setLocale(const CEGUI::String& language, const CEGUI::String& country)
{
// Set the locale
Locale tempLocale = Locale::createFromName((language + "_" + country).c_str());
if(tempLocale.isBogus())
return false;

m_locale = tempLocale;
return true;
}

const Locale& ICU::getLocale()
{
// Retrive the locale
return m_locale;
}

bool ICU::setCurrency(const char *currency)
{
// Set the currency
if(currency==NULL || strlen(currency)!=3)
return false;

// Invariant-character conversion to UChars
u_charsToUChars(currency, m_currency, 4);
return true;
}

bool ICU::formatNumber(const CEGUI::String& rawValue, const CEGUI::String& mask, CEGUI::String& formattedValue)
{
// Format a unformatted number according to the rules specified within the mask
// An unformatted number only contains numeric digits and a period as the decimal point
// Note that a decimal value is broken down into two numbers, an
// integer and a decimal number for formatting and then reassembled
// into a single string. This makes it possible to handle numbers
// as large as 999,999,999,999,999,999.9999999 (18 integers and 7 decimals).
// However it makes it impossible to specify a positive mask as well as a
// negative mask; only one mask is supported. It is also impossible to
// format a negative value with a mask similar to "(#,##0.00)"
UErrorCode status = U_ZERO_ERROR;
formattedValue.clear();
CEGUI::String formattedInteger, formattedDecimal;
CEGUI::String::size_type idx;

// Separate the integer and the decimal parts from the value
CEGUI::String maskInteger, maskDecimal, integerValue, decimalValue;
idx = rawValue.find(".");
if(idx == CEGUI::String::npos)
{
// If the value is empty then force the integer to 0, otherwise use the value
// Since there is no decimal point force a decimal value of .0
integerValue = rawValue.empty() ? "0" : rawValue;
decimalValue = ".0";
}
else
{
// If there is no integer portion then force an integer value of 0
integerValue = idx == 0 ? "0" : rawValue.substr(0, idx);
decimalValue = rawValue.substr(idx);
}

// Separate the integer and the decimal parts from the mask
_splitIntegerDecimal(mask, maskInteger, maskDecimal);

// Prepare the numeric formatter
DecimalFormatSymbols* decimalFormatSymbols = new DecimalFormatSymbols(m_locale, status);
if( U_FAILURE(status) )
return false;

if(!maskInteger.empty())
{
// Prepare the integer parser
UnicodeString patternInteger(maskInteger.c_str());
DecimalFormat* fmt = new DecimalFormat(patternInteger, *decimalFormatSymbols, status);
if( U_FAILURE(status) )
{
delete decimalFormatSymbols;
return false;
}

// Parse the string value into an integer value
UnicodeString uIntegerValue(integerValue.c_str());
Formattable fIntegerValue;
fmt->parse(uIntegerValue, fIntegerValue, status);
if( U_FAILURE(status) )
{
status = U_ZERO_ERROR;
fIntegerValue.setInt64(0);
}

// Format the integer value
uIntegerValue = "";
((NumberFormat*)fmt)->format(fIntegerValue.getInt64(), uIntegerValue);
delete fmt;

UnicodeToCeguiString(uIntegerValue, formattedInteger);
}

if(!maskDecimal.empty())
{
// Prepare the decimal parser
DecimalFormat* fmtParse = new DecimalFormat(status);
if( U_FAILURE(status) )
{
delete decimalFormatSymbols;
return false;
}
fmtParse->applyLocalizedPattern("0.0000003", status);

// Parse the string value into a decimal value
UnicodeString uDecimalValue(decimalValue.c_str());
Formattable fDecimalValue;
fmtParse->parse(uDecimalValue, fDecimalValue, status);
delete fmtParse;
if( U_FAILURE(status) )
{
status = U_ZERO_ERROR;
fDecimalValue.setDouble(0.0);
}

// Prepare the decimal formatter
UnicodeString patternDecimal(maskDecimal.c_str());
DecimalFormat* fmt = new DecimalFormat(patternDecimal, *decimalFormatSymbols, status);
if( U_FAILURE(status) )
{
delete decimalFormatSymbols;
return false;
}

// Format the decimal value
uDecimalValue = "";
fmt->format(fDecimalValue.getDouble(), uDecimalValue);
delete fmt;

UnicodeToCeguiString(uDecimalValue, formattedDecimal);
}

delete decimalFormatSymbols;

formattedValue = formattedInteger + formattedDecimal;
return true;
}

bool ICU::formatNumber(const double rawValue, const CEGUI::String& mask, CEGUI::String& formattedValue)
{
// Format a number using the appropriate locale rules
// Note that the use of a double limits the effective range
UErrorCode status = U_ZERO_ERROR;
formattedValue.clear();

// Prepare the numeric formatter
DecimalFormatSymbols* symbols = new DecimalFormatSymbols(m_locale, status);
if( U_FAILURE(status) )
return false;

// Create a number formatter for the current locale
UnicodeString pattern(mask.c_str());
DecimalFormat* fmt = new DecimalFormat(pattern, *symbols, status);
if( U_FAILURE(status) )
{
delete symbols;
return false;
}

// Format the number
UnicodeString uValue;
fmt->format(rawValue, uValue, status);
delete symbols;
delete fmt;
if( U_FAILURE(status) )
return false;

UnicodeToCeguiString(uValue, formattedValue);
return true;
}

bool ICU::formatNumber(const int32_t rawValue, const CEGUI::String& mask, CEGUI::String& formattedValue)
{
// Format a number using the appropriate locale rules
// Note that the use of a double limits the effective range
UErrorCode status = U_ZERO_ERROR;
formattedValue.clear();

// Prepare the numeric formatter
DecimalFormatSymbols* symbols = new DecimalFormatSymbols(m_locale, status);
if( U_FAILURE(status) )
return false;

// Create a number formatter for the current locale
UnicodeString pattern(mask.c_str());
DecimalFormat* fmt = new DecimalFormat(pattern, *symbols, status);
if( U_FAILURE(status) )
{
delete symbols;
return false;
}

// Format the number
UnicodeString uValue;
fmt->format(rawValue, uValue, status);
delete symbols;
delete fmt;
if( U_FAILURE(status) )
return false;

UnicodeToCeguiString(uValue, formattedValue);
return true;
}

bool ICU::numberToText(const double rawValue, CEGUI::String& formattedValue)
{
// Convert a number to a text
// "1.2" to "one point two"
return _ruleBasedNumberFormat(rawValue, URBNF_SPELLOUT, formattedValue);
}

bool ICU::numberToText(const int32_t rawValue, CEGUI::String& formattedValue)
{
// Convert a number to a text
// "12" to "twelve"
return _ruleBasedNumberFormat(rawValue, URBNF_SPELLOUT, formattedValue);
}

bool ICU::numberToOrdinal(const double rawValue, CEGUI::String& formattedValue)
{
// Convert a number to ordinal text
// "1.5" to "2nd"
return _ruleBasedNumberFormat(rawValue, URBNF_ORDINAL, formattedValue);
}

bool ICU::numberToOrdinal(const int32_t rawValue, CEGUI::String& formattedValue)
{
// Convert a number to ordinal text
// "1" to "1st"
return _ruleBasedNumberFormat(rawValue, URBNF_ORDINAL, formattedValue);
}

bool ICU::formatText(const CEGUI::String& rawValue, const CEGUI::String& mask, const CEGUI::String& zeroPlaceHolder, CEGUI::String& formattedValue)
{
/* Format a value according to a pattern
* Format specifiers:
* 0 forced digit: will be replaced by a digit or if there is no digit, by 'zeroPlaceHolder'
* # potential digit: will be replaced by a digit if there is one otherwise nothing
* ' literal character: the following character is to be treated as a character
* rather than a format specifier
* ex the value "1" with the format "'00" will result in the string "01"
* Note that if the value is larger than the pattern then it is truncated to the left
* ex the value "1234" with the format "#0" results in the string "34"
*/
formattedValue.clear();

if(!rawValue.length() || !mask.length())
return false;

// Parse the mask
std::vector<CEGUI::String> maskList;
CEGUI::String maskDigit;
for(CEGUI::String::size_type idxMask = 0; idxMask < mask.length(); ++idxMask)
{
if(!mask.compare(idxMask, 1, "0"))
{
maskDigit = "ForcedDigit";
maskList.push_back(maskDigit);
}
else if(!mask.compare(idxMask, 1, "#"))
{
maskDigit = "PotentialDigit";
maskList.push_back(maskDigit);
}
else
{
if(!mask.compare(idxMask, 1, "'") && idxMask < mask.length() - 1)
++idxMask; // Literal specifier followed by a mask digit, so skip over the apostrophe
maskDigit = mask.at(idxMask);
maskList.push_back(maskDigit);
}
}

// Format the numeric value
CEGUI::String::size_type idxValue;
idxValue = rawValue.length();
std::vector<CEGUI::String>::reverse_iterator itMask;
for(itMask = maskList.rbegin(); itMask != maskList.rend(); ++itMask)
{
if(!(*itMask).compare("ForcedDigit"))
{
if(idxValue)
{
// We have a digit remaining
--idxValue;
formattedValue = rawValue.at(idxValue) + formattedValue;
}
else
{
// We're out of digits
formattedValue = zeroPlaceHolder + formattedValue;
}
}
else if(!(*itMask).compare("PotentialDigit"))
{
if(idxValue)
{
// We have a digit remaining
--idxValue;
formattedValue = rawValue.at(idxValue) + formattedValue;
}
}
else
{
// Literal character
formattedValue = (*itMask) + formattedValue;
}
}
return true;
}

bool ICU::formatCurrency(const double& currency, CEGUI::String& formattedValue)
{
// Format a number using the appropriate locale rules
// Note that the use of a double limits the effective range
UErrorCode status = U_ZERO_ERROR;
formattedValue.clear();

// Create a number formatter for the current locale
NumberFormat *fmt = NumberFormat::createCurrencyInstance(m_locale, status);
if( U_FAILURE(status) )
return false;

// Format the currency
UnicodeString uValue;
fmt->format(currency, uValue);
delete fmt;

UnicodeToCeguiString(uValue, formattedValue);
return true;
}

bool ICU::formatDateTime(UDate rawDateTime, const CEGUI::String& mask, CEGUI::String& formattedDateTime)
{
// Format a date/time given the specified mask
// Note that although a UDate can support both date and time in
// realite the resolution is insufficient. In order to precisely
// represent a date/time value they should be processed separately
UErrorCode status = U_ZERO_ERROR;
formattedDateTime.clear();

// Create a Date/Time formatter
DateFormat* fmt = DateFormat::createDateTimeInstance(DateFormat::kDefault, DateFormat::kDefault, m_locale); // kDefault is not really used

// Activate our pattern (overrides DateFormat::kDefault)
UnicodeString pattern(mask.c_str());
((SimpleDateFormat*) fmt)->applyPattern(pattern);

// Format the date/time
UnicodeString uValue;
fmt->format(rawDateTime, uValue, status);
delete fmt;
if( U_FAILURE(status) )
return false;

UnicodeToCeguiString(uValue, formattedDateTime);
return true;
}

bool ICU::localToGmt(const UDate& localDate, const UDate& localTime, UDate& gmtDate, UDate& gmtTime)
{
// Convert a local date/time into a GMT date/time
return _convertLocalAndGmt(localDate, localTime, gmtDate, gmtTime, true);
}

bool ICU::gmtToLocal(const UDate& gmtDate, const UDate& gmtTime, UDate& localDate, UDate& localTime)
{
// Convert a GMT date/time into a local date/time string
return _convertLocalAndGmt(gmtDate, gmtTime, localDate, localTime, false);
}

bool ICU::CeguiStringToDateTime(const CEGUI::String& stringDateTime, const CEGUI::String& mask, UDate& unicodeDateTime)
{
// Convert a string date/time into a UDate
UErrorCode status = U_ZERO_ERROR;
unicodeDateTime = 0.0;

// Create a Date/Time formatter
DateFormat* fmt = DateFormat::createDateTimeInstance(DateFormat::kDefault, DateFormat::kDefault, m_locale);

// Activate our pattern
UnicodeString pattern(mask.c_str());
((SimpleDateFormat*) fmt)->applyPattern(pattern);

// Parse the string into a date/time
UnicodeString uValue(stringDateTime.c_str());
unicodeDateTime = fmt->parse(uValue, status);
delete fmt;
if( U_FAILURE(status) )
return false;

return true;
}

bool ICU::CeguiStringToInt32(const CEGUI::String& stringValue, int32_t& int32Value)
{
// Convert a string into an int32_t
UErrorCode status = U_ZERO_ERROR;
int32Value = 0;

// Create an integer formatter
NumberFormat *fmt = NumberFormat::createInstance(Locale::getUS(), status);
if( U_FAILURE(status) )
return false;

// Activate our pattern
UnicodeString pattern("#,##0");
((DecimalFormat*) fmt)->applyPattern(pattern, status);
if( U_FAILURE(status) )
{
delete fmt;
return false;
}

// Parse the string into a double
UnicodeString uValue(stringValue.c_str());
Formattable result;
fmt->parse(uValue, result, status);
delete fmt;
if( U_FAILURE(status) )
return false;

int32Value = result.getLong();

return true;
}

void ICU::UnicodeToCeguiString(const UnicodeString& unicodeString, CEGUI::String& ceguiString)
{
// Convert a unicode string to a CEGUI string
ceguiString.clear();

CEGUI::String digit;
for(int32_t i = 0; i < unicodeString.length(); ++i)
{
digit = unicodeString.charAt(i);
ceguiString.append(digit);
}
}

void ICU::_splitIntegerDecimal(const CEGUI::String& combined, CEGUI::String& integerPart, CEGUI::String& decimalPart)
{
// Split a decimal value into its constituent integer and decimal parts
CEGUI::String::size_type idx = combined.find(".");
if(idx == CEGUI::String::npos)
{
integerPart = combined;
decimalPart.clear();
}
else
{
integerPart = combined.substr(0, idx);
decimalPart = combined.substr(idx);
}
}

bool ICU::_convertLocalAndGmt(const UDate& localDate, const UDate& localTime, UDate& gmtDate, UDate& gmtTime, bool fromLocalToGMT)
{
// Helper function to convert between a local and a GMT date/time
UErrorCode status = U_ZERO_ERROR;
gmtDate = gmtTime = 0.0;

// Create a calendar for the local date
Calendar* calLocalDate = Calendar::createInstance(m_locale, status);
if( U_FAILURE(status) )
return false;
calLocalDate->clear();
calLocalDate->setTime(localDate, status);
if( U_FAILURE(status) )
{
delete calLocalDate;
return false;
}

// Create a calendar for the local time
Calendar* calLocalTime = Calendar::createInstance(m_locale, status);
if( U_FAILURE(status) )
{
delete calLocalDate;
return false;
}
calLocalTime->clear();
calLocalTime->setTime(localTime, status);
if( U_FAILURE(status) )
{
delete calLocalDate;
delete calLocalTime;
return false;
}

// Retrieve the offset between this time zone and the GMT time zone
// The Daylight Saving Time offset is zero when DST is not in effect
// Note that adding the local date and time together introduces an
// inaccuracy of up to 1 minute 47 seconds. However the only impact
// of this inaccuracy is to advance/delay the activation or deactivation
// of daylight savings
int32_t rawOffset, dstOffset, gmtOffset;
calLocalDate->getTimeZone().getOffset(localDate + localTime, true, rawOffset, dstOffset, status);
gmtOffset = (rawOffset + dstOffset) / 1000 / 60 / 60; // Convert from milliseconds to hours

// Converting from local to GMT requires "reversing" the time zone
// EST is GMT-5 so it requires adding 5 hours to local time to obtain GMT
// Converting from GMT to local requires the opposite
int32_t hour = calLocalTime->get(UCAL_HOUR_OF_DAY, status);
if(fromLocalToGMT)
hour -= gmtOffset;
else
hour += gmtOffset;

// Adjust the time and date if necessary
if(hour >= 24)
{
// We've moved to the next day
hour -= 24;
calLocalDate->add(UCAL_DAY_OF_MONTH, 1, status);
if( U_FAILURE(status) )
{
delete calLocalDate;
delete calLocalTime;
return false;
}
}
else if(hour < 0)
{
// We've moved to the previous day
hour += 24;
calLocalDate->add(UCAL_DAY_OF_MONTH, -1, status);
if( U_FAILURE(status) )
{
delete calLocalDate;
delete calLocalTime;
return false;
}
}
calLocalTime->set(UCAL_HOUR_OF_DAY, hour);

// Retrieve the converted date and time
gmtDate = calLocalDate->getTime(status);
gmtTime = calLocalTime->getTime(status);

delete calLocalDate;
delete calLocalTime;
if( U_FAILURE(status) )
return false;

return true;
}

bool ICU::_ruleBasedNumberFormat(const double rawValue, URBNFRuleSetTag tag, CEGUI::String& formattedValue)
{
UErrorCode status = U_ZERO_ERROR;
formattedValue.clear();

// Create a rule based number formatter
RuleBasedNumberFormat* fmt = new RuleBasedNumberFormat(tag, m_locale, status);
if( U_FAILURE(status) )
return false;

UnicodeString uValue;
fmt->format(rawValue, uValue);
delete fmt;

formattedValue.clear();
UnicodeToCeguiString(uValue, formattedValue);
return true;
}

bool ICU::_ruleBasedNumberFormat(const int32_t rawValue, URBNFRuleSetTag tag, CEGUI::String& formattedValue)
{
UErrorCode status = U_ZERO_ERROR;
formattedValue.clear();

// Create a rule based number formatter
RuleBasedNumberFormat* fmt = new RuleBasedNumberFormat(tag, m_locale, status);
if( U_FAILURE(status) )
return false;

UnicodeString uValue;
Formattable fValue(rawValue);
fmt->format(fValue, uValue, status);
delete fmt;
if( U_FAILURE(status) )
return false;

formattedValue.clear();
UnicodeToCeguiString(uValue, formattedValue);
return true;
}
</pre>

===FormattedData.h===
<pre>
#ifndef _FormattedData_h_
#define _FormattedData_h_

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

#include "ICU.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("FormattedData.layout");
sheet->addChildWindow(guiLayout);

/******** ICU Stuff ********/

// Display one ISO country in a combo box
Combobox* countries = static_cast<Combobox*>(winMgr.getWindow("Countries"));
countries->setReadOnly(true);
ListboxTextItem* listboxTextItem;
listboxTextItem = new ListboxTextItem( Locale::getDefault().getCountry() );
listboxTextItem->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
countries->addItem(listboxTextItem);
countries->setText( Locale::getDefault().getCountry() );
countries->subscribeEvent(Combobox::EventListSelectionAccepted, Event::Subscriber(&DemoSample::onLocaleChanged, this));

// Display two ISO languages in a combo box
Combobox* languages = static_cast<Combobox*>(winMgr.getWindow("Languages"));
languages->subscribeEvent(Combobox::EventListSelectionAccepted, Event::Subscriber(&DemoSample::onLocaleChanged, this));
languages->setReadOnly(true);
listboxTextItem = new ListboxTextItem("en");
listboxTextItem->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
languages->addItem(listboxTextItem);
listboxTextItem = new ListboxTextItem("fr");
listboxTextItem->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
languages->addItem(listboxTextItem);
languages->setText("en");
languages->subscribeEvent(Combobox::EventListSelectionAccepted, Event::Subscriber(&DemoSample::onLocaleChanged, this));
PushButton* everyISO = static_cast<PushButton*>(winMgr.getWindow("EveryISO"));
everyISO->subscribeEvent(PushButton::EventClicked, Event::Subscriber(&DemoSample::onLoadEveryISO, this));

// Configure the currency widgets
Editbox* currencyValue = static_cast<Editbox*>(winMgr.getWindow("CurrencyValue"));
currencyValue->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onCurrencyChanged, this));
RadioButton* radio;
radio = static_cast<RadioButton*>(winMgr.getWindow("RadioCAD"));
radio->subscribeEvent(RadioButton::EventSelectStateChanged, Event::Subscriber(&DemoSample::onCurrencySelected, this));
radio->setID(1);
radio->setSelected(true);
radio = static_cast<RadioButton*>(winMgr.getWindow("RadioUSD"));
radio->subscribeEvent(RadioButton::EventSelectStateChanged, Event::Subscriber(&DemoSample::onCurrencySelected, this));
radio->setID(2);
radio = static_cast<RadioButton*>(winMgr.getWindow("RadioEUR"));
radio->subscribeEvent(RadioButton::EventSelectStateChanged, Event::Subscriber(&DemoSample::onCurrencySelected, this));
radio->setID(3);
radio = static_cast<RadioButton*>(winMgr.getWindow("RadioMRO"));
radio->subscribeEvent(RadioButton::EventSelectStateChanged, Event::Subscriber(&DemoSample::onCurrencySelected, this));
radio->setID(4);

// Configure the numeric widgets
Editbox* numericValue = static_cast<Editbox*>(winMgr.getWindow("NumericValue"));
numericValue->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onNumericChanged, this));
Editbox* numericFormat = static_cast<Editbox*>(winMgr.getWindow("NumericFormat"));
numericFormat->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onNumericChanged, this));
PushButton* numericFormatButton = static_cast<PushButton*>(winMgr.getWindow("NumericFormatButton"));
numericFormatButton->subscribeEvent(PushButton::EventClicked, Event::Subscriber(&DemoSample::onNumericFormatClicked, this));

// Configure the date/time widgets
Editbox* dateValue = static_cast<Editbox*>(winMgr.getWindow("DateValue"));
dateValue->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onDateTimeChanged, this));
Editbox* timeValue = static_cast<Editbox*>(winMgr.getWindow("TimeValue"));
timeValue->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onDateTimeChanged, this));
Editbox* dateFormat = static_cast<Editbox*>(winMgr.getWindow("DateFormat"));
dateFormat->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onDateTimeChanged, this));
Editbox* timeFormat = static_cast<Editbox*>(winMgr.getWindow("TimeFormat"));
timeFormat->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onDateTimeChanged, this));
PushButton* dateTimeFormatButton = static_cast<PushButton*>(winMgr.getWindow("DateTimeFormatButton"));
dateTimeFormatButton->subscribeEvent(PushButton::EventClicked, Event::Subscriber(&DemoSample::onDateTimeFormatClicked, this));

// Configure the spinner
Spinner* spinner = static_cast<Spinner*>(winMgr.getWindow("Spinner"));
spinner->subscribeEvent(Spinner::EventValueChanged, Event::Subscriber(&DemoSample::onSpinnerValueChanged, this));
static_cast<Editbox*>(winMgr.getWindow(spinner->getName() + "__auto_editbox__"))->setReadOnly(true); // We cannot handle manually specified values yet
spinner->setTextInputMode(Spinner::FloatingPoint); // FloatingPoint, Integer, Hexadecimal, Octal
spinner->setMinimumValue(-10.0f);
spinner->setMaximumValue(10.0f);
spinner->setStepSize(0.02f);
spinner->setCurrentValue(5.2f);

// Configure the character widgets
Editbox* characterValue = static_cast<Editbox*>(winMgr.getWindow("CharacterValue"));
characterValue->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onCharacterChanged, this));
Editbox* characterFormat = static_cast<Editbox*>(winMgr.getWindow("CharacterFormat"));
characterFormat->subscribeEvent(Editbox::EventTextChanged, Event::Subscriber(&DemoSample::onCharacterChanged, this));
PushButton* characterFormatButton = static_cast<PushButton*>(winMgr.getWindow("CharacterFormatButton"));
characterFormatButton->subscribeEvent(PushButton::EventClicked, Event::Subscriber(&DemoSample::onCharacterFormatClicked, this));
EventArgs e;
onCharacterFormatClicked(e);

// Initialize the localise values
RefreshLocalisedValues();
}
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)
{
CEGUI::FontManager::getSingleton().destroyAllFonts();
}
private:
ICU icu; // International Components for Unicode

void RefreshLocalisedValues()
{
// Trigger changes in localised widgets to refresh their values accordingly
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
EventArgs eventArgs;
static_cast<RadioButton*>(winMgr.getWindow("RadioCAD"))->fireEvent(RadioButton::EventSelectStateChanged, eventArgs);
static_cast<PushButton*>(winMgr.getWindow("NumericFormatButton"))->fireEvent(PushButton::EventClicked, eventArgs);
static_cast<PushButton*>(winMgr.getWindow("DateTimeFormatButton"))->fireEvent(PushButton::EventClicked, eventArgs);
static_cast<Spinner*>(winMgr.getWindow("Spinner"))->fireEvent(Spinner::EventValueChanged, eventArgs);
}

bool onLocaleChanged(const CEGUI::EventArgs& e)
{
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
String country = static_cast<Combobox*>(winMgr.getWindow("Countries"))->getText();
String language = static_cast<Combobox*>(winMgr.getWindow("Languages"))->getText();
if(icu.setLocale(language.c_str(), country.c_str()))
RefreshLocalisedValues();
else
MessageBox(NULL,
("Error with setLocale(" + language + ", " + country + ")").c_str(),
"Error",
MB_OK | MB_ICONERROR | MB_TASKMODAL);

return true;
}

bool onLoadEveryISO(const CEGUI::EventArgs& e)
{
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
ListboxTextItem* listboxTextItem;
int32_t count;

// Change the label of the button
PushButton* everyISO = static_cast<PushButton*>(winMgr.getWindow("EveryISO"));
everyISO->setText("This will take a few seconds...");

// Display every ISO countries in a combobox
Combobox* countries = static_cast<Combobox*>(winMgr.getWindow("Countries"));
const char * const * listCountries = Locale::getISOCountries();
for(count = 0; listCountries[count]; count++)
{
listboxTextItem = new ListboxTextItem(listCountries[count]);
listboxTextItem->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
countries->addItem(listboxTextItem);
}
countries->setText( Locale::getDefault().getCountry() );

// Display every ISO languages in a combobox
Combobox* languages = static_cast<Combobox*>(winMgr.getWindow("Languages"));
const char * const * listLanguages = Locale::getISOLanguages();
for(count = 0; listLanguages[count]; count++)
{
listboxTextItem = new ListboxTextItem(listLanguages[count]);
listboxTextItem->setSelectionBrushImage("TaharezLook", "MultiListSelectionBrush");
languages->addItem(listboxTextItem);
}
languages->setText( Locale::getDefault().getLanguage() );

// Remove this button since it is no longer useful
everyISO->setEnabled(false);
everyISO->setVisible(false);

return true;
}

bool onCurrencyChanged(const CEGUI::EventArgs& e)
{
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
EventArgs eventArgs;
static_cast<RadioButton*>(winMgr.getWindow("RadioCAD"))->fireEvent(RadioButton::EventSelectStateChanged, eventArgs);
return true;
}

bool onCurrencySelected(const CEGUI::EventArgs& e)
{
// Reformat the numeric value into a properly formatted currency
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();

// Set the currency
CEGUI::uint id = static_cast<RadioButton*>(winMgr.getWindow("RadioCAD"))->getSelectedButtonInGroup()->getID();
switch(id)
{
case 1:
icu.setCurrency("CAD");
break;
case 2:
icu.setCurrency("USD");
break;
case 3:
icu.setCurrency("EUR");
break;
case 4:
// Mauritania does not use a decimal division of units
// and yet ICU still displays decimal units??
icu.setCurrency("MRO");
break;
}

CEGUI::String rawValue = static_cast<Editbox*>(winMgr.getWindow("CurrencyValue"))->getText();
double currency = atof(rawValue.c_str());
CEGUI::String formattedValue;
if( icu.formatCurrency(currency, formattedValue) )
static_cast<Editbox*>(winMgr.getWindow("CurrencyFormattedValue"))->setText(formattedValue);

return true;
}

bool onNumericChanged(const CEGUI::EventArgs& e)
{
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
EventArgs eventArgs;
static_cast<PushButton*>(winMgr.getWindow("NumericFormatButton"))->fireEvent(PushButton::EventClicked, eventArgs);

return true;
}

bool onNumericFormatClicked(const CEGUI::EventArgs& e)
{
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
String formattedText;
if( icu.formatNumber(static_cast<Editbox*>(winMgr.getWindow("NumericValue"))->getText(),
static_cast<Editbox*>(winMgr.getWindow("NumericFormat"))->getText(),
formattedText) )
static_cast<Editbox*>(winMgr.getWindow("NumericFormattedValue"))->setText(formattedText);

// Ordinal representation of an integer value
double doubleValue = atof(static_cast<Editbox*>(winMgr.getWindow("NumericValue"))->getText().c_str());
if( icu.numberToOrdinal((int) doubleValue, formattedText) )
static_cast<Editbox*>(winMgr.getWindow("NumericFormattedOrdinal"))->setText(formattedText);

// Textual representation of the numeric value
// Note that this value must be raw, containing only digits and a decimal point
// Since atof() is used to convert from a string to a double this numeric value is not localised
if( icu.numberToText(doubleValue, formattedText) )
static_cast<Editbox*>(winMgr.getWindow("NumericFormattedText"))->setText(formattedText);

return true;
}

bool onDateTimeChanged(const CEGUI::EventArgs& e)
{
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
EventArgs eventArgs;
static_cast<PushButton*>(winMgr.getWindow("DateTimeFormatButton"))->fireEvent(PushButton::EventClicked, eventArgs);

return true;
}

bool onDateTimeFormatClicked(const CEGUI::EventArgs& e)
{
// Format the date and time according to their specified values and formats
// In theory a format can include both the date and the time: yyyy/MM/dd HH:mm:ss
// However in practice the resulting time is not accurate (within 1 minute 47 seconds)
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
UDate localDate, localTime, gmtDate, gmtTime, gmtDateTime;
if(icu.CeguiStringToDateTime( static_cast<Editbox*>(winMgr.getWindow("DateValue"))->getText(),
"yyyy/MM/dd", // Internal format
localDate)
&& icu.CeguiStringToDateTime( static_cast<Editbox*>(winMgr.getWindow("TimeValue"))->getText(),
"HH:mm:ss", // Internal format
localTime) )
{
String formattedDate, formattedTime;
if(icu.formatDateTime( localDate,
static_cast<Editbox*>(winMgr.getWindow("DateFormat"))->getText(),
formattedDate)
&& icu.formatDateTime( localTime,
static_cast<Editbox*>(winMgr.getWindow("TimeFormat"))->getText(),
formattedTime)
)
static_cast<Editbox*>(winMgr.getWindow("LocalDateTimeFormattedValue"))->setText(formattedDate + " " + formattedTime);

// GMT time
if( icu.CeguiStringToDateTime(static_cast<Editbox*>(winMgr.getWindow("LocalDateTimeFormattedValue"))->getText(),
"yyyy/MM/dd HH:mm:ss",
gmtDateTime)
&& icu.localToGmt(localDate, localTime, gmtDate, gmtTime)
&& icu.formatDateTime(gmtDate, "yyyy/MM/dd", formattedDate)
&& icu.formatDateTime(gmtTime, "HH:mm:ss", formattedTime)
)
static_cast<Editbox*>(winMgr.getWindow("GmtDateTimeFormattedValue"))->setText(formattedDate + " " + formattedTime);
}

return true;
}

bool onSpinnerValueChanged(const CEGUI::EventArgs& e)
{
// Reformat the displayed value into a locale appropriate format
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
Spinner* spinner = static_cast<Spinner*>(winMgr.getWindow("Spinner"));

String formattedValue;
if( icu.formatNumber(spinner->getCurrentValue(), "#0.00", formattedValue) )
{
// Disable the Editbox events, especially the EventTextChanged that
// triggers Spinner::handleEditTextChange, which attempts to convert
// the textual value into a non-localised numeric value
Editbox* editbox = static_cast<Editbox*>(winMgr.getWindow(spinner->getName() + "__auto_editbox__"));
bool muted = editbox->isMuted();
editbox->setMutedState(true);
spinner->setText(formattedValue);
editbox->setMutedState(muted);
}

return true;
}

bool onCharacterChanged(const CEGUI::EventArgs& e)
{
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
EventArgs eventArgs;
static_cast<PushButton*>(winMgr.getWindow("CharacterFormatButton"))->fireEvent(PushButton::EventClicked, eventArgs);

return true;
}

bool onCharacterFormatClicked(const CEGUI::EventArgs& e)
{
using namespace CEGUI;
WindowManager& winMgr = WindowManager::getSingleton();
String formattedText;
if( icu.formatText(static_cast<Editbox*>(winMgr.getWindow("CharacterValue"))->getText(),
static_cast<Editbox*>(winMgr.getWindow("CharacterFormat"))->getText(),
"*",
formattedText) )
static_cast<Editbox*>(winMgr.getWindow("CharacterFormattedValue"))->setText(formattedText);

return true;
}

};

#endif // _FormattedData_h_
</pre>

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

#include "FormattedNumericData.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();
}
</pre>

===FormattedData.layout===
<pre>
<?xml version="1.0" encoding="UTF-8"?>

<GUILayout >
<Window Type="DefaultWindow" Name="Root" >
<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="TaharezLook/FrameWindow" Name="FrameWindow" >
<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.07125,0},{0.013335,0},{0.910001,0},{0.873733,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseTarget" />
<Window Type="TaharezLook/Spinner" Name="Spinner" >
<Property Name="Text" Value="10.00" />
<Property Name="StepSize" Value="1" />
<Property Name="CurrentValue" Value="10" />
<Property Name="MaximumValue" Value="32767" />
<Property Name="MinimumValue" Value="-32768" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.8473,0},{0.731682,0},{0.951964,0},{0.790123,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="SpinnerLabel" >
<Property Name="Text" Value="Localised Spinner widget with 2 decimals:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.395457,0},{0.731682,0},{0.836346,0},{0.790123,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="CurrencyFormattedValue" >
<Property Name="ReadOnly" Value="True" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.616765,0},{0.203821,0},{0.954642,0},{0.262262,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioCAD" >
<Property Name="Text" Value="Canadian (CAD)" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.430655,0},{0.158378,0},{0.614153,0},{0.187144,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioMRO" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Mauritania (MRO)" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.430655,0},{0.26902,0},{0.614153,0},{0.297787,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioUSD" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="US (USD)" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.430655,0},{0.195183,0},{0.5605,0},{0.22395,0}}" />
</Window>
<Window Type="TaharezLook/RadioButton" Name="RadioEUR" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Euro (EUR)" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.430655,0},{0.232215,0},{0.5605,0},{0.260983,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="CountriesLabel" >
<Property Name="Text" Value="Countries:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.022504,0},{0.069049,0},{0.132414,0},{0.117804,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="LanguagesLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Languages:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.268405,0},{0.069049,0},{0.385766,0},{0.117804,0}}" />
</Window>
<Window Type="TaharezLook/Combobox" Name="Countries" >
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.142027,0},{0.069049,0},{0.245976,0},{0.902039,0}}" />
<Property Name="MaxEditTextLength" Value="1073741823" />
</Window>
<Window Type="TaharezLook/Combobox" Name="Languages" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.395379,0},{0.069049,0},{0.499329,0},{0.90204,0}}" />
<Property Name="MaxEditTextLength" Value="1073741823" />
</Window>
<Window Type="TaharezLook/StaticText" Name="Separator1" >
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.013562,0},{0.141452,0},{0.995305,0},{0.150048,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="Separator2" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.013562,0},{0.309408,0},{0.995305,0},{0.318004,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="Separator3" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.013562,0},{0.553045,0},{0.995305,0},{0.561642,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="Separator5" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.007601,0},{0.814139,0},{0.989344,0},{0.822736,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="NumericFormatLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Format:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.036292,0},{0.403136,0},{0.141946,0},{0.461576,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="NumericFormat" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="#,##0.03" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.150298,0},{0.403136,0},{0.421111,0},{0.461576,0}}" />
</Window>
<Window Type="TaharezLook/Button" Name="NumericFormatButton" >
<Property Name="Text" Value="Apply" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.473919,0},{0.370638,0},{0.603204,0},{0.429079,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Editbox" Name="NumericFormattedValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="ReadOnly" Value="True" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.616765,0},{0.339418,0},{0.954642,0},{0.397859,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="DateFormatLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Format:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.036292,0},{0.63711,0},{0.141946,0},{0.695551,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="DateFormat" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="yyyy/MM/dd" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.150298,0},{0.63711,0},{0.269099,0},{0.695551,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="DateValueLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Date:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.036292,0},{0.574987,0},{0.141946,0},{0.633428,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="DateValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="2006/05/14" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.150298,0},{0.574987,0},{0.267608,0},{0.633428,0}}" />
</Window>
<Window Type="TaharezLook/Button" Name="DateTimeFormatButton" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Apply" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.473919,0},{0.610743,0},{0.603205,0},{0.669184,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Editbox" Name="LocalDateTimeFormattedValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="ReadOnly" Value="True" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.724067,0},{0.578862,0},{0.954642,0},{0.637303,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="TimeValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="12:00:01" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.351492,0},{0.574987,0},{0.441976,0},{0.633428,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="TimeValueLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Time:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.280703,0},{0.574987,0},{0.347609,0},{0.633428,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="TimeFormat" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="HH:mm:ss" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.281446,0},{0.63711,0},{0.441976,0},{0.695551,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="NumericValueLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Numeric:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.036292,0},{0.339418,0},{0.141946,0},{0.397857,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="NumericValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="123456.78" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.150298,0},{0.339418,0},{0.421111,0},{0.397858,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="CurrencyValueLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Currency:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.036292,0},{0.203821,0},{0.141946,0},{0.26226,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="CurrencyValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="123456.78" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.150298,0},{0.203821,0},{0.421111,0},{0.262262,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="Separator4" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.013562,0},{0.702202,0},{0.995305,0},{0.710798,0}}" />
</Window>
<Window Type="TaharezLook/Button" Name="EveryISO" >
<Property Name="Text" Value="Load every country and languages" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.559611,0},{0.069049,0},{0.94523,0},{0.12749,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Editbox" Name="NumericFormattedText" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="ReadOnly" Value="True" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.153278,0},{0.482989,0},{0.954642,0},{0.54143,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="CharacterFormattedValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="ReadOnly" Value="True" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.616765,0},{0.883872,0},{0.954642,0},{0.942313,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="CharacterFormat" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="000 000 000" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.150298,0},{0.908716,0},{0.421111,0},{0.967156,0}}" />
</Window>
<Window Type="TaharezLook/Button" Name="CharacterFormatButton" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Apply" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.473919,0},{0.883872,0},{0.603205,0},{0.942313,0}}" />
<Property Name="MouseCursorImage" Value="set:TaharezLook image:MouseArrow" />
</Window>
<Window Type="TaharezLook/Editbox" Name="CharacterValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="123456" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.150298,0},{0.844998,0},{0.421111,0},{0.903438,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="LocalDateTimeFormattedLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Local:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.641358,0},{0.578862,0},{0.718697,0},{0.637302,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="GmtDateTimeFormattedLabel" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="GMT:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.641358,0},{0.63711,0},{0.718697,0},{0.69555,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="GmtDateTimeFormattedValue" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="ReadOnly" Value="True" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.725558,0},{0.63711,0},{0.954642,0},{0.695551,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="NumericValueLabel1" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Numeric:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.036292,0},{0.844998,0},{0.141946,0},{0.903437,0}}" />
</Window>
<Window Type="TaharezLook/StaticText" Name="NumericFormatLabel1" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="Text" Value="Format:" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.036292,0},{0.908716,0},{0.141946,0},{0.967156,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="NumericFormattedOrdinal" >
<Property Name="Font" Value="Commonwealth-10" />
<Property Name="ReadOnly" Value="True" />
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedMaxSize" Value="{{1,0},{1,0}}" />
<Property Name="UnifiedAreaRect" Value="{{0.616765,0},{0.403136,0},{0.954642,0},{0.461577,0}}" />
</Window>
</Window>
</Window>
</GUILayout>
</pre>

Scheme files

2011-01-07T09:53:41Z

Makofierce:

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

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

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

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

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

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

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

Each element will be described individually below.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Attributes:
* '''Name''' - Name of the factory / window type which is to be added.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Introduction To Auto Windows

2011-01-07T09:52:26Z

Makofierce:

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

<code><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");
...
</code>

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:
<code><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");
...
</code>

==== 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|CrazyEddie]]

Subversion

2011-01-07T09:51:55Z

Makofierce:

This page introduce the use of subversion. If you're only intent is to get the files from subversion you should start with [[HOWTO: Obtain 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]]

Changes and Porting Tips for 0.5.0

2011-01-07T09:51:17Z

Makofierce:

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

To be continued...

The Beginners Guide to Falagard skinning - Part I

2011-01-07T09:49:49Z

Makofierce:

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

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

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:

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

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.

<?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>

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.

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

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:

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

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.

<?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>

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

<Image imageset="MyImages" image="ButtonBG" />

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

<VertFormat type="Stretched" />
<HorzFormat type="Stretched" />

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.

<?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>

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.

<ImagerySection name="label">
<TextComponent>
</TextComponent>
</ImagerySection>

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

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

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:

<?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>

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:

<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" />

*''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:

<Section name="label">
<ColourProperty name="NormalTextColour" />
</Section>

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:

<?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>

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|lindquist]] 06:10, 6 Dec 2005 (CET)

Create ImageButtons

2011-01-07T09:47:22Z

Makofierce:

If you write a GUI for a game, at some time comes the point where you want to create the most exciting kind of buttons: ImageButtons ! But care, I'm not talking about a default button frame, that has a picture instead of a text, I'm talking about ''completely'' self-drawn buttons. I've found two ways to accomplish that task, both are nice.

== Preparations ==
There are a few tasks we have to accomplish before being able to create an ImageButton.

=== Draw it ! ===
The most important thing is, of course, draw the pictures. If you don't want to accomplish this, ask your graphics artist :)
You have to draw 4 pictures/button, wich represents the four states:
#Normal: That is how the button looks like most of the time.
#Hover: This is how the button should look when the mouse comes over it.
#Pushed: When the user clicks the mouse button (and holds it down a bit) over the button, it looks like this.
#Disabled: You can imagine what this is.

This is the file we'll use for this HOWTO and as you see, i didn't ask my graphics artist to do one :p
You can find all other files (source code, data files) there too.
[[http://pompei2.cesar4.be/cegui/imgButton/]]
Edit: shit the link is currently dead ... I hope I find the files so I can upload them again, but atm everything that is written here must be enough. On questions/problems just ask in the forum.

=== The Imageset ===
When I talk about an Imageset, I mean two files: The picture file (.tga, .png, or whatever) and the description (.imageset) file. The picture file can contain a lot of images, but its size has to be a power of two. The description file is an xml file wich gives a name to a (rectangular) location in the picture. So you can call the location (150,150,32,32) "UnitIcon" for example.

'''An example for a .imageset file:'''
<?xml version="1.0" encoding="UTF-8"?>

<Imageset Name="THEButton" Imagefile="THEButton.png" >
<Image Name="btnNormal" XPos="0" YPos="0" Width="64" Height="20" />
<Image Name="btnHover" XPos="0" YPos="20" Width="64" Height="20" />
<Image Name="btnPushed" XPos="0" YPos="40" Width="64" Height="20" />
<Image Name="btnDisabl" XPos="0" YPos="60" Width="64" Height="20" />
</Imageset>
We will use this imageset in our examples. It defines four named images: btnNormal, btnHover, btnPushed and btnDisabl (saved in the file "THEButton.png"). The whole imageset is called "THEButton" and saved in a file named "THEButton.imageset".

How to use this imageset now ? This is very simple, you just have to do this in your initialisation code:
// Load the THEButton Imageset that has the pictures for our button.
CEGUI::ImagesetManager::getSingleton().createImageset( "THEButton.imageset" );
That's all ! Of course, you should do this in a try/catch block.

If, for some wicked reason, you want to do something in code with this imageset, you can either save the pointer that the function above returns, or you just get that pointer if you know the name of the imageset (what you usually do), using this function:
CEGUI::Imageset *m_pImageSet = CEGUI::ImagesetManager::getSingleton().getImageset( "THEButton" );

Enough about imagesets.

== The programmer's job ==
Now we can create the button itself (in two different ways):

=== The first way: mainly in code ===
One way is to create the button in code, you usually do this if you only know wich button to display at runtime. Maybe a strategy game is the best to illustrate this. Imagine you have the buttonspanel, a place on screen with an array of buttons. The buttons that are present there depend on something (like wich unit is currently selected or so). The first thing you have to do, is not in code. Create one layout file for every button. The file should look somewhat like this:

'''Content of button1.layout version 0.1'''
<?xml version="1.0" encoding="UTF-8" ?>
<GUILayout>
<Window Type="TaharezLook/ImageButton" Name="btnNewGame">
<Property Name="UnifiedPosition" Value="{{0,0},{0,0}}" />
<Property Name="UnifiedSize" Value="{{0,64},{0,20}}" />
<nowiki>
</nowiki>
<Property Name="NormalImage" Value="set:THEButton image:btnNormal" />
<Property Name="HoverImage" Value="set:THEButton image:btnHover" />
<Property Name="PushedImage" Value="set:THEButton image:btnPushed" />
<Property Name="DisabledImage" Value="set:THEButton image:btnDisabl" />
<nowiki></nowiki>
</Window>
</GUILayout>

If you have an imagebutton but you want it to have a caption, you could write this kind of layout file:

'''Content of button1.layout version 0.2'''
<?xml version="1.0" encoding="UTF-8" ?>
<GUILayout>
<Window Type="TaharezLook/ImageButton" Name="btnNewGame">
<Property Name="UnifiedPosition" Value="{{0,0},{0,0}}" />
<Property Name="UnifiedSize" Value="{{0,64},{0,20}}" />
<nowiki>
</nowiki>
<Property Name="NormalImage" Value="set:THEButton image:btnNormal" />
<Property Name="HoverImage" Value="set:THEButton image:btnHover" />
<Property Name="PushedImage" Value="set:THEButton image:btnPushed" />
<Property Name="DisabledImage" Value="set:THEButton image:btnDisabl" />
<nowiki></nowiki>
<Window Type="TaharezLook/StaticText" Name="btnNewGame_text__">
<nowiki>
</nowiki>
<Property Name="UnifiedPosition" Value="{{0,0},{0,0}}" />
<Property Name="UnifiedSize" Value="{{1,0},{1,0}}" />
<nowiki></nowiki>
<Property Name="FrameEnabled" Value="False" />
<Property Name="BackgroundEnabled" Value="False" />
<nowiki></nowiki>
<Property Name="HorzFormatting" Value="WordWrapCentred" />
<Property Name="VertFormatting" Value="Middle" />
<nowiki>

</nowiki>
<Property Name="Disabled" Value="True" />
<nowiki></nowiki>
<Property Name="Text">New game</Property>
</Window>
</Window>
</GUILayout>

This adds a child window of type StaticText, with no border and background, that takes all the place in the button, so we can center it. If your caption has to be not centered, play with the values.

A problem that comes up now, is that if the user clicks on the button, the click will be absorbed by the StaticText, and won't reach the button. That's bad. I searched around and found the following two propertys:
<Property Name="MousePassThroughEnabled" Value="True" />
<Property Name="DistributeCapturedInputs" Value="True" />
But both didn't seem to work as expected, I asked the forums and lindquist told me that "If all you want is a simple label added to the ImageButton then adding a TextComponent in the looknfeel is a much cleaner solution.". He is probably right, but I didn't struggle with looknfeels yet. If you achieved this, you can tell me or add a chapter to this wiki :)

The solution he suggested (and the only one wich worked, if i remember correctly, is disabling the staticText (like in the complete code written above)

<Property Name="Disabled" Value="True" />

Now all you need to do to load and show the button are the following four lines of code.

CEGUI::Window *w = CEGUI::WindowManager::getSingleton().loadWindowLayout( "button1.layout" );
rootWin->addChildWindow( w );
w->setPosition( CEGUI::UVector2( CEGUI::UDim(0.5f,-32.0f), CEGUI::UDim(0.5f,-10.0f) ) );
w->setVisible( true );
Supposing rootWin is your current root window, or any other window you want to put the button in.
We set the position to be the center (0.5f) minus the half the height/width of the button, so the button is really centered.
Of course, you can do everything else you want before (and while) showing the button.

That's it ! now you can work with the button however you want :)

=== The second way: Let the power of layout guide you ===
I suppose you read the first way, because they are very similar and I won't rewrite the whole code here. The main difference is that if you like layouts, you'll already have declared all your windows in layout files. The the "'''Content of button1.layout version 0.2'''" won't be alone in a layout file of its own, but it will be in your already existing layout files.
You still have to load the Imageset. I Provided a sample, named imgButtonSample.layout

That's it ! If you got suggestions, corrections or whatever feedback, just tell me.
----

--[[User:Pompei2|Pompei2]] 11:18, 11 January 2007 (PST)

--[[User:fezztah|fezztah]]
To properly centre the label on an image button vertically as well as horizontally I had to change the line: <Property Name="VertFormatting" Value="Middle" /> such that Value="VertCentred" instead. I'm not sure if the original is a mistake so I won't alter it in case it has some other purpose.

Hit testing of non rectangular windows with CEGUI 0.7.x

2011-01-07T09:44:46Z

Makofierce:

{{notice|message=To use this tutorial with CEGUI's OgreRenderer, you will require a recent bug fix which is available from the stable v0-7 branch of subversion r2564 or later, or a snapshot build of CEGUI dated later than 14th June 2010 (or in other words, a snapshot with a version higher than 0.7.100614).<br/>For users of the Direct3D renderers (all versions), the technique described in this article is not currently supported due to an unimplemented function – I will implement this missing function soon.}}

== Why this tutorial? ==
Generally speaking, CEGUI's idea of a window is something that is rectangular. For most normal uses this is fine and perfectly adequate, however, there are times when perhaps it would be nice to have a button (or something else) that's a little bit... special. So, if you're interested in implementing round buttons, pie segment buttons, some type of weird non-rectangular window or window with a hole in it, this tutorial is for you!

=== What it is ===
This tutorial is solely about hit testing. Meaning when a CEGUI window reports that a given point hits and when a given point does not hit the window. The code in the tutorial will test the alpha component of the window's rendered imagery, thus allowing pixel accurate hit testing of windows built from irregular shaped imagery.

=== What it is not ===
This tutorial does not present a window that is truly non-rectangular. For example, any child content added to the window type shown here will still be clipped – as normal – to the rectangular region defined for the parent window. What is shown is purely about hit testing, although this will be useful in a very large number of cases.

== Overview of the what and the how ==
As you should know, the rendering for a CEGUI window is made up of various images which may be drawn at a one to one pixel size or alternatively may be stretched over some arbitrary area of the window's surface. This presents a challenging situation when we have a desire to examine the pixels of those images, because we can not easily and quickly calculate which bit of a given image is drawn at a particular location for a given window instance. If you factor in the way that various properties can also affect the rendered output, we quickly find ourselves in an almost impossible situation. What we really need is to be able to access the final rendered output of the window in isolation.

In order to achieve our aims, we will have to create a subclass of one of the existing classes in the CEGUI::Window hierarchy and register this type with the system for use. This could be a totally new window type with all new functionality, or we could subclass one of the existing types in order to take advantage of existing functionality, but add in our new hit testing code. For this tutorial we will be sub-classing the CEGUI::PushButton type to provide a push button which has the advanced hit testing which is the topic of this tutorial. At the most basic level, all we are really going to do is override the Window::isHit member function and do something different in there. However, due to the nature of what we are trying to do, some other parts are required in order that we can have access to the required data.

Starting with the 0.7.0 release, CEGUI provides reasonably simple means by which we can render a window to its own texture. Aside from all the other benefits, this affords us a means to examine the rendering performed for a particular window by examining its associated texture – and it is this approach that we will use in this tutorial.

The basic approach will be to first do the existing rectangular hit test, because we don't want the expense of testing at the pixel level if the test point is outside of the window's bounding rectangle. Once we know the point is within the window's area, we can then proceed to look at the alpha channel in the rendered output to see if we should report a hit or not – a value of 0 in the alpha channel is 100% transparent, and so will not register a hit, whereas any other value will register a hit. One enhancement that could be made to the code presented here is to allow this to be a configurable threshold value.

Of course, when doing anything of this nature, performance needs to be considered, and you probably already know that frequent reads from texture / video memory by the CPU is likely to be expensive, so our solution attempts to mitigate that somewhat by using a secondary buffer in system RAM that contains a copy of the rendered output, which is only populated when the rendered output changes. This means that for most of the tests we will be operating out of an existing buffer in system memory, which should have minimal impact on overall performance.

== Implementation ==
=== Class Declaration ===
First I'll introduce the class declaration, and then we can discuss the various functions and such that we see there. Our class is called AlphaHitWindow, which was somewhat arbitrarily chosen just for the sake of this tutorial.

<code>class AlphaHitWindow : public CEGUI::PushButton
{
public:
//! Window factory name.
static const CEGUI::String WidgetTypeName;

//! Constructor
AlphaHitWindow(const CEGUI::String& type, const CEGUI::String& name);
//! Destructor
~AlphaHitWindow();

// overridden from Window base class
bool isHit(const CEGUI::Vector2& position, const bool allow_disabled = false) const;

protected:
//! handler to copy rendered data to a memory buffer
bool renderingEndedHandler(const CEGUI::EventArgs& args);
// overridden from Window base class
bool testClassName_impl(const CEGUI::String& class_name) const;

//! Pointer to buffer holding the render data
CEGUI::uint32* d_hitTestBuffer;
//! Size of the hit test buffer (i.e. its capacity)
size_t d_hitBufferCapacity;
//! Dimensions in pixels of the data in the hit test buffer
CEGUI::Size d_hitBufferSize;
//! whether data in hit test buffer is inverted.
bool d_hitBufferInverted;
};</code>
As we can see, with the exception of the Window::isHit override, the new function renderingEndedHandler and some member variables, the class is mainly standard boiler plate stuff needed when creating a new window type for CEGUI – as such, we'll just be covering the important bits and ignoring those other, standard, parts.

=== Constructor ===
Since we have some special requirements, we need to do a couple of things in the constructor. First, because we need texture backing in order to read our rendered output from a texture, we enable the auto rendering surface for our window (if this is not supported, our window will revert back to regular rectangular hit testing).
<code> setUsingAutoRenderingSurface(true);</code>
Next, in order that we only update our buffer when the texture content gets changed, we will subscribe a handler to be called when rendering for each rendering queue is ended.
<code> CEGUI::RenderingSurface* rs = getRenderingSurface();
if (rs)
rs->subscribeEvent(CEGUI::RenderingSurface::EventRenderQueueEnded,
CEGUI::Event::Subscriber(&AlphaHitWindow::renderingEndedHandler, this));</code>
All simple stuff so far!

=== The Window::isHit override ===
This mainly uses the member variables and such which are set up in the event handler discussed below.

The first thing we do is call the base class implementation, and if that returns false, so will we.
<code> if (!CEGUI::PushButton::isHit(position, allow_disabled))
return false;</code>
Next we see if out pointer to a system memory copy of the texture data is valid. If not, it means that either something has gone wrong, or the hardware we're running on does not support what we're trying to do, so in these cases we return true to default back to the standard rectangular hit testing.
<code> if (!d_hitTestBuffer)
return true;</code>
Next we convert the screen pixel point we were given to a local window pixel point, and then use this to calculate the index into the buffer for the pixel described by the given point (this is just a basic calculation of ((y * width) + x).
<code> const CEGUI::Vector2 wpos(CEGUI::CoordConverter::screenToWindow(*this, position));
const size_t idx = (d_hitBufferInverted ?
d_hitBufferSize.d_height - wpos.d_y :
wpos.d_y) * d_hitBufferSize.d_width + wpos.d_x;</code>
Finally we read the pixel from the buffer, shift right so we are left with just the alpha part and test this against our threshold value – which in this example is simply 0.
<code> return (d_hitTestBuffer[idx] >> 24) > 0;</code>

=== The renderingEndedHandler event handler function ===
If there is any magic to doing this, then it happens in this function. It's here that we grab a copy of the rendered texture data and update the other member variables to be ready for subsequent use in the override of the Window::isHit function.

Since our handler will get called for each render queue that is drawn, the first thing we should do is quietly exit for any queue except the one the main rendering will be done on – which is CEGUI::RQ_BASE. In actual fact, it's highly likely that this will be the only queue drawn, but we need the check just to be safe.
<code> if (static_cast<const CEGUI::RenderQueueEventArgs&>(args).queueID != CEGUI::RQ_BASE)
return false;</code>
Next we'll grab the CEGUI::RenderingSurface and make sure it's the right type. If there is no surface or it is not the right type, we'll bail out. Generally this should not happen, but it might if the hardware does not support rendering to texture, or if the user has changed settings in such a way to affect the rendering surface.
<code> CEGUI::RenderingSurface* const rs = getRenderingSurface();
if (!rs || !rs->isRenderingWindow())
return false;</code>
Now we simply get the CEGUI::TextureTarget for our CEGUI::RenderingWindow rendering surface.
<code> CEGUI::TextureTarget& tt =
static_cast<CEGUI::RenderingWindow* const>(rs)->getTextureTarget();</code>
And now we access the actual texture to obtain its dimensions and calculate the size of the buffer needed to hold the data (in 32bit pixels, since all CEGUI rendering is ARGB format).
<code> CEGUI::Texture& texture = tt.getTexture();
const CEGUI::Size tex_sz(texture.getSize());
const size_t reqd_capacity =
static_cast<int>(tex_sz.d_width) * static_cast<int>(tex_sz.d_height);</code>
At this point, we may need to allocate or reallocate our buffer depending on the previous state. So we simply compare the required buffer size we just calculated against the stored buffer size, and if we need a bigger buffer we free the existing one so that we know to reallocate in the next step.
<code> if (reqd_capacity > d_hitBufferCapacity)
{
delete[] d_hitTestBuffer;
d_hitTestBuffer = 0;
d_hitBufferCapacity = 0;
}</code>
Next we see if we already have a buffer allocated, and if not, allocate a buffer of the appropriate size.
<code> if (!d_hitTestBuffer)
{
d_hitTestBuffer = new CEGUI::uint32[reqd_capacity];
d_hitBufferCapacity = reqd_capacity;
}</code>
Next we store some details about the buffer so we know how to interpret the data within the isHit function.
<code> d_hitBufferInverted = tt.isRenderingInverted();
d_hitBufferSize = tex_sz;</code>
And the most important step, save the data from the texture into our buffer
<code> texture.saveToMemory(d_hitTestBuffer);</code>
And finally, return that we handled this event
<code> return true;</code>

=== Registering the Window and making Schemes! ===
Now we have our new Window type and we know how it all works, we need to register this new type with CEGUI so that the system knows of its existence and can make instances of it. This is another incredibly simple step, requiring just a single line of code.
<code>CEGUI::WindowFactoryManager::addFactory<CEGUI::TplWindowFactory<AlphaHitWindow> >();</code>
Now we can add an entry in our scheme file which uses our new type in a Falagard window mapping, such that it gets used. For this tutorial, we'll use TaharezLook as the example, though the changes or additions are generally the same for any scheme.

We have the option of creating an all new window type mapping, which will allow us to continue to use the existing TaharezLook/Button type, like this:
<code><FalagardMapping WindowType="TaharezLook/AlphaHitButton" TargetType="AlphaHitWindow" Renderer="Falagard/Button" LookNFeel="TaharezLook/Button" /></code>
Or, we can modify the existing mapping so that TaharezLook/Button will use our new class instead, like this:
<code><FalagardMapping WindowType="TaharezLook/Button" TargetType="AlphaHitWindow" Renderer="Falagard/Button" LookNFeel="TaharezLook/Button" /></code>

== Conclusion ==
Here we have created a new window type that will take advantage of certain abilities in CEGUI 0.7.x to allow us to have hit testing at the pixel level. The example above uses TaharezLook imagery for the button, which is probably not ideal as an example to show the effects achieved here, and perhaps this will be modified in a future update.

Below you can find the full class declaration and source code for the AlphaHitWindow class. You need to include the main CEGUI.h header file in order to compile the code. I hope you find this useful, and please direct any questions about this to the forum or the #cegui IRC channel on irc.freenode.net.

== Class Declaration ==
<code>class AlphaHitWindow : public CEGUI::PushButton
{
public:
//! Window factory name.
static const CEGUI::String WidgetTypeName;

//! Constructor
AlphaHitWindow(const CEGUI::String& type, const CEGUI::String& name);
//! Destructor
~AlphaHitWindow();

// overridden from Window base class
bool isHit(const CEGUI::Vector2& position, const bool allow_disabled = false) const;

protected:
//! handler to copy rendered data to a memory buffer
bool renderingEndedHandler(const CEGUI::EventArgs& args);
// overridden from Window base class
bool testClassName_impl(const CEGUI::String& class_name) const;

//! Pointer to buffer holding the render data
CEGUI::uint32* d_hitTestBuffer;
//! Size of the hit test buffer (i.e. its capacity)
size_t d_hitBufferCapacity;
//! Dimensions in pixels of the data in the hit test buffer
CEGUI::Size d_hitBufferSize;
//! whether data in hit test buffer is inverted.
bool d_hitBufferInverted;
};</code>

== Class Implementation ==
<code>//----------------------------------------------------------------------------//
const CEGUI::String AlphaHitWindow::WidgetTypeName("AlphaHitWindow");

//----------------------------------------------------------------------------//
AlphaHitWindow::AlphaHitWindow(const CEGUI::String& type, const CEGUI::String& name) :
CEGUI::PushButton(type, name),
d_hitTestBuffer(0),
d_hitBufferCapacity(0)
{
// always use this since we want to sample the pre-composed imagery when we
// do hit testing and this requires we have texture backing.
setUsingAutoRenderingSurface(true);

// here we subscribe an event which will grab a copy of the rendered content
// each time it is rendered, so we can easily sample it without needing to
// read texture content for every mouse move / hit test.
CEGUI::RenderingSurface* rs = getRenderingSurface();
if (rs)
rs->subscribeEvent(CEGUI::RenderingSurface::EventRenderQueueEnded,
CEGUI::Event::Subscriber(&AlphaHitWindow::renderingEndedHandler, this));
}

//----------------------------------------------------------------------------//
AlphaHitWindow::~AlphaHitWindow()
{
delete[] d_hitTestBuffer;
}

//----------------------------------------------------------------------------//
bool AlphaHitWindow::isHit(const CEGUI::Vector2& position, const bool allow_disabled) const
{
// still do the rect test, since we only want to do the detailed test
// if absolutely neccessary.
if (!CEGUI::PushButton::isHit(position, allow_disabled))
return false;

// if buffer is not allocated, just hit against area rect, so return true
if (!d_hitTestBuffer)
return true;

const CEGUI::Vector2 wpos(CEGUI::CoordConverter::screenToWindow(*this, position));
const size_t idx = (d_hitBufferInverted ?
d_hitBufferSize.d_height - wpos.d_y :
wpos.d_y) * d_hitBufferSize.d_width + wpos.d_x;

return (d_hitTestBuffer[idx] >> 24) > 0;
}

//----------------------------------------------------------------------------//
bool AlphaHitWindow::renderingEndedHandler(const CEGUI::EventArgs& args)
{
if (static_cast<const CEGUI::RenderQueueEventArgs&>(args).queueID != CEGUI::RQ_BASE)
return false;

// rendering surface needs to exist and needs to be texture backed
CEGUI::RenderingSurface* const rs = getRenderingSurface();
if (!rs || !rs->isRenderingWindow())
return false;

CEGUI::TextureTarget& tt =
static_cast<CEGUI::RenderingWindow* const>(rs)->getTextureTarget();

CEGUI::Texture& texture = tt.getTexture();
const CEGUI::Size tex_sz(texture.getSize());
const size_t reqd_capacity =
static_cast<int>(tex_sz.d_width) * static_cast<int>(tex_sz.d_height);

// see if we need to reallocate buffer:
if (reqd_capacity > d_hitBufferCapacity)
{
delete[] d_hitTestBuffer;
d_hitTestBuffer = 0;
d_hitBufferCapacity = 0;
}

// allocate buffer to hold data if it's not already allocated
if (!d_hitTestBuffer)
{
d_hitTestBuffer = new CEGUI::uint32[reqd_capacity];
d_hitBufferCapacity = reqd_capacity;
}

// save details about what will be in the buffer
d_hitBufferInverted = tt.isRenderingInverted();
d_hitBufferSize = tex_sz;

// grab a copy of the data.
texture.saveToMemory(d_hitTestBuffer);

return true;
}

//----------------------------------------------------------------------------//
bool AlphaHitWindow::testClassName_impl(const CEGUI::String& class_name) const
{
return (class_name == "AlphaHitWindow")|| CEGUI::PushButton::testClassName_impl(class_name);
}

//----------------------------------------------------------------------------//</code>

[[User:Crazyeddie|Crazyeddie]] 19:31, 14 June 2010 (UTC)

Unified Positions and Sizes System

2011-01-07T09:43:34Z

Makofierce:

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

'''note: This page only applies to CEGUI >= 0.4.0'''

The unified metrics system in CEGUI 0.4.0 and up, allows you to have both a relative and absolute component of a coordinate / dimension. This gives you alot more flexibility in how you layout your windows. For example you can use relative metrics for the height and absolute metrics for the width. Or simply mix and match.

There are three different forms in unified metrics:
*UDim - a single dimension.
*UVector2 - a two dimensional UDim vector
*URect - four UDims describing a rectangle by its left, top, right and bottom edges.

The property system in CEGUI uses a special syntax for unified dimensions.
== UDim ==
The UDim is the simplest.
<pre>{''scale'',''offset''} fx: {1,0}</pre>
The scale component relative to the parent window, after it has been translated to pixels the offset is added. So if we used the example above as value for the ''UnifiedWidth'' property we would get a window exactly the width of its parent.
Another example could be <pre>{0.5,25}</pre> which would make it half the width of its parent plus 25 pixels.

The properties that take a single UDim like the ones used above are:
*UnifiedXPosition
*UnifiedYPosition
*UnifiedWidth
*UnifiedHeight

== UVector2 ==
The UVector2 is used for position and size if you want avoid specifying each single dimension seperately (x,y,w,h).
<pre>{{''x-scale'',''x-offset''},{''y-scale'',''y-offset''}} fx: {{1,0},{1,0}}</pre>
Besides the extra {..} around its two UDims, it's very similar. Let's say we use the example above as value for the ''UnifiedSize'' property of a window, we would get a window that had exactly the same size as its parent.
<pre>{{1,0},{0,100}}</pre> would yield a window width the same width as its parent but an absolute height of 100 pixels.

The properties that take UVector2 values are:
*UnifiedPosition
*UnifiedSize
*UnifiedMinSize
*UnifiedMaxSize

== URect ==
The last type is URect. It's a little special in that it specifies the ''left'', ''top'', ''right'' and ''bottom'' edges instead of position and size.
As there is alot of parameters I'll write ''ls'' instead of ''left-scale'', ''to'' instead of ''top-offset'' etc.
<pre>{{ls,lo},{ts,to},{rs,ro},{bs,bo}} fx: {{0,0},{0,0},{1,0},{1,0}}</pre>
The example above is the default rectangle for a DefaultWindow type window. It will cover the entire area of its parent window.
There is only one property that takes a URect. ''UnifiedAreaRect''.
The fact that we are specifying edges instead of size, can be useful. For example if we want a window to cover its entire parent, but leave a 10 pixel border a value like this could be used: <pre>{{0,10},{0,10},{1,-10},{1,-10}}</pre>
The x and y position are simple absolute-only dims with a value of 10 pixels. The right and bottom edges are 100% relative components with a offset of -10 which will make it "move back" 10 pixels relative to the parent's right and bottom edges.

== XML examples==

<pre>
<Property Name="UnifiedPosition" Value="{{0.1,10},{1.0,-30}}" />
</pre>

X-position: 10% of the width of the parent window + 10 pixel

Y-position: 30 pixel above the bottom of the parent window

<pre>
<Property Name="UnifiedSize" Value="{{0.6,5},{0.3,20}}" />
</pre>

Width: 60% of the width of the parent window + 5 pixel

Height: 30% of the height of the parent window + 20 pixel

<pre>
<Property Name="UnifiedXPosition" Value="{0.25,-5}" />
</pre>

X-position: 25% of the width of the parent window minus 5 pixel

<pre>
<Property Name="UnifiedAreaRect" Value="{{0.1,0},{0.1,0},{0.9,0},{0.9,0}}" />
</pre>

X-position: 10% of the width of the parent window.

Y-position: 10% of the height of the parent window.

Width: 80% of the width of the parent window.

Height: 80% of the height of the parent window.

The Beginner Guide to Resource Groups

2011-01-07T09:43:08Z

Makofierce:

{{VersionBadge|0.6}}

{{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:
<code><cpp/>
Imageset* wlis = ImagesetManager::getSingleton().createImageset(
"./mygame/datafiles/gui/imagesets/WindowsLook.imageset");
</code>

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

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

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

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):
<code><cpp/>
const String& getDefaultResourceGroup();
void setDefaultResourceGroup(const String& groupname);
</code>

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:
<code><cpp/>
const String& XercesParser::getSchemaDefaultResourceGroup();
void XercesParser::setSchemaDefaultResourceGroup(const String& groupname);
</code>

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:
<code><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/");
</code>
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:
<code><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");
</code>

== 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|CrazyEddie]]

The Beginner Guide to Creating a CEGUI Window

2011-01-07T09:40:46Z

Makofierce:

{{VersionBadge|0.6}}

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

The purpose of this tutorial is to show you how to create a simple window and get it on screen. Before continuing here, it is very important that you have already read and fully understood the previous articles in this series [[The Beginner Guide to Getting CEGUI Rendering]], [[The Beginner Guide to Resource Groups]] and [[The Beginner Guide to Loading Data Files and Initialisation]]; this is important because this tutorial builds upon the basic ideas introduced in those tutorials.

== Introduction to window and widget concepts ==

Before we get the the meat of this tutorial there are some essential ideas that you must first consider.

=== Every widget is a window ===
This is the most central concept that must be grasped when working with CEGUI. Every widget within the system is derived from the same Window base class; so for the purposes of this tutorial, whenever I mention a window, the same ideas could just as easily be applied to a push button or scrollbar widget.

=== Many settings are inherited ===
Many of the settings and properties available for windows in CEGUI are passed down the window hierarchy. For example, if you set the alpha transparency on a particular window to 0.5, then by default, all window and widgets attached to that window will also be affected by the change applied at the higher level; although note also that the actual setting on the child window remains unchanged - the final values and/or settings used are usually some combination of the setting values from all windows in the hierarchy down to the current window. This also applies to things such as window destruction; by default, a window will destroy attached child windows and widgets when it is destroyed. The main advantages of this arrangement are that you can easily affect a the whole GUI by making changes to the root window settings for things like alpha, visibility, enabled / disabled state, and can easily 'clean up' an entire GUI layout by simply destroying the root window. The default 'inherited' behaviours can be overridden on a per window basis where more fine grained control is needed, or where certain advanced management techniques are to be used.

== Creating the windows ==
Enough of the waffle! Lets create a window.

There are two ways of doing this, via C++ code and XML layout files. Each approach is discussed below.

=== GUI Creation via C++ code ===
All windows in CEGUI are created by the WindowManager singleton object. You can get access to this object via the usual getSingleton method as follows:

using namespace CEGUI;
WindowManager& wmgr = WindowManager::getSingleton();

In general, you will be using what is known as a DefaultWindow (or to use its old name, DefaultGUISheet) as the 'root' window in your GUI. This is not required, but is the accepted pattern of usage for CEGUI and, once you start adding more top-level windows, helps simplify laying things out.

So, to get the ball rolling, we'll create a DefaultWindow as set it as the root 'GUI Sheet' for the GUI:

Window* myRoot = wmgr.createWindow( "DefaultWindow", "root" );
System::getSingleton().setGUISheet( myRoot );

The createWindow method of the WindowManager takes two strings as its parameters. The first one, "DefaultWindow" in this example, tells the system the type or class of the window you wish to create. Generally, the windows you have available are those which were registered when you loaded your scheme file, although some, like DefaultWindow, are global types and are always available. The second parameter, "root" in this example, is a unique name which will be assigned to the window; this name can be used to retrieve a pointer to the window from the WindowManager at a later time. Note that naming your root window "root" is not required, but is a common convention.

The setGUISheet method in the System singleton object is used to specify a given window as the root of the GUI. This will replace any current sheet / root window, although do note that the previous window hierarchy is not actually destroyed; it is just unlinked from the display - you can easily switch between GUI 'pages' by simply flipping between them using the setGUISheet method.

Now you have created your first window and attached it to the GUI system, and the system will use this window as the root of the GUI when it draws the GUI. But, if you were to compile a simple program using this code, you still can't see anything; what gives? There's nothing wrong with your application, the DefaultWindow which we created above is just totally invisible! This is what makes the DeafultWindow ideally suited as a root window; it serves as a blank canvas onto which other window and widgets can be attached. So, lets do that now...

Here we will create a frame window; this is a window that functions in a similar manner to the windows on your desktop UI, it has a title bar and can be moved and re-sized.

FrameWindow* fWnd = (FrameWindow*)wmgr.createWindow( "TaharezLook/FrameWindow", "testWindow" );

here we are creating a "TaharezLook/FrameWindow" window. This name uses a convention seen throughout the system, whereby a window type is prefixed by the name of the widget set (if you were to load the WindowsLook scheme, you could create a "WindowsLook/FrameWindow" object instead). We have given our new window the simple test name of "testWindow". One final thing to note is the use of the cast, this is required since the createWindow method always returns a base Window type; in this, and many other cases a basic Window pointer will suffice, but there are times when you'll want to access methods introduced in the window and widget sub-classes, so the use of the cast as shown is common when using CEGUI.

In order for the system to be able to do something useful with our new window, we must perform a few additional steps.

First, we must attach the window to the root window we established above:

myRoot->addChildWindow( fWnd );

Now, we can set an initial position and size for our window. CEGUI uses a 'unified' co-ordinate system enabling the use of relative (scale) and absolute (offset) components at the same time - this is why each co-ordinate you will see has two parts. For a slightly extended introduction of this concept see [[Introduction and overview of core "Falagard" support systems]]. Back to the example:

// position a quarter of the way in from the top-left of parent.
fWnd->setPosition( UVector2( UDim( 0.25f, 0 ), UDim( 0.25f, 0 ) ) );

// set size to be half the size of the parent
fWnd->setSize( UVector2( UDim( 0.5f, 0 ), UDim( 0.5f, 0 ) ) );

Finally, we set a caption for the frame window's title bar:

fWnd->setText( "Hello World!" );

And that's it! When compiled into an application, you will now see a simple frame window in the middle of the display.

=== XML layouts ===
All of the above is very nice, but there is one major drawback; any time you wish to adjust the GUI layout, you need to edit your code and recompile. This will get old pretty quick, so what you really want is to be able to specify your GUI layout externally, and have your code load the layout via a file. This is the purpose of the CEGUI layout XML files.

The system supports XML layout files, which can be loaded via the WindowManager using the loadWindowLayout method. This method creates all the windows for you and returns a pointer to the root window of the loaded hierarchy; which is ideal for assigning as the root of the GUI!

So, first of all we need a layout file. The following XML saved as a text file, is a layout file equivalent to the code we discussed above:

<?xml version="1.0" ?>
<GUILayout>
<Window Type="DefaultWindow" Name="root">
<Window Type="TaharezLook/FrameWindow" Name="testWindow">
<Property Name="UnifiedPosition" Value="{{0.25,0},{0.25,0}}" />
<Property Name="UnifiedSize" Value="{{0.5,0},{0.5,0}}" />
<Property Name="Text" Value="Hello World!" />
</Window>
</Window>
</GUILayout>

The Window elements show an obvious mapping to the createWindow method from the WindowManager object; they take a type and a name which directly correspond to the parameters discussed previously.

Nesting of the Window elements is used to attach certain windows to others. Note that you may only have one 'root' level window in a layout file, which is another reason you'll usually see the DefaultWindow used as a canvas on which other windows and widgets are placed.

The Property elements are used to set properties on the Window being defined. There are many properties available for each window/widget class, and each class also inherits all properties from its parent class. See the [http://www.cegui.org.uk/api_reference/namespaces.html <element>Properties namespaces in the API reference] for documentation on the available hard-coded properties and their 'value string' formats. Since 'Falagard' skins can create their own properties, it is likely that the windows you are using contain many more properties than listed in the previous link - for these 'soft' properties, you need to consult whichever documentation is provided with the skin you are using (for the sample skins see [[SetProperty|TaharezLook]] and [[SetProperty (WindowsLook)|WindowsLook]]).

If saved as a file called "test.layout", you could load this layout and set it as the GUI root as follows:

using namespace CEGUI;
Window* myRoot = WindowManager::getSingleton().loadWindowLayout( "test.layout" );
System::getSingleton().setGUISheet( myRoot );

The end result is exactly the same as what was done in C++ code earlier, except that now you can modify and enhance the GUI layout without the need for constant editing and recompilation of the application code.

== Conclusion ==
Here you have seen how to perform basic window creation, how to create a simple window hierarchy, and how modify some window settings. You have seen how this can be accomplished using both C++ code and external XML layout files. There are many advanced possibilities available using both methods, although this is best left for a more advanced tutorial.

[[User:CrazyEddie|CrazyEddie]]

The Beginner Guide to Injecting Inputs

2011-01-07T09:40:29Z

Makofierce:

{{VersionBadge|0.6}}

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

Having read the previous tutorials in this series, you now have your GUI rendering setup, the files loaded, and even have a window on the screen - however you are probably wanting to have some user interaction too. This is the subject of this final tutorial in the series; here we will show the required tasks in order to end up with a complete functioning GUI in your application. (CrazyEddie's joke: Alternatively, you got tired of waiting 15 months for this tutorial and worked it out for yourself!).

== Introduction to input for CEGUI ==

=== First the bad news ===
It shocks some people to discover that CEGUI does not do any automatic collection of user input; it is the applications job to tell CEGUI about any events that it should know about. This means that you have to tell CEGUI each time a key is pressed, or the mouse moves, and so on. While this may seem strange at first, it actually affords you a lot more power - we are not tying you down to any particular system for your inputs, and you may also filter inputs before they get to CEGUI, although those are more advanced concepts best left for another time.

=== Get your inputs fuel injected stylee! ===
In order to tell CEGUI about the input events going on around it, we have an input injection interface. This consists of a set of members in the CEGUI::System class - there is one member function for each type of base input we accept:

bool injectMouseMove( float delta_x, float delta_y );
bool injectMousePosition( float x_pos, float y_pos );
bool injectMouseLeaves( void );
bool injectMouseButtonDown( MouseButton button );
bool injectMouseButtonUp( MouseButton button );
bool injectKeyDown( uint key_code );
bool injectKeyUp( uint key_code );
bool injectChar( utf32 code_point );
bool injectMouseWheelChange( float delta );
bool injectTimePulse( float timeElapsed );

Yes, that's quite a collection! The first thing that you might notice is that there appears to be some repetition - things like 'mouse move' and 'mouse position', 'key down' and 'char'. For the mouse, we offer the possibility of injecting a relative movement of the mouse from its last injected location or an absolute position - which you choose will largely depend upon the type of inputs that your input library provides you with for the mouse. For keys, it is required that both up/down strokes and also characters are injected - there are a couple of reasons for this; first, not all keys generate a character code (like shift, alt, and so on), and second, it allows you to do your own custom (or operating system supplied) key-mapping and key auto-repeat (since CEGUI does not currently offer these functions).

The other thing to notice is the boolean return value from the injector functions. This is used to relay back to your application whether or not CEGUI actually consumed the input. If this returns false, it means that CEGUI did nothing useful with the input, and that your application may like to perform some action based on it instead.

== A little more detail - what each injector is used for ==
Here we will offer a brief description of what each injection function is used for, the data it expects, and what, in general, is done with the input.

=== bool injectMouseMove( float delta_x, float delta_y ) ===
This is used to inject relative mouse movements. The inputs 'delta_x' and 'delta_y' specify the direction and number of screen pixels the mouse has moved on the x axis and y axis respectively. This causes the mouse to move by the specified amount (the actual amount moved can be changed by setting a mouse scaling factor via CEGUI::System::setMouseMoveScaling). If you use this, you generally do not need to use injectMousePosition.

=== bool injectMousePosition( float x_pos, float y_pos ) ===
This is used to inject the current absolute position of the mouse. The inputs 'x_pos' and 'y_pos' specify the position of the mouse in pixels, with (0, 0) representing the top-left hand corner of the CEGUI display (so if you're in windowed mode, it's the corner of the window and not the whole screen). The CEGUI mouse cursor will be set to the new position. If you use this, you generally do not need to use injectMouseMove.

=== bool injectMouseLeaves( void ) ===
This function informs CEGUI that the mouse cursor has left the system application window which CEGUI considers its rendering area. This is useful if running in windowed mode to inform widgets that the mouse has actually left the CEGUI display completely (otherwise it may not get to know, since under some systems no more mouse events are generated for a OS window once the mouse has left it).

=== bool injectMouseButtonDown( MouseButton button ) ===
This tells CEGUI that a mouse button has been pressed down. The value 'button' is one of the CEGUI::MouseButton enumerated values, which are as follows:
enum MouseButton
{
LeftButton,
RightButton,
MiddleButton,
X1Button,
X2Button,
MouseButtonCount,
NoButton
};

If the values from your input library do not match these, you will have to perform a translation step. Also note that the value NoButton is not 0.

=== bool injectMouseButtonUp( MouseButton button ) ===
This tells CEGUI that a mouse button has been released. As for the injectMouseButtonDown function, the value 'button' is one of the MouseButton enumerated values.

=== bool injectKeyDown( uint key_code ) ===
This tells CEGUI that a key has been pressed. The value 'key_code' is a scan code for the key - note that this is not an ASCII or other text encoding value. The available scan codes are defined in the CEGUI::Key::Scan enumeration. If you are using Microsoft DirectInput, then our scan codes are the same ones output by that library, in other cases you may be required to perform some translation. Note that for current releases, and depending upon your expected use, it may not be required to inject all key down/up strokes - the most common ones that you likely will need are for backspace, delete, enter, the shift keys and the arrow keys.

At present no automatic key mapping for generation of character codes is performed, also no key auto-repeat functionality is available - although these functions may appear in future releases. If you need key auto-repeat then you will need to either use an input library that offers that ability, or implement something directly. Of course you will almost certainly need character input, so for that look at the injectChar function below.

=== bool injectKeyUp( uint key_code ) ===
This tells CEGUI that a key has been released. As for the injectKeyDown function, the value 'key_code' is a scan code for the key - and again note that this is not an ASCII or other text encoding value - see above for a more detailed description of the key scan codes.

=== bool injectChar( utf32 code_point ) ===
This function tells CEGUI that a character key has been pressed - you will need this in order to input text into CEGUI widgets. The 'code_point' input is a Unicode UTF32 code point (see [http://unicode.org/ the unicode website] for information about unicode). How you obtain this value is something that is dependant upon the input library that you are using - for many people, who just wish to use ASCII values, you can just pass in your ASCII codes unmodified, since Unicode values between 0 and 127 are the same as the standard ASCII codes. For other uses, you will need to consult the API documentation for your input library (it is possible, for example, to get the Microsoft Windows message pump to send you key codes in UTF32 form, though exactly how it is done is beyond the scope of this introductory tutorial.

=== bool injectMouseWheelChange( float delta ) ===
This function is used to tell CEGUI about the use of the mouse wheel or scroll wheel (whatever you like to call it). Use positive values for forward movement (rolling the wheel away from the user), and negative values for backwards movement (rolling the wheel towards the user).

=== bool injectTimePulse( float timeElapsed ) ===
This function is used to keep CEGUI informed about time (CEGUI doesn't have a watch, you see!). The 'timeElapsed' is a floating point number that indicates the number of seconds - or part seconds - that have passed since the last time the injector was called (or since CEGUI was started). The use of this function is becoming more and more important - it now controls things such as fades and timing for tool-tip widgets, menus, and also auto-repeat for mouse buttons.

== Conclusion ==
Here we have seen the general idiom that CEGUI uses for obtaining externally generated input events. We have seen the methods for passing these inputs to CEGUI, and type and format of the information to be passed.

Unlike some of the other tutorials in this series, we did not provide concrete code examples. The main reason for this was to keep the tutorial reasonably short; to prevent it becoming a jumble of code for every possible combination of input system, and in the process causing more confusion. The use of any individual input library could easily fill a tutorial of its own.

To see some concrete examples, there are two immediate sources of information:
*We have some great tutorials here on the wiki
**[[Using CEGUI with SDL and OpenGL#Injecting_Input|Using CEGUI with SDL and OpenGL]]
**[[Using CEGUI with Producer and OpenGL#Injecting_Input_to_CEGUI_via_Producer|Using CEGUI with Producer and OpenGL]]

*The samples framework code: see the files in cegui_mk2/Samples/common/src:
**Win32AppHelper.cpp - contains a windows message procedure injecting mouse and character inputs into CEGUI, and using DirectInput for keyboard up and down messages.
**CEGuiOgreBaseApplication.cpp - contains an example Ogre::FrameListener class which takes inputs generated by the [http://sourceforge.net/projects/wgois/ OIS Library] and injects these into CEGUI.
**CEGuiOpenGLBaseApplication.cpp - registers callback functions with glut to process inputs, and also shows the use of a key translation table.

Additionally, Irrlicht users can use the supplied Irrlicht event pusher - whenever an event comes your way from Irrlicht you can use the OnEvent member in the Irrlicht Renderer to forward this to CEGUI (you then just have to inject time pulses).

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

Developer Requirements

2011-01-07T09:38:44Z

Makofierce:

This page talks about skills required from a developer before he/she can start messing with CEGUI. Helpful links how to get started on different topics are sometimes provided, if you aren't sure about many of these topics, please buy/borrow a book instead, recommended C++ books are at the bottom of this article. Unless you can meet all these requirements, you are less likely to get help on CEGUI forums or the IRC channel. You may still receive some help, but please understand that we are sick of answering the same beginner C++ questions all over again. Thanks for understanding.

== General ==
* updating to latest stable before reporting bugs/problems (it is likely that some bugs were fixed and memorising the changelog is a pain)
* being very confident, knowledgeable and experienced on your platform of choice (knowing your way around files, folders and all that complex and confusing stuff ;-))
* ability to search via Google and forum search (the answer is often already out there, finding it is usually faster than asking the question again)
* able to try things out yourself, not asking about trivial problems every 10 minutes... You learn much more if you just try to make it work yourself...
* not being scared of error messages, they are there to actually help you! Read them, not just copy paste them for somebody else to solve!
* at least beginner level English (if you don't have that you don't understand this anyways, so it's probably pointless to write it here :-D)

== C++ ==
You have to be able to answer the following questions.

* What is an include file? How is it related to include path? [http://en.wikipedia.org/wiki/Header_file]
* What is a symbol? How is it related to linking?
* What is a compiler? What is a linker? [http://en.wikipedia.org/wiki/Compiler] [http://en.wikipedia.org/wiki/Linker_(computing)]
* What is the difference between .so/.dll (Linux/Windows) and .lib (both)?
* Static vs dynamic linking. What is the advantage of static linking? [http://en.wikipedia.org/wiki/Static_library]
* What is usually included in an SDK? What is the difference between building CEGUI yourself and using its SDK?

Plus you have to be at least a little proficient in your work environment (be it a full fledged IDE - MSVC, Eclipse, whatever, or command line tools).

== Recommended books ==
* C++ Programming Language, The (3rd Edition) by Stroustrup [http://www.amazon.com/exec/obidos/ASIN/0201889544]
* Effective C++ by Meyers [http://www.amazon.com/exec/obidos/ASIN/0321334876]
* C++ How to program by Deitel [http://www.deitel.com/books/cpphtp4/]
* C++ templates by Vandervoorde and Josuttis, online for free! [http://books.google.cz/books?id=yQU-NlmQb_UC&printsec=frontcover&dq=C%2B%2B+templates+by+Josuttis+and+Vandervoorde&source=bl&ots=EdpL60TxFV&sig=ZDKvNkd8u7-PH9zyBEYA3yFJP58&hl=cs&ei=7iu8TMqJGsmgOvfouYYN&sa=X&oi=book_result&ct=result&resnum=1&ved=0CBUQ6AEwAA#v=onepage&q&f=false]
* Beginning Visual C++ 2010 by Horton [http://www.amazon.com/Ivor-Hortons-Beginning-Visual-Programmer/dp/0470500883/]

Animation System

2011-01-07T09:37:24Z

Makofierce:

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.2}}

== Basic concepts ==
In UI lots of animations are likely to be shared (for example widget specific animation), so CEGUI splits the animation between definition and instance. You can have one animation definition animating large amount of Windows, having only one animation per window is also fine (one animation with only one instance). Animation definitions aren't tied to window type, the only condition is that the target must have all affected (target properties of all affectors inside the animation) and source properties (all source properties in key frames, if any).

== Purpose of animation classes ==

=== Animation Definition (class CEGUI::Animation) ===
This class holds defining data for animations. Specifically duration, replay mode, auto start and list of Affectors. This class doesn't directly animate anything. You have to instantiate it via CEGUI::AnimationManager::instantiateAnimation.

=== Affector (class CEGUI::Affector) ===
Affector affects (changes the value of) one property. It holds application method (more about that later), target property, used interpolator and list of key frames.

=== Key Frame (class CEGUI::KeyFrame) ===
Key frame represents the value of affected property at given time position. It holds value, source property and time position. Key frames can use values of properties of the affected window. If source property is not empty, property is saved when animation starts and used as value for this key frame.

=== Animation Instance (class CEGUI::AnimationInstance) ===
This class uses animation definition to animate Window. It holds animation position and playback speed.

=== Animation Manager (class CEGUI::AnimationManager ===
Singleton class. You use it to create new animation definitions and instantiate existing animation definitions. (You should not construct Animation definitions or Animation instances directly, always use Animation Manager).

=== Interpolator (class CEGUI::Interpolator) ===
To be able to animate smoothly between 2 discrete keyframes, interpolators had to be introduced. You don't have to use them directly, everything is done for you in the animation classes. You only need to understand their internals if you need custom interpolator (as all basic interpolators are included in CEGUI, if you find some property that can't be animated with stock interpolators, let us know).

== Defining animations ==

=== Via code ===
This sample animation takes 0.3 seconds and in that time, it fades the window and rotates it 10 degrees around Y axis.
<code><cpp/>
{
CEGUI::Animation* anim = CEGUI::AnimationManager::getSingleton().createAnimation("Testing");
anim->setDuration(0.3f); // duration in seconds
anim->setReplayMode(CEGUI::Animation::RM_Once); // when this animation is started, only play it once, then stop

// now we define affector inside our Testing animation
{
// this affector changes YRotation and interpolates keyframes with float interpolator
CEGUI::Affector* affector = anim->createAffector("YRotation", "float");
// at 0.0 seconds, the animation should set YRotation to 10.0 degrees
affector->createKeyFrame(0.0f, "0.0");
// at 0.3 seconds, YRotation should be 0 degrees and animation should progress towards this in an accelerating manner
affector->createKeyFrame(0.3f, "10.0", CEGUI::KeyFrame::P_QuadraticAccelerating);
}

// animation can have more than one affectors! lets define another affector that changes Alpha
{
// this affector will again use float interpolator
CEGUI::Affector* affector = anim->createAffector("Alpha", "float");
affector->createKeyFrame(0.0f, "1.0"); // at 0.0 seconds, set alpha to 0.5
affector->createKeyFrame(0.3f, "0.5", CEGUI::KeyFrame::P_QuadraticDecelerating); // at 1.0 seconds, set alpha to 1.0, now decelerating!
}
}
</code>

=== Via Falagard looknfeel XML ===
<code>
<WidgetLook ...>
...
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
<Affector property="Alpha" interpolator="float">
<KeyFrame position="0.0" value="1.0" />
<KeyFrame position="0.3" value="0.5" />
</Affector>
<Affector property="YRotation" interpolator="float">
<KeyFrame position="0.0" value="0" />
<KeyFrame position="0.3" value="10" />
</Affector>
</AnimationDefinition>
</WidgetLook>
</code>

=== Via separate animation list XML (AnimationManager::loadAnimationsFromXML) ===
<code>
<Animations>
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
<Affector property="Alpha" interpolator="float">
<KeyFrame position="0.0" value="1.0" />
<KeyFrame position="0.3" value="0.5" />
</Affector>
<Affector property="YRotation" interpolator="float">
<KeyFrame position="0.0" value="0" />
<KeyFrame position="0.3" value="10" />
</Affector>
</AnimationDefinition>
</Animations>
</code>

== Instantiating animations ==
If you created the animation in code or via separate animation definition file, you have to instantiate it (only Falagard instantiates and sets target automatically).

<code><cpp/>
CEGUI::AnimationInstance* instance = CEGUI::AnimationManager::getSingleton().instantiateAnimation(anim);
// after we instantiate the animation, we have to set its target window
instance->setTargetWindow(targetWindow);

// at this point, you can start this instance and see the results
instance->start();
</code>

== Connecting events and animations ==
You often want your animation to start when something happens (Mouse gets over the widget, new FrameWindow is opened, etc). You have two options to achieve this.

If you already are using XML to define animations, the easiest solution is to use the auto event subscription facility. You add pairs of Event name and action that should happen with the animation ("Start", "Stop", "Pause", "Unpause", etc.) and when target window is set, these subscriptions are automatically made for your convenienve.

Both Falagard and Animations.xml approaches are the same with regards to this. This XML snippet starts the animation when mouse enters the target window's area.
<code>
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
...
<Subscription event="MouseEntersArea" action="Start" />
</AnimationDefinition>
</code>

Doing this in code is much more powerful (you can subscribe to a window that's different than target window) but also more messy:
<code><cpp/>
windowWithEvent->subscribeEvent(CEGUI::Window::EventMouseEntersArea, CEGUI::Event::Subscriber(&CEGUI::AnimationInstance::handleStart, instance));
</code>

You can also do this from a Lua script:
<code>
CEGUI.WindowManager:getSingleton():getWindow("WindowName"):subscribeEvent("MouseEnter", "luafunctionname")
</code>
This code sets up the window specified in WindowName, the name of that window on creation or from the XML "Name" property, to react to the mouse entering it by calling the Lua function specified in luafunctionname. The Lua function name argument should be the name, without trailing (), to a function declared in Lua or exported to Lua from C.

== Progression ==
As I created the implementation, I noticed that linear animations look really boring and predictable. Often times accelerating or decelerating anims will look much better and lively. To make creating those easier, I introduced progression to key frames. This enum tells the system how to progress towards the key frame that holds the progression (that means progression on the first key frame is never used!). The default is linear, meaning that progress towards the keyframe is completely linear. Try the other options yourself to see the differences.
=== animations.xml example ===
Here we have edited the example animation so that the alpha value uses the quadratic deceleration progression. This will make the alpha value drop quickly in the first frames but the speed of the change will decrease quickly and give a smooth finish to the transition.
<code>
<Animations>
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
<Affector property="Alpha" interpolator="float">
<KeyFrame position="0.0" value="1.0" />
<KeyFrame position="0.3" value="0.5" progression="quadratic decelerating" />
</Affector>
<Affector property="YRotation" interpolator="float">
<KeyFrame position="0.0" value="0" />
<KeyFrame position="0.3" value="10" />
</Affector>
</AnimationDefinition>
</Animations>
</code>
Possible values for this property, in XML, are:
* "linear": (default value) Simple linear transition. Same rate of progression for every frame.
* "discrete": Abrupt progression, goes from one value straight to the next one.
* "quadratic accelerating": Starts slow but accelerates to very fast towards the end.
* "quadratic decelerating": Starts very fast but comes smoothly to a halt in the end.

== Application methods ==
Affectors offer 3 different "application methods". One is absolute, meaning that the keyframe value is taken as absolute and is directly set to the property after interpolation. The other 2 are relative. That means that when the animation starts, the old values of properties are saved and later used when animating. AM_Relative means saved_value + interpolated_value, AM_RelativeMultiply means saved_value * interpolated_float.

=== animations.xml example: ===
In the following example we have changed the rotation affector to do relative rotation instead of absolute, which is default. This means that whatever rotation the window had when the animation started it will add the new rotation to that value. The absolute method would have reset the rotation to 0 in the first key frame and then proceeded to rotate it by 10 degrees during 0.3 seconds.
<code>
<Animations>
<AnimationDefinition name="Testing" duration="0.3" replayMode="once">
<Affector property="Alpha" interpolator="float">
<KeyFrame position="0.0" value="1.0" />
<KeyFrame position="0.3" value="0.5" />
</Affector>
<Affector property="YRotation" interpolator="float" applicationMethod="relative">
<KeyFrame position="0.0" value="0" />
<KeyFrame position="0.3" value="10" />
</Affector>
</AnimationDefinition>
</Animations>
</code>
Possible values for this property, in XML, are:
* "absolute": (default setting) The interpolated value is set as the new property value.
* "relative": The interpolated value is added to the starting value of the property.
* "relative multiply": The interpolated value is multiplied with the starting value of the property.

Performance tips

2011-01-07T09:36:14Z

Makofierce:

{{VersionBadge|0.7}} {{VersionBadge|0.8}}

This page provides some generic tips on getting the most performance out of CEGUI. People often claim that CEGUI is slow and don't realise it could be them doing something wrong. I will try to gather some areas where people claim CEGUI is slow and "just sucks" and try to provide tips about what is wrong.

== Problem: Loading layouts takes few seconds and halts my application! ==
This is a complaint I have seen multiple times. The reporter usually has a dialog that in its constructor loads a XML layout off the HDD and constructs its hierarchy based on that. Depending on how the layout is complex, this can indeed take a few seconds (depending on many many factors). What is flawed about this is the fact that the user loads the layout always when the dialog is constructed. Wouldn't it be better if we loaded the layout once, stored it somewhere and reused that whenever the dialog has to reappear instead of deleting the layout when user closes the dialog and loading it from scratch when it's opened?

There are two ways of avoiding this. If the dialog is modal and can only appear once, it pays off to just load it, set it to invisible and the show/hide as necessary. This is the fastest solution.

If you need multiple instances of the dialog, you need to clone the widget tree somehow. This is why Widget (Window in 0.7 and previous) ::clone method has been implemented (only CEGUI 0.7.5 and newer!). It allows you to clone the entire widget hiearchy. The idea is to load this when the dialog is first used (or even when loading the application, depends on how the dialog is used). Store the widget pointer somewhere (could be a static member variable in the Dialog class) and upon construction, just clone the hierarchy and add the cloned widget while leaving the original alone for further cloning.
(TODO: add some example code)

== A quick and (relatively) painless way to get roughly 40% performance increase in certain areas (0.8 only!) ==
By default, CEGUI uses no custom allocators at all. That means the plain old new and delete. You can set the allocator to anything you want but we recommend nedmalloc. It's a very robust memory allocator tailored to give maximum performance. It speeds things up especially when initialising, loading layouts, creating windows, ... Give it a try. See [[Memory Allocation]] for more details.

== Speeding up a rarely changing info window (or any widget) with complex elements inside it ==
CEGUI allows caching. This is done with the "AutoRenderingSurface" property. What this means is that the widget gets rendered once with its child widgets (the entire hierarchy). The result is stored in a texture and from this moment on, whenever rendering needs to be done, just one quad with the texture is drawn. When widgets change inside, it invalidates the cache and everything is redrawn from scratch. This is especially useful for complex deep hierarchy widgets that users rarely interact with or aren't interactive at all.

Caveat: The texture caching causes the widget to hard clip its children to its dimensions! That means that a combobox at the bottom of a frame window will get "cut" when you open the options of it. This is likely to get fixed but as of now (5th January 2011) it's still a problem in both 0.7 and 0.8.