使用 Pan Manipulator¶

使用 Pan Manipulator 使用户能够在您的 Kanzi 应用程序中移动节点。

例如，您可以使用 Pan Manipulator 来使用户移动地图。请参阅为节点启用平移手势。

使用 Pan Manipulator 触发器对平移手势做出反应。例如，您可以在用户平移该节点时设置节点的外观。

请参阅使用 Pan Manipulator 触发器。

Pan Manipulator 是您可以用来在 Kanzi 应用程序中为节点添加手势识别的输入操控器之一。

请参阅使用输入操纵器。

通过完成教程学习如何使用 Pan Manipulator。请参阅教程：平移、缩放、轻触。

为节点启用平移手势¶

要为节点启用平移手势：

在 Kanzi Studio 中，使用 Application 模板创建一个项目。
在 Node Tree 中创建一个您想启用平移手势的节点。

例如，创建一个 Image 节点并将其命名为 PanNode。
在 Node Tree 中选择您在上一步中创建的节点，在 Properties 中添加 Input > Hit Testable 属性，并将其设置为启用。

当您启用属性时，用户能选取节点。

默认情况下，Button、Toggle Button、List Box Item Container、Scroll View、Slider 和 Text Box 节点启用了命中测试。

请参阅定义哪个节点接收输入。
在 Node Components 按 Alt 并右键单击 Input Manipulators 中，选择 Pan Manipulator。

通过这种方式，您可以使 PanNode 节点对平移手势作出反应。

通过向节点添加 Pan Manipulator 组件，您可以在该节点上安装 PanManipulator。

要控制 PanManipulator 的行为，您可以在 Pan Manipulator 组件中添加并设置这些属性：
- Recognition Threshold 设置指针在 x 和 y 轴上必须移动的像素阈值，Kanzi 才能将其识别为平移手势。默认值是两个轴上都是 5 像素。
  
  要禁用任一轴上的平移手势，请将该轴的 Recognition Threshold 属性字段设置为 -1。
- Minimum Touch Points 设置在节点区域上识别平移手势所需的最小触摸次数，以便已安装的 PanManipulator 能够识别平移手势。默认值为 1。
- Maximum Touch Points 设置在已安装的 PanManipulator 识别平移手势时节点区域允许的最大触摸次数。默认值为 10。
在 Node Tree 按 Alt 并右键单击中，创建的节点并选择 Alias。

Kanzi Studio 创建一个指向您创建别名的节点的别名，并将其添加到其最近的包含资源字典的祖先节点的资源字典中。

使用 # 符号后跟别名名称访问别名目标节点。
选择 File > Export > Export KZB。

Kanzi Studio creates the kzb file and configuration files from your Kanzi Studio project. Kanzi Studio stores the exported files in the <ProjectName>/Application/bin directory or the location that you set in Project > Properties in the Binary Export Directory property. The kzb file contains all nodes and resources from your Kanzi Studio project, except the resources that you mark in a localization table as locale packs.

当您从 Visual Studio 运行您的 Kanzi 应用程序时，您的应用程序会加载 kzb 文件和配置文件。
在 Kanzi Studio 中，选择 File > Open Kanzi Command Prompt。

Kanzi Command Prompt 打开 Windows 命令提示符，并为您打开 Kanzi Command Prompt 的 Kanzi 版本设置 Kanzi 环境变量。

使用 Kanzi Command Prompt 访问 Kanzi 实用工具和构建工具（例如 Gradle 和 CMake），而无需使用绝对路径或设置环境变量。

小技巧

您可以在 Windows 开始菜单的 Rightware 目录中找到 Kanzi Command Prompt。

当您安装了多个版本的 Kanzi 时，确保将您要在该命令提示符下使用的 Kanzi 版本的 Kanzi Command Prompt 启动。
在 <ProjectName>/Application 目录中的 Kanzi Command Prompt 中，运行生成应用程序的 Visual Studio 解决方案的脚本。
```
generate_cmake_vs2022_solution.bat
```
此脚本会在 <ProjectName>/Application/build_vs2022 目录中为应用程序生成 Visual Studio 解决方案。

在 Visual Studio 中，打开 <ProjectName>/Application/build_vs<Version>/<ProjectName>.sln Visual Studio 解决方案，并在实现应用程序逻辑的文件中定义如何响应平移手势：

为平移消息定义处理程序。

例如，在实现应用程序逻辑的类的 public 部分后添加：

