构建 Qt 虚拟键盘

概述

本文档描述了如何构建 Qt 虚拟键盘插件。

项目分为以下子项目

examples/virtualkeyboard/basic	Qt 虚拟键盘演示应用
src/components/	Qt 虚拟键盘组件 QML 插件 (QtQuick.VirtualKeyboard.Components)
src/plugin/	Qt 虚拟键盘平台输入上下文插件。此插件提供 QPlatformInputContext 接口，作为 QML 输入上下文和平台之间的一层。
src/plugins/	一个包含 Qt 虚拟键盘插件的目录 (QtQuick.VirtualKeyboard.Plugins)，它们实现了复杂数入方法，如 HunspellInputMethod。构建时间配置指定哪些插件在运行时构建和加载。
src/settings/	Qt 虚拟键盘设置 QML 插件 (QtQuick.VirtualKeyboard.Settings)。此插件为虚拟键盘提供应用可配置的设置。
src/styles/	Qt 虚拟键盘样式 QML 插件 (QtQuick.VirtualKeyboard.Styles)
src/virtualkeyboard/	Qt 虚拟键盘模块和 QML 插件。

配置选项

下表包含配置虚拟键盘功能的顶级选项。这些选项传递给 configure 工具。

选项	参数	描述	备注
-vkb-enable <code>[,<code>]*"	支持的语言代码或 'all'	启用指定的语言	可以使用此选项明确启用指定的语言。每个语言代码的格式为 language[_country]，其中 language 是小写，两位的 ISO 639 语言代码 country 是大写，两位的 ISO 3166 国家代码可以使用此选项定义所需的语言支持。虚拟键盘可以同时支持一种或多种语言。例如，`-vkb-enable de_DE,fi_FI` 启用对德语和芬兰语的支持。如果没有指定其他语言，虚拟键盘将自动包含所有受支持的语言。
-vkb-handwriting	[no\|example-hwr\|myscript-hwr\|cerence-hwr]	启用或禁用手写输入	此标志启用手写输入。默认情况下，如果插件放在正确的插件文件夹中，即使不使用此选项，引擎也会自动激活。但是，如果MyScript和Cerence SDK共存，则其中之一必须配置为[no\|myscript-hwr\|cerence-hwr]。需要显式启用example-hwr选项。这可以用于开发和测试目的。
[-no]-vkb-arrow-keynavigation		启用或禁用键盘的箭头键导航	允许使用箭头键和回车键控制键盘。此功能默认关闭。
-vkb-style	[标准\|复古]	选择虚拟键盘的样式	Qt虚拟键盘支持两种样式，即标准和复古。两种样式都将包含在软件包中，但此选项允许您更改内置的默认样式。
[-no]-vkb-cangjie		启用或禁用繁体中文的Cangjie输入法。	此选项启用或禁用繁体中文语言的Cangjie输入法。如果启用对繁体中文的支持，则默认启用输入法。
[-no]-vkb-zhuyin		启用或禁用繁体中文的Zhuyin输入法。	此选项启用或禁用繁体中文语言的Zhuyin输入法。如果启用对繁体中文的支持，则默认启用输入法。
[-no]-vkb-desktop		启用或禁用桌面集成	默认情况下，当目标环境为X11或Windows桌面时，将启用桌面集成。使用此选项可以禁用桌面集成。注意：对于嵌入式集成，如果InputPanel是通过应用程序实例化的，则无需显式使用此选项。如果应用程序在将焦点设置到输入字段之前创建了InputPanel，虚拟键盘将不会创建桌面输入面板。
[-no]-vkb-layouts		启用或禁用内置布局	默认情况下，虚拟键盘插件包含英语键盘布局。通过指定 -no-vkb-layouts，内置布局将从虚拟键盘插件中排除。注意：在这种情况下，运行应用程序之前应在文件系统目录中设置 `QT_VIRTUALKEYBOARD_LAYOUT_PATH` 环境变量，该目录包含自定义键盘布局。
-vkb-hunspell	[no\|3rdparty\|system]	选择Hunspell集成方式	强制将Hunspell集成方法指定为指定选项。 3rdparty 选项选择使用虚拟键盘库中的项目文件本地构建的Hunspell源代码。此选项要求将Hunspell git存储库克隆到src/plugins/hunspell/3rdparty/hunspell目录。 system 选项通过 pkg-config 选择系统软件包。 no 选项禁用Hunspell插件。
-vkb-no-bundle-pinyin	n/a	禁用拼音资源的捆绑	此选项将从插件二进制文件中排除拼音资源。此选项可用于减小插件二进制文件的大小。
-vkb-no-bundle-tcime	n/a	禁用tcime资源的捆绑	此选项将从插件二进制文件中排除tcime资源。此选项可用于减小插件二进制文件的大小。
-vkb-cerence-sdk	path/to/cerence/sdk	配置Cerence SDK的位置并启用Cerence手写和XT9集成。	Cerence SDK zip文件必须使用src/plugins/cerence/unpack.py脚本解压缩。默认情况下，SDK解压缩到src/plugins/cerence/sdk目录，其中构建脚本可以自动捡取。但是，通过使用unpack.py脚本的第二个参数，可以使用不同的SDK位置。在这种情况下，必须使用-vkb-cerence-sdk命令行参数将位置传递给构建脚本。
-vkb-cerence-static	handwriting	启用Cerence手写引擎的静态链接。	Cerence手写引擎默认为动态链接。使用 -vkb-cerence-static 来强制静态链接。
-vkb-bundle-cerence-hwr 或 -vkb-bundle-cerence	n/a	启用捆绑Cerence手写资源	此选项将Cerence手写资源捆绑到插件二进制文件中。
-vkb-bundle-xt9 或 -vkb-bundle-cerence	n/a	启用捆绑XT9资源	此选项将XT9资源捆绑到插件二进制文件中。
-vkb-myscript-sdk	path/to/myscript/sdk	配置MyScript Text SDK位置并启用MyScript手写集成。	已解压到src/plugins/myscript/sdk的MyScript Text SDK (zip)，可由构建脚本自动获取。但是，SDK可以放置在不同的位置。在这种情况下，必须使用`-vkb-myscript-sdk`命令行参数将位置传递给构建脚本。
-vkb-myscript-arch	[x86\|x64\|armv7hf\|armv7\|arm64]	配置目标CPU架构	MyScript Text SDK为不同的CPU架构提供共享（动态）库 - [x86\|x64\|armv7hf\|armv7\|arm64]适用于Linux和[x86\|x64]适用于Windows。它可以自动配置。但是，用户也可以使用`-vkb-myscript-arch`命令行参数指定目标CPU架构。

