Qt Virtual Keyboard Visión general

Características

Las principales funciones de Qt Virtual Keyboard son:

• Diseños y estilos de teclado personalizables con cambio dinámico.
• Introducción predictiva de texto con selección de palabras.
• Vista previa de caracteres y vista de caracteres alternativos.
• Inserción automática de mayúsculas y espacios.
• Escalabilidad a diferentes resoluciones.
• Compatibilidad con distintos juegos de caracteres (latín, chino simplificado/tradicional, hindi, japonés, árabe, hebreo, coreano y otros).
• Compatible con los idiomas de entrada más comunes, con posibilidad de ampliar fácilmente la compatibilidad lingüística.
• Entrada de izquierda a derecha y de derecha a izquierda.
• Teclas de hardware para navegación en 2 y 5 direcciones.
• Soporte de escritura a mano, con gestos para entrada a pantalla completa.
• Respuesta de audio.
• Funcionalidad multiplataforma.
• Compatible con las aplicacionesQt Quick y Qt Widgets .

Idiomas admitidos

El teclado virtual es compatible con los siguientes idiomas:

Para añadir compatibilidad con un idioma adicional, consulte Añadir nuevas distribuciones de teclado.

Complementos de terceros

Qt Virtual Keyboard admite complementos de terceros de los siguientes proveedores:

• Cerence XT9 entrada avanzada.
• Entrada de texto manuscritoCerence.
• Reconocimiento de escritura a manoMyScript Text

Laconstrucción de Qt Virtual Keyboard describe cómo integrar estos plugins en Qt Virtual Keyboard.

Conceptos básicos

El proyecto Qt Virtual Keyboard es un plugin de contexto de entrada Qt que implementa las interfaces QPlatformInputContextPlugin y QPlatformInputContext. Estas interfaces permiten utilizar el plugin como plugin de contexto de entrada de plataforma en aplicaciones Qt.

El propio plugin proporciona un marco de entrada que soporta múltiples métodos de entrada, así como una interfaz de usuario QML para el teclado virtual. El marco de entrada es extensible a través de una interfaz de plugin, que permite cargar métodos de entrada y diseños de teclado de terceros en tiempo de ejecución.

El marco de entrada proporciona las siguientes interfaces principales:

• QVirtualKeyboardInputContextProporciona información contextual para el teclado virtual y otros componentes de entrada. Actúa como interfaz del componente de entrada de texto subyacente.
• QVirtualKeyboardInputEngineexpone una API para integrar los eventos de entrada del usuario (pulsación de teclas, etc.) y actúa como anfitrión para los métodos de entrada.
• QVirtualKeyboardAbstractInputMethodUn tipo base para métodos de entrada basados en C++. El método de entrada normalmente maneja eventos de teclado, pero también puede manejar eventos de ratón y entrada táctil.
• InputMethodun tipo base para métodos de entrada basados en QML. El método de entrada normalmente maneja eventos de teclas, pero también puede manejar eventos de entrada táctil y de ratón.

Contexto de entrada

El contexto de entrada lo utilizan tanto el teclado como los métodos de entrada concretos. InputContext es una instancia singleton alojada en QML. Una aplicación no debe interactuar directamente con el contexto de entrada.

Información contextual

El contexto de entrada proporciona acceso a información contextual procedente de la aplicación. Esta información incluye, entre otras cosas

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

Configuración regional

El motor del teclado virtual genera la lista de configuraciones regionales compatibles a partir de los directorios de diseño específicos de cada configuración regional en layouts/. Cada directorio de configuración debe contener una definición o una alternativa para los siguientes tipos de configuración: teclado de marcación, dígitos, escritura a mano, principal, números y símbolos. Las definiciones se implementan en los archivos .qml, mientras que las alternativas se definen mediante un archivo de marcador de posición con la extensión .fallback. El directorio layouts/ debe contener un subdirectorio fallback/ que contenga las definiciones de cada tipo de diseño.

Cada directorio de diseño puede contener la definición de uno o más tipos de diseño. Si el diseño específico de la configuración regional es el mismo que el de la configuración regional alternativa, puede añadir un archivo de marcador de posición para el diseño denominado <layout type>.fallback. Esto indica al teclado virtual que debe utilizar la distribución de reserva.

