使用 Long-Press Manipulator

使用 Long-Press Manipulator 使用户能够在您的 Kanzi 应用程序中长按节点。

这样可以让应用程序在用户于节点上按下指针并按住达到您在 Long-Press Manipulator 中设定的时长时做出响应。

例如，使用 Long-Press Manipulator 打开上下文菜单。请参阅 为节点启用长按手势。

您可以使用以下方式响应长按手势：

• Long-Press Manipulator 在 Kanzi Studio 中触发。请参阅 使用 Long-Press Manipulator 触发器。

• Kanzi Engine API。请参阅 使用 Kanzi Engine API 对长按手势作出反应。。

Long-Press Manipulator 是您可以用来在 Kanzi 应用程序中的节点添加手势识别的输入操控器之一。请参阅 使用输入操纵器。

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

为节点启用长按手势

本节介绍了如何为任意节点启用长按手势。要为 Button 节点启用长按，请参阅 使用 Button 触发器。

要为节点启用长按手势：

1. 在 Node Tree 中创建一个您想启用长按手势的节点。

   例如，创建一个 Empty Node 2D 节点，将其命名为 LongPressNode，并向该节点添加内容。

   

2. 在 Node Tree 中选择您在上一步中创建的节点，在 Properties 中添加 Input > Hit Testable 属性，并将其设置为启用。

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

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

   请参阅 定义哪个节点接收输入。

   

3. 在 Node Components 按 Alt 并右键单击 Input Manipulators 中，选择 Long-Press Manipulator。

   通过这种方式，您可以使 LongPressNode 节点对长按手势做出反应。通过向节点添加 Long-Press Manipulator 组件，您可以在该节点上安装 LongPressManipulator。

   在 Long-Press Manipulator 组件中，使用 Long Press Duration 属性设置用户必须按住节点的时间（以毫秒为单位），以便 LongPressManipulator 识别长按手势。

   

4. 使用 Long-Press Manipulator 触发器来响应长按手势。例如，您可以在用户点击并按住该节点的时间达到该触发器中设置的时间时，更改节点的外观。

   请参阅 使用 Long-Press Manipulator 触发器。

使用 Long-Press Manipulator 触发器

使用 Long-Press Manipulator 触发器来响应长按手势。例如，您可以在用户点击并按住该节点的时间达到该触发器中设置的时间时，更改节点的外观。

Long-Press Manipulator 具有以下触发器：

• 当用户在节点区域按下并按住节点 500 毫秒或该节点中 Long-Press Manipulator 的 Long Press Duration 属性设置的毫秒数时，Long Press 触发器被触发。

• 当在长按手势期间焦点移出节点时，Long Press Cancel 触发器被触发。

要使用 Long-Press Manipulator 触发器：

1. 为节点启用长按手势。请参阅 为节点启用长按手势。

2. 定义您想通过 Long-Press Manipulator 触发器设置的行为。

   例如，创建状态机，您可以定义状态以设置节点在 Long Press 和 Long Press Cancel 触发器被触发时的外观。请参阅 创建状态机。

3. 添加和配置 Long-Press Manipulator 触发器：

   1. 在 Node Tree 中选择您要添加触发器的节点，然后在 Node Components > Triggers 中添加一个 Long-Press Manipulator 触发器。

      例如：在 Node Tree 中，选择您为其启用长按手势的节点，在 Node Components 按 Alt 并右键单击 Triggers 中，选择 Message Trigger > Long Press > Long Press。

      

   2. 在您上一步创建的触发器中，禁用 Set Message Handled 属性。

      当您禁用 Set Message Handled 属性时，此触发器会拦截消息，但不会停止它。这样，您可以让输入操控器处理该消息。

      

   3. 在 Node Components 按 Alt 并右键单击 中，选择您创建的触发器，选择一个操作，并进行配置。

      例如，选择 Dispatch Message Action > State Manager > Next State，并在操作集中：

      • Target Item 到使用您创建的状态管理器来设置节点外观的节点，当 Long Press 触发器被重复触发时。

      • 将 State Group 到包含您要在 Long Press 触发器触发时切换的状态的状态组中。

      

使用 Kanzi Engine API 对长按手势作出反应。

您可以在应用程序代码中定义应用程序如何响应长按手势。

要使用 Kanzi Engine API 响应长按手势：

1. 在 Kanzi Studio 中，使用 Application 模板创建一个项目。

   

2. 为节点启用长按手势。请参阅 为节点启用长按手势。

   当您在 Kanzi Studio 中为节点启用长按手势时，您会在该节点中创建一个 LongPressManipulatorComponent，它会在节点上安装一个 LongPressManipulator。

3. 在 Node Tree 按 Alt 并右键单击 中，创建的节点并选择 Alias。

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

   使用 # 符号后跟别名名称访问别名目标节点。

   

4. 选择 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 文件和配置文件。

   

5. 在 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 启动。

6. 在 <ProjectName>/Application 目录中的 Kanzi Command Prompt 中，运行生成应用程序的 Visual Studio 解决方案的脚本。

   generate_cmake_vs2022_solution.bat
   

   此脚本会在 <ProjectName>/Application/build_vs2022 目录中为应用程序生成 Visual Studio 解决方案。

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

   1. 为长按消息定义处理程序。

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

      private:
          // Define the handler for the LongPressManipulator::LongPressMessage message from the nodes
          // that have an input manipulator which generates the long-press message.
          void onLongPress(LongPressManipulator::LongPressMessageArguments&)
          {
              // Add the code that handles the long-press event.
          }
      

   2. 在 Application::onProjectLoaded 函数中订阅 LongPressManipulator 消息。

      例如，添加：

      void onProjectLoaded() override
      {
          ScreenSharedPtr screen = getScreen();
      
          // Get the LongPressNode node using its alias.
          NodeSharedPtr longPressNode = screen->lookupNode<Node>("#LongPressNode");
      
          // Subscribe to the LongPressManipulator::LongPressMessage message at the LongPressNode node.
          // The LongPressManipulator manipulator generates this message when the user presses the node
          // for the amount of milliseconds you set with the LongPressManipulator::setPressDuration function.
          longPressNode->addMessageHandler(LongPressManipulator::LongPressMessage, bind(&MyProject::onLongPress, this, placeholders::_1));
      }
      

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

   在应用程序中，按下您启用了长按手势的节点。应用程序执行您在 LongPressManipulator::LongPressMessage 消息的处理程序中定义的行为。

另请参阅

教程：平移、缩放、轻触

处理用户输入

使用 Click Manipulator

使用 Multi-Click Manipulator

部署 Kanzi 应用程序

使用触发器