Hunspell集成

默认情况下，除非找到Hunspell库和开发头文件，否则HunspellInputMethod将不可用。对于Linux/X11目标，可以通过安装libhunspell-dev软件包来提供Hunspell库。或者，可以将Hunspell git仓库克隆到src/plugins/hunspell/3rdparty/hunspell目录。qmake将自动检测源代码，项目将配置为使用本地的Hunspell。如果使用Hunspell源代码，则字典文件也必须复制到src/plugins/hunspell/3rdparty/hunspell/data目录。

设置Hunspell源代码和字典文件后目录结构应如下所示

3rdparty
└── hunspell
    ├── data
    │   ├── en_GB.aff
    │   └── en_GB.dic
    ├── hunspell <-- Hunspell git repository
    └── CMakeLists.txt

Cerence手写集成

Cerence手写集成支持字母和CJK（中文、日文、韩文）引擎。两个引擎都通过T9WriteInputMethod进行集成。输入法每次初始化一个引擎。引擎选择基于当前输入区域自动进行。

Cerence手写兼容性

Qt虚拟键盘与Cerence手写v8.7或更高版本兼容。

Cerence手写构建准备

SDK内容必须使用位于cerence目录中的unpack.py脚本来解压。这确保了CMake可以找到内容所需的正确目录结构。

$ cd src/plugins/cerence/
$ python unpack.py filename.zip

这将在src/plugins/cerence/sdk目录中解压缩内容，该目录可以自动由CMake获取。

或者，您可以通过向命令行添加额外的参数将内容解压缩到任何其他目录。在这种情况下，必须将SDK位置传递给configure脚本。

configure ... -vkb-cerence-sdk /path/to/cerence/sdk

