Changes and Porting Tips for 0.4.0

Written for CEGUI 0.3

---

Works with versions 0.3.x (obsolete)

This is a short document detailing the main changes that were made to CEGUI while implementing what is known as the "Falagard" skinning system.

There have been substantial changes to the system which may result in existing code breaking. For the most part, these changes will only affect people who have written their own widget sub-classes, although some changes may also affect normal 'client' code.

• The various 'create<Widget>' abstract methods which are employed to get widget sub-classes to create required component widgets previously took no parameters, and the sub-class was free to name the widget. This has now changed, and these 'create' methods are passed a String which contains the name that must be used for the created widget.

• It used to be part of the job of the WindowFactory classes to call Window::initialise on the created Window/Widget. This is no longer the case. You must NOT call the 'initialise' method in the WindowFactory classes any more. The system will now call 'initialise' for you.

• Certain colour settings (like the label colours in the button classes) used to ignore the alpha component of the supplied colour, and replace this with the Window alpha at render time. This has now been changed; the alpha component is now significant and will be combined with the window alpha at render time.

• For all Listbox (and similar) types, the renderBaseImagery virtual method has been renamed to cacheBaseImagery, and should cache items into the Window's RenderCache rather than drawing directly.

• Redundant ListHeaderSegment::d_normalMouseCursor field has been removed, so you no lomger need to initialise this. Instead, initialse the normal mouse cursor via the standard Window interface.

• In MultiLineEditbox, renderEditboxBaseImagery virtual method is renamed as cacheEditboxBaseImagery, and should cache items into the Window's RenderCache rather than drawing directly.

• In MultiLineEditbox, renderCarat virtual method is renamed as cacheCaratImagery, and should cache items into the Window's RenderCache rather than drawing directly.

• The standard pattern for Window sub-class rendering has changed. We now recommend the use of the Window::populateRenderCache virtual method over the Window::drawSelf method. populateRenderCache should fill the 'd_renderCache' RenderCache object with position independant information about images and texts required to display the window/widget. The drawSelf method is still present and works the same as before, although in certain cases using this method may result in unexpected behaviour.

• The mouse constraints area now correctly maintans the same relative area when the display gets re-sized. Although you still pass in absolute pixel values, these are converted internally to display relative values. If you need absolute values, this can be achieved via the 'unified' co-ordinate system mentioned below.

• We have introduced a new 'unified' co-ordinate system which allows absolute and relative components at the same time. We now recommend this system for all new code. The old system continues to function, although in rare cases, unexpected results may be seen.

• Widget 'look' modules can now optionally offer a CEGUI::uint registerAllFactories(void) function, to register all factories for a module. This saves from having to list all the widgets in a scheme file when you want all of them.

• All widgets with virtual method 'layoutComponentWidgets' have had this removed in favour of base Window class supported system of laying out children (via performChildWindowLayout).