Por ejemplo: puede añadir una disposición específica de la configuración regional para el finés, que defina el tipo de disposición principal en main.qml. Para los demás tipos de distribución, se opta por el mecanismo de reserva. Su árbol layouts/ tendrá este aspecto:

.
├── 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

Es imprescindible que el directorio layouts/fallback contenga siempre un conjunto de archivos de implementación completos.

La aplicación puede especificar la disposición inicial cambiando la configuración regional predeterminada. Sin embargo, esto debe hacerse antes de que la aplicación se inicialice y cargue el plugin del método de entrada. Si no hay cambios en la configuración regional por defecto, se utiliza la configuración regional actual del sistema.

La configuración regional del teclado sigue esta secuencia:

• layouts/<language>_<country>
• layouts/<language>_*
• layouts/fallback - la configuración por defecto aquí es en_GB.

Primero, la configuración regional se compara con el nombre completo de la configuración regional. Si no hay una coincidencia completa, sólo se compara el idioma de la configuración regional. Por último, el contenido de layouts/fallback se utiliza como alternativa cuando tampoco hay una coincidencia parcial.

Una vez seleccionada la configuración regional, el teclado actualiza la configuración regional y la dirección de entrada para que coincidan con el diseño actual. La aplicación puede recibir esta información a través de la interfaz QInputMethod.

Internamente, la configuración regional de entrada actual también se actualiza en QVirtualKeyboardInputEngine y las instancias del método de entrada actual.

Motor de entrada

El objeto motor de entrada es propiedad de InputContext. Al igual que InputContext, sólo existe una instancia de QVirtualKeyboardInputEngine. El motor de entrada contiene funciones API que el teclado utiliza para asignar interacciones del usuario, como eventos de pulsación y liberación de teclas, al método de entrada.

Por ejemplo, los eventos de tecla del teclado virtual se mapean a través de los siguientes métodos:

• QVirtualKeyboardInputEngine::virtualKeyPress
• QVirtualKeyboardInputEngine::virtualKeyRelease

Los métodos mencionados anteriormente están destinados a la integración del teclado virtual, de ahí la palabra "virtual" en los nombres de los métodos. Esto también significa que los métodos no son adecuados para la asignación de las pulsaciones de teclas físicas. Esto es consecuencia del hecho de que la acción real se realiza sólo cuando se suelta la tecla.

Si la pulsación de la tecla se interrumpe antes del evento de liberación de la tecla, el teclado invoca el método QVirtualKeyboardInputEngine::virtualKeyCancel.

Método de entrada

El método de entrada es una implementación concreta del controlador de pulsación de teclas. Su función principal es manejar los eventos de pulsación de teclas y mantener la información de estado para la entrada del usuario. Interactúa con el editor de texto a través de QVirtualKeyboardInputContext vía pre-edición de texto o eventos de tecla.

La instancia del método de entrada puede crearse de varias maneras, dependiendo del caso de uso:

• KeyboardLayout::inputMethod: la distribución del teclado puede crear una instancia de método de entrada únicamente para esta distribución de teclado. Hay que tener en cuenta que esta instancia se destruirá cuando cambie la distribución del teclado. Por lo tanto, este método suele limitarse a casos de uso muy restringidos.
• KeyboardLayout::createInputMethod()Disposición del teclado: la disposición del teclado puede crear dinámicamente un método de entrada que puede utilizarse con esta disposición y también con shared layouts (por ejemplo, disposición de símbolos). Esta es la forma preferida para crear métodos de entrada especializados, como los que implican lenguajes complejos o escritura a mano.
• DefaultInputMethodTeclado virtual: el teclado virtual intenta crear este tipo de método de entrada al iniciarse. Esta instancia se utilizará como método de entrada predeterminado en todas las distribuciones de teclado, a menos que la distribución de teclado utilice un método de entrada personalizado. Esta instancia sobrevive a los cambios de distribución del teclado en todos los idiomas y es la forma preferida de crear y anular el método de entrada predeterminado.

Plugins del teclado virtual

El directorio src/plugins del teclado virtual contiene los plugins existentes para el teclado virtual. Estos plugins son módulos QML estándar cargados implícitamente por el módulo QtQuick.VirtualKeyboard.Plugins QML.

