Changes and Porting Tips for 0.5.0

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

Release

• 0.5.0 stable Released on November the 6th 2006: goto download page
• 0.5.0 RC1 Released on June the 20th 2006: goto download page
• 0.5.0 RC2 Released on August the 13th 2006: goto download page

ChangeLog

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

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.

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:

        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)

StaticText:

        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

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