Difference between revisions of "Changes and Porting Tips for 1.0.0"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
 
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{VersionBadge|0.8}}
+
{{VersionBadge|1.0}}
  
 
{{Section|1=Introduction|2=
 
{{Section|1=Introduction|2=
Porting guide for the upcomin 1.0.0 version. The guide is for porting 0.8 to 1.0, for porting from older versions please also see the older porting guides.
+
Porting guide for the upcoming 1.0.0 version. The guide is for porting 0.8 to 1.0, for porting from older versions please also see the older porting guides (0.7->0.8 etc) in combination with this guide.
 
}}
 
}}
  
 
{{Section|1=Major renames/API changes|2=
 
{{Section|1=Major renames/API changes|2=
 +
* Default GUIContext was removed. Each context must be explicitly created with System::createGUIContext() when it is required.
 
* The Editbox "MaskText" property was renamed to "TextMasked" for consistency
 
* The Editbox "MaskText" property was renamed to "TextMasked" for consistency
 
* Editbox and MultilineEditbox now inherit common behaviour from the EditboxBase class.  
 
* Editbox and MultilineEditbox now inherit common behaviour from the EditboxBase class.  
 
* The Editbox and MultilineEditbox methods getSelectionStartIndex() and getSelectionEndIndex() were renamed to getSelectionStart() and getSelectionEnd()
 
* The Editbox and MultilineEditbox methods getSelectionStartIndex() and getSelectionEndIndex() were renamed to getSelectionStart() and getSelectionEnd()
 +
* XMLAttributes::getValueAsString signature and parameters changed to: String getValueAsString(const String&, const String&) const from  const String& getValueAsString(const String&, const String& ) const
 +
* Text Mask property renaming, done for consistency with naming conventions and associated methods. Properties renamed: "MaskText" renamed to "TextMaskingEnabled", "MaskCodepoint" renamed to "TextMaskingCodepoint"
 +
* Text Mask events renamed: Editbox::EventMaskedRenderingModeChanged("MaskedRenderingModeChanged") becomes EditboxBase::EventTextMaskingEnabledChanged("TextMaskingEnabledChanged"), EditboxBase::EventMaskCodePointChanged("MaskCodePointChanged") becomes EditboxBase::EventTextMaskingCodepointChanged("TextMaskingCodepointChanged")
 +
* Editbox::setTextMasked changed to EditboxBase::setTextMaskingEnabled, Editbox::setMaskCodePoint changed to EditboxBase::setTextMaskingCodepoint, Editbox::onMaskedRenderingModeChanged changed to EditboxBase::onTextMaskingEnabledChanged
 +
* All std maps and sets using StringFastLessCompare are replaced by std::unordered_map and std::unordered_set
 +
* A hash template was added to CEGUI::String so that this type can be used in c++11 unordered_set and unordered_map as key
 +
* The CEGUI_THROW, CEGUI_TRY, CEGUI_CATCH and CEGUI_RETHROW defines have been replaced by the regular C++ keywords available for these purposes
 +
* Combobox: The following renames happened for consistency/clarity: setSelection -> setTextSelection, setSelectionStart -> setTextSelectionStart, setSelectionLength -> setTextSelectionLength, getSelectionStartIndex -> getSelectionStart,  getSelectionEndIndex --> getSelectionEnd, getSelectionLength --> getTextSelectionLength
 +
* Combobox Properties: "SelectionStart" -> "TextSelectionStart", "SelectionLength" -> "TextSelectionLength"
 +
* Internal custom allocators were removed (CEGUI_NEW_AO, etc) and replaced with the normal keywords as this is the way to go on all modern systems and consoles, with very few exceptions (some AAA games seem to use custom ones)
 +
* Cmake minimum version was changed to 3.0.0
 +
* All RenderTargets (as well as RenderTextureTargets and subclasses) were reworked in order to remove the templatisation, which induced a sort of diamond inheritance. The classes now inherit the base classes in the expected way by using virtual inheritance. RenderTarget is now a virtual class ( which is not to be confused with a class that has virtual member methods etc. - i.e. a regular superclass) . This fixes the diamond inheritance issue and makes it much easier to understand what is going on.
 +
* PropertyHelper was heavily reworked using C++11 features. The implementation now resides in a separate file which improves compilation time. Stringstreams are used to ensure thread-safety for the future and to ensure that the correct locale ("C" locale) is used, as defined by us.
 +
* Almost all CEGUI Types now feature stream operators >> and << which are used to read and write them to strings, which is done during file parsing, writing and property writing and reading (if this is not done using the native types). Nevertheless, the fromString() and toString() functions should be used to parse types from strings or convert them to strings instead of the stream operators, as they also do error checking in this context and are guaranteed to work for all CEGUI types correctly.
 +
* The functions OpenGL3Renderer::enableStateResetting and OpenGLRenderer::enableStateResetting were renamed to setStateResettingEnabled respectively. The functionality is now default ON and has been slightly reworked. We hope to solve more state-change related issues for users this way. If you think we are not resetting a state to default that should be reset in this way, please inform us on the forum or create a bug on the bitbucket issue tracker!
 +
* CEGUI PropertyHelper now uses the unsigned types std::uint64_t and std::uint32_t. "unsigned long" and CEGUI::uint have been removed in this context. In general, many types that were never used or had uncertain length are now replaced by fixed length types such as std::int8_t to std::int64_t and std::uint8_t to std::uint64_t as defined by the C++11 standard.
 +
* CEGUI's integer types (CEGUI::uint, CEGUI::ulong, etc) have been replaced by fixed width types according to C++11 (std::uint32_t etc)
 
}}
 
}}
  