private:
    // Define the handler for the PanManipulator::StartedMessage message from 2D nodes
    // that have an input manipulator which generates pan messages.
    // This handler prepares a 2D node for a pan gesture.
    void onPanStarted(PanManipulator::StartedMessageArguments& messageArguments)
    {
        // Get from the message arguments the node that the user pans.
        Node2DSharedPtr node2d = dynamic_pointer_cast<Node2D>(messageArguments.getSource());

        if (!node2d)
        {
            return;
        }

        // When starting a pan gesture on the node, bring the node to front.
        node2d->moveToFront();
    }

    // Define the handler for the PanManipulator::MovedMessage message from 2D nodes
    // that have an input manipulator which generates pan messages.
    // This handler translates a 2D node by the amount of the pan gesture.
    void onPanMoved(PanManipulator::MovedMessageArguments& messageArguments)
    {
        // Get from the message arguments the node that the user pans.
        Node2DSharedPtr node2d = dynamic_pointer_cast<Node2D>(messageArguments.getSource());

        if (!node2d)
        {
            return;
        }

        // Get the distance in pixels that the pan has progressed
        // since the last message in the pan gesture sequence.
        Vector2 translationDelta = messageArguments.getDelta();

        // Get the Render Transformation property of the node.
        SRTValue2D nodeTransform = node2d->getRenderTransformation();

        // Get the current translation of the node.
        Vector2 translation = nodeTransform.getTranslation();

        // Apply the translation from the pan message.
        Vector2 translationTarget = translation + translationDelta;

        // Set the new translation.
        nodeTransform.setTranslation(translationTarget);

        // Apply the new transform to the node.
        node2d->setRenderTransformation(nodeTransform);
    }

在 Application::onProjectLoaded 函数中订阅 PanManipulator 消息。

例如，添加：

void onProjectLoaded() override
{
    ScreenSharedPtr screen = getScreen();

    // Get the PanNode node using its alias.
    NodeSharedPtr panNode = screen->lookupNode<Node>("#PanNode");

    // Subscribe to the PanManipulator::StartedMessage message at the PanNode node.
    // The PanManipulator generates this message when the user starts to drag a finger on the attached node and
    // the pan recognizition treshold is exceeded.
    panNode->addMessageHandler(PanManipulator::StartedMessage, bind(&MyProject::onPanStarted, this, placeholders::_1));

    // Subscribe to the PanManipulator::MovedMessage message at the PanNode node.
    // The PanManipulator generates this message when the user continues to drag a finger on the attached node.
    panNode->addMessageHandler(PanManipulator::MovedMessage, bind(&MyProject::onPanMoved, this, placeholders::_1));
}

构建并运行您的应用程序。请参阅部署 Kanzi 应用程序。

在应用程序中点击并拖动已启用平移手势的节点。

使用 Pan Manipulator 触发器¶

使用 Pan Manipulator 触发器对平移手势做出反应。例如，您可以在用户平移该节点时设置节点的外观。

Pan Manipulator 具有以下触发器：

当用户点击一个节点但尚未拖动该节点时，Pan Started 触发器被激活。
当用户使用平移手势移动节点时，Pan Moved 触发器被激活。
当用户通过释放鼠标按钮结束平移手势时，Pan Finished 触发器被激活。
当在平移手势期间焦点移出节点时，Pan Canceled 触发器被激活。
当平移手势进入节点时，Pan Entered 触发器被激活。
当平移手势离开节点时，Pan Left 触发器被触发。

要使用 Pan Manipulator 触发器：

为节点启用平移手势。请参阅为节点启用平移手势。
定义您想通过 Pan Manipulator 触发器设置的行为。

例如，创建一个状态管理器，在其中定义状态，以在 Pan Started、Pan Moved 和 Pan Finished 触发器被触发时设置节点的外观。请参阅创建状态机。
添加和配置 Pan Manipulator 触发器：
1. 在 Node Tree 中选择您要添加触发器的节点，并在 Node Components > Triggers 中添加一个 Pan Manipulator 触发器。
  
  例如：在 Node Tree 中，选择您为其启用了平移手势的节点，在 Node Components 按 Alt 并右键单击 Triggers 中，选择 Message Trigger > Pan > Pan Started。
2. 在您上一步创建的触发器中，禁用 Set Message Handled 属性。
  
  当您禁用 Set Message Handled 属性时，此触发器会拦截消息，但不会停止它。这样，您可以让输入操控器处理该消息。
3. 在 Node Components 按 Alt 并右键单击中，选择您创建的触发器，选择一个操作，并进行配置。
  
  例如，选择 Dispatch Message Action > State Manager > Go to State，然后在操作集中：
  - 将 Target Item 到您启用平移手势的节点。
  - State 到设置节点外观的状态，当 Pan Started 触发器被触发时。
重复上一步，以添加并配置更多 Pan Manipulator 触发器。

例如，添加 Pan Moved 和 Pan Finished 触发器。

在每个触发器的 Go to State 操作中，将 State 设置为当该触发器被触发时设置节点外观的状态。
选择 File > Export > Export KZB。
构建并运行您的应用程序。请参阅部署 Kanzi 应用程序。

在应用程序中点击并拖动已启用平移手势的节点。

另请参阅¶