Техническое руководство

Обзор

В данном документе представлен технический обзор плагина Qt Virtual Keyboard.

Основные концепции

Проект Qt Virtual Keyboard представляет собой плагин контекста ввода Qt 5, реализующий интерфейсы QPlatformInputContextPlugin и QPlatformInputContext. Эти интерфейсы позволяют использовать плагин в качестве плагина контекста ввода в приложениях Qt 5.

Сам плагин предоставляет фреймворк для поддержки нескольких методов ввода, а также QML-интерфейс для виртуальной клавиатуры. Фреймворк для ввода расширяется через интерфейс плагинов, что позволяет загружать сторонние методы ввода и раскладки клавиатуры во время выполнения.

Фреймворк ввода предоставляет следующие основные интерфейсы:

• QVirtualKeyboardInputContext: предоставляет контекстную информацию для виртуальной клавиатуры и других компонентов ввода. Выступает в роли интерфейса к базовому компоненту ввода текста.
• QVirtualKeyboardInputEngine: предоставляет API для интеграции событий ввода пользователя (нажатия клавиш и т.д.) и выступает в роли хоста для методов ввода.
• QVirtualKeyboardAbstractInputMethod: базовый тип для методов ввода на C++. Метод ввода обычно обрабатывает события нажатия клавиш, но также может обрабатывать события мыши и сенсорного ввода.
• InputMethod: базовый тип для методов ввода на QML. Метод ввода обычно обрабатывает события нажатия клавиш, но также может обрабатывать события мыши и сенсорного ввода.
• QVirtualKeyboardExtensionPlugin: интерфейс плагина для расширений виртуальной клавиатуры, предоставляющих дополнительные функции.

Контекст ввода

Контекст ввода используется клавиатурой, а также конкретными методами ввода. InputContext — это единственный экземпляр, размещённый в QML. Приложение не должно напрямую взаимодействовать с контекстом ввода.

Контекстная информация

Контекст ввода предоставляет доступ к контекстной информации, поступающей из приложения. Эта информация включает, но не ограничивается:

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

Локали

Список поддерживаемых локалей определяется наличием директории раскладки, специфичной для локали, в "layouts/*". Каждая директория раскладки может содержать одну или несколько раскладок, например, fi_FI/main.qml или symbols.qml. Если раскладка, специфичная для локали, не отличается от локали по умолчанию, то может быть добавлен файл-заполнитель <layout type>.fallback для раскладки. Это укажет, что для раскладки по умолчанию может быть использована виртуальная клавиатура.

По меньшей мере, директория раскладки должна содержать следующие файлы:

• dialpad.fallback
• digits.fallback
• main.fallback
• numbers.fallback
• symbols.fallback

Приложение может указать начальную раскладку, изменив локаль по умолчанию. Однако это необходимо сделать до инициализации приложения и загрузки плагина метода ввода. Если изменения в локали по умолчанию не произведены, используется текущая системная локаль.

Сопоставление локали клавиатуры выполняется в следующей последовательности:

• layouts/<language>_<country>
• layouts/<language>_*
• layouts/en_GB

Сначала локаль сопоставляется с полным именем локали. Если точного совпадения нет, то сопоставляется только язык локали. Если частичного совпадения нет, то в качестве резервного варианта используется локаль "en_GB".

После выбора локали клавиатура обновляет локаль ввода и направление ввода, чтобы соответствовать текущей раскладке. Приложение может получить эту информацию через интерфейс QInputMethod.

Внутренне текущая локаль ввода также обновляется для QVirtualKeyboardInputEngine и текущих экземпляров методов ввода.

Движок ввода

Объект движка ввода принадлежит InputContext. Как и InputContext, существует только один экземпляр QVirtualKeyboardInputEngine. Движок ввода содержит функции API, которые используются клавиатурой для сопоставления пользовательских взаимодействий, таких как события нажатия и отпускания клавиш, с методом ввода.

Например, события нажатия клавиш виртуальной клавиатуры сопоставляются через следующие методы:

• QVirtualKeyboardInputEngine::virtualKeyPress
• QVirtualKeyboardInputEngine::virtualKeyRelease

Вышеупомянутые методы предназначены для интеграции виртуальной клавиатуры, отсюда и слово "virtual" в именах методов. Это также означает, что методы не подходят для сопоставления физических нажатий клавиш. Это следствие того, что фактическое действие выполняется только при отпускании клавиши.

Если нажатие клавиши прерывается до события отпускания клавиши, клавиатура вызывает метод QVirtualKeyboardInputEngine::virtualKeyCancel.

Метод ввода

Метод ввода — это конкретная реализация обработчика нажатия клавиш. Его основная функция — обработка событий нажатия клавиш и сохранение информации о состоянии пользовательского ввода. Он взаимодействует с текстовым редактором через QVirtualKeyboardInputContext через предварительно отформатированный текст или события нажатия клавиш.

