Kanzi 3.7 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.6.6 to Kanzi 3.7.

Kanzi libraries

Kanzi libraries are now available only for Visual Studio 2015 and 2017. To migrate your Kanzi 3.6.6 projects to Kanzi 3.7 and use Visual Studio 2017 configurations:

1. Open the Visual Studio solution of the project in Visual Studio:

   1. In the Solution Explorer right-click the project, select Properties > General > Platform Toolset, and make sure that the Visual Studio 2017 v141 compiler is selected. If your project includes a Kanzi Engine plugin, do this for the plugin and executable projects.

      

   2. In the Configuration Manager create 2017 configurations.

      For example, open the Configuration Manager, in the Active solution configuration dropdown menu select <New...>, name the configuration GL_vs2017_Release, click OK, and in the Configuration Manager set all projects to use the GL_vs2017_Release configuration.

      

   3. In Visual Studio build all configurations of the plugins that you want to use.

2. In Kanzi Studio open the Kanzi Studio project and let Kanzi Studio convert the project to the current version.

3. In Kanzi Studio in the Library > Kanzi Engine Plugins select the GL VS2013 Debug and Release versions of the plugin and in the Properties set the plugin.

   For example, for GL VS2017 Release plugin in the Library > Kanzi Engine Plugins select the GL VS2013 Release plugin and in the Properties set:

   • Name to GL VS2017 Release

   • Windows DLL Path to ..\Application\lib\Win32\GL_vs2017_Release_DLL\<ProjectName>.dll

   

Bindings changes

The changes in bindings require that you update all code that uses BindingSharedPtr objects to use AbstractBindingSharedPtr objects, to which any type of binding is assigned. Most bindings become either one-way a Binding or an ExpressionBinding (a binding that executes operations) objects. Specific binding create functions provide shorthands equivalent to legacy binding create functions.

Focus manager changes

• The Focus Scope property (FocusManager::FocusScopeProperty) is now deprecated. To make a node into a focus scope, use the Focus Scope Type property and set it to Group (FocusManager::FocusScopeTypeProperty).

• Focus fences are no longer non-focusable focus scopes. To make a node into a focus fence, use the Focus Scope Type property and set it to Fence. Make sure that focus fence nodes are focusable by adding and enabling the Focusable property (Node::FocusableProperty).

• The Node::trySetActiveFocus() function no longer returns a boolean value, but the node on which you call it, or, if the node is a focus scope node, one of its child nodes.

• By default the Focusable property (Node::FocusableProperty) is now disabled for all nodes. The exceptions are Button, Toggle Button, List Box, Scroll View, and Slider nodes, whose Focusable property is by default enabled.

• Changed the focus fence logic from

  Focus Scope Type property enabled (FocusManager::FocusScopeProperty) and Focusable property disabled (Node::FocusableProperty)

  to

  Focus Scope Type property set to Fence (FocusManager::FocusScopeTypeProperty set to FocusManager::Fence) and Focusable property enabled (Node::FocusableProperty)

Resource manager changes

Made changes to these resource manager functions:

• Replaced ResourceManager::getResourcePathFromURL() with detail::stripProjectName().

• Moved getRelativePathFromAbsolutePath() under detail namespace and updated its argument type from

  static kzString ResourceManager::getRelativePathFromAbsolutePath(kzString absolutePath)

  to

  string getRelativePathFromAbsolutePath(string_view absolutePath)

Glyph, font, and text changes

Made these changes to glyph, font, and text functionality:

• Replaced class KzuTextManager with kanzi::GlyphCacheManager and kanzi::FontManager.

• Removed classes KzuTextRenderer, KzuTextManager, KzuTruetypeSystem, and KzuConfiguredFont, and moved part of the functionality to kanzi::TextFormat and kanzi::FontManager.

• Removed the Constrain Content Height (TextBlockConcept::ConstrainContentHeightProperty) property from Text Block nodes. To truncate text, use the Overflow property. The Constrain Content Height property truncated text only when the text exceeded the height of a Text Block node. In Kanzi 3.7 the Overflow property truncates text if the text exceeds width or height of a Text Block node. Kanzi Studio automatically converts the Text Block nodes in your project. To achieve the same rendering result after automatic project conversion, you must make adjustments to the Text Block nodes when you set the Overflow property to a value that is not the default value and you disabled text truncation by setting the Constrain Content Height property to disabled. The Kanzi Studio converter removes the Constrain Content Height property, but does not remove the Overflow property, which enables text truncation after the conversion.

In Kanzi 3.7 to set the font rasterizer engine, create font, access font loaders, and access glyph cache manager, use the kanzi::FontManager.

Kanzi 3.6.6	Kanzi 3.7
KzuFont	kanzi::FontFile
KzuBitmapFont	kanzi::BitmapFontFile
KzuBitmapFontSystem	kanzi::BitmapFontLoader
KzuItypeFont	kanzi::ItypeFontFile
KzuItypeSystem	kanzi::ItypeFontLoader
KzuFreetypeFont	kanzi::FreeTypeFontFile
KzuFreetypeSystem	kanzi::FreeTypeFontLoader
KzuTextFormat	kanzi::TextFormat
KzuTextLayouter	kanzi::TextLayouter
KzuTextLayout	kanzi::TextLayout
KzuGlyphCache	kanzi::GlyphCache

Message dispatcher changes

Converted the KzuMessageDispatcher class to C++ and made these changes:

• Split the functionality into kanzi::MessageDispatcher and kanzi::Timer classes.

