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", you can replace the call with CEGUI::System::getSingleton().getDefaultGUIContext().some_foobar_method*()
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.