Changes and Porting Tips for 0.7.0

Written for CEGUI 0.6

---

Works with versions 0.6.x (obsolete)

Written for CEGUI 0.5

---

Works with versions 0.5.x (obsolete)

Introduction

A small number of these changes are reversions of poorly considered and/or poorly implemented facilities added in the 0.6.x series. In most cases this removed functionality is believed largely unused or similar results achievable via previously existing facilities.

Also note that while attempts have been made to see that most of the major changes are listed on this page, it's entirely possible - even likely - that somewhere along the line some things have been missed out. In those cases, please visit the CEGUI forums

Organisation and Structure

The overall structure of the CEGUI code tree has been considerably modified:

• All actual code for the library and associated modules has been relocated beneath a 'cegui' directory, within this directory there is are src and include subdirectories that contain the source code and public headers respectively. Possibly one of the main advantages of this is that non-linux based systems will now have an identical header layout to what linux has always had.
• In addition to this main change, the datafiles directory has moved from Samples to the root directory.
• The XMLRefSchema directory has moved into the datafiles directory and is renamed xml_schemas.
• Other changes will largely have minimal impact so we've not covered everything in minute detail.

The file and directory naming for Renderer implementaions has been modified, although is now unified for all implementations:

• Headers are now accessed RendererModules/<name of API>/CEGUI<name of API><name of component>.h
  • Examples:
    • the OpenGL renderer header is at: RendererModules/OpenGL/CEGUIOpenGLRenderer.h
    • the Ogre geometry buffer header is at: RendererModules/Ogre/CEGUIOgreGeometryBuffer.h
    • the Direct3D10 render target header is at: RendererModules/Direct3D10/CEGUIDirect3D10RenderTarget.h

Windows / MSVC++ changes

The renderer module output has been unified with that of other systems, so for example, rather than OpenGLGUIRenderer.dll it's now CEGUIOpenGLRenderer.dll.

Apple Mac / Xcode changes

We are changing the default bundle locations regarding both embedded frameworks and loadable bundles.

• Previously all frameworks were incorrectly expected to be in the app bundle's Resources directory, additionally the XMLParser and ImageCodec based loadable modules (bundles) were packaged within the CEGUI framework itself, this has changed as follows:
  • All CEGUI related frameworks are to be placed in the correct location of the app bundles's Frameworks directory.
  • The XMLParser and ImageCodec based modules are to be placed within the app bundles PlugIns directory. This decision was taken because it's up to each app developer to decide which loadable bundles they want to support and so it's more logical to have those placed at the app level rather than embedded deeper within the CEGUI frameworks. Having said this, CEGUI will still look in the PlugIns location of the CEGUIBase framework for bundles; if you wish to reconfigure the loadable bundle targets to be placed there instead, CEGUI will find them (it's just that it's not the preferred default).

The main framework is renamed from CEGUI to CEGUIBase

• This is mostly to have parity across all platforms as far as module names go, although also reflects the fact that 'CEGUI' on the Mac is no longer a monolithic entity.

