Changes and Porting Tips for 0.5.0

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

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