Difference between revisions of "Changes and Porting Tips for 0.5.0"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
(ChangeLog)
m
Line 3: Line 3:
 
=Release=  
 
=Release=  
  
 +
* 0.5.0 RC1 Released on June the 20th: [[Downloads 0.5.0-RC1|goto download page]]
 
=ChangeLog=
 
=ChangeLog=
 
<pre>
 
<pre>

Revision as of 21:50, 19 June 2006

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

Release

ChangeLog

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 it's 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 prett
y 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 it's 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.


Changes and Porting

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

Code Changes

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


The new WindowRenderer system

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

*** TODO ***


CEGUI::System Constructor

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

The new constructor has the form:

System(Renderer* renderer,
      ResourceProvider* resourceProvider = 0,
      XMLParser* xmlParser = 0,
      ScriptModule* scriptModule = 0,
      const String& configFile = "",
      const String& logFile = "CEGUI.log");

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

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


System::setTooltip changed to System::setDefaultTooltip

The member function

System::setTooltip

has been renamed as

System::setDefaultTooltip

this was a change for API consistency. Update your code to use the new name for this member.


Window MetricsMode removed

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

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


Window Metrics and other conversion members removed

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

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

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


Component Widget creation abstract members

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

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


Component Widget member fields

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

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

*** TODO ***


RenderableElement, RenderableImage and RenderableFrame classes

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

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


Static, StaticImage and StaticText classes

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

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

StaticImage:

        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 it's own copy of TinyXML.

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

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


Data File Changes

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


Updated XSD files for Xerces

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


Falagard Additions

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


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

Attributes:

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


controlProperty

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


TextComponent

Two new sub-elements are now valid for TextComponent.

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

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

To be continued...