{{Section|1=Minor renames/API changes|2=
+
{{Section|1=Changes regarding the datafiles / XML|2=
 +
* Multiple Fonts can now be loaded per file. The root node is now called Fonts instead of Font and contains the version attribute. Font has no version attribute anymore and multiple font nodes can be inside the Fonts node. Use ceed-migrate if you want to migrate multiple files (Search for ceed migrate in the wiki)
 +
}}
 +
 
 +
{{Section|1=Tools|2=
 +
* Old python CEED may become partially incompatible with 1.0 data. In this case CEED C++ port must be used which is based on CEGUI default branch.
 +
}}
 +
 
 +
{{Section|1=Minor changes|2=
 
* Scrollbar::isAtEnd() and Scrollbar::getMaxScrollPosition() are now public
 
* Scrollbar::isAtEnd() and Scrollbar::getMaxScrollPosition() are now public
* MultilineEditbox now also has a MaskText property
+
* MultilineEditbox now has the Text Masking functionality, which previously only Editboxes featured
 +
* Combobox now fires EventListSelectionAccepted events also if a user calls a method to change the selection, etc.
 
}}
 
}}
  
 
[[Category:Manuals]]
 
[[Category:Manuals]]

Latest revision as of 12:03, 10 July 2019

Written for CEGUI 1.0


Works with versions 1.0.x (unstable)

Introduction

Porting guide for the upcoming 1.0.0 version. The guide is for porting 0.8 to 1.0, for porting from older versions please also see the older porting guides (0.7->0.8 etc) in combination with this guide.