If you previously relied upon adding the framework to your project and using the CEGUI prefix in include lines, you will either have to add the framework Headers directory in the search paths, or change the include statements accordingly. (If you'd like this changed back, nag us!)

Window and WindowRenderer factory registration changes

There have been changes / additions to the way that new factories for Window and WindowRenderer subclasses are registered with the system. This removes the old preprocessor macro based system with a much cleaner template based arrangement that means you no longer need to directly create your factory classes and nor do you need to keep a static instance hanging around. The overall impact of this means that it's now incredibly simple to register new classes with the system

• If you have a Window subclass named 'MyWidget, to add this to the system you can now simply do:

CEGUI::WindowFactoryManager::addFactory<TplWindowFactory<MyWidget> >();

• If you have a WindowRenderer subclass named 'MyWidgetRenderer', to add this to the system you can now simply do:

CEGUI::WindowRendererManager::addFactory<TplWindowRendererFactory<MyWidgetRenderer> >();

• Anybody creating a WindowRenderSet module will find that the macro system previously employed for that purpose has been removed in favour of a class based approach. As well as making the code more transparent and generally easier to set up, it also means your module just needs to export a single function to returns a CEGUI::WindowRendererModule object; all other interactions are done via that object.

Window interface breaking / behavioural changes.

• getRenderCache is removed. You probably now want to be doing something with getGeometryBuffer.
• requestRedraw function is replaced by invalidate function (NB: function also changes from const to non-const)
• render function now takes a RenderingContext object pointer.
• drawSelf function replaces float z parameter with a const reference to a RenderingContext object.
• Protected member RenderCache d_renderCache is removed.
• Window::EventRenderingStarted and Window::EventRenderingEnded are now fired only when a Window object's GeometryBuffer content gets regenerated.
• Window 'inner rect' support is now functioning as it should; this means that many layouts - especially those using FrameWindow - will need to be updated. Or put another way, child content is now positioned and sized based upon the window client area (inner rect) as opposed to the overall area - this resolves long standing issues such as content getting hidden by the titlebar when sizing / switching skins.
• Window::d_text is now known as Window::d_logicalText.
• Rather than manipulate d_logicalText directly, you should always go via Window::setText in order for bi-directional text support to function properly (when enabled/compiled in).
• Window::createWindow 3rd argument 'prefix' is removed.
• Window::getPrefix and Window::setPrefix are removed.
• Window::recursiveChildSearch is removed.
• Window::isHit has an added boolean parameter allow_disabled, which when set to true will test for a hit if the Window is disabled. Don't forget to update the signatures of any overrides.
• Window::getUnclippedPixelRect is renamed Window::getUnclippedOuterRect.
• Window::getPixelRect is renamed Window::getOuterRectClipper (and should only really be used for rendering clipping).
• Window::getInnerRect is renamed Window::getInnerRectClipper (and should only really be used for rendering clipping).
• Added Window::getHitTestRect which returns the actual visible area of the outer rect - this area may not match the actual clipping area rects, which sometimes do not clip all they appear to ;)
• Added Window::getUnclippedRect function taking a bool that indicates the inner or outer rect to be returned.
• Added Window::getClipRect function taking a bool that indicates whether the content is for the non-client area (and so returns inner or outer clipper accordingly).
• Window::getPixelRect_impl virtual function is removed.

Renderer breaking interface changes and related items.

• Renderer objects are no longer directly created or destroyed. Use the static create and destroy functions to create the renderer objects.
• Unused OrientationFlags enumeration is removed.
• addQuad function is removed. Geometry is now added directly to the per-window GeometryBuffer object(s).
• clearRenderList function is removed.
• setQueueingEnabled function is removed.
• isQueueingEnabled function is removed.
• doRender function is removed. Final rendering is now achieved by calling draw on the root RenderingSurface(s).
• getWidth and getHeight functions are removed.
• getSize function becomes getDisplaySize returning a const Size reference.
• getRect function is removed.
• getHorzScrennDPI and getVertScreenDPI are replaced with a single getDisplayDPI function returning a const Vector2 reference.
• resetZValue function is removed.
• advanceZValue function is removed.
• getCurrentZ function is removed.
• getZLayer function is removed.
• createTexture function taking a single float value is replaced by createTexture taking a const reference to a Size object.
• createResourceProvider function is removed. A DefaultResourceProvider is now used unless you explicitly provide an alternative.
• The protected member String d_identifierString is removed.
• The protected member ResourceProvider d_resourceProvider is removed.
• The renderer is no longer derived from EventSet. The Renderer::EventDisplaySizeChanged is moved to the System object. Informing the system that the display has changed size is now done by calling System::notifyDisplaySizeChanged, which in turn will set the display size back on the Renderer object. This gives a fully uniform interface for this procedure, and is better than the old ad-hoc approach.

