Porting tips and changes from 0.7.X to 0.8.X

Written for CEGUI 0.7

---

Works with versions 0.7.x (obsolete)

Introduction

The 0.8.x branch has already seen releases. Please see the sourceforge page for tarball downloads.

Major renames/API changes

• CEGUI::Window was renamed to CEGUI::Widget as Widget is the coined term for that, WindowManager renamed to WidgetManager, etc... (not in mercurial yet!)
• The stock/standard window renderer set (now widget renderer set) FalagardWRBase was renamed to StandardWRSet to avoid confusion with core Falagard facilities (not in mercurial yet!)
• Windows now don't have absolute names! Every window's name only has to be unique in it's parent window. Therefore WindowManager::getSingleton().getWindow no longer made sense and was removed. If root's name was "Root" and your the window name was "Root/Stuff/After/Root/Name", you can emulate its behaviour with root->getChild("Stuff/After/Root/Name"). It's recommended to migrate to a more encapsulated model.
• CEGUI::GUIContext class has been created that is responsible for injecting input and event handling, setting the default font, setting the root window, setting a default tooltip object and type, and manipulating the mouse cursor.
• CEGUI::GUIContext needs time impulses injected separately! You should also inject time pulses into CEGUI::System. This API "wart" may disappear in future versions.
• CEGUI::MouseCursor is no longer a singleton, and can be accessed and manipulated from CEGUI::GUIContext.

General

• All XML attributes must now be in lowercase, e.g. <WidgetLook Name="TaharezLook/FrameWindow"> must be <WidgetLook name="TaharezLook/FrameWindow">
• PropertyHelper has been turned into a template class, instead of PropertyHelper::uintToString you do PropertyHelper<uint>::toString, instead of PropertyHelper::stringToUint you do PropertyHelper<uint>::fromString
• All instances of the word caret that were incorrectly spelt 'carat' have been corrected. This affects all APIs, properties, events and datafiles.
• Window::EventWindowUpdated renamed to Window::EventUpdated and the associated string is changed from "WindowUpdate" to "Updated"
• ListHeader::SegmentNameSuffix changed type from character array to CEGUI::String
• EventMouseEnters renamed to EventMouseEntersSurface (old name removed)
• EventMouseLeaves renamed to EventMouseLeavesSurface (old name removed)
• BiDiVisualMapping renamed to BidiVisualMapping. Also renamed the files, so CEGUIBiDiVisualMapping.h is now CEGUIBidiVisualMapping.h
• class colour renamed to Colour, as a side effect the "colour" interpolator is now "Colour" interpolator, this breaks animation definitions!
• Point typedef removed, please use Vector2 instead
• Many event string values changed to match the C++ name (but without the Event prefix). A list of which strings changed value will appear here soon.
• Window::setRestoreCapture renamed to Window::setRestoreOldCapture
• CEGUI now supports custom memory allocation, see Memory Allocation to check if this concerns you or not.
• Window::addChildWindow renamed to Window::addChild, Window::removeChildWindow renamed to Window::removeChild, several other methods (mostly in layout containers) changed from *ChildWindow* to *Child*
• CEGUI::String can now be just a typedef or a class, depending on String configuration (CEGUI can now use std::string as CEGUI::String for apps not requiring unicode)
• Window::getChild_impl method completely removed, it was only used by Window::getParentPixelSize, shouldn't be hard to replace
• Vector2, Vector3, Size and Rect are now templated, you should use Vector2<float> (or just Vector2<> as a shortcut since float is the default type) instead of Vector2, UVector2 class was removed, UVector2 is now just a typedef to Vector2<UDim>. Same with Vector3, Size and Rect.
• Texture::saveToMemory is renamed Texture::blitToMemory.
• Renderer and Texture interfaces changed in order to support named textures.
• Window::isDisabled(localOnly) is now split into Window::isDisabled (= old isDisabled(true) and Window::isEffectiveDisabled (= old isDisabled(false))
• Window::isVisible(localOnly) is now split into Window::isVisible (= old isDisabled(true) and Window::isEffectiveVisible (= old isVisible(false))
• WindowManager::loadWindowLayout is renamed to WindowManager::loadLayoutFromFile
• NamedXMLResourceManager::create is renamed to NamedXMLResourceManager::createFromFile (Ex. CEGUI::SchemeManager::createFromFile)
• Property from Window called "ZOrderChangeEnabled" renamed to "ZOrderingEnabled"
• Property from Window called "MouseButtonDownAutoRepeat" renamed to "MouseAutoRepeatEnabled"
• Property from Window called "CustomTooltipType" renamed to "TooltipType"
• Property from Window called "Tooltip" renamed to "TooltipText"
• Property from Window called "RiseOnClick" renamed to "RiseOnClickEnabled"
• Property from Window called "UnifiedAreaRect" renamed to "Area", "UnifiedSize" renamed to "Size", etc...
• CEGUI::DefaultLogger no longer throws const char* but a real exception in setLogFilename - http://www.cegui.org.uk/mantis/view.php?id=443
• CEGUI now has inbuilt copy, cut, paste support, if you used a custom solution, you might want to check CEGUI::Clipboard and System::inject{Copy,Cut,Paste}Request
• CEGUI::ProgressBar::getStep renamed to getStepSize for consistency with setStepSize
• CEGUI::WidgetLookManager::parseLookNFeelSpecification is now called parseLookNFeelSpecificationFromFile, variants for loading from string and raw data container have been added
• XRotation, YRotation, ZRotation properties merged into the new Rotation property, which is a Quaternion.

Image and ImageManager

• Image::draw renamed to Image::render
• Image class is now an abstract interface. BasicImage implementation is provided, and used for internally created Image objects.
• Imageset class is removed. It remains a CEGUI format that allows to conveniently define multiple images on one texture but the data is no longer stored in any class. When Imageset is loaded, the ImageManager creates a new BasicImage for each of the images in the imageset. Only the images themselves will remain after imageset is loaded. You now use the new ImageManager to access defined images.
• ImagesetManager class is removed. You now use the new ImageManager.
• Images belonging to a certain imageset can be accessed like so: "ImageSetName/ImageName" (ex. "AlfiskoSkin/MouseArrow").

GUIContext

A lot of API has been moved from CEGUI::System to CEGUI::GUIContext. CEGUI now allows you to create multiple independent GUI contexts with their own input injection.

As a rule of thumb, whenever you see "There is no CEGUI::System::some_foobar_method method", it is likely that you can replace the call with CEGUI::System::getSingleton().getDefaultGUIContext().someFoobarMethod(). This holds for all the System::inject* methods for example.

WindowManager::getSingleton().getWindow() was removed. You can emulate its behaviour with root->getChild("Stuff/After/Root/Name"). To get Root Window you can call GUIContext::getRootWindow();

SIDE NOTE: The chain call of methods CEGUI::System::getSingleton().getDefaultGUIContext() should be called as rarely as possible, instead one should keep it's result in appropriate variable.

PyCEGUI

• EventSet.subscribeEvent now has a different, more pythonic syntax, any python callable (bound member function, free function, lambda, functor, ...) is allowed (EventSet.subscribeEvent("EventName", instance, "someMethodInIt") is now EventSet.subscribeEvent("EventName", instance.someMethodInIt)

Falagard

• The attributes of the Image elements are now:
  • ("component") and "name", instead of:
  • ("type"), "imageset" and "image"
    • For example an up-to-date Image element inside a FrameComponent element would be: <Image component="LeftEdge" name="TaharezLook/EditBoxLeft" />
• The OperatorDim has changed to DimOperator and works slightly differently. See the new datafiles and the API for more information.