部署指南

概述

本文档介绍了如何在 Qt 应用程序中部署和使用Qt Virtual Keyboard 插件。

部署

各种Qt Virtual Keyboard 插件和文件部署在以下位置：

依赖项

更多信息请参阅《部署 Qt 库》。

集成方法

Qt Virtual Keyboard 目前支持两种使用该插件的集成方法：

• Desktop：无需对现有应用程序进行任何修改。系统中的所有 Qt 应用程序均可使用 Qt Virtual Keyboard。

  在此集成方法中，键盘将显示在专用的顶级窗口中。

• Application：通过在 QML 中实例化一个 `InputPanel ` 控件，将虚拟键盘嵌入到 Qt 应用程序本身中。

  在不支持多个顶级窗口的环境（如嵌入式设备）中，此方法是必需的，但在桌面应用程序中也可以使用。

  Qt Wayland Compositor也可以使用此方法来提供服务器端的虚拟键盘。详情请参见下文。

集成方式由项目文件自动选择。但在桌面环境中，可以通过设置QT_VIRTUALKEYBOARD_DESKTOP_DISABLE 环境变量，或在configure 命令行中添加-no-vkb-desktop ，来覆盖桌面集成方式并改用应用程序集成方式。

在 Qt Wayland 中使用Qt Virtual Keyboard

本节介绍如何使用Qt Virtual Keyboard 与Qt Widgets 中的“行编辑”示例进行交互，并以“Fancy Compositor”示例作为合成器。

我们将使用 Ubuntu 18.04 运行该示例，并采用 X11 作为窗口系统。示例合成器（fancy-compositor ）将在 X11 会话中作为窗口打开。

1. 启动合成器：

   QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_CLIENT_BUFFER_INTEGRATION=xcomposite-egl \
   QT_IM_MODULE=qtvirtualkeyboard ./fancy-compositor -platform xcb

2. 在运行客户端应用程序之前，请确保未设置 QT_IM_MODULE：

   unset QT_IM_MODULE

3. 以客户端身份启动“Line Edits”示例：

   ./lineedits -platform wayland

4. 点击一个行编辑框，Qt Virtual Keyboard 的输入面板将打开。

如果遇到问题，可以在运行合成器时设置以下环境变量，以获取有助于诊断问题的调试输出：

WAYLAND_DEBUG=1
QT_LOGGING_RULES="qt.virtualkeyboard=true;qt.qpa.wayland*=true"

加载插件

在两种集成方法中，应用程序都必须使用QT_IM_MODULE 环境变量来加载插件。例如：

$ QT_IM_MODULE=qtvirtualkeyboard myapp

或在 main() 函数中：

qputenv("QT_IM_MODULE", QByteArray("qtvirtualkeyboard"));

在桌面集成方法中，仅需此步骤即可使用Qt Virtual Keyboard 。而在应用程序集成方法中，应用程序需要按照下一章的说明创建InputPanel 的实例。

创建 InputPanel

以下示例演示了如何创建InputPanel 以及如何与应用程序容器划分屏幕区域。

import QtQuick
import QtQuick.VirtualKeyboard

Item {
    id: root
    Item {
        id: appContainer
        anchors.left: parent.left
        anchors.top: parent.top
        anchors.right: parent.right
        anchors.bottom: inputPanel.top
        ...
    }
    InputPanel {
        id: inputPanel
        y: Qt.inputMethod.visible ? parent.height - inputPanel.height : parent.height
        anchors.left: parent.left
        anchors.right: parent.right
    }
}

输入面板必须作为应用容器的同级元素紧邻其旁。请务必不要将输入面板放置在应用容器内部，否则会与应用程序的内容重叠。此外，输入面板的高度会根据可用宽度自动调整；其宽高比保持恒定。

插件参数

某些参数可通过将其附加到QT_IM_MODULE 的值后（紧跟冒号）来指定，例如QT_IM_MODULE=qtvirtualkeyboard:wordCandidateListVisible 。部分参数为以"=" 分隔的键值对。

环境变量

该模块定义了以下几个环境变量：