Qt Virtual Keyboard Descripción general
Características
Las características principales de « Qt Virtual Keyboard » incluyen:
- 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 visualización de caracteres alternativos.
- Mayúsculas automáticas e inserción automática de espacios.
- Escalabilidad a diferentes resoluciones.
- Compatibilidad con diferentes conjuntos de caracteres (latino, chino simplificado/tradicional, hindi, japonés, árabe, hebreo, coreano y otros).
- Compatibilidad con los idiomas de entrada más comunes, con la posibilidad de ampliar fácilmente la compatibilidad lingüística.
- Entrada de izquierda a derecha y de derecha a izquierda.
- Compatibilidad con teclas físicas para navegación en 2 y 5 direcciones.
- Compatibilidad con la escritura manuscrita, con gestos para la introducción de datos a pantalla completa.
- Respuesta sonora.
- Funcionalidad multiplataforma.
- Compatible tanto con aplicaciones deQt Quick como de Qt Widgets .
Idiomas compatibles
El teclado virtual admite los siguientes idiomas:
Para añadir compatibilidad con un idioma adicional, consulta «Añadir nuevas distribuciones de teclado».
Complementos de terceros
Qt Virtual Keyboard es compatible con complementos de terceros de los siguientes proveedores:
- Entrada avanzadaCerence XT9.
- Entrada de textomanuscrito conCerence Handwriting.
- Reconocimiento de escritura manuscritaMyScript Text
El documento « Qt Virtual Keyboard » describe cómo integrar estos complementos en el Qt Virtual Keyboard.
Conceptos básicos
El proyecto « Qt Virtual Keyboard » es un complemento de contexto de entrada de Qt que implementa las interfaces QPlatformInputContextPlugin y QPlatformInputContext. Estas interfaces permiten utilizar el complemento como complemento de contexto de entrada de la plataforma en aplicaciones Qt.
El propio complemento proporciona un marco de entrada que admite 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 complemento, lo que permite cargar métodos de entrada y distribuciones de teclado de terceros en tiempo de ejecución.
El marco de entrada proporciona las siguientes interfaces principales:
- QVirtualKeyboardInputContext: proporciona información contextual sobre el teclado virtual y otros componentes de entrada. Actúa como interfaz para el componente de entrada de texto subyacente.
- QVirtualKeyboardInputEngine: expone una API para integrar eventos de entrada del usuario (pulsaciones de teclas, etc.) y actúa como anfitrión para los métodos de entrada.
- QVirtualKeyboardAbstractInputMethod: un tipo base para métodos de entrada basados en C++. El método de entrada suele gestionar eventos de teclas, pero también puede gestionar eventos de entrada del ratón y táctiles.
- InputMethod: un tipo base para métodos de entrada basados en QML. El método de entrada suele gestionar eventos de teclas, pero también puede gestionar eventos de entrada del ratón y táctiles.
Contexto de entrada
El contexto de entrada es utilizado tanto por el teclado como por los métodos de entrada concretos. InputContext es una instancia singleton alojada por 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 otros:
- 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 admitidas a partir de los directorios de distribución específicos de cada configuración regional en layouts/. Cada directorio de distribución debe contener una definición o una alternativa para los siguientes tipos de distribución: teclado numérico, dígitos, escritura manuscrita, principal, números y símbolos. Las definiciones se implementan en archivos .qml, mientras que las alternativas se definen mediante un archivo marcador de posición con la extensión .fallback. El directorio « layouts/ » debe contener un subdirectorio « fallback/ » que incluya definiciones para cada tipo de distribución.
Cada directorio de distribución puede contener la definición de uno o más tipos de distribución. Si la distribución específica de la configuración regional es la misma que la de la configuración regional de reserva, puedes añadir un archivo de marcador de posición para la distribución llamado <layout type>.fallback. Esto indica al teclado virtual que utilice la distribución de reserva en su lugar.
Por ejemplo: puedes añadir una distribución específica para la configuración regional del finés, que defina el tipo de distribución principal en main.qml. Para los demás tipos de distribución, optas por el mecanismo de reserva. Tu á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.fallbackEs imprescindible que el directorio layouts/fallback contenga siempre un conjunto completo de archivos de implementación.
La aplicación puede especificar la distribución inicial cambiando la configuración regional predeterminada. Sin embargo, esto debe hacerse antes de que la aplicación se inicialice y cargue el complemento del método de entrada. Si no se realizan cambios en la configuración regional predeterminada, se utiliza la configuración regional actual del sistema.
La correspondencia con la configuración regional del teclado sigue esta secuencia:
layouts/<language>_<country>layouts/<language>_*layouts/fallback– la distribución predeterminada aquí es en_GB.
En primer lugar, se compara la configuración regional con el nombre completo de la misma. Si no hay una coincidencia completa, solo 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 realizada la selección de la configuración regional, el teclado actualiza la configuración regional de entrada y la dirección de entrada para que coincidan con la distribución actual. La aplicación puede recibir esta información a través de la interfaz QInputMethod.
A nivel interno, la configuración regional de entrada actual también se actualiza en QVirtualKeyboardInputEngine y en las instancias del método de entrada actuales.
Motor de entrada
El objeto del motor de entrada pertenece a ` InputContext`. Al igual que el ` InputContext`, solo hay una instancia del ` QVirtualKeyboardInputEngine`. El motor de entrada contiene funciones de la API que el teclado utiliza para asignar las interacciones del usuario, como los eventos de pulsación y liberación de teclas, al método de entrada.
Por ejemplo, los eventos de teclas del teclado virtual se asignan mediante los siguientes métodos:
Los métodos mencionados anteriormente están pensados para 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 asignar las pulsaciones de teclas físicas. Esto se debe a que la acción real solo se lleva a cabo cuando se suelta la tecla.
Si la pulsación de la tecla se interrumpe antes del evento de suelta de 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 pulsaciones de teclas. Su función principal es gestionar los eventos de pulsación de teclas y mantener la información de estado de la entrada del usuario. Interactúa con el editor de texto a través de ` QVirtualKeyboardInputContext ` mediante eventos de texto previo a la edición o eventos de teclas.
La instancia del método de entrada se puede crear de diversas formas, dependiendo del caso de uso:
KeyboardLayout::inputMethod: la distribución de teclado puede crear una instancia de método de entrada exclusivamente para dicha distribución. Cabe señalar que esta instancia se eliminará cuando cambie la distribución de teclado. Por lo tanto, este método suele limitarse a casos de uso muy concretos.KeyboardLayout::createInputMethod(): la distribución de teclado puede crear dinámicamente un método de entrada que se pueda utilizar con esta distribución y también con el « shared layouts » (por ejemplo, la distribución de símbolos). Esta es la forma preferida para crear métodos de entrada especializados, como los que implican idiomas complejos o la escritura manuscrita.DefaultInputMethod: 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 perdura más allá de los cambios de distribución de teclado entre idiomas y es la forma preferida de crear y anular el método de entrada predeterminado.
Complementos del teclado virtual
El directorio src/plugins del teclado virtual contiene los complementos existentes para el teclado virtual. Estos complementos son módulos QML estándar que se cargan de forma implícita mediante el módulo QML ` QtQuick.VirtualKeyboard.Plugins`.
Un complemento 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(). De lo 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/<IDIOMA_PAÍS>, por lo que es esencial utilizar esta ruta exacta también en el complemento. Las rutas de los recursos de Qt pueden solaparse, lo que significa que el complemento puede anular las distribuciones existentes en el teclado virtual.
También es posible anular las distribuciones de teclado integradas cargándolas directamente desde el sistema de archivos mediante la variable de entorno QT_VIRTUALKEYBOARD_LAYOUT_PATH.
Añadir un método de entrada
El complemento puede registrar un método de entrada que otros diseños de teclado puedan utilizar de forma predeterminada (como DefaultInputMethod) o un método de entrada que se utilice de forma privada en el complemento (proporcionando además un diseño de teclado personalizado, 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 por decidir qué interfaz se utiliza, QML o C++. En este ejemplo se utiliza la interfaz QML. La misma lógica e interfaces se aplican a la interfaz C++ QVirtualKeyboardAbstractInputMethod. En este caso, el complemento 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 motor de entrada llama al método InputMethod::inputModes() antes de establecer un modo de entrada. El método devuelve una lista de los modos de entrada disponibles en la configuración regional especificada.
Un método de entrada se inicializa en el método InputMethod::setInputMode() con una configuración regional y un modo de entrada. Tras establecer la configuración regional y el modo de entrada, el método de entrada debería estar listo para su uso.
InputMethod::reset() se invoca cuando es necesario restablecer un método de entrada. El restablecimiento solo debe restablecer el estado interno del método de entrada, y no el texto del usuario.
InputMethod::update() se invoca cuando se actualiza el contexto de entrada y es posible que el estado de entrada esté desincronizado. El método de entrada debe confirmar el texto actual.
Los eventos de pulsación de teclas se gestionan en InputMethod::keyEvent(). Este método gestiona un único evento de pulsación de tecla y devuelve true si el evento se ha procesado. De lo contrario, la pulsación de tecla es gestionada por el método de entrada predeterminado.
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 trabajo de entrada admite varios tipos de listas, como la lista de palabras candidatas. Las responsabilidades en la implementación de las listas se distribuyen de tal forma que el método de entrada se encarga del contenido y de las acciones, como el comportamiento al hacer clic. El marco de entrada se encarga de mantener el modelo de la lista y de presentarla en 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 de entrada. El método InputMethod::selectionLists() devuelve una lista de los tipos de listas de selección necesarios:
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 requiere 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)Relleno de elementos en las listas de selección
Los elementos se rellenan mediante funciones de devolución de llamada que proporcionan el número de elementos de una lista, así como los datos de cada elemento individual.
La llamada de retorno ` InputMethod::selectionListItemCount ` solicita el número de elementos de la lista identificada 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, SelectionListModel.Role.Display solicita los datos del texto que se muestra.
Respuesta a las acciones del usuario
Cuando el usuario selecciona un elemento de la lista, el método de entrada responde al evento mediante la llamada de retorno 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 manuscrita
Un método de entrada también puede utilizar datos de entrada procedentes 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 recopila la entrada en nombre del método de entrada. Del mismo modo, cuando se retira el dedo o el lápiz óptico, el evento finaliza con la llamada ` traceEnd `. El método de entrada procesa los datos recopilados y genera texto mediante la interfaz ` InputContext `.
Existen distribuciones de teclado predefinidas para la escritura manuscrita. Sin embargo, no se incluyen de forma predeterminada, por lo que el complemento de escritura manuscrita debe incorporarlas en sus propios recursos. Para ver ejemplos de cómo hacerlo, consulta los complementos de escritura manuscrita existentes de MyScript o Cerence.
Modelo de datos para la entrada de escritura a mano
El teclado virtual recopila los datos de escritura a mano en un modelo de datos especial QVirtualKeyboardTrace. Cada trazo representa un conjunto de datos muestreados a partir de un toque (por ejemplo, un deslizamiento por la pantalla). Habrá tantas instancias de QVirtualKeyboardTrace como toques haya en el área de entrada de escritura a mano.
Por definición, un «trace» es un conjunto de datos muestreados a partir de un toque. Además de los datos básicos de puntos, 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 inicio de un evento «trace».
El método de entrada no participa en la recopilación real de los datos de «trace». Sin embargo, el método de entrada tiene control total sobre la entrada, ya que puede aceptar o rechazar un « QVirtualKeyboardTrace » (por ejemplo, si hay demasiadas instancias que gestionar). Esto también permite un control preciso sobre el número de dedos que se pueden utilizar simultáneamente.
El método de entrada puede recopilar tantos trazos como considere oportuno y puede comenzar a procesarlos 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 retraso adecuado desde la última entrada, de modo que el procesamiento no afecte negativamente a la interfaz de usuario.
API de trazas para métodos de entrada
La API de trazas consta de los siguientes métodos virtuales, que el método de entrada debe implementar para recibir y procesar los datos de entrada de trazas.
Al implementar estos métodos, el método de entrada puede recibir y procesar datos procedentes de diversas fuentes de entrada (por ejemplo, la distribución del teclado o la 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 crear un nuevo objeto de rastreo. Si el método de entrada acepta la interacción, crea un nuevo objeto de rastreo y lo devuelve al llamante. A partir de ese momento, se recopilan los datos de rastreo hasta que se llama al método `traceEnd`.
Cuando se invoca el método `traceEnd`, el método de entrada puede comenzar a procesar los datos contenidos en el objeto de rastreo. Tras procesar los datos, el método de entrada debe destruir el objeto. Esto también elimina el rastreo representado en la pantalla.
Configuraciones de teclado
Las distribuciones de teclado se encuentran en el directorio src/layouts/builtin. Cada subdirectorio del directorio de distribuciones representa una configuración regional. El directorio de la configuración regional es una cadena con el formato «idioma_país», donde «idioma» es un código de idioma ISO 639 de dos letras en minúsculas, y «país» es un código de país ISO 3166 de dos o tres letras en mayúsculas.
Tipos de distribución
En los distintos modos de entrada se utilizan diferentes tipos de distribución de teclado. La distribución predeterminada, que se utiliza para la introducción de texto habitual, se denomina distribució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 llama «main.qml».
Lista de tipos de distribución compatibles:
mainLa distribución principal para la introducción de texto normalsymbolsDisposición de símbolos para caracteres especiales, etc. (se activa desde la disposición principal)numbersDisposición numérica para números formateados (se activa mediante Qt::ImhFormattedNumbersOnly)digitsDiseño «solo dígitos» (se activa mediante ` Qt::ImhDigitsOnly`)dialpadTeclado numérico para introducir números de teléfono (se activa pulsando Qt::ImhDialableCharactersOnly)handwritingDisposición de escritura manuscrita para el reconocimiento de escritura (se activa desde la disposición 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 se pueden configurar si es necesario:
property var inputMethod | Especifica un método de entrada para esta distribución. Si no se define el método de entrada, se utiliza el método de entrada actual. |
property int inputMode | Especifica un modo de entrada para esta disposición. |
property real keyWeight | Especifica el peso predeterminado de las teclas que se utiliza para todas las teclas de esta distribución de teclado. El peso de las teclas es un valor proporcional que afecta al tamaño de las teclas individuales en relación unas con otras. |
Las nuevas filas se añaden a la distribución del teclado utilizando el tipo « KeyboardRow ». El tipo « KeyboardRow » también puede especificar el peso de tecla predeterminado para sus elementos hijos. De lo contrario, el peso de tecla se hereda de su elemento padre.
Las nuevas teclas se añaden a la fila del teclado utilizando el tipo «Key» o uno de los tipos de tecla especializados. A continuación se muestra la lista de todos los tipos de tecla:
Tecla de retroceso para distribuciones de teclado | |
Tecla de cambio de idioma para distribuciones de teclado | |
Tecla Intro para distribuciones de teclado | |
Tecla de relleno para distribuciones de teclado | |
Tecla «Flick» para distribuciones de teclado | |
Tecla de modo de escritura a mano para las distribuciones de teclado | |
Tecla «Ocultar teclado» para las distribuciones de teclado | |
Tecla de modo de entrada para distribuciones de teclado | |
Tecla de caracteres normales para distribuciones de teclado | |
Tecla de modo genérico para distribuciones de teclado | |
Tecla de números especiales para distribuciones de teclado | |
Tecla «Shift» para las distribuciones de teclado | |
Tecla de espacio para las distribuciones de teclado | |
Tecla de modo de símbolos para distribuciones de teclado | |
Una tecla especializada para recopilar datos de entrada táctil |
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, los anchos de las teclas se calculan a partir de la relación entre sus pesos, y la altura se determina dividiendo el espacio de forma equitativa entre las filas del teclado.
En el ejemplo anterior, el tamaño de las teclas se hereda de los elementos padres en este orden:
Tecla > KeyboardRow > KeyboardLayout
El valor efectivo del peso de la tecla será 160. A modo de ejemplo, añadimos otra tecla que especifica un peso 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, el ancho de cada tecla se calcula de la siguiente manera:
anchura de la tecla en píxeles = peso de la tecla / SUMA(pesos de las teclas de una fila) * anchura de la fila en píxeles
Esto significa que el teclado se puede escalar a cualquier tamaño, mientras que los tamaños relativos de las teclas permanecen iguales.
Teclas alternativas
La tecla puede especificar una propiedad `alternativeKeys`, lo que da lugar a una ventana emergente que muestra una lista de teclas alternativas cuando el usuario pulsa y mantiene pulsada la tecla. La propiedad `alternativeKeys` puede especificar una cadena o una lista de cadenas. Si `alternativeKeys` es una cadena, el usuario puede seleccionar entre los caracteres de dicha cadena.
Estilos y distribuciones
Las distribuciones del teclado no pueden especificar ningún elemento visual. En su lugar, la distribución se visualiza mediante el estilo del teclado. Por otro lado, el estilo del 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 posible presentar en una sola distribución de teclado. Una solución consiste en integrar varias distribuciones de teclado en el mismo contexto utilizando el elemento ` 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 de teclado se activa asignando el identificador 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 para escritura a mano
Cada idioma que admita el reconocimiento de escritura manuscrita 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 de teclado
- proporciona una instancia de «HandwritingInputMethod» como método de entrada.
La distribución de escritura manuscrita también puede incluir el elemento « ChangeLanguageKey ». Para ello, es importante utilizar el atributo « customLayoutsOnly », que filtrará los idiomas que no utilicen la escritura manuscrita.
Tanto la distribución principal como la de escritura a mano deben contener una tecla para activar y desactivar el modo de entrada por escritura a mano. Esto se puede hacer añadiendo un « HandwritingModeKey » a la distribución.
Añadir diseños personalizados
El sistema de diseños de teclado virtual admite tanto diseños integrados como diseños personalizados. Los diseños integrados están incrustados 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 necesidad de recompilar el propio teclado virtual, o bien pueden ubicarse en un archivo de recursos.
La selección de distribuciones en tiempo de ejecución depende de 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 recurre a las distribuciones predeterminadas integradas.
Para evitar que las distribuciones integradas se incluyan en el complemento del teclado virtual cuando se utilicen distribuciones personalizadas, añade la opción ` -no-vkb-layouts ` al script ` configure `. Para obtener más información, consulta Opciones de configuración.
Estilos de teclado
El sistema de estilos del teclado virtual admite tanto estilos integrados como estilos personalizados. Los estilos integrados se incrustan como recursos de Qt en el binario del complemento, mientras que 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 viene determinada por la variable de entorno QT_VIRTUALKEYBOARD_STYLE, que puede establecerse con el nombre del estilo integrado, por ejemplo, «retro», o con cualquiera de los estilos personalizados instalados en el directorio Styles:
$$[QT_INSTALL_QML]/QtQuick/VirtualKeyboard/StylesEn caso de que la variable de entorno no esté configurada o contenga un nombre de estilo no válido, el teclado virtual utilizará por defecto el estilo integrado predeterminado.
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 de QML dentro de la estructura de directorios basada en URL QtQuick/VirtualKeyboard/Styles/. Consulte Ruta de importación de QML para obtener información sobre las rutas de importación de QML. El nombre del directorio no puede contener espacios ni caracteres especiales, salvo el guión bajo. Además, el nombre del directorio no puede coincidir con el de ninguno de los estilos integrados, que actualmente incluyen «default» y «retro».
Un buen punto de partida para crear un nuevo estilo es utilizar un estilo integrado ya existente como plantilla y editarlo. Puedes encontrar los estilos integrados en el directorio de fuentes del teclado virtual src/styles/builtin. Copia uno de los directorios que contenga un estilo integrado en el directorio Styles y cámbiale el nombre por «test». La estructura del directorio debería quedar ahora así:
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.pngEl archivo de configuración QRC, que en este caso es innecesario, se puede eliminar sin problema.
Nota: El archivo style.qml no debe renombrarse; de lo contrario, el teclado virtual no podrá cargar el estilo.
A continuación, abre el archivo style.qml en tu editor favorito y establece la propiedad resourcePrefix en una cadena vacía. El prefijo de recursos no es necesario, ya que los recursos se encuentran en el mismo directorio que el archivo style.qml.
Además, para que resulte más evidente que el estilo personalizado se está cargando y utilizando realmente, establece el fondo del teclado en un color diferente:
keyboardBackground: Rectangle {
color: "gray"
}El último paso es ejecutar la aplicación de ejemplo con tu estilo personalizado:
QT_VIRTUALKEYBOARD_STYLE=test virtualkeyboardUso de « Qt Virtual Keyboard » con QQuickWidget
Al utilizar « Qt Virtual Keyboard » en un « QQuickWidget » en un dispositivo táctil, es necesario establecer el atributo « Qt::WA_AcceptTouchEvents » mediante « QWidget::setAttribute()». Si no se establece este atributo, los eventos procedentes de un dispositivo táctil se convertirán en eventos de ratón sintetizados.
© 2026 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.