Qt Virtual Keyboard 概要

機能

Qt Virtual Keyboard の主な機能は以下の通りです：

• 動的な切り替えが可能な、カスタマイズ可能なキーボードレイアウトとスタイル。
• 単語選択機能付き予測入力。
• 文字のプレビューおよび代替文字の表示。
• 大文字への自動変換およびスペースの自動挿入。
• さまざまな解像度への対応。
• さまざまな文字セット（ラテン文字、簡体字・繁体字中国語、ヒンディー語、日本語、アラビア語、ヘブライ語、韓国語など）に対応。
• 最も一般的な入力言語に対応しており、言語サポートを簡単に拡張可能。
• 左から右、および右から左への入力に対応。
• 2方向および5方向のナビゲーションに対応したハードウェアキーのサポート。
• 手書き入力のサポート、およびフルスクリーン入力用のジェスチャー。
• 音声フィードバック。
• クロスプラットフォーム機能。
• Qt Quick およびQt Widgets アプリケーションの両方をサポート。

対応言語

仮想キーボードは、以下の言語に対応しています：

他の言語のサポートを追加するには、「新しいキーボードレイアウトの追加」を参照してください。

サードパーティ製プラグイン

Qt Virtual Keyboard は、以下のベンダーが提供するサードパーティ製プラグインに対応しています:

• Cerence XT9アドバンスト入力。
• Cerence Handwritingテキスト入力。
• MyScriptText 手書き文字認識

『Qt Virtual Keyboard の構築』では、これらのプラグインをQt Virtual Keyboard に統合する方法について解説しています。

基本概念

Qt Virtual Keyboard プロジェクトは、QPlatformInputContextPlugin および QPlatformInputContext インターフェースを実装する Qt 入力コンテキストプラグインです。これらのインターフェースにより、このプラグインを Qt アプリケーション内のプラットフォーム入力コンテキストプラグインとして使用することができます。

プラグイン自体は、複数の入力方式をサポートする入力フレームワークと、仮想キーボード用のQML UIを提供します。この入力フレームワークはプラグインインターフェースを通じて拡張可能であり、これによりサードパーティ製の入力方式やキーボードレイアウトを実行時に読み込むことができます。

この入力フレームワークは、主に以下のインターフェースを提供します：

• QVirtualKeyboardInputContext: 仮想キーボードやその他の入力コンポーネントに関するコンテキスト情報を提供します。基盤となるテキスト入力コンポーネントへのインターフェースとして機能します。
• QVirtualKeyboardInputEngine: ユーザー入力イベント（キー押下など）を統合するためのAPIを公開し、入力メソッドのホストとして機能します。
• QVirtualKeyboardAbstractInputMethod: C++ベースの入力メソッドの基底型です。入力メソッドは通常、キーイベントを処理しますが、マウスやタッチ入力イベントも処理できます。
• InputMethod: QMLベースの入力メソッドの基底型です。入力メソッドは通常、キーイベントを処理しますが、マウスやタッチ入力のイベントも処理できます。

入力コンテキスト

入力コンテキストは、キーボードおよび具体的な入力メソッドによって使用されます。InputContext は、QMLによってホストされるシングルトンインスタンスです。アプリケーションは入力コンテキストと直接やり取りしてはなりません。

コンテキスト情報

入力コンテキストは、アプリケーションに由来するコンテキスト情報へのアクセスを提供します。この情報には、以下が含まれますが、これらに限定されません：

• InputContext::cursorPosition
• InputContext::cursorRectangle
• InputContext::inputMethodHints
• InputContext::preeditText
• InputContext::selectedText
• InputContext::surroundingText

ロケール

仮想キーボードエンジンは、layouts/ 内のロケール固有のレイアウトディレクトリから、サポートされるロケールのリストを生成します。各レイアウトディレクトリには、dialpad、digits、handwriting、main、numbers、およびsymbols の各レイアウトタイプに対する定義またはフォールバックが含まれている必要があります。定義は.qml ファイルで実装され、フォールバックは.fallback というファイル拡張子を持つプレースホルダーファイルで定義されます。layouts/ ディレクトリには、各レイアウトタイプの定義を含むfallback/ サブディレクトリが含まれている必要があります。

