導入ガイド

概要

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

デプロイ

各種Qt Virtual Keyboard プラグインおよびファイルは、以下の場所に配置されます。

依存関係

詳細は「Qt ライブラリのデプロイ」を参照してください。

統合方法

Qt Virtual Keyboard 現在、このプラグインを使用するための 2 つの統合方法がサポートされています：

• 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 の使用

このセクションでは、Fancy Compositor サンプルをコンポジターとして使用し、Qt Virtual Keyboard を用いて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_IM_MODULE の値の末尾（コロン「:」の後に）を追加することで指定できます。例：QT_IM_MODULE=qtvirtualkeyboard:wordCandidateListVisible 。一部のパラメータは、"=" で区切られたキーと値のペアです。

環境変数

このモジュールによって定義されている環境変数はいくつかあり、以下に挙げます：