Kanzi 3.7 迁移指南

使用此迁移指南将 Kanzi 应用程序从 Kanzi 3.6.6 更新到 Kanzi 3.7。

Kanzi 库

Kanzi 库现在仅适用于 Visual Studio 2015 和 2017。要将您的 Kanzi 3.6.6 项目迁移到 Kanzi 3.7 并使用 Visual Studio 2017 配置：

  1. 在 Visual Studio 中打开工程的 Visual Studio 解决方案：

    1. 在 Solution Explorer 中右键点击工程，选择属性> 通用> 平台工具集 (Properties > General > Platform Toolset)，并确保选中了 Visual Studio 2017 v141 编译器。如果您的项目包含 Kanzi Engine 插件，请对插件和可执行项目执行此操作。

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

    2. 在配置管理器中创建 2017 配置。

      例如，打开配置管理器，在活动解决方案配置下拉菜单中选择 <New …>，将配置命名为 GL_vs2017_Release，点击 OK，并在配置管理器中将所有工程设置为使用 GL_vs2017_Release 配置。

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

    3. 在 Visual Studio 中，构建您要使用的插件的所有配置。

  2. 在 Kanzi Studio 中打开 Kanzi Studio 项目，并让 Kanzi Studio 将项目转换为当前版本。

  3. 在 Kanzi Studio 中，在 Library > Kanzi Engine Plugins 中选择插件的 GL VS2013 Debug 和 Release 版本，并在 Properties 中设置插件。

    例如：对于 Library > Kanzi Engine Plugins 中的 GL VS2017 Release 插件，选择 GL VS2013 Release 插件，并在 Properties 中设置：

    • Name 到 GL VS2017 Release。

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

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

Bindings changes

绑定中的更改要求您更新所有使用 BindingSharedPtr 对象的代码，以使用 AbstractBindingSharedPtr 对象，并分配任何类型的绑定。大多数绑定变为单向 Binding 或 ExpressionBinding （执行操作的绑定）对象。特定的绑定创建函数提供了等同于传统绑定创建函数的简写。

Focus manager 更改

  • Focus Scope 属性（FocusManager::FocusScopeProperty）现已弃用。要将节点设为焦点范围，请使用 Focus Scope Type 属性并将其设置为 Group （FocusManager::FocusScopeTypeProperty）。

  • 焦点栅栏不再是不可聚焦的焦点范围。要将节点变为焦点栅栏，使用 Focus Scope Type 属性并将其设置为 Fence。确保将焦点栅栏节点设为可聚焦，通过添加并启用 Focusable 属性（Node::FocusableProperty）。

  • Node::trySetActiveFocus() 函数不再返回布尔值，而是返回您调用它的节点，或者如果该节点是焦点范围节点，则返回其子节点之一。

  • 默认情况下，所有节点的 Focusable 属性（Node::FocusableProperty）现在已禁用。例外情况是 Button、Toggle Button、List Box、Scroll View 和 Slider 节点，这些节点的 Focusable 属性默认情况下已启用。

  • 将焦点围栏逻辑从

    Focus Scope Type 属性已启用 (FocusManager::FocusScopeProperty) 和 Focusable 属性已禁用 (Node::FocusableProperty)

    至 (To)

    Focus Scope Type 属性设置为 Fence （FocusManager::FocusScopeTypeProperty 设置为 FocusManager::Fence），并启用 Focusable 属性（Node::FocusableProperty）。

Resource manager 更改

对这些 Resource Manager 函数进行了更改：

  • 将 ResourceManager::getResourcePathFromURL() 替换为 detail::stripProjectName()。

  • 将 getRelativePathFromAbsolutePath() 移动到 detail 命名空间下，并将其参数类型从更新为

    static kzString ResourceManager::getRelativePathFromAbsolutePath(kzString absolutePath)

    至 (To)

    string getRelativePathFromAbsolutePath(string_view absolutePath)