各レイアウトディレクトリには、1 つ以上のレイアウトタイプの定義を含めることができます。ロケール固有のレイアウトがフォールバックロケールのレイアウトと同じである場合は、<layout type>.fallback という名前のレイアウトのプレースホルダーファイルを追加することができます。これにより、仮想キーボードは代わりにフォールバックレイアウトを使用するようになります。

例えば、フィンランド語用のロケール固有のレイアウトを追加する場合、main.qml 内でメインのレイアウトタイプを定義します。その他のレイアウトタイプについては、フォールバック機構を採用します。layouts/ ツリーは次のようになります:

.
├── fallback
│   ├── dialpad.qml
│   ├── digits.qml
│   ├── handwriting.qml
│   ├── main.qml
│   ├── numbers.qml
│   └── symbols.qml
└── fi_FI
    ├── dialpad.fallback
    ├── digits.fallback
    ├── handwriting.fallback
    ├── main.qml
    ├── numbers.fallback
    └── symbols.fallback

layouts/fallback ディレクトリには、常に一連の完全な実装ファイルが含まれていることが不可欠です。

アプリケーションは、デフォルトのロケールを変更することで初期レイアウトを指定できます。ただし、これはアプリケーションが入力メソッドプラグインを初期化および読み込む前に実行する必要があります。デフォルトのロケールに変更がない場合は、現在のシステムロケールが使用されます。

キーボードロケールの対応は、以下の順序に従います：

• layouts/<language>_<country>
• layouts/<language>_*
• layouts/fallback – ここでのデフォルトのレイアウトはen_GB です。

まず、ロケールが完全なロケール名と照合されます。完全に一致するものがなければ、ロケールの言語のみが照合されます。最後に、部分的な一致もない場合、layouts/fallback の内容がフォールバックとして使用されます。

ロケールの選択が完了すると、キーボードは現在のレイアウトに合わせて入力ロケールと入力方向を更新します。アプリケーションは、QInputMethod インターフェースを通じてこの情報を受け取ることができます。

内部的には、現在の入力ロケールも `QVirtualKeyboardInputEngine ` および現在の入力メソッドインスタンスに対して更新されます。

入力エンジン

入力エンジンオブジェクトは、InputContext が所有しています。InputContext と同様に、QVirtualKeyboardInputEngine のインスタンスは 1 つだけです。入力エンジンには、キーの押下や離しイベントなどのユーザー操作を入力メソッドにマッピングするためにキーボードが使用する API 関数が含まれています。

たとえば、仮想キーボードのキーイベントは、以下のメソッドを通じてマッピングされます：

• QVirtualKeyboardInputEngine::virtualKeyPress
• QVirtualKeyboardInputEngine::virtualKeyRelease

上記のメソッドは仮想キーボードの統合を目的としているため、メソッド名に「virtual」という語が含まれています。これはまた、これらのメソッドが物理的なキーストロークのマッピングには適していないことを意味します。これは、実際のアクションがキーが離されたときにのみ実行されるという事実によるものです。

キーの押下イベントがキーの離しイベントの前に中断された場合、キーボードはQVirtualKeyboardInputEngine::virtualKeyCancel メソッドを呼び出します。

入力メソッド

入力メソッドは、キープレスハンドラの具体的な実装です。その主な機能は、キープレスイベントを処理し、ユーザー入力の状態情報を維持することです。入力メソッドは、QVirtualKeyboardInputContext を通じて、プレエディットテキストやキーイベントを介してテキストエディタとやり取りを行います。

入力メソッドのインスタンスは、ユースケースに応じてさまざまな方法で作成できます：

• KeyboardLayout::inputMethod: キーボードレイアウトは、そのキーボードレイアウト専用に入力メソッドのインスタンスを作成できます。ただし、このインスタンスはキーボードレイアウトが変更されると破棄される点に注意が必要です。そのため、この方法は通常、ごく限られたユースケースに限定されます。
• KeyboardLayout::createInputMethod(): キーボードレイアウトは、そのレイアウトおよびshared layouts で利用できる入力メソッドを動的に作成できます（例：記号レイアウト）。これは、複雑な言語や手書き入力を扱うような特殊な入力メソッドを作成する際に推奨される方法です。
• DefaultInputMethod: 仮想キーボードは、起動時にこのタイプの入力メソッドを作成しようとします。このインスタンスは、キーボードレイアウトがカスタム入力メソッドを使用していない限り、すべてのキーボードレイアウトにおいてデフォルトの入力メソッドとして使用されます。このインスタンスは、言語を跨ぐキーボードレイアウトの変更後も存続し、デフォルトの入力メソッドを作成および上書きするための推奨される方法です。