For people wanting an overview of the new renderer arrangements, perhaps prior to porting an existing renderer module (or if you're looking to writing a new one), please see An Overview of Renderer Model 2 (pdf)

Texture breaking interface changes.

• getWidth and getHeight are replaced with a single getSize function returning a const Size reference.
• getOriginalWidth and getOriginalHeight are replaced with a single getOriginalDataSize function returning a const Size reference.
• getYScale and getXScale are replaced with a single getTexelScaling function returning a const Vector2 reference.
• loadFromMemory replaces the float buffWidth and buffHeight parameters with a single Size object reference buffer_size parameter.
• getRenderer function is removed.

Scripting and Script Modules

• ScriptWindowHelper is removed.
• Global 'this' that was (sometimes) available within lua event handlers is removed.
• ScriptModule::getLanguage is removed.
• LuaScriptModule object constructor made private. Construction is now to be done via the LuaScriptModule::create static function.
• LuaScriptModule object destructor made private. Destruction is now to be done via the LuaScriptModule::destroy static function.

Falagard Window Renderers

• FalagardStaticText::HorzFormatting enumeration removed, use HorizontalTextFormatting enumeration instead.
• FalagardStaticText::VertFormatting enumeration removed, use VerticalTextFormatting enumeration instead.
• FalagardStaticText::getHorizontalFormatting modified to return a HorzontalTextFormatting value.
• FalagardStaticText::getVerticalFormatting modified to return a VerticalTextFormatting value.
• FalagardStaticText::setHorizontalFormatting modified to take a HorzontalTextFormatting value.
• FalagardStaticText::setVerticalFormatting modified to take a VerticalTextFormatting value.

Font and FontManager

• FontManager is now derived from new NamedXMLResourceManager template class (part of resource system improvments to make things cleaner and easier to maintain).
• FontManager::createFont functions are renamed to FontManager::create (inherited from base class), FontManager::createFreeTypeFont and FontManager::createPixmapFont. All have totally new signatures.
• FontManager::destroyFont functions renamed to FontManager::destroy (inherited from new base class).
• FontManager::destroyAllFonts function renamed to FontManager::destroyAll (inherited from new base class).
• FontManager::isFontPresent function is renamed to FontManager::isDefined (inherited from new base class).
• FontManager::create, FontManager::createFreeTypeFont and FontManager::createPixmapFont functions return a Font reference rather than a pointer (to reinforce that it will never return 0)
• FontManager::getFont function is renamed to FontManager::get (inherited from new base class)
• FontManager::get returns a reference instead of a pointer (to reinforce that it will never return 0).
• FontManager::create, FontManager::createFreeTypeFont and FontManager::createPixmapFont functions take an optional XMLResourceExistsAction parameter to indicate what action to take when loading a font with a name that already exists.
• FontManager::notifyScreenResolution function renamed to FontManager::notifyDisplaySizeChanged.
• Font::notifyScreenResolution function renamed to Font::notifyDisplaySizeChanged.
• Font::drawWrappedText (protected) function is removed.
• Font::drawTextLine (protected) function is removed.
• Font::drawTextLineJustified (protected) function is removed.
• Font::getNextWord (protected) function is removed.
• Font::getWrappedTextExtent (protected) function is removed.
• all Font::drawText overloaded functions replaced with a single drawText function (beware if you use the scale values - there is a new float in the signature that you may overlook).
• Font::drawText function no longer returns a value (since it only ever renders one line).
• Font::drawText function has an added parameter receiving a GeometryBuffer reference, and have had the float z parameter removed.
• Font::getFormattedTextExtent function is removed.
• Font properties "FileName" and "ResourceGroup" are removed.
• Font property "Name" will no longer incorrectly allow a Font name to be changed (a 'soft' error is logged instead).

Image, Imageset and ImagesetManager

• ImagesetManager is now derived from new NamedXMLResourceManager template class (part of resource system improvments to make things cleaner and easier to maintain).
• ImagesetManager::createImageset functions are renamed to ImagesetManager::create (main one inherited from base class, and others for overload consistency).
• ImagesetManager::destroyImageset functions renamed to ImagesetManager::destroy (inherited from new base class).
• ImagesetManager::destroyAllImagesets function renamed to ImagesetManager::destroyAll (inherited from new base class).
• ImagesetManager::isImagesetPresent function is renamed to ImagesetManager::isDefined (inherited from new base class).
• ImagesetManager::createImagesetFromImageFile is renamed to ImagesetManager::createFromImageFile (remove verbosity / consistency).
• ImagesetManager::create and ImagesetManager::createFromImageFile functions return an Imageset reference rather than a pointer (to reinforce that it will never return 0)
• ImagesetManager::getImageset function is renamed to ImagesetManager::get (inherited from new base class)
• ImagesetManager::get returns a reference instead of a pointer (to reinforce that it will never return 0).
• ImagesetManager::create and ImagesetManager::createFromImageFile functions take an optional XMLResourceExistsAction parameter to indicate what action to take when loading an imageset with a name that already exists.
• ImagesetManager::create overload taking a Texture pointer is replaced with a version taking a Texture reference.
• ImagesetManager::notifyScreenResolution function renamed to ImagesetManager::notifyDisplaySizeChanged.
• All Imageset and Image drawing functions have an added parameter receiving a GeometryBuffer reference, and have had the float z parameter removed.
• Imageset constructor taking a Texture pointer is replaced with a version taking a Texture reference.
• Imageset::notifyScreenResolution function renamed to Imageset::notifyDisplaySizeChanged.

Scheme and SchemeManager

• SchemeManager is now derived from new NamedXMLResourceManager template class (part of resource system improvments to make things cleaner and easier to maintain).
• SchemeManager::loadScheme function is renamed to SchemeManager::create (inherited from base class)
• SchemeManager::unloadScheme function renamed to SchemeManager::destroy (inherited from new base class).
• SchemeManager::unloadAllSchemes function renamed to SchemeManager::destroyAll (inherited from new base class).
• SchemeManager::isSchemePresent function is renamed to SchemeManager::isDefined (inherited from new base class).
• SchemeManager::getScheme function is renamed to SchemeManager::get (inherited from new base class)
• SchemeManager::get returns a reference instead of a pointer (to reinforce that it will never return 0).
• SchemeManager::create returns a reference instead of a pointer (to reinforce that it will never return 0).
• SchemeManager::create function takes an optional XMLResourceExistsAction parameter to indicate what action to take when loading a scheme with a name that already exists.

Events and input handling

We have changed the way that inputs are marked as handled by the System. Generally speaking all mouse inputs are now marked as handled by the system, with the exception of events that get through to a DefaultWindow set as the root that has mouse pass-though enabled, in these cases the inject* functions will return false so you know the event was not handled by an actual UI element, and can proceed to consider the event for other functions (playfield picking etc...).

EventHandler::handled field is changed from a bool to a CEGUI::uint. Anywhere you previously did:

args.handled = true;

should be updated to

++args.handled;

Note that the boolean return values from subscribed event handlers are unchanged; the EventArgs::handled counter is increased for each subscribed handler that returns true.

Miscellany

• MouseCursor member d_position changes type from Vector3 to Vector2
• ListboxItem::d_itemText renamed to ListboxItem::d_textLogical.
• TreeItem::d_itemText renamed to TreeItem::d_textLogical.
• WindowManager::loadWindowLayout overload taking a boolean and using a random prefix is removed.
• Unused(?) header CEGUITask.h removed.
• InstancedWindows demo removed.
• TextFormatting enumeration is removed, use VerticalTextFormatting and HorizontalTextFormatting enumerations instead.
• Old config file system has been totally replaced (old configs will no longer work). The new config file system will be documented shortly :).
• WindowRenderer::getPixelRect virtual function is removed.
• System object constructor made private. Construction is now to be done via the System::create static function.
• System object destructor made private. Destruction is now to be done via the System::destroy static function.
• Renderer object passed when creating the System object is now passed by reference instead of by pointer (reinforces that it may not be 0).
• CEGUI::Exception is now derived from std::exception. If you need to differentiate between the two, make sure you catch your CEGUI::Exceptions first!

Crazyeddie 15:59, 16 August 2009 (UTC)