Guía de implementación
Descripción general
Este documento describe cómo implementar y utilizar el complemento « Qt Virtual Keyboard » con aplicaciones Qt.
Implementación
Los distintos complementos y archivos de Qt Virtual Keyboard se instalan en las siguientes ubicaciones:
| Elemento | Ruta de instalación en el escritorio | Ruta de instalación de Boot2Qt |
|---|---|---|
| qtvirtualkeyboardplugin: complemento de contexto de entrada de la plataforma | <QT_INSTALL_PLUGINS>/platforminputcontexts | /system/plugins/platforminputcontexts |
| qtvkbplugin: complemento QML | <QT_INSTALL_QML>/QtQuick/VirtualKeyboard | /system/qml/QtQuick/VirtualKeyboard |
| Complemento QML «qtvkbcomponentsplugin» | <QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Components | /system/qml/QtQuick/VirtualKeyboard/Components |
| qtvkblayoutsplugin: complemento QML | <QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Layouts | /system/qml/QtQuick/VirtualKeyboard/Layouts |
| qtvkbpluginsplugin: complemento QML | <QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Plugins | /system/qml/QtQuick/VirtualKeyboard/Plugins |
| Complementos QML de la extensión | <QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Plugins/* | /system/qml/QtQuick/VirtualKeyboard/Plugins/* |
| qtvkbsettingsplugin: complemento QML | <QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Settings | /system/qml/QtQuick/VirtualKeyboard/Settings |
| qtvkbstylesplugin: complemento QML | <QT_INSTALL_QML>/QtQuick/VirtualKeyboard/Styles | /system/qml/QtQuick/VirtualKeyboard/Styles |
| Datos del teclado virtual | <QT_INSTALL_DATA>/qtvirtualkeyboard | /system/qtvirtualkeyboard |
Dependencias
Más información en «Implementación de las bibliotecas de Qt».
Método de integración
Qt Virtual Keyboard Actualmente admite dos métodos de integración alternativos para utilizar el complemento:
Desktop: no requiere cambios en las aplicaciones existentes. El teclado virtual está disponible para todas las aplicaciones Qt del sistema.En este método de integración, el teclado se muestra en una ventana dedicada de nivel superior.
Application: el teclado virtual se integra directamente en la propia aplicación Qt mediante la instanciación de un elemento ` InputPanel ` en QML.Este método es obligatorio en entornos en los que no se admiten varias ventanas de nivel superior (como los dispositivos integrados), pero también puede utilizarse en aplicaciones de escritorio.
Los Qt Wayland Compositors también pueden utilizar este método para proporcionar un teclado virtual del lado del servidor. Consulta la sección siguiente para obtener más detalles.
El método de integración se selecciona automáticamente mediante los archivos del proyecto. Sin embargo, en entornos de escritorio, es posible anular el método de integración de escritorio y utilizar en su lugar el método de integración de la aplicación, mediante la variable de entorno QT_VIRTUALKEYBOARD_DESKTOP_DISABLE o añadiendo -no-vkb-desktop a la línea de comandos de configure.
Uso de ` Qt Virtual Keyboard ` con Qt Wayland
En esta sección se explica cómo utilizar Qt Virtual Keyboard para interactuar con el ejemplo «Qt Widgets Line Edits» utilizando el ejemplo «Fancy Compositor» como compositor.
Utilizaremos Ubuntu 18.04 para ejecutar el ejemplo, con X11 como sistema de ventanas. El compositor del ejemplo (fancy-compositor) se abrirá como una ventana dentro de una sesión de X11.
- Inicia el compositor:
QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_CLIENT_BUFFER_INTEGRATION=xcomposite-egl \ QT_IM_MODULE=qtvirtualkeyboard ./fancy-compositor -platform xcb - Antes de ejecutar la aplicación cliente, asegúrate de que QT_IM_MODULE no esté definido:
unset QT_IM_MODULE - Inicia el ejemplo «Line Edits» como cliente:
./lineedits -platform wayland - Haz clic en un campo de edición de línea y se abrirá el panel de entrada de Qt Virtual Keyboard.
Si surgen problemas, se pueden configurar las siguientes variables de entorno al ejecutar el compositor para obtener información de depuración que ayude a diagnosticar el problema:
WAYLAND_DEBUG=1
QT_LOGGING_RULES="qt.virtualkeyboard=true;qt.qpa.wayland*=true"Carga del complemento
En ambos métodos de integración, la aplicación debe utilizar la variable de entorno QT_IM_MODULE para cargar el complemento. Por ejemplo:
$ QT_IM_MODULE=qtvirtualkeyboard myappo en la función main():
qputenv("QT_IM_MODULE", QByteArray("qtvirtualkeyboard"));En el método de integración de escritorio, este paso es todo lo que se necesita para utilizar Qt Virtual Keyboard. En el método de integración de la aplicación, es necesario que la aplicación cree una instancia de InputPanel, tal y como se explica en el siguiente capítulo.
Creación de InputPanel
El siguiente ejemplo muestra cómo crear un InputPanel y cómo dividir el área de la pantalla con el contenedor de la aplicación.
import QtQuick
import QtQuick.VirtualKeyboard
Item {
id: root
Item {
id: appContainer
anchors.left: parent.left
anchors.top: parent.top
anchors.right: parent.right
anchors.bottom: inputPanel.top
...
}
InputPanel {
id: inputPanel
y: Qt.inputMethod.visible ? parent.height - inputPanel.height : parent.height
anchors.left: parent.left
anchors.right: parent.right
}
}El panel de entrada debe ser un elemento hermano situado junto al contenedor de la aplicación. Es importante no colocar el panel de entrada dentro del contenedor de la aplicación, ya que, de hacerlo, se superpondría con el contenido de la aplicación. Además, la altura del panel de entrada se actualizará automáticamente en función del ancho disponible; la relación de aspecto del panel de entrada es constante.
Parámetros del complemento
Algunos parámetros pueden especificarse añadiéndolos al valor del QT_IM_MODULE (tras dos puntos), por ejemplo, QT_IM_MODULE=qtvirtualkeyboard:wordCandidateListVisible. Otros parámetros son pares clave-valor separados por "=".
| Parámetro | Finalidad |
|---|---|
| wordCandidateListVisible | Muestra la lista de palabras candidatas. |
| wordCandidateListAutoCommitWord | Activa la función AutoCommit para la lista de palabras candidatas. |
| pantalla completa | Utilizar el modo de pantalla completa |
| style=<nombre> | Establece el estilo |
| locale=<nombre> | Establecer la configuración regional |
Variables de entorno
El módulo define varias variables de entorno, que se enumeran a continuación:
| Variable | Finalidad |
|---|---|
| QT_VIRTUALKEYBOARD_HUNSPELL_DATA_PATH | Anula la ubicación de los archivos de datos de Hunspell. La ubicación por defecto depende del valor de ` Consulte Integración de Hunspell para obtener más información. |
| QT_VIRTUALKEYBOARD_PINYIN_DICTIONARY | Anula la ubicación del diccionario Pinyin. Por defecto, el diccionario se incluye en los recursos del complemento. Para desactivar la inclusión de recursos, añade -vkb-no-bundle-pinyin a la línea de comandos de configuración de Qt. En este caso, la ubicación predeterminada depende del valor de ` |
| QT_VIRTUALKEYBOARD_CANGJIE_DICTIONARY | Anula la ubicación del diccionario Cangjie. Por defecto, el diccionario viene incluido en los recursos del complemento. Para desactivar la inclusión de recursos, añade -vkb-no-bundle-tcime a la línea de comandos de configuración de Qt. En este caso, la ubicación por defecto depende del valor de ` |
| QT_VIRTUALKEYBOARD_ZHUYIN_DICTIONARY | Anula la ubicación del diccionario Zhuyin. Por defecto, el diccionario se incluye en los recursos del complemento. Para desactivar la inclusión de recursos, añade -vkb-no-bundle-tcime a la línea de comandos de configuración de Qt. En este caso, la ubicación predeterminada depende del valor de ` |
| QT_VIRTUALKEYBOARD_PHRASE_DICTIONARY | Anula la ubicación del diccionario de frases. Por defecto, el diccionario se incluye en los recursos del complemento. Para desactivar la inclusión de recursos, añade -vkb-no-bundle-tcime a la línea de comandos de configuración de Qt. En este caso, la ubicación por defecto depende del valor de ` |
| QT_VIRTUALKEYBOARD_CERENCE_HWR_DB_PATH | Especifica la ubicación de la base de datos de escritura manuscrita de Cerence Handwriting. Las ubicaciones de búsqueda predeterminadas para la base de datos de escritura manuscrita de Cerence Handwriting son:
La variable de entorno puede contener varias rutas. Las rutas se separan con punto y coma en Windows y con dos puntos en otros sistemas operativos. |
| QT_VIRTUALKEYBOARD_XT9_LDB_PATH | Especifica la ubicación de las bases de datos XT9. Las rutas de búsqueda predeterminadas para los archivos LDB son:
Se pueden especificar rutas de búsqueda adicionales configurando esta variable de entorno. Las rutas múltiples se separan con punto y coma en Windows y con dos puntos en otros sistemas operativos. Los archivos LDB son compartidos entre los complementos XT9 y Cerence Handwriting, por lo que esta variable de entorno afecta a ambos complementos. |
| QT_VIRTUALKEYBOARD_STYLE | Especifica la ubicación del estilo que se va a utilizar con el teclado virtual. Esto también se puede especificar en QML estableciendo ` VirtualKeyboardSettings::styleName`, o en el momento de la compilación utilizando las opciones de configuración. |
| QT_VIRTUALKEYBOARD_LAYOUT_PATH | Especifica la ubicación de las distribuciones que se utilizarán con el teclado virtual. |
| QT_VIRTUALKEYBOARD_DESKTOP_DISABLE | Desactiva el método de integración con el escritorio. |
| QT_VIRTUALKEYBOARD_FORCE_EVENTS_WITHOUT_FOCUS | Habilita Qt Virtual Keyboard para enviar eventos de teclas y utilizar la tecla Mayús sin que haya ningún campo de entrada de texto activo. Esta variable debe configurarse explícitamente en el entorno de ejecución de una aplicación que desee beneficiarse de ello. No basta con utilizar ` qputenv()` en la propia aplicación. |
© 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.