Un plugin puede proporcionar distribuciones de teclado y métodos de entrada (normalmente ambos). El método de entrada utilizado por el teclado virtual depende de la distribución de teclado que se esté utilizando. La distribución de teclado puede proporcionar una instancia de un método de entrada personalizado mediante la función KeyboardLayout.createInputMethod(). En caso contrario, se utiliza el método de entrada por defecto (DefaultInputMethod) creado por el teclado virtual.

Añadir distribuciones de teclado

El complemento puede añadir distribuciones de teclado para el teclado virtual incluyendo los archivos de distribución en los recursos Qt del binario del complemento.

El teclado virtual busca las distribuciones de teclado (por idioma) en una ruta específica /qt-project.org/imports/QtQuick/VirtualKeyboard/Layouts/<language_COUNTRY>, por lo que es esencial utilizar esta ruta exacta también en el plugin. Las rutas de los recursos Qt pueden solaparse, lo que significa que el plugin puede anular los diseños existentes en el teclado virtual.

También es posible sobreescribir las distribuciones de teclado incorporadas cargándolas directamente desde el sistema de archivos usando la variable de entorno QT_VIRTUALKEYBOARD_LAYOUT_PATH.

Añadir método de entrada

El plugin puede registrar un método de entrada que otras distribuciones de teclado pueden usar por defecto (como DefaultInputMethod) o un método de entrada que se usa de forma privada en el plugin (proporcionando también una distribución de teclado personalizada, que crea el método de entrada).

El método de entrada debe implementar una interfaz QVirtualKeyboardAbstractInputMethod (C++) o InputMethod (QML) y debe ser registrado como un tipo QML (QML_NAMED_ELEMENT) por el complemento.

Implementación de un método de entrada personalizado

La implementación de métodos de entrada comienza decidiendo qué interfaz se utiliza, QML o C++. En este ejemplo se utiliza la interfaz QML. La misma lógica e interfaces se aplican con la interfaz C++ QVirtualKeyboardAbstractInputMethod. En este caso, el plugin debe estar vinculado al módulo VirtualKeyboard.

El siguiente ejemplo muestra la funcionalidad mínima que se requiere de un método de entrada:

// 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;
    }
}

El método InputMethod::inputModes() es llamado por el motor de entrada antes de que se establezca un modo de entrada. El método devuelve una lista de los modos de entrada disponibles en la configuración regional dada.

Un método de entrada se inicializa en el método InputMethod::setInputMode() con una configuración regional y un modo de entrada. Después de establecer la configuración regional y el modo de entrada, el método de entrada debería estar listo para su uso.

InputMethod::reset() es llamado cuando un método de entrada necesita ser reiniciado. El reinicio sólo debe restablecer el estado interno del método de entrada, y no el texto del usuario.

InputMethod::update() se ejecuta cuando el contexto de entrada se actualiza y el estado de entrada está posiblemente desincronizado. El método de entrada debe confirmar el texto actual.

Los eventos de pulsación de teclas se manejan en InputMethod::keyEvent(). Este método maneja un único evento de pulsación de tecla y devuelve true si el evento fue procesado. En caso contrario, la pulsación se procesa con el método de entrada por defecto.

Listas de selección

Las listas de selección son una característica opcional que puede integrarse en el método de entrada. El marco de entrada admite varios tipos de listas, como la lista de palabras candidatas. Las responsabilidades en la implementación de las listas se manejan de tal manera que el método de entrada es responsable del contenido y las actividades, como el comportamiento de clic. El marco de entrada es responsable de mantener el modelo de lista y la entrega a la interfaz de usuario.

Asignación de las listas de selección

Las listas de selección se asignan cuando se activa el método input. El método InputMethod::selectionLists() devuelve una lista de los tipos de listas de selección requeridos:

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

En el ejemplo anterior, el método de entrada asigna la lista de palabras candidatas para su uso.

Actualización de las listas de selección

Cuando el método de entrada requiera que la interfaz de usuario actualice el contenido de una lista de selección, emitirá la señal InputMethod::selectionListChanged. Del mismo modo, si el método de entrada requiere que la interfaz de usuario resalte un elemento de la lista, emitirá la señal InputMethod::selectionListActiveItemChanged.

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

Rellenar los elementos de las listas de selección

Los elementos se rellenan con métodos de devolución de llamada que proporcionarán el número de elementos de una lista, así como los datos de los elementos individuales.

La llamada de retorno InputMethod::selectionListItemCount solicita el número de elementos de la lista identificados por el tipo dado.

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

