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.

      ../../_images/set-platform-toolset-compiler-37.png

    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.

      ../../_images/open-configuration-manager-37.png ../../_images/new-solution-configuration.png

    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

    ../../_images/engine-plugin-properties-37.png

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