仮想キーボードプラグイン

仮想キーボードのsrc/pluginsディレクトリには、仮想キーボード用の既存のプラグインが含まれています。これらのプラグインは、QtQuick.VirtualKeyboard.Plugins QML モジュールによって暗黙的に読み込まれる標準的な QML モジュールです。

プラグインは、キーボードレイアウトや入力メソッド（通常は両方）を提供することができます。仮想キーボードで使用される入力メソッドは、どのキーボードレイアウトが使用されているかによって異なります。キーボードレイアウトは、KeyboardLayout.createInputMethod() 関数によってカスタム入力メソッドのインスタンスを提供することができます。そうでない場合は、仮想キーボードによって作成されたデフォルトの入力メソッド（DefaultInputMethod）が使用されます。

キーボードレイアウトの追加

プラグインは、プラグインバイナリの Qt リソースにレイアウトファイルを含めることで、Qt Virtual Keyboard用のキーボードレイアウトを追加できます。

Qt Virtual Keyboardは、特定のパス/qt-project.org/imports/QtQuick/VirtualKeyboard/Layouts/<LANGUAGE_COUNTRY> から（言語ごとの）キーボードレイアウトを検索するため、プラグイン内でもこの正確なパスを使用することが不可欠です。 Qt リソースのパスは重複する可能性があるため、プラグインは Virtual Keyboard 上の既存のレイアウトを上書きすることができます。

また、QT_VIRTUALKEYBOARD_LAYOUT_PATH環境変数を使用して、ファイルシステムから直接キーボードレイアウトを読み込むことで、組み込みのキーボードレイアウトを上書きすることも可能です。

入力メソッドの追加

プラグインは、他のキーボードレイアウトがデフォルトで使用できる入力メソッド（DefaultInputMethod など）や、プラグイン内で内部的に使用される入力メソッド（入力メソッドを作成するカスタムキーボードレイアウトも提供することで）を登録することができます。

入力メソッドは、QVirtualKeyboardAbstractInputMethod （C++）またはInputMethod （QML）インターフェースを実装している必要があり、プラグインによってQMLタイプ（QML_NAMED_ELEMENT ）として登録されている必要があります。

カスタム入力メソッドの実装

入力メソッドの実装は、QML インターフェースと C++ インターフェースのどちらを使用するかを決定することから始まります。この例では QML インターフェースを使用します。C++ インターフェースQVirtualKeyboardAbstractInputMethod についても、同様のロジックとインターフェースが適用されます。この場合、プラグインはVirtualKeyboardモジュールにリンクされている必要があります。

以下の例は、入力メソッドに必要とされる最低限の機能を示しています：

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

import QtQuick
import QtQuick.VirtualKeyboard as VKB

// file: CustomInputMethod.qml

VKB.InputMethod {
    function inputModes(locale) {
        return [VKB.InputEngine.InputMode.Latin];
    }

    function setInputMode(locale, inputMode) {
        return true
    }

    function setTextCase(textCase) {
        return true
    }

    function reset() {
        // TODO: reset the input method without modifying input context
    }

    function update() {
        // TODO: commit current state and update the input method
    }

    function keyEvent(key, text, modifiers) {
        var accept = false
        // TODO: Handle key and set accept or fallback to default processing
        return accept;
    }
}

InputMethod::inputModes() メソッドは、入力モードが設定される前に入力エンジンによって呼び出されます。このメソッドは、指定されたロケールで利用可能な入力モードのリストを返します。

入力メソッドは、InputMethod::setInputMode() メソッド内でロケールと入力モードを指定して初期化されます。ロケールと入力モードの設定後、入力メソッドは使用可能な状態になるはずです。