La llamada de retorno InputMethod::selectionListData solicita los datos de los elementos.

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
}

El parámetro role identifica qué datos se solicitan para un elemento. Por ejemplo, el parámetro SelectionListModel.Role.Display solicita los datos de texto de la pantalla.

Respuesta a las acciones del usuario

Cuando el usuario selecciona un elemento de la lista, el método de entrada responde al evento en la devolución de llamada del método InputMethod::selectionListItemSelected.

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

Integración del reconocimiento de escritura

Un método de entrada también puede utilizar datos de entrada de la pantalla táctil u otros dispositivos de entrada.

Cuando comienza la entrada, el teclado virtual llama a la función del método de entrada traceBegin , que devuelve un nuevo objeto Trace en el que se recoge la entrada en nombre del método de entrada. Del mismo modo, cuando se levanta el dedo o el lápiz óptico, el evento finaliza con la llamada traceEnd . El método de entrada procesa los datos recogidos y produce texto utilizando la interfaz InputContext.

Existen diseños de teclado predefinidos para la escritura a mano. Sin embargo, no se incluyen por defecto, y el plugin de escritura a mano debe incluirlos en sus propios recursos. Para ver ejemplos de cómo hacerlo, consulte los plugins existentes para escritura a mano de MyScript o Cerence.

Modelo de datos para la entrada de escritura a mano

Teclado virtual recoge los datos de escritura a mano en un modelo de datos especial QVirtualKeyboardTrace. Cada trazo representa una colección de datos muestreados de un toque (por ejemplo, un barrido en la pantalla). Habrá tantas instancias de QVirtualKeyboardTrace como toques en el área de entrada de escritura.

Por definición, la traza es un conjunto de datos muestreados a partir de un toque. Además de los datos básicos del punto, también puede incluir otros tipos de datos, como la hora de cada punto. El método de entrada puede definir los canales de entrada deseados al principio de un evento de rastreo.

El método de entrada no participa en la recopilación real de los datos de rastreo. Sin embargo, el método de entrada tiene un control total sobre la entrada, ya que puede aceptar o rechazar un QVirtualKeyboardTrace (por ejemplo, si hay demasiadas instancias que manejar). Esto también permite controlar con precisión cuántos dedos pueden utilizarse simultáneamente.

El método de entrada puede recoger tantas huellas como considere oportuno y puede empezar a procesarlas cuando sea necesario. El procesamiento puede incluso realizarse en paralelo mientras se muestrean los datos, aunque no se recomienda debido a los posibles problemas de rendimiento. Lo recomendable es iniciar el procesamiento en un hilo en segundo plano tras un retardo adecuado desde la última entrada, para que el procesamiento no afecte negativamente a la interfaz de usuario.

API de rastreo para métodos de entrada

La API de rastreo consiste en los siguientes métodos virtuales, que el método de entrada debe implementar para recibir y procesar los datos de entrada de rastreo.

• patternRecognitionModes
• traceBegin
• traceEnd

Al implementar estos métodos, el método de entrada puede recibir y procesar datos de una variedad de fuentes de entrada (por ejemplo, diseño de teclado o pantalla completa).

El método patternRecognitionModes devuelve una lista de modos de reconocimiento de patrones compatibles con el método de entrada. Un modo de reconocimiento de patrones, como Handwriting , define el método mediante el cual el método de entrada procesa los datos.

La interacción de rastreo se inicia cuando una fuente de entrada detecta un nuevo punto de contacto, y llama al método traceBegin para un nuevo objeto de rastreo. Si el método de entrada acepta la interacción, crea un nuevo objeto de rastreo y lo devuelve a quien lo ha llamado. A partir de este momento, los datos de rastreo se recogen hasta que se llama al método traceEnd.

Cuando se llama al método traceEnd, el método de entrada puede empezar a procesar los datos contenidos en el objeto trace. Después de procesar los datos, el método de entrada debe destruir el objeto. Esto también elimina la traza renderizada en la pantalla.

Distribuciones de teclado

Las distribuciones de teclado se encuentran en el directorio src/layouts/builtin. Cada subdirectorio del directorio layout representa una locale. El directorio locale es una cadena de la forma "language_country", donde language es un código de idioma ISO 639 de dos letras en minúscula, y country es un código de país ISO 3166 de dos o tres letras en mayúscula.

