Kanzi 3.9 beta 1 migration guide

Use this migration guide to update Kanzi applications from Kanzi 3.9 alpha 6 to Kanzi 3.9 beta 1.

Changes to the focus functionality

  • Deprecated the Logical Focus property (FocusManager::LogicalFocusProperty).

    Kanzi Studio automatically converts projects that use the Logical Focus property by replacing the Logical Focus property with the Focus Order property set to 0. This change sets a node that has the Focus Order property set to 0 as the first focusable node in the focus scope. See Moving focus in the focus chain.

  • Removed from the FocusManager these properties and options related to directional navigation:

    • NextFocusNodePathProperty, PreviousFocusNodePathProperty, UpNavigationNodePathProperty, DownNavigationNodePathProperty, LeftNavigationNodePathProperty, and RightNavigationNodePathProperty properties.

    • FocusChainDirection options UpFocusable, DownFocusable, LeftFocusable, and RightFocusable.

    Use the Navigation Manipulator to implement directional navigation. See Using the Navigation Manipulator.

  • Renamed or removed these FocusManager methods:

    Kanzi 3.9.0 alpha 6

    Kanzi 3.9.0 beta 1

    FocusManager::getActiveFocus()

    FocusManager::getFocus()

    FocusManager::trySetActiveFocus()

    FocusManager::trySetFocus()

    FocusManager::tryMoveActiveFocus()

    FocusManager::tryMoveFocus()

    FocusManager::tryMoveActiveFocusForward()

    FocusManager::tryMoveFocusForward()

    FocusManager::tryMoveActiveFocusBackward()

    FocusManager::tryMoveFocusBackward()

    FocusManager::tryMoveActiveFocusUpward()

    removed

    FocusManager::tryMoveActiveFocusDownward()

    removed

    FocusManager::tryMoveActiveFocusLeft()

    removed

    FocusManager::tryMoveActiveFocusRight()

    removed

  • Renamed or removed these Kanzi Studio JavaScript scripting functions:

    Kanzi 3.9.0 alpha 6

    Kanzi 3.9.0 beta 1

    tryMoveActiveFocusForward

    tryMoveFocusForward

    tryMoveActiveFocusBackward

    tryMoveFocusBackward

    tryMoveActiveFocusUpward

    removed

    tryMoveActiveFocusDownward

    removed

    tryMoveActiveFocusLeft

    removed

    tryMoveActiveFocusRight

    removed

Changes to the scrolling functionality

  • The Scroll View 2D and Grid List Box 2D nodes now by default scroll the same amount as the user drags the pointer. To migrate your project to Kanzi 3.9 beta 1, in the Scroll View 2D and Grid List Box 2D nodes adjust the value of the Scroll Sensitivity property (ScrollViewConcept::SensitivityProperty, GridListBoxConcept::SensitivityProperty). The default value is 1. For example, to set the node to scroll twice the amount that the user drags the pointer, set the value of the Scroll Sensitivity property to 2.

    Kanzi 3.9 beta 1 removes the unintended behavior caused by setting the Scroll Sensitivity property to a negative value. The Scroll Sensitivity property can no longer have a negative value. For example, to change the direction of scrolling in a Scroll View 2D node that you use to rotate a 3D model, modify the binding that binds the rotation to the scroll position. See Tutorial: Rotate a 3D model.

  • In the Scroll View, Grid List Box, and Trajectory List Box 3D nodes the value of the Scroll Position property (ScrollViewConcept::ScrollPositionProperty, GridListBoxConcept::ScrollPositionProperty, TrajectoryListBox3D::ScrollPositionProperty) now decreases when the pointer moves right and down. To migrate your project to Kanzi 3.9 beta 1, adjust the bindings and Set Property actions that target the scroll position of a Scroll View or List Box node. In some cases you must replace a Set Property action with a binding. For example, if you in an earlier version of Kanzi used the value of the Scroll Position property to set the translation of content in a Scroll View node, negate the value of the Scroll Position property. See Creating a Scroll View node.

  • Deprecated the Scroll Axis property (ScrollViewConcept::ScrollAxisProperty).

    Kanzi Studio automatically converts projects that use the Scroll Axis property by replacing the Scroll Axis property with the Allowed Scroll Axis property.

Changes to the ListBoxItemContainer

ListBoxItemContainer2D and ListBoxItemContainer3D now inherit from ContentLayout2D and ContentLayout3D.

Changes to the ResourceManager

Modernized the ResourceManager ProtocolHandler signature:

  • Instead of a function pointer, it now uses std::function.

  • Removed the userdata argument. You can now capture additional state with the function, such as with lambda captures.

Changes to 2D node caching

Removed these properties:

  • Cache Children (Node2D::CacheChildrenProperty)

    Kanzi no longer supports caching only the children of a node. To cache the descendants of a node without caching the node itself, move the child nodes to a separate node and in that node set the Caching Mode property to Enabled.

  • Cache Result (Node2D::CacheResultProperty)

    Kanzi Studio automatically converts projects that use the Cache Result property by replacing it with the Caching Mode property.

  • Cache Self (Node2D::CacheSelfProperty)

    Kanzi no longer supports caching a node but not caching the descendants of that node. To cache a node without caching its descendants, move the descendant nodes to a separate node, and in the node that you want to cache set the Caching Mode property to Enabled.