InputMethod::reset() は、入力メソッドをリセットする必要がある際に呼び出されます。リセットでは、入力メソッドの内部状態のみをリセットし、ユーザーの入力テキストはリセットしてはなりません。

InputMethod::update()は、入力コンテキストが更新され、入力状態が同期を失っている可能性がある場合に呼び出されます。入力メソッドは、現在のテキストをコミットする必要があります。

キーストロークイベントは、InputMethod::keyEvent() メソッドで処理されます。このメソッドは単一のキーストロークイベントを処理し、イベントが処理された場合はtrue を返します。そうでない場合、キーストロークはデフォルトの入力メソッドによって処理されます。

選択リスト

選択リストは、入力メソッドに統合できるオプション機能です。入力フレームワークは、単語候補リストなど、さまざまな種類のリストをサポートしています。 リストの実装における役割分担は、入力方式が内容やクリック時の動作などの処理を担当し、入力フレームワークがリストモデルの維持管理とユーザーインターフェースへの提供を担当するように定められています。

選択リストの割り当て

選択リストは、入力方式がアクティブ化された際に割り当てられます。InputMethod::selectionLists() メソッドは、必要な選択リストの型の一覧を返します。

function selectionLists() {
    return [SelectionListModel.Type.WordCandidateList];
}

上記の例では、入力メソッドは自身の使用のために単語候補リストを割り当てています。

選択リストの更新

入力メソッドがUIに対して選択リストの内容を更新するよう要求する場合、InputMethod::selectionListChanged シグナルを発行します。同様に、入力メソッドがUIに対してリスト内の項目をハイライトするよう要求する場合、InputMethod::selectionListActiveItemChanged シグナルを発行します。

selectionListChanged(SelectionListModel.Type.WordCandidateList)
selectionListActiveItemChanged(SelectionListModel.Type.WordCandidateList, wordIndex)

選択リストへの項目の設定

項目は、リスト内の項目数および個々の項目のデータを提供するメソッドコールバックによって設定されます。

InputMethod::selectionListItemCount コールバックは、指定された型で識別されるリスト内の項目数を要求します。

function selectionListItemCount(type) {
    if (type == SelectionListModel.Type.WordCandidateList) {
        return wordList.length
    }
    return 0
}

InputMethod::selectionListData コールバックは、項目のデータを要求します。

function selectionListData(type, index, role) {
    var result = null
    if (type == SelectionListModel.Type.WordCandidateList) {
        switch (role) {
        case SelectionListModel.Role.Display:
            result = wordList[index]
            break
        default:
            break
        }
    }
    return result
}

role パラメータは、アイテムに対してどのデータを要求するかを指定します。たとえば、SelectionListModel.Role.Display は、表示テキストデータを要求します。

ユーザー操作への対応

ユーザーがリスト内の項目を選択すると、入力メソッドは `InputMethod::selectionListItemSelected ` メソッドのコールバック内でそのイベントに応答します。

function selectionListItemSelected(type, index) {
    if (type == SelectionListModel.Type.WordCandidateList) {
        inputContext.commit(wordlist[index])
        update()
    }
}

手書き認識の統合

入力メソッドは、タッチスクリーンやその他の入力デバイスからの入力データを使用することもできます。

入力が開始されると、仮想キーボードは入力メソッド関数 ` traceBegin ` を呼び出し、この関数は入力メソッドに代わって入力が収集される新しい `Trace ` オブジェクトを返します。同様に、指やスタイラスを離すと、` traceEnd ` の呼び出しによってイベントが終了します。入力メソッドは収集されたデータを処理し、`InputContext ` インターフェースを使用してテキストを生成します。

手書き入力用の定義済みキーボードレイアウトが存在します。ただし、これらはデフォルトでは含まれていないため、手書きプラグインは独自のリソースにそれらを含める必要があります。その方法の例については、MyScriptやCerence の既存の手書きプラグインを参照してください。

手書き入力のデータモデル

仮想キーボードは、特別なデータモデルQVirtualKeyboardTrace を使用して手書きデータを収集します。各トレースは、1回のタッチ（例：画面上のスワイプ）からサンプリングされたデータの集合を表します。手書き入力領域でのタッチ数だけ、QVirtualKeyboardTrace のインスタンスが存在することになります。