Экземпляр метода ввода может быть создан различными способами в зависимости от случая использования:

• KeyboardLayout::inputMethod: раскладка клавиатуры может создавать экземпляр метода ввода только для этой раскладки клавиатуры. Следует отметить, что этот экземпляр будет уничтожен при изменении раскладки клавиатуры. Поэтому этот метод обычно ограничен очень узкими случаями использования.
• KeyboardLayout::createInputMethod(): раскладка клавиатуры может динамически создавать метод ввода, который может использоваться с этой раскладкой, а также с общими раскладками (например, раскладкой символов). Это предпочтительный способ создания специализированных методов ввода, таких как методы, связанные со сложными языками или рукописным вводом.
• DefaultInputMethod: виртуальная клавиатура пытается создать этот тип метода ввода при запуске. Этот экземпляр будет использоваться как метод ввода по умолчанию для всех раскладок клавиатуры, если только раскладка клавиатуры не использует пользовательский метод ввода. Этот экземпляр сохраняется при изменениях раскладок клавиатуры между языками и является предпочтительным способом создания и переопределения метода ввода по умолчанию.

Плагин расширения виртуальной клавиатуры

Плагин расширения позволяет сторонним поставщикам улучшать функциональность виртуальной клавиатуры без перекомпиляции. В настоящее время плагин расширения может предоставлять раскладки клавиатуры и пользовательские методы ввода. Создание плагина для Qt Virtual Keyboard аналогично стандартному способу создания плагина Qt:

• Связь с библиотекой виртуальной клавиатуры.

  Модуль virtualkeyboard должен быть связан с плагином:

  QT += virtualkeyboard

  Это позволяет плагину получать доступ к QVirtualKeyboardInputContext и другим интерфейсам.

• Реализация подкласса QVirtualKeyboardExtensionPlugin.

  Плагин предоставляет виртуальной клавиатуре необходимую метаданные, что позволяет ей сортировать и загружать плагины.

Добавление раскладок клавиатуры

Плагин может добавлять раскладки клавиатуры для виртуальной клавиатуры, включив файлы раскладки в Qt-ресурсы двоичного файла плагина.

Виртуальная клавиатура ищет раскладки клавиатуры (по языку) из определенного пути /QtQuick/VirtualKeyboard/content/layouts/<language_COUNTRY>, поэтому очень важно использовать этот точный путь и в плагине. Пути Qt-ресурсов могут перекрываться, однако плагин не может переопределять существующие раскладки в плагине виртуальной клавиатуры.

Если плагин расширения должен переопределять встроенную раскладку клавиатуры, виртуальную клавиатуру необходимо перекомпилировать только с определенными языками (например, CONFIG+=lang-en) или без раскладок клавиатуры (например, CONFIG+=disable-layouts). В качестве альтернативы, если перекомпиляция невозможна, можно переопределить встроенные раскладки клавиатуры и загрузить их непосредственно из файловой системы, используя переменную окружения QT_VIRTUALKEYBOARD_LAYOUT_PATH.

Добавление метода ввода

Плагин может регистрировать метод ввода, который по умолчанию могут использовать другие раскладки клавиатуры (например, DefaultInputMethod) или метод ввода, который используется в плагине.

Метод ввода должен реализовывать интерфейс QVirtualKeyboardAbstractInputMethod (C++) или InputMethod (QML), и плагин должен зарегистрировать его как тип QML в методе {QVirtualKeyboardExtensionPlugin::registerTypes}.

Метаданные для плагина расширения

Метаданные позволяют виртуальной клавиатуре инспектировать плагин перед загрузкой фактической библиотеки. Они также предотвращают загрузку конфликтующих плагинов расширений виртуальной клавиатуры, например, двух плагинов рукописного ввода.

Следующий пример метаданных взят из плагина расширения Lipi-Toolkit (lipi.json):

{
    "Name": "handwriting",
    "Provider": "Qt Lipi-Toolkit Extension",
    "InputMethod": "HandwritingInputMethod",
    "Version": 100
}

Реализация пользовательского метода ввода

Реализация методов ввода начинается с выбора используемого интерфейса: QML или C++. В этом примере используется интерфейс QML.

Следующий пример демонстрирует минимальные функциональные возможности, необходимые от метода ввода:

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Virtual Keyboard module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:GPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3 or (at your option) any later version
** approved by the KDE Free Qt Foundation. The licenses are as published by
** the Free Software Foundation and appearing in the file LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/

import QtQuick 2.0
import QtQuick.VirtualKeyboard 1.0

// file: CustomInputMethod.qml