Tipos de disposición

Los distintos tipos de distribución del teclado se utilizan en diferentes modos de entrada. La disposición predeterminada que se utiliza para la introducción de texto normal se denomina disposición "principal". El tipo de distribución viene determinado por el nombre del archivo de distribución. Por lo tanto, el archivo de distribución "principal" se denomina "main.qml".

Lista de tipos de presentación admitidos:

• main El diseño principal para la introducción de texto normal
• symbols Disposición de símbolos para caracteres especiales, etc. (activada desde la disposición principal)
• numbers Disposición numérica para números formateados (activada por Qt::ImhFormattedNumbersOnly)
• digits Disposición de sólo dígitos (activada por Qt::ImhDigitsOnly)
• dialpad Disposición del teclado para la introducción de números de teléfono (activada en Qt::ImhDialableCharactersOnly)
• handwriting Diseño de escritura a mano para el reconocimiento de escritura a mano (activado desde el diseño principal)

Añadir nuevas distribuciones de teclado

El elemento de distribución del teclado debe basarse en el tipo QML KeyboardLayout. Este tipo define el elemento raíz de la distribución. El elemento raíz tiene las siguientes propiedades opcionales que pueden establecerse si es necesario:

Las nuevas filas se añaden a la distribución del teclado utilizando el tipo KeyboardRow. KeyboardRow también puede especificar el peso de las teclas por defecto para sus elementos hijos. De lo contrario, el peso de las teclas se hereda de su elemento padre.

Las nuevas teclas se añaden a la fila del teclado utilizando el tipo Tecla o uno de los tipos de tecla especializados. A continuación se muestra la lista de todos los tipos de teclas:

Por ejemplo, para añadir una tecla normal que envíe un evento de tecla al método de entrada:

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"
        }
    }
}

Cálculo del tamaño de las teclas

Las distribuciones de teclado son escalables, lo que significa que no se pueden establecer tamaños fijos para ningún elemento de la distribución. En su lugar, las anchuras de las teclas se calculan a partir del peso de las teclas entre sí y de la altura dividiendo el espacio equitativamente entre las filas del teclado.

En el ejemplo anterior, el tamaño de las teclas se hereda de los elementos padre en este orden:

Tecla > KeyboardRow > KeyboardLayout

El valor efectivo del peso de la tecla será 160. Por el bien del ejemplo, añadimos otra tecla que especifica un peso de tecla personalizado:

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
        }
    }
}

Ahora el peso total de las teclas de una fila es 160 + 200 = 360. Cuando se activa la distribución del teclado, la anchura de una tecla individual se calcula del siguiente modo:

anchura de tecla en píxeles = peso de tecla / SUMA(pesos de tecla en una fila) * anchura de fila en píxeles

Esto significa que el teclado puede escalarse a cualquier tamaño, mientras que los tamaños relativos de las teclas siguen siendo los mismos.

Teclas alternativas

Las teclas pueden especificar una propiedad alternativeKeys, que da lugar a una ventana emergente con una lista de teclas alternativas cuando el usuario pulsa y mantiene pulsada la tecla. Las alternativeKeys pueden especificar una cadena o una lista de cadenas. Si alternativeKeys es una cadena, el usuario puede seleccionar entre los caracteres de la cadena.

Estilos y disposiciones

Las distribuciones de teclado no pueden especificar ningún elemento visual. En su lugar, la disposición se visualiza mediante el estilo de teclado. Por otra parte, el estilo de teclado no puede afectar al tamaño de la distribución del teclado.

Distribuciones de teclado con varias páginas de teclas

Algunas distribuciones de teclado, como las de símbolos, pueden contener más teclas de las que es factible presentar en una única distribución de teclado. Una solución es incrustar varias distribuciones de teclado en el mismo contexto utilizando KeyboardLayoutLoader.

Cuando se utiliza KeyboardLayoutLoader como elemento raíz de una distribución de teclado, las distribuciones de teclado reales se envuelven dentro de elementos Component. La distribución del teclado se activa asignando el id de un componente activo a la propiedad sourceComponent.

Por ejemplo

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
                }
            }
        }
    }
}

Disposición de teclado de escritura a mano

Cada idioma compatible con el reconocimiento de escritura a mano debe proporcionar una distribución de teclado especial denominada handwriting.qml.

