配備ガイド

概要

このドキュメントでは、Qt Virtual Keyboard プラグインを Qt アプリケーションにデプロイして使用する方法について説明します。

配置

様々なQt Virtual Keyboard プラグインとファイルは以下の場所に配置されます:

項目デスクトップのインストールパスBoot2Qt のインストールパス
qtvirtualkeyboardplugin プラットフォーム入力コンテキストプラグイン<QT_INSTALL_PLUGINS>/platforminputcontexts/system/plugins/platforminputcontexts
qtvkbplugin QML プラグイン<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/system/qml/QtQuick/VirtualKeyboard
qtvkbcomponentsplugin QML プラグイン<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Components/system/qml/QtQuick/VirtualKeyboard/Components
qtvkblayoutsplugin QML プラグイン<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Layouts/system/qml/QtQuick/VirtualKeyboard/Layouts
qtvkbplugins プラグイン QML プラグイン<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Plugins/system/qml/QtQuick/VirtualKeyboard/Plugins
拡張 QML プラグイン<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Plugins/*/system/qml/QtQuick/VirtualKeyboard/Plugins/*
qtvkbsettingsplugin QML プラグイン<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Settings/system/qml/QtQuick/VirtualKeyboard/Settings
qtvkbstylesplugin QML プラグイン<QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Styles/system/qml/QtQuick/VirtualKeyboard/Styles
仮想キーボードデータ<QT_INSTALL_DATA>/qtvirtualkeyboard/system/qtvirtualkeyboard

依存関係

詳しくはQt のライブラリのデプロイ をご覧ください。

統合方法

Qt Virtual Keyboard Qtvkbstylesplugin では、プラグインを使用するために 2 つの統合方法をサポートしています:

  • Desktop既存のアプリケーションに変更を加える必要がありません。システム内のすべての Qt アプリケーションが仮想キーボードを利用できます。

    この統合方法では、キーボードは専用のトップレベルウィンドウに表示されます。

  • Applicationこの統合方法では、キーボードは専用のトップレベルウィンドウに表示されます。 : 仮想キーボードは Qt アプリケーションの中に埋め込まれ、QML のInputPanel アイテムをインスタンス化します。

    この方法は、複数のトップレベルウィンドウがサポートされていない環境(組み込み機器など)では必須ですが、デスクトップアプリケーションでも使用できます。

    また、このメソッドはQt Waylandコンポジタがサーバサイドの仮想キーボードを提供するために使用することもできます。詳細は以下のセクションを参照してください。

統合方法はプロジェクトファイルによって自動的に選択されます。しかしデスクトップ環境では、QT_VIRTUALKEYBOARD_DESKTOP_DISABLE 環境変数を使うか、configure コマンドラインに-no-vkb-desktop を追加することで、デスクトップ統合方式をオーバーライドし、代わりにアプリケーション統合方式を使うことができます。

Qt WaylandでQt Virtual Keyboard

このセクションでは、Qt Virtual Keyboard を使用して、コンポジターとしてFancy Compositor のサンプルを使用して、Qt Widgets Line Edits のサンプルと対話する方法を説明します。

ここでは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_virtualkeyboard_hunspell_data_pathHunspellデータファイルの場所を上書きします。

デフォルトの場所はQLibraryInfo::path(QLibraryInfo::DataPath) の値に依存します。 例えば、ソースからビルドされた Qt ライブラリの場合はqtbase/qtvirtualkeyboard/hunspell になります。

詳細については、「Hunspell Integration」を参照してください。

qt_virtualkeyboard_pinyin_dictionaryピンイン辞書の場所を上書きします。

デフォルトでは、辞書はプラグインのリソースにバンドルされています。

リソースをバンドルしないようにするには、Qt configureコマンドラインに-vkb-no-bundle-pinyinを追加します。このシナリオでは、デフォルトの場所はQLibraryInfo::path(QLibraryInfo::DataPath) の値に依存します。 例えば、ソースからビルドされた Qt ライブラリの場合は、qtbase/qtvirtualkeyboard/pinyin/dict_pinyin.dat になります。

qt_virtualkeyboard_cangjie_dictionaryCangjie辞書の場所を上書きします。

デフォルトでは、辞書はプラグインのリソースにバンドルされています。

リソースをバンドルしないようにするには、Qt configureコマンドラインに-vkb-no-bundle-tcimeを追加してください。このシナリオでは、デフォルトの場所はQLibraryInfo::path(QLibraryInfo::DataPath) の値に依存します。 例えば、ソースからビルドされたQtライブラリの場合は、qtbase/qtvirtualkeyboard/tcime/dict_cangjie.dat になります。

qt_virtualkeyboard_zhuyin_dictionaryZhuyin辞書の場所を上書きします。

デフォルトでは、辞書はプラグインのリソースにバンドルされています。

リソースのバンドルを無効にするには、Qt configureコマンドラインに-vkb-no-bundle-tcimeを追加します。このシナリオでは、デフォルトの場所はQLibraryInfo::path(QLibraryInfo::DataPath) の値に依存します。例えば、ソースからビルドされた Qt ライブラリの場合、qtbase/qtvirtualkeyboard/tcime/dict_zhuyin.dat になります。

qt_virtualkeyboard_phrase_dictionaryフレーズ辞書の場所を上書きします。

デフォルトでは、辞書はプラグインのリソースにバンドルされています。

リソースをバンドルしないようにするには、Qt configure コマンドラインに-vkb-no-bundle-tcimeを追加します。このシナリオでは、デフォルトの場所はQLibraryInfo::path(QLibraryInfo::DataPath) の値に依存します。例えば、ソースからビルドされた Qt ライブラリの場合、qtbase/qtvirtualkeyboard/tcime/dict_phrases.dat になります。

qt_virtualkeyboard_cerence_hwr_db_pathCerence Handwriting 手書きデータベースの場所を指定します。

Cerence Handwriting 手書きデータベースのデフォルトの検索場所は次のとおりです:

  • QT_VIRTUALKEYBOARD_CERENCE_HWR_DB_PATH
  • QLibraryInfo::location(QLibraryInfo::DataPath) + "/qtvirtualkeyboard/cerence/handwriting"
  • ":/qt-project.org/imports/QtQuick/VirtualKeyboard/Cerence/Handwriting"

環境変数には複数のパスを指定できます。複数のパスは、Windows ではセミコロンで区切られ、その他のオペレーティング システムではコロンで区切られます。

qt_virtualkeyboard_xt9_ldb_pathXT9データベースの場所を指定します。

LDB ファイルのデフォルトの検索場所は次のとおりです:

  • QT_VIRTUALKEYBOARD_XT9_LDB_PATH
  • QLibraryInfo::location(QLibraryInfo::DataPath) + "/qtvirtualkeyboard/cerence/xt9"
  • ":/qt-project.org/imports/QtQuick/VirtualKeyboard/Cerence/Xt9"

この環境変数を設定することで、追加の検索パスを指定できます。複数のパスは、Windowsではセミコロンで、他のOSではコロンで区切られる。

LDB ファイルは XT9 と Cerence Handwriting プラグイン間で共有されるため、この環境変数は両方のプラグインに影響します。

qt_virtualkeyboard_style仮想キーボードで使用するスタイルの場所を指定します。

これは QML でVirtualKeyboardSettings::styleName を設定するか、ビルド時に設定オプションを使って指定することもできます。

qt_virtualkeyboard_layout_path仮想キーボードで使うレイアウトの場所を指定します。
qt_virtualkeyboard_desktop_disableデスクトップ統合方式を無効にします。
qt_virtualkeyboard_force_events_without_focusテキスト入力にフォーカスがなくてもQt Virtual Keyboard にキーイベントを送ったり Shift キーを使えるようにする。

この変数を利用したいアプリケーションの実行環境で明示的に設定する必要があります。アプリケーション自体でqputenv() を使用するだけでは十分ではありません。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.