• Updated the MessageArguments and ScrollView classes to use for timestamps chrono::time_points instead of chrono::milliseconds.

• The MessageArguments::setTimestamp() now takes as a timestamp argument chrono::steady_clock::time_point and MessageArguments::getTimestamp() now returns timestamp argument, instead of chrono::milliseconds.

• Removed the direct message routing.

Kanzi 3.6.6	Kanzi 3.7
KzuTimerMessageMode	Timer::TimerMode
kanzi::addTimerHandler()	Timer::addSubscription()
kanzi::removeTimerHandler()	Timer::removeSubscription()
kzuMessageDispatcherDispatchQueuedMessages()	Timer::update()
kzuMessageDispatcherGetProposedSleepTime()	Timer::getProposedSleepTime()
kzuMessageDispatcherAddHandler()	MessageDispatcher::addBubblingHandler()
kzuMessageDispatcherAddTunnelingHandler()	MessageDispatcher::addTunnelingHandler()
kzuMessageDispatcherRemoveHandler()	MessageDispatcher::removeHandler()
kzuMessageDispatcherDispatchMessage()	MessageDispatcher::dispatchMessage()

Rendering changes

Moved or renamed these enums:

Kanzi 3.6.6	Kanzi 3.7
kanzi::Renderer::Multisample	kanzi::Multisample
kanzi::Renderer::ProgramBinary	kanzi::ProgramBinary
kanzi::Renderer::HalfFloatTexture	kanzi::HalfFloatTexture
kanzi::Renderer::TexStorage	kanzi::TexStorage
kanzi::Renderer::InvalidateFramebuffer	kanzi::InvalidateFramebuffer
kanzi::Renderer::State	kanzi::RendererState
kanzi::Renderer::FixedMatrix	kanzi::FixedMatrix
kanzi::Renderer::Support	kanzi::RendererSupport
kanzi::Texture::Type	kanzi::TextureType
kanzi::Texture::RenderTargetMode	kanzi::RenderTargetMode
kzuTimerMessageMode	kanzi::Timer::TimerMode

Kanzi no longer supports the Legacy Render Pass (deprecated).

Plugin metadata changes

Unified the registration syntax for the plugin metadata attributes. If you use the old syntax, Kanzi issues a warning.

Kanzi 3.6.6	Kanzi 3.7
metadata["defaultValue"]	metadata.defaultValue
metadata["lowerBound"]	metadata.lowerBound
metadata["upperBound"]	metadata.upperBound
metadata["step"]	metadata.step
metadata["sendable"]	metadata.sendable
metadata["listenable"]	metadata.listenable
metadata["studioVisibility"]	metadata.studioVisibility
metadata["legacyName"]	metadata.legacyName

Other changes

• Removed from the Kanzi Engine API kzc_vector*, kzc_matrix*, and kzc_etc.

• Replaced the KzEventQueue with EventQueue. This introduces changes to EventSources when you gather events.

• Core and coreui libraries are now built as separate dll files. As a result these following items have been updated:

  • KANZI_API is not defined anymore. Use KANZI_CORE_API for core, and KANZI_COREUI_API for coreui.

  • Kanzi applications must include the kzcore_<ConfigurationName>.dll.

  • To export createModule() method, instead of using KANZI_API_IMPORT, Kanzi applications use own CUSTOM_COMPONENT_API_EXPORT.

  • To check whether Kanzi Engine was built as a dll, the application must use KANZI_API_IMPORT.

• As a result of conversion to C++, these items have changed:

  Kanzi 3.6.6	Kanzi 3.7
  kzcVector2	kanzi::Vector2
  kzcVector3	kanzi::Vector3
  kzcVector4	kanzi::Vector4
  kzcMatrix3x3	kanzi::Matrix3x3
  kzcMatrix4x4	kanzi::Matrix4x4
  kzcPlane	kanzi::Plane
  kzcRay	kanzi::Ray
  kzcRectangle	kanzi::Rectangle<T>
  kzuMessageDispatcher	kanzi::MessageDispatcher kanzi::Timer

• Changed these enums for input translation configuration:

  Kanzi 3.6.6	Kanzi 3.7
  KZS_INPUT_TRANSLATE_NONE	TranslateNone
  KZS_INPUT_TRANSLATE_POINTER_TO_TOUCH	TranslatePointerToTouch
  KZS_INPUT_TRANSLATE_POINTER_TO_TOUCH_PRESERVE	TranslatePointerToTouchPreserve
  KZS_INPUT_TRANSLATE_TOUCH_TO_POINTER	TranslateTouchToPointer
  KZS_INPUT_TRANSLATE_TOUCH_TO_POINTER_PRESERVE	TranslateTouchToPointerPreserve

• Replaced this functionality with the standard definitions:

  Kanzi 3.6.6	Kanzi 3.7
  kzsThread	kanzi::thread kanzi::condition_variable
  kzcSort	kanzi::sort
  kzcRandom	kanzi::default_random_engine kanzi::uniform_int_distribution kanzi::uniform_real_distribution

• Rectangle<T>::overlaps() function now catches the case where one rectangle is contained within another.

• Removed this functionality:

  File	Function
  kzc_solve.hpp	void kzcSolveQuadratic() void kzcSolveNormalizedQuadratic()
  kzc_integrate.hpp	void kzcIntegrateExponentialDecay()

• Moved several graphics backend header files. The new location is usually one of these directories:

  • kanzi/core.ui/graphics

  • kanzi/core.ui/graphics2d

  • kanzi/core.ui/graphics3d

See also

Kanzi 3.7 release notes

Known issues