The caching system for 2D nodes now supports automatic cache refresh and invalidation. See Caching 2D nodes.

Changes to Code Behind

Kanzi 3.9 beta 1 introduces changes to the Code Behind functionality that are not compatible with the previous version of Kanzi. When you open in Kanzi Studio the project of your application, the Preview does not start until you migrate your application to Kanzi 3.9 beta 1.

If your Kanzi application uses Code Behind, to migrate your Kanzi 3.9 alpha 6 application to Kanzi 3.9 beta 1:

  1. Move the contents of the <ProjectName>/CodeBehind/Application directory:

    • If your application is based on the Kanzi Studio project template:

      1. Move the contents of the <ProjectName>/CodeBehind/Application directory to the <ProjectName>/CodeBehind directory.

      2. Delete the <ProjectName>/CodeBehind/Application directory.

      3. In the <ProjectName>/Build Configurations/<ProjectName>/Application/CMakeLists.txt file change:

        set(CodeBehind_lib_dir "${CMAKE_CURRENT_SOURCE_DIR}/../../../CodeBehind/Application")

        to

        set(CodeBehind_lib_dir "${CMAKE_CURRENT_SOURCE_DIR}/../../../CodeBehind")

    • If your application is based on the Application, Application with data source plugin, or Application with Kanzi Engine plugin template:

      1. Move the contents of the <ProjectName>/Tool_project/CodeBehind/Application directory to the <ProjectName>/Tool_project/CodeBehind directory.

      2. Delete the <ProjectName>/Tool_project/CodeBehind/Application directory.

      3. In the <ProjectName>/Application/CMakeLists.txt file change:

        set(CodeBehind_lib_dir "${CMAKE_CURRENT_SOURCE_DIR}/../Tool_project/CodeBehind/Application")

        to

        set(CodeBehind_lib_dir "${CMAKE_CURRENT_SOURCE_DIR}/../Tool_project/CodeBehind")

  2. In Kanzi Studio open the project of your application that uses Code Behind, in the Library > Kanzi Engine Plugins select each version of the Code Behind plugin and in the Properties change the Kanzi Engine Plugin DLL Properties > Windows DLL Path property from:

    CodeBehind\Application\lib\Win32\<GL_vs2017_Debug_DLL|GL_vs2017_Release_DLL>\<ProjectName>_CodeBehind.dll

    to

    CodeBehind\lib\Win32\<GL_vs2017_Debug_DLL|GL_vs2017_Release_DLL>\<ProjectName>_CodeBehind.dll

    ../../_images/migrate-code-behind-library.png ../../_images/migrate-code-behind-properties.png

Removed the deprecated Play Animation action

Removed the deprecated Play Animation action. Use the Animation Player instead. See Using keyframe animations and Creating animations and timelines using the Kanzi Engine API.

Changes to the Timer functionality

The Timer functionality is now part of the MainLoopScheduler subsystem and it replaces the removed Timer subsystem.

Now you add timer tasks directly into the main loop:

  • To add a timer task before a stage, use MainLoopScheduler::prependTimer.

  • To add a timer task after a stage, use MainLoopScheduler::appendTimer.

  • To remove a timer, use MainLoopScheduler::removeTimer.

Timers now have these recurrence options:

  • Kanzi executes the MainLoopScheduler::TimerRecurrence::OneTime timer tasks once when the specified time since their addition has elapsed.

  • Kanzi executes the MainLoopScheduler::TimerRecurrence::Recurring timer tasks periodically at specified intervals. When multiple intervals have elapsed between the main loop iterations, Kanzi executes recurring tasks just once, but provides the repeat count through their callback interface.

Timers no longer use message arguments or properties, instead the timer callback directly receives elapsed duration rounded down to a multiple of the interval of the timer and number of elapsed intervals as arguments.

Changes to the MainLoopScheduler functionality

To reduce memory consumption, the MainLoopScheduler tasks now support string literal names.

In all the interfaces for creating tasks, you must now choose between FixedString and MetadataGeneratedName types for the task name:

  • FixedString wraps a string literal

  • MetadataGeneratedName accepts any string-like object and makes a copy of it

Changes to bindings

In the previous versions of Kanzi, if a binding used as a source value a property type that was not present in the source node, Kanzi did not apply that binding. Now when a property type is not present in the source node, bindings use the default value of that property type.

Changes to the DataObject classes

  • DataObject classes no longer have public constructors. You must construct them using a static create function:

    Kanzi 3.9.0 alpha 6

    Kanzi 3.9.0 beta 1

    DataObject::DataObject(Domain*, string_view)

    DataObject::create(Domain*, string_view)

    DataObjectBool::DataObjectBool(Domain*, string_view)

    DataObjectBool::create(Domain*, string_view)

    DataObjectInt::DataObjectInt(Domain*, string_view)

    DataObjectInt::create(Domain*, string_view)

    DataObjectReal::DataObjectReal(Domain*, string_view)

    DataObjectReal::create(Domain*, string_view)

    DataObjectString::DataObjectString(Domain*, string_view)

    DataObjectString::create(Domain*, string_view)

Other changes

  • Replaced rayPickCalculateRay with Camera::calculateCameraRay.