定義上、トレースは1回のタッチからサンプリングされたデータの集合です。基本的なポイントデータに加え、各ポイントの時刻など、他の種類のデータも含まれる場合があります。入力メソッドは、トレースイベントの開始時に、必要な入力チャネルを定義できます。

入力メソッドは、トレースデータの実際の収集には関与しません。ただし、入力メソッドは「QVirtualKeyboardTrace 」を受け入れるか拒否するか（例：処理しきれないほど多くのインスタンスがある場合）を決定できるため、入力を完全に制御できます。これにより、同時に使用できる指の本数を正確に制御することも可能です。

入力メソッドは、適切と判断する数のトレースを収集でき、必要に応じてそれらの処理を開始できます。 データのサンプリングと並行して処理を実行することも可能ですが、パフォーマンス上の問題が生じる可能性があるため推奨されません。推奨される方法は、ユーザーインターフェースに悪影響を与えないよう、最後の入力から適切な遅延時間を置いた後にバックグラウンドスレッドで処理を開始することです。

入力メソッド用のトレース API

トレース API は、トレース入力データを受信および処理するために入力メソッドが実装しなければならない、以下の仮想メソッドで構成されています。

• patternRecognitionModes
• traceBegin
• traceEnd

これらのメソッドを実装することで、入力メソッドはさまざまな入力ソース（キーボードレイアウトやフルスクリーンなど）からのデータを受信し、処理できるようになります。

patternRecognitionModes メソッドは、入力メソッドがサポートするパターン認識モードのリストを返します。 Handwriting などのパターン認識モードは、入力メソッドがデータを処理する方法を定義します。

トレースのインタラクションは、入力ソースが新しい接触点を検出し、新しいトレースオブジェクトに対して traceBegin メソッドを呼び出したときに開始されます。入力メソッドがインタラクションを受け入れる場合、新しいトレースオブジェクトを作成し、それを呼び出し元に返します。この時点から、traceEnd メソッドが呼び出されるまでトレースデータが収集されます。

traceEndメソッドが呼び出されると、入力メソッドはトレースオブジェクトに含まれるデータの処理を開始できます。データの処理後、入力メソッドはオブジェクトを破棄する必要があります。これにより、画面に描画されていたトレースも削除されます。

キーボードレイアウト

キーボードレイアウトは、src/layouts/builtinディレクトリにあります。 レイアウトディレクトリの各サブディレクトリは、1つのロケールを表しています。ロケールディレクトリ名は「language_country」という形式の文字列で、ここで language は小文字の 2 文字の ISO 639 言語コード、country は大文字の 2 文字または 3 文字の ISO 3166 国コードです。

レイアウトの種類

入力モードごとに異なるキーボードレイアウトの種類が使用されます。通常のテキスト入力に使用されるデフォルトのレイアウトは、「main」レイアウトと呼ばれます。レイアウトの種類は、レイアウトファイル名によって決定されます。したがって、「main」レイアウトファイルは「main.qml」という名前になります。

サポートされているレイアウトタイプのリスト：

• main 通常のテキスト入力用のメインレイアウト
• symbols 特殊文字などのための記号レイアウト（メインレイアウトから有効化）
• numbers 書式付き数値用の数値レイアウト（Qt::ImhFormattedNumbersOnly で有効化）
• digits 数字専用レイアウト（Qt::ImhDigitsOnly で有効化）
• dialpad 電話番号入力用のダイヤルパッドレイアウト（Qt::ImhDialableCharactersOnly で有効化）
• handwriting 手書き認識用の手書きレイアウト（メインレイアウトから切り替え可能）

新しいキーボードレイアウトの追加

キーボードレイアウト要素は、KeyboardLayout QML タイプに基づいている必要があります。このタイプは、レイアウトのルートアイテムを定義します。ルートアイテムには、必要に応じて設定できる以下のオプションのプロパティがあります：

KeyboardRow 型を使用することで、キーボードレイアウトに新しい行を追加できます。KeyboardRow は、その子要素に対するデフォルトのキーウェイトを指定することもできます。指定しない場合、キーウェイトは親要素から継承されます。