Major renames/API changes

  • Default GUIContext was removed. Each context must be explicitly created with System::createGUIContext() when it is required.
  • The Editbox "MaskText" property was renamed to "TextMasked" for consistency
  • Editbox and MultilineEditbox now inherit common behaviour from the EditboxBase class.
  • The Editbox and MultilineEditbox methods getSelectionStartIndex() and getSelectionEndIndex() were renamed to getSelectionStart() and getSelectionEnd()
  • XMLAttributes::getValueAsString signature and parameters changed to: String getValueAsString(const String&, const String&) const from const String& getValueAsString(const String&, const String& ) const
  • Text Mask property renaming, done for consistency with naming conventions and associated methods. Properties renamed: "MaskText" renamed to "TextMaskingEnabled", "MaskCodepoint" renamed to "TextMaskingCodepoint"
  • Text Mask events renamed: Editbox::EventMaskedRenderingModeChanged("MaskedRenderingModeChanged") becomes EditboxBase::EventTextMaskingEnabledChanged("TextMaskingEnabledChanged"), EditboxBase::EventMaskCodePointChanged("MaskCodePointChanged") becomes EditboxBase::EventTextMaskingCodepointChanged("TextMaskingCodepointChanged")
  • Editbox::setTextMasked changed to EditboxBase::setTextMaskingEnabled, Editbox::setMaskCodePoint changed to EditboxBase::setTextMaskingCodepoint, Editbox::onMaskedRenderingModeChanged changed to EditboxBase::onTextMaskingEnabledChanged
  • All std maps and sets using StringFastLessCompare are replaced by std::unordered_map and std::unordered_set
  • A hash template was added to CEGUI::String so that this type can be used in c++11 unordered_set and unordered_map as key
  • The CEGUI_THROW, CEGUI_TRY, CEGUI_CATCH and CEGUI_RETHROW defines have been replaced by the regular C++ keywords available for these purposes
  • Combobox: The following renames happened for consistency/clarity: setSelection -> setTextSelection, setSelectionStart -> setTextSelectionStart, setSelectionLength -> setTextSelectionLength, getSelectionStartIndex -> getSelectionStart, getSelectionEndIndex --> getSelectionEnd, getSelectionLength --> getTextSelectionLength
  • Combobox Properties: "SelectionStart" -> "TextSelectionStart", "SelectionLength" -> "TextSelectionLength"
  • Internal custom allocators were removed (CEGUI_NEW_AO, etc) and replaced with the normal keywords as this is the way to go on all modern systems and consoles, with very few exceptions (some AAA games seem to use custom ones)
  • Cmake minimum version was changed to 3.0.0
  • All RenderTargets (as well as RenderTextureTargets and subclasses) were reworked in order to remove the templatisation, which induced a sort of diamond inheritance. The classes now inherit the base classes in the expected way by using virtual inheritance. RenderTarget is now a virtual class ( which is not to be confused with a class that has virtual member methods etc. - i.e. a regular superclass) . This fixes the diamond inheritance issue and makes it much easier to understand what is going on.
  • PropertyHelper was heavily reworked using C++11 features. The implementation now resides in a separate file which improves compilation time. Stringstreams are used to ensure thread-safety for the future and to ensure that the correct locale ("C" locale) is used, as defined by us.
  • Almost all CEGUI Types now feature stream operators >> and << which are used to read and write them to strings, which is done during file parsing, writing and property writing and reading (if this is not done using the native types). Nevertheless, the fromString() and toString() functions should be used to parse types from strings or convert them to strings instead of the stream operators, as they also do error checking in this context and are guaranteed to work for all CEGUI types correctly.
  • The functions OpenGL3Renderer::enableStateResetting and OpenGLRenderer::enableStateResetting were renamed to setStateResettingEnabled respectively. The functionality is now default ON and has been slightly reworked. We hope to solve more state-change related issues for users this way. If you think we are not resetting a state to default that should be reset in this way, please inform us on the forum or create a bug on the bitbucket issue tracker!
  • CEGUI PropertyHelper now uses the unsigned types std::uint64_t and std::uint32_t. "unsigned long" and CEGUI::uint have been removed in this context. In general, many types that were never used or had uncertain length are now replaced by fixed length types such as std::int8_t to std::int64_t and std::uint8_t to std::uint64_t as defined by the C++11 standard.
  • CEGUI's integer types (CEGUI::uint, CEGUI::ulong, etc) have been replaced by fixed width types according to C++11 (std::uint32_t etc)

Changes regarding the datafiles / XML

  • Multiple Fonts can now be loaded per file. The root node is now called Fonts instead of Font and contains the version attribute. Font has no version attribute anymore and multiple font nodes can be inside the Fonts node. Use ceed-migrate if you want to migrate multiple files (Search for ceed migrate in the wiki)

Tools

  • Old python CEED may become partially incompatible with 1.0 data. In this case CEED C++ port must be used which is based on CEGUI default branch.

Minor changes

  • Scrollbar::isAtEnd() and Scrollbar::getMaxScrollPosition() are now public
  • MultilineEditbox now has the Text Masking functionality, which previously only Editboxes featured
  • Combobox now fires EventListSelectionAccepted events also if a user calls a method to change the selection, etc.