Cerence SDK布局

SDK解压内容看起来像这样

sdk
├───t9write
│   ├───api
│   ├───data
│   │   ├───arabic
│   │   ├───hebrew
│   │   └───thai
│   └───lib
│       ├───linux
│       │   ├───arm64
│       │   │   ├───shared
│       │   │   │   ├───alphabetic
│       │   │   │   └───cjk
│       │   │   └───static
│       │   │       ├───alphabetic
│       │   │       └───cjk
│       │   └───x86_64
│       │       ├───shared
│       │       │   ├───alphabetic
│       │       │   └───cjk
│       │       └───static
│       │           ├───alphabetic
│       │           └───cjk
│       └───win32
│           ├───x86
│           │   ├───shared
│           │   │   ├───alphabetic
│           │   │   └───cjk
│           │   └───static
│           │       ├───alphabetic
│           │       └───cjk
│           └───x86_64
│               ├───shared
│               │   ├───alphabetic
│               │   └───cjk
│               └───static
│                   ├───alphabetic
│                   └───cjk
└───xt9
    ├───api
    ├───data
    └───lib
        ├───linux
        │   ├───arm64
        │   │   ├───shared
        │   │   └───static
        │   └───x86_64
        │       ├───shared
        │       └───static
        └───win32
            ├───x86
            │   ├───shared
            │   └───static
            └───x86_64
                ├───shared
                └───static

其中每个目录的内容如下

目录	描述	备注
api	此目录应包含所有API文件	API文件通常位于SDK的“api”和“public”目录中，有时位于“demo”目录中。当同时使用字母和CJK引擎时，可以从任一SDK复制任何重叠的文件。
data	此目录应包含所有HWR数据库，以及可选的XT9数据库。	Cerence手写字母的HWR数据库 _databas_le.bin Cerence 手写 CJK 数据库 cjk_HK_std_le.hdb 香港中文 cjk_J_std_le.hdb 日文 cjk_K_mkt_le.hdb 韩文 cjk_S_gb18030_le.hdb 简体中文 cjk_T_std_le.hdb 繁体中文语言数据库文件扩展名是 .ldb 或 .phd
lib/<target>/<linkage>/<engine-variant>	包含支持的构建目标目录结构	这些目录应包含所需的目标库。如果找到共享库和静态库，则优先选择共享库。

描述

备注

api

此目录应包含所有API文件

API文件通常位于SDK的“api”和“public”目录中，有时位于“demo”目录中。

当同时使用字母和CJK引擎时，可以从任一SDK复制任何重叠的文件。

data

此目录应包含所有HWR数据库，以及可选的XT9数据库。

Cerence手写字母的HWR数据库

_databas_le.bin

Cerence 手写 CJK 数据库

cjk_HK_std_le.hdb 香港中文
cjk_J_std_le.hdb 日文
cjk_K_mkt_le.hdb 韩文
cjk_S_gb18030_le.hdb 简体中文
cjk_T_std_le.hdb 繁体中文

语言数据库

文件扩展名是 .ldb 或 .phd

lib/<target>/<linkage>/<engine-variant>

包含支持的构建目标目录结构

这些目录应包含所需的目标库。如果找到共享库和静态库，则优先选择共享库。

当检测到 Cerence SDK 时，将自动激活 Cerence 手写和 XT9 集成代码。

在构建 Cerence 扩展之前，应从 [qtbase]/plugins/virtualkeyboard 目录中清除所有其他扩展，以避免运行时的冲突行为。Cerence 扩展不需要任何其他虚拟键盘插件即可运行。

XT9 的手写数据库和语言数据库安装在 [qtbase]/qtvirtualkeyboard/cerence 目录中。此外，还有两种定位这些文件的其他方法

由环境变量定义的定制运行时位置
将资源嵌入插件二进制的 -vkb-bundle-cerence 命令行选项

MyScript Text SDK 集成

MyScript Text 设计用于构建启用手写文本识别的应用程序。MyScript Text 支持孤立字符、草书、印刷和叠加书写。MyScript 叠加书写集成到 Qt 虚拟键盘。它能够识别写在一行上的字母、单词或单词的一部分，无需连续片段之间的任何明确定义。它在内存和 CPU 约束的设备上能够运行。