InputMethod {
    function inputModes(locale) {
        return [InputEngine.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];
}

В приведённом примере метод ввода распределяет список кандидатов слов для своего использования.

Обновление списков выбора

Когда методу ввода требуется обновить содержимое списка выбора в пользовательском интерфейсе, он генерирует сигнал InputMethod::selectionListChanged. Аналогично, если методу ввода требуется выделить элемент в списке, он генерирует сигнал 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()
    }
}

Интеграция распознавания рукописного ввода

Начиная с версии 2.0 виртуальной клавиатуры, методы ввода могут потреблять данные сенсорного ввода с сенсорных экранов или других устройств ввода. Это позволяет бесшовно интегрировать движок распознавания рукописного ввода в виртуальную клавиатуру без каких-либо изменений в существующих раскладках клавиатуры (поскольку виртуальная клавиатура уже предоставляет раскладки клавиатуры для рукописного ввода для большинства языков).

Для метода ввода распознавание рукописного ввода работает по тому же принципу, что и обработка обычного ввода с клавиатуры, т. е. данные ввода собираются раскладкой клавиатуры и передаются механизмом ввода методу ввода для обработки.

Модель данных для рукописного ввода

Виртуальная клавиатура собирает данные рукописного ввода в специальной модели данных QVirtualKeyboardTrace. Каждый след представляет собой набор данных, собранных с одного касания (например, свайп по экрану). Будет столько экземпляров QVirtualKeyboardTrace, сколько касаний на области ввода рукописного ввода.

По определению, след — это набор данных, собранных с одного касания. Помимо базовых данных точек, он также может включать другие типы данных, такие как время каждой точки. Метод ввода может определить желаемые каналы ввода в начале события следа.

Метод ввода не участвует в фактическом сборе данных следа. Однако метод ввода имеет полный контроль над вводом, поскольку он может принять или отклонить QVirtualKeyboardTrace (например, если существует слишком много экземпляров, чтобы их обработать). Это также позволяет точно контролировать, сколько пальцев может использоваться одновременно.

Метод ввода может собрать столько следов, сколько посчитает нужным, и может начать обрабатывать их при необходимости. Обработка может выполняться даже параллельно во время выборки данных, хотя это не рекомендуется из-за возможных проблем с производительностью. Рекомендуемый способ — начать обработку в фоновом потоке после подходящей задержки с последнего ввода, чтобы обработка не оказывала негативного влияния на пользовательский интерфейс.

API следов для методов ввода

API следов состоит из следующих виртуальных методов, которые метод ввода должен реализовать для получения и обработки данных ввода следов.

• patternRecognitionModes
• traceBegin
• traceEnd

Реализовав эти методы, метод ввода может получать и обрабатывать данные из различных источников ввода (например, раскладки клавиатуры или полноэкранного режима).

Взаимодействие с следами начинается, когда источник ввода обнаруживает новую точку контакта и вызывает метод traceBegin для нового объекта следа. Если метод ввода принимает взаимодействие, он создает новый объект следа и возвращает его вызывающему объекту. С этого момента данные следа собираются до вызова метода traceEnd.

Когда вызывается метод traceEnd, метод ввода может начать обработку данных, содержащихся в объекте следа. После обработки данных метод ввода должен уничтожить объект. Это также удаляет след, отображаемый на экране.

Раскладки клавиатуры

Раскладки клавиатуры находятся в каталоге src/virtualkeyboard/content/layouts. Каждый подкаталог каталога раскладки представляет локаль. Каталог локали — это строка вида "язык_страна", где язык — двухбуквенный код языка ISO 639 в нижнем регистре, а страна — двух- или трехбуквенный код страны ISO 3166 в верхнем регистре.

Типы раскладок

Разные типы раскладок клавиатуры используются в разных режимах ввода. По умолчанию используется раскладка "основная", которая используется для обычного текстового ввода. Тип раскладки определяется именем файла раскладки. Поэтому файл "основной" раскладки называется "main.qml".

Список поддерживаемых типов раскладок:

• main Основная раскладка для обычного текстового ввода
• symbols Символьная раскладка для специальных символов и т. д. (активируется из основной раскладки)
• numbers Числовая раскладка для форматированных чисел (активируется Qt::ImhFormattedNumbersOnly)
• digits Раскладка только цифр (активируется Qt::ImhDigitsOnly)
• dialpad Раскладка номеронабирателя для ввода номера телефона (активируется Qt::ImhDialableCharactersOnly)
• handwriting Раскладка рукописного ввода для распознавания рукописного ввода (активируется из основной раскладки)

Добавление новых раскладок клавиатуры

Элемент раскладки клавиатуры должен быть основан на типе QML KeyboardLayout. Этот тип определяет корневой элемент раскладки. Корневой элемент имеет следующие необязательные свойства, которые можно установить при необходимости:

Новые строки добавляются в расклад клавиатуры с помощью типа KeyboardRow. KeyboardRow также может указать значение веса клавиш по умолчанию для своих дочерних элементов. В противном случае вес клавиш наследуется от родительского элемента.