新しいキーは、`Key` タイプまたは専用のキータイプのいずれかを使用して、キーボード行に追加されます。以下に、すべてのキータイプのリストを示します：

たとえば、入力方式にキーイベントを送信する通常のキーを追加するには：

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/main.qml

KeyboardLayout {
    keyWeight: 160
    KeyboardRow {
        Key {
            key: Qt.Key_Q
            text: "q"
        }
    }
}

キーサイズの計算

キーボードレイアウトはスケーラブルであるため、レイアウト内のどの項目に対しても固定サイズを設定することはできません。代わりに、キーの幅は各キーの重み（ウェイト）の相対的な関係に基づいて計算され、高さはキーボードの各行にスペースを均等に分割することで決定されます。

上記の例では、キーサイズは親要素から以下の順序で継承されます：

キー >KeyboardRow >KeyboardLayout

キーの重みに対する有効な値は 160 となります。例を挙げるために、カスタムなキーの重みを指定する別のキーを追加します：

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/main.qml

KeyboardLayout {
    keyWeight: 160
    KeyboardRow {
        Key {
            key: Qt.Key_Q
            text: "q"
        }
        Key {
            key: Qt.Key_W
            text: "w"
            keyWeight: 200
        }
    }
}

これで、行のキーウェイトの合計は160 + 200 = 360 となります。キーボードレイアウトが有効になると、個々のキーの幅は次のように計算されます：

キーの幅（ピクセル） = キーの重み / 行内のキーの重みの合計 × 行の幅（ピクセル）

つまり、キーボードは任意のサイズに拡大・縮小でき、キーの相対的なサイズは変化しません。

代替キー

キーには `alternativeKeys` プロパティを指定できます。これにより、ユーザーがキーを長押しすると、代替キーを一覧表示するポップアップが表示されます。`alternativeKeys` には、文字列または文字列のリストを指定できます。`alternativeKeys` が文字列の場合、ユーザーはその文字列に含まれる文字から選択できます。

スタイルとレイアウト

キーボードレイアウトでは視覚的な要素を指定することはできません。代わりに、レイアウトはキーボードスタイルによって視覚化されます。一方、キーボードスタイルはキーボードレイアウトのサイズに影響を与えることはできません。

複数のページにまたがるキーを持つキーボードレイアウト

記号レイアウトなど、一部のキーボードレイアウトには、単一のキーボードレイアウト上で表示するには多すぎる数のキーが含まれている場合があります。その解決策として、KeyboardLayoutLoader を使用して、複数のキーボードレイアウトを同じコンテキストに埋め込むことができます。

KeyboardLayoutLoader をキーボードレイアウトのルートアイテムとして使用する場合、実際のキーボードレイアウトはComponent要素で囲まれます。アクティブなコンポーネントのidをsourceComponentプロパティに割り当てることで、そのキーボードレイアウトが有効化されます。

例：

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/symbols.qml

KeyboardLayoutLoader {
    property bool secondPage
    onVisibleChanged: if (!visible) secondPage = false
    sourceComponent: secondPage ? page2 : page1
    Component {
        id: page1
        KeyboardLayout {
            KeyboardRow {
                Key {
                    displayText: "1/2"
                    functionKey: true
                    onClicked: secondPage = !secondPage
                }
            }
        }
    }
    Component {
        id: page2
        KeyboardLayout {
            KeyboardRow {
                Key {
                    displayText: "2/2"
                    functionKey: true
                    onClicked: secondPage = !secondPage
                }
            }
        }
    }
}

手書き入力キーボードレイアウト

手書き認識をサポートする各言語では、「handwriting.qml」という名前の特別なキーボードレイアウトを提供する必要があります。

この種のキーボードレイアウトは、以下の要件を満たす必要があります：

• キーボードレイアウト内にTraceInputKey を含むこと
• 入力方式として HandwritingInputMethod のインスタンスを提供すること。

手書きレイアウトには、ChangeLanguageKey を含めることもできます。この目的のためには、customLayoutsOnly 属性を使用することが重要です。これにより、手書きを使用しない言語が除外されます。