MyScript Text SDK 输入手写风格

最终用户可以像下面描述的那样，一个单词片段覆盖另一个单词片段，或者一个字符覆盖另一个字符。两个写出的单词之间的空间会自动添加，因此不需要任何明确定义的手势。

在字符上书写

在单词片段上书写

MyScript Text SDK 的语言覆盖范围

MyScript Superimposed 支持 72 种语言。

MyScript Text SDK 软件包安装

MyScript 配送团队可以为您提供带有各种 .zip 存档的软件包。要访问构建自己的手写应用程序所需的全部代码、工具和资源，请将所有软件包提取到与 src/plugins/myscript/sdk 相同的目标文件夹中，CMake 可以自动获取这些软件包。

或者，您可以将软件包提取到任何其他目录中。在这种情况下，必须将 SDK 的位置传递给 configure 脚本。

configure ... -vkb-myscript-sdk /path/to/myscript/sdk

文件层次结构应如下所示

myscript
└── sdk
    ├─── conf
    ├─── doc
    ├─── edk
    ├─── engine
    │   └─── bin
    │       ├─── lin-arm64
    │       │   └─── *.so
    │       ├─── lin-armv7
    │       │   └─── *.so
    │       ├─── lin-armv7hf
    │       │   └─── *.so
    │       ├─── lin-x64
    │       │   └─── *.so
    │       ├─── lin-x86
    │       │   └─── *.so
    │       ├─── win-x64
    │       │   └─── *.dll
    │       ├─── win-x86
    │       │   └─── *.dll
    │       (etc.)
    ├─── rdk
    ├─── resources
    │   ├─── ar
    │   │   └─── *.res
    │   ├─── en_GB
    │   │   └─── *.res
    │   ├─── ja_JP
    │   │   └─── *.res
    │   ├─── ko_KR
    │   │   └─── *.res
    │   ├─── zh_CN
    │   │   └─── *.res
    │   (etc.)
    ├─── tools
    └─── voim
        ├─── api
        ├─── bin
        │   ├─── lin-arm64
        │   │   └─── *.so
        │   ├─── lin-armv7
        │   │   └─── *.so
        │   ├─── lin-armv7hf
        │   │   └─── *.so
        │   ├─── lin-x64
        │   │   └─── *.so
        │   ├─── lin-x86
        │   │   └─── *.so
        │   ├─── win-x64
        │   │   └─── *.dll
        │   ├─── win-x86
        │   │   └─── *.dll
        │   (etc.)
        └─── conf

每个目录的内容描述如下

目录	描述
conf	包含引擎用来配置语言资源的语言配置文件。
doc	包含 HTML 文档文件。文件 `index.html` 显示主页面。
edk	包含引擎开发工具包和为每个受支持的编程语言 API 提供的手写编程元素，包括代码示例。
engine	包含每个引擎对象的库，根据目标平台，可能是 SO、A 或 DLL。
rdk	包含资源开发工具包，即创建自定义资源的工具和示例。
resources	包含带 /c .res 扩展名的资源文件。它们是不同 MyScript 技术在运行时用于执行各种识别任务的二进制资产。
tools	包含有用的程序员工具，包括墨迹测试的 InkTool。
voim	包含MyScript文本输入法的库。它是对MyScript文本识别系统的扩展SDK，旨在简单快速地构建使用手写识别功能的输入法。

设置MyScript文本SDK证书

有效的证书是使用MyScript文本SDK的必备条件。这是确保您作为MyScript技术合法客户的唯一安全措施。证书帮助MyScript追踪客户的身份和已购买的产品。

证书以[your_login].vo.zip包的形式提供。解压此包后，证书将自动放置在合适的位置。这确保了证书立即在你的服务和提供的代码示例中生效。

如何使用MyScript文本SDK构建Qt虚拟键盘

检测到MyScript文本SDK时，MyScript集成代码会自动激活。

MyScript文本SDK的语言资源安装在了[qtbase]/qtvirtualkeyboard/myscript目录中。

静态构建

虚拟键盘可以构建并静态链接到应用程序。这意味着Qt也会以静态方式构建（在配置命令行中使用静态选项 -static）。