Este tipo de distribución de teclado debe cumplir los siguientes requisitos:

• contiene un TraceInputKey en la distribución del teclado
• proporciona una instancia de HandwritingInputMethod como método de entrada.

La disposición de escritura a mano también puede incluir ChangeLanguageKey. Para ello, es importante utilizar el atributo customLayoutsOnly, que filtrará los idiomas que no utilicen escritura a mano.

Tanto la presentación principal como la de escritura a mano deben contener una tecla para activar y desactivar el modo de entrada de escritura a mano. Para ello, añada HandwritingModeKey a la presentación.

Añadir disposiciones personalizadas

El sistema de distribuciones del teclado virtual admite distribuciones integradas y personalizadas. Las distribuciones integradas se incrustan como recursos Qt en el binario del complemento. Los diseños personalizados se encuentran en el sistema de archivos, de modo que pueden instalarse sin tener que volver a compilar el teclado virtual, o pueden encontrarse en un archivo de recursos.

La selección de diseños en tiempo de ejecución se ve afectada por la variable de entorno QT_VIRTUALKEYBOARD_LAYOUT_PATH.

En caso de que la variable de entorno no esté definida o contenga un directorio no válido, el teclado virtual volverá a los diseños incorporados por defecto.

Para evitar que las distribuciones incorporadas se integren en el complemento del teclado virtual cuando se utilizan distribuciones personalizadas, añada la opción -no-vkb-layouts al script configure. Para obtener más información, consulte Opciones de configuración.

Estilos de teclado

El sistema de estilos del teclado virtual admite estilos integrados y personalizados. Los estilos incorporados se incrustan como recursos Qt en el binario del complemento y los estilos personalizados se encuentran en el sistema de archivos y pueden instalarse sin necesidad de recompilar el propio teclado virtual.

La selección del estilo en tiempo de ejecución se ve afectada por una variable de entorno QT_VIRTUALKEYBOARD_STYLE, que puede establecerse con el nombre del estilo integrado, por ejemplo "retro", o cualquiera de los estilos personalizados instalados en el directorio Styles:

$$[QT_INSTALL_QML]/QtQuick/VirtualKeyboard/Styles

En caso de que la variable de entorno no esté definida, o contenga un nombre de estilo no válido, el teclado virtual volverá al estilo incorporado por defecto.

Añadir estilos personalizados

El proceso de creación de un nuevo estilo comienza creando un nuevo subdirectorio para el estilo en una ruta de importación QML bajo la estructura de directorios basada en URL QtQuick/VirtualKeyboard/Styles/. Consulte Ruta de importación QML para obtener información sobre las rutas de importación QML. El nombre del directorio no puede contener espacios ni caracteres especiales distintos del guión bajo. Además, el nombre del directorio no puede ser el mismo que uno de los estilos incorporados, que actualmente incluyen "default" y "retro".

Un buen punto de partida para crear un nuevo estilo es utilizar un estilo incorporado existente como plantilla y editarlo. Puedes encontrar los estilos incorporados en el directorio de fuentes del teclado virtual src/styles/builtin. Copie uno de los directorios que contiene un estilo incorporado en el directorio Styles y cámbiele el nombre a "test". La estructura de directorios debería ser ahora la siguiente

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

El archivo de configuración QRC, innecesario en este caso, puede eliminarse sin problemas.

A continuación, abra el archivo style.qml en su editor favorito y establezca la propiedad resourcePrefix en una cadena vacía. El prefijo del recurso no es necesario, ya que los recursos se encuentran en el mismo directorio que el archivo style.qml.

Además, para que sea más obvio ver que el estilo personalizado se está cargando y utilizando, establezca el fondo del teclado a un color diferente:

keyboardBackground: Rectangle {
    color: "gray"
}

El paso final es ejecutar la aplicación de ejemplo con su estilo personalizado:

QT_VIRTUALKEYBOARD_STYLE=test virtualkeyboard

Usando Qt Virtual Keyboard con QQuickWidget

Cuando se utiliza Qt Virtual Keyboard en un QQuickWidget en un dispositivo táctil, es necesario establecer el atributo Qt::WA_AcceptTouchEvents a través de QWidget::setAttribute(). Sin este atributo establecido, los eventos de un dispositivo táctil se convertirán en eventos de ratón sintetizados.