Новые клавиши добавляются в строку клавиатуры с помощью типа Key или одного из специализированных типов клавиш. Ниже приведён список всех типов клавиш:

• Клавиша
• Клавиша Backspace
• Клавиша смены языка
• Клавиша Enter
• Клавиша-заполнитель
• Клавиша скрытия клавиатуры
• Цифровая клавиша
• Клавиша Shift
• Пробел
• Клавиша символьного режима
• Клавиша режима рукописного ввода
• Клавиша ввода следа

Например, чтобы добавить обычную клавишу, которая отправляет событие нажатия клавиши методу ввода:

import QtQuick 2.0
import QtQuick.Layouts 1.0
import QtQuick.VirtualKeyboard 2.1

// file: layouts/en_GB/main.qml

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

Расчёт размера клавиш

Макеты клавиатуры масштабируемы, что означает, что для элементов макета нельзя устанавливать фиксированные размеры. Вместо этого ширина клавиш вычисляется исходя из веса клавиш по отношению друг к другу и высоты путём равного распределения пространства между строками клавиатуры.

В приведённом выше примере размер клавиши наследуется от родительских элементов в следующем порядке:

Клавиша > Строка клавиатуры > Раскладка клавиатуры

Эффективное значение веса клавиши будет равно 160. Для примера добавим ещё одну клавишу, которая указывает собственный вес клавиши:

import QtQuick 2.0
import QtQuick.Layouts 1.0
import QtQuick.VirtualKeyboard 2.1

// file: layouts/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. Раскладка клавиатуры активируется путём назначения идентификатора активного компонента свойству sourceComponent.

Например:

import QtQuick 2.0
import QtQuick.Layouts 1.0
import QtQuick.VirtualKeyboard 2.1

// file: layouts/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.

Если переменная среды не установлена или содержит недопустимый каталог, виртуальная клавиатура возвращается к стандартным встроенным раскладкам.

Чтобы предотвратить включение встроенных раскладок в плагин виртуальной клавиатуры при использовании пользовательских раскладок, добавьте disable-layouts к переменной qmake CONFIG. Дополнительные сведения см. в разделе Дополнительные параметры конфигурации.

Стили клавиатуры

Система стилей виртуальной клавиатуры поддерживает встроенные и пользовательские стили. Встроенные стили встроены как Qt-ресурсы в двоичный файл плагина, а пользовательские стили хранятся в файловой системе и могут быть установлены без перекомпиляции самой виртуальной клавиатуры.

Выбор стиля во время выполнения зависит от переменной среды QT_VIRTUALKEYBOARD_STYLE, которая может быть установлена на имя встроенного стиля, например, "retro", или на любое имя пользовательского стиля, установленного в каталоге Styles:

$$[QT_INSTALL_QML]/QtQuick/VirtualKeyboard/Styles

Если переменная среды не установлена или содержит недопустимое имя стиля, виртуальная клавиатура возвращается к стандартному встроенному стилю.

Добавление пользовательских стилей

Процесс создания нового стиля начинается с создания нового подкаталога для стиля в пути импорта QML по структуре URL QtQuick/VirtualKeyboard/Styles/. Сведения об путях импорта QML см. в разделе Путь импорта QML. Имя каталога не может содержать пробелов или специальных символов, кроме нижнего подчёркивания. Кроме того, имя каталога не может совпадать с именем встроенного стиля, которые в настоящее время включают "default" и "retro".

Хорошей отправной точкой для создания нового стиля является использование существующего встроенного стиля в качестве шаблона и его редактирование. Вы можете найти встроенные стили в каталоге исходных кодов виртуальной клавиатуры src/virtualkeyboard/content/styles. Скопируйте один из каталогов, содержащих встроенный стиль, в каталог 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 не следует переименовывать, иначе виртуальная клавиатура не сможет загрузить стиль.

Далее, откройте style.qml в вашем любимом редакторе и установите свойство resourcePrefix в пустую строку. Префикс ресурсов не требуется, так как ресурсы находятся в той же папке, что и файл style.qml.

Также, чтобы было более очевидно, что пользовательский стиль фактически загружается и используется, установите фон клавиатуры в другой цвет:

keyboardBackground: Rectangle {
    color: "gray"
}

Заключительным шагом является запуск приложения-примера с вашим пользовательским стилем:

QT_VIRTUALKEYBOARD_STYLE=test virtualkeyboard

Использование Qt Virtual Keyboard с QQuickWidget

При использовании Qt Virtual Keyboard в QQuickWidget на сенсорном устройстве необходимо установить атрибут Qt::WA_AcceptTouchEvents с помощью QWidget::setAttribute(). Без этого атрибута события со сенсорного устройства будут преобразованы в синтезированные события мыши.