部署指南

概览

本文档描述了如何在 Qt 应用程序中部署和使用 Qt 虚拟键盘插件。

部署

各种 Qt 虚拟键盘插件和文件部署在以下位置

依赖项

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

集成方法

Qt 虚拟键盘目前支持两种不同的集成方法来使用此插件

• Desktop: 无需修改现有应用程序。虚拟键盘可供系统中的所有 Qt 应用使用。

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

• Application: 通过在 QML 中实例化一个 InputPanel 元素将其嵌入到 Qt 应用程序本身中。

  在没有多顶层窗口支持的环境中（如嵌入式设备），此方法是强制性的，但也可以用于桌面应用程序。

  此方法还可以由 Qt Wayland 合成器使用，以提供服务器端虚拟键盘。有关详细信息，请参阅下文部分。

集成方法由项目文件自动选择。然而，在桌面环境中，可以通过使用环境变量 QT_VIRTUALKEYBOARD_DESKTOP_DISABLE 覆盖桌面集成方法，或者通过将 -no-vkb-desktop 添加到 configure 命令行，来使用应用程序集成方法。

使用 Qt Wayland 与 Qt 虚拟键盘

本节解释如何使用 Qt 虚拟键盘与Qt Widgets Line Edits 示例以及使用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 虚拟键盘的输入面板将打开。

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

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 虚拟键盘所必需的。在应用程序集成方法中，应用程序需要根据下列章节中的说明创建一个 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
    }
}

输入面板必须是应用程序容器旁边的兄弟元素。重要的一点是不将输入面板放在应用程序容器中，否则它会与应用程序的内容重叠。另外，输入面板的高度将自动根据可用的宽度更新；输入面板的宽高比是恒定的。

环境变量

以下列出了由模块定义的几个环境变量