字形、字体和文本更改

对字形、字体和文本功能进行了以下更改：

  • 将类 KzuTextManager 替换为 kanzi::GlyphCacheManager 和 kanzi::FontManager。

  • 移除类 KzuTextRenderer、KzuTextManager、KzuTruetypeSystem 和 KzuConfiguredFont，并将部分功能移至 kanzi::TextFormat 和 kanzi::FontManager。

  • 从 Text Block 节点中移除了 Constrain Content Height (TextBlockConcept::ConstrainContentHeightProperty) 属性。要截断文本，请使用 Overflow 属性。Constrain Content Height 属性仅在文本超过 Text Block 节点的高度时截断文本。在 Kanzi 3.7 中，Overflow 属性在文本超过 Text Block 节点的宽度或高度时截断文本。Kanzi Studio 会自动转换项目中的 Text Block 节点。要在自动项目转换后实现相同的渲染效果，当您将 Overflow 属性设置为非默认值并通过将 Constrain Content Height 属性设置为禁用来禁用文本截断时，必须对 Text Block 节点进行调整。Kanzi Studio 转换器会移除 Constrain Content Height 属性，但不会移除 Overflow 属性，该属性在转换后启用文本截断。

在 Kanzi 3.7 中，要设置字体光栅化引擎、创建字体、访问字体加载器和访问字形缓存管理器，请使用 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

消息调度器更改

将 KzuMessageDispatcher 类转换为 C++ 并进行了以下更改：

  • 将功能拆分为 kanzi::MessageDispatcher 和 kanzi::Timer 类。

  • 更新了 MessageArguments 和 ScrollView 类，以使用 chrono::time_points 作为时间戳，而不是 chrono::milliseconds。

  • MessageArguments::setTimestamp() 现在将 chrono::steady_clock::time_point 作为时间戳参数，而 MessageArguments::getTimestamp() 现在返回时间戳参数，而不是 chrono::milliseconds。

  • 删除了直接消息路由。

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()

渲染更改

移动或重命名了这些枚举：

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 不再支持 Legacy Render Pass (deprecated)。

插件元数据更改

统一了插件元数据属性的注册语法。如果您使用旧语法，Kanzi 会发出警告。

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

其他更改

  • 从 Kanzi Engine API 中移除了 kzc_vector*、kzc_matrix* 和 kzc_etc。

  • 将 KzEventQueue 替换为 EventQueue。这在您收集事件时会对 EventSources 引入更改。

  • Core 和 coreui 库现在被构建为单独的 dll 文件。因此，以下项目已更新：

    • KANZI_API 不再定义。使用 KANZI_CORE_API 用于 core，使用 KANZI_COREUI_API 用于 coreui。

    • Kanzi 应用程序必须包含 kzcore_<ConfigurationName>.dll。

    • 要导出 createModule() 方法，Kanzi 应用程序使用自己的 CUSTOM_COMPONENT_API_EXPORT，而不是使用 KANZI_API_IMPORT。

    • 要检查 Kanzi Engine 是否被构建为 dll，应用程序必须使用 KANZI_API_IMPORT。

  • 由于转换为 C++，这些项目已更改：

    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

  • 更改了这些枚举以进行输入转换配置：

    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

  • 将此功能替换为标准定义：

    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() 函数现在捕获一个矩形包含在另一个矩形内的情况。

  • 移除了此功能：

    文件 (File)

    函数

    kzc_solve.hpp

    void kzcSolveQuadratic()

    void kzcSolveNormalizedQuadratic()

    kzc_integrate.hpp

    void kzcIntegrateExponentialDecay()

  • 移动了几个图形后端头文件。新位置通常是以下目录之一：

    • kanzi/core.ui/graphics

    • kanzi/core.ui/graphics2d

    • kanzi/core.ui/graphics3d

另请参阅

Kanzi 3.7 发行说明

已知问题