メインレイアウトと手書きレイアウトの両方に、手書き入力モードを有効または無効にするキーを含める必要があります。これは、レイアウトにHandwritingModeKey を追加することで実現できます。

カスタムレイアウトの追加

仮想キーボードのレイアウトシステムは、組み込みのレイアウトだけでなく、カスタムレイアウトもサポートしています。組み込みのレイアウトは、Qtリソースとしてプラグインバイナリに埋め込まれています。カスタムレイアウトはファイルシステム上に配置されるため、仮想キーボード自体を再コンパイルすることなくインストールできます。また、リソースファイル内に配置することも可能です。

実行時のレイアウトの選択は、QT_VIRTUALKEYBOARD_LAYOUT_PATH 環境変数によって制御されます。

この環境変数が設定されていない場合、または無効なディレクトリが指定されている場合、仮想キーボードはデフォルトの組み込みレイアウトを使用します。

カスタムレイアウトを使用する際に、組み込みレイアウトが仮想キーボードプラグインに組み込まれるのを防ぐには、configure スクリプトに-no-vkb-layouts オプションを追加してください。詳細については、「設定オプション」を参照してください。

キーボードのスタイル

仮想キーボードのスタイリングシステムは、組み込みスタイルとカスタムスタイルの両方をサポートしています。組み込みスタイルは Qt リソースとしてプラグインバイナリに埋め込まれており、カスタムスタイルはファイルシステム上に配置され、仮想キーボード自体を再コンパイルすることなくインストールできます。

実行時のスタイルの選択は、環境変数 `QT_VIRTUALKEYBOARD_STYLE` によって制御されます。この変数には、組み込みスタイルの名前（例: "retro"）や、`Styles` ディレクトリにインストールされた任意のカスタムスタイル名を設定できます。

$$[QT_INSTALL_QML]/QtQuick/VirtualKeyboard/Styles

環境変数が設定されていない場合、または無効なスタイル名が含まれている場合、仮想キーボードはデフォルトの組み込みスタイルに切り替わります。

カスタムスタイルの追加

新しいスタイルを作成するには、まず、URL ベースのディレクトリ構造QtQuick/VirtualKeyboard/Styles/ 内の QML インポートパス上に、そのスタイル用の新しいサブディレクトリを作成することから始めます。QML インポートパスに関する詳細については、「QML インポートパス」を参照してください。 ディレクトリ名には、スペースやアンダースコア以外の特殊文字を含めることはできません。また、ディレクトリ名は、現在「default」や「retro」などが含まれる組み込みスタイルの名前と同じにすることはできません。

新しいスタイルを作成する際のよい出発点は、既存の組み込みスタイルをテンプレートとして使用し、それを編集することです。 組み込みスタイルは、仮想キーボードのソースディレクトリ src/styles/builtin にあります。組み込みスタイルを含むディレクトリのいずれかをStylesディレクトリにコピーし、その名前を「test」に変更してください。これで、ディレクトリ構造は次のようになります:

test/default_style.qrc
test/style.qml
test/images
test/images/backspace.png
test/images/check.png
test/images/enter.png
test/images/globe.png
test/images/hidekeyboard.png
test/images/search.png
test/images/shift.png

このケースでは不要な QRC 設定ファイルは、安全に削除しても構いません。

次に、お好みのエディタで style.qml を開き、resourcePrefix プロパティを空の文字列に設定します。リソースは style.qml ファイルと同じディレクトリ内に含まれているため、リソースプレフィックスは必要ありません。

また、カスタムスタイルが実際に読み込まれて使用されていることが一目でわかるように、キーボードの背景色を別の色に変更してください:

keyboardBackground: Rectangle {
    color: "gray"
}

最後のステップとして、カスタムスタイルを適用したサンプルアプリケーションを実行します：

QT_VIRTUALKEYBOARD_STYLE=test virtualkeyboard

QQuickWidgetでのQt Virtual Keyboard の使用

タッチ対応デバイス上のQQuickWidget でQt Virtual Keyboard を使用する場合、QWidget::setAttribute() を通じてQt::WA_AcceptTouchEvents 属性を設定する必要があります。この属性を設定しないと、タッチデバイスからのイベントは合成されたマウスイベントに変換されてしまいます。