Entradas en un dispositivo Linux embebido
En tu dispositivo Linux embebido, cuando no hay ningún sistema de ventanas, las entradas del ratón, el teclado y la pantalla táctil se leen directamente a través de evdev o utilizando bibliotecas auxiliares como libinput o tslib. Sin embargo, este comportamiento requiere que los nodos de dispositivo /dev/input/event* sean legibles para el usuario. eglfs y linuxfb tienen todo el código de gestión de entradas compilado.
Utilizar libinput
libinput es una biblioteca para gestionar dispositivos de entrada que ofrece una alternativa al soporte de entrada propio de Qt, evdev. Para habilitar el uso de libinput, al configurar y compilar Qt, asegúrate de que los archivos de desarrollo de libudev y libinput estén disponibles. Si necesitas compatibilidad con el teclado, también es necesario xkbcommon. Con eglfs y linuxfb, no es necesario realizar ninguna acción adicional, ya que estos complementos utilizan libinput de forma predeterminada. Si la compatibilidad con libinput no está disponible o se ha establecido la variable de entorno QT_QPA_EGLFS_NO_LIBINPUT, se utilizarán en su lugar los propios controladores evdev de Qt.
Las siguientes variables de entorno están disponibles cuando se reciben eventos de entrada a través de libinput:
| Variable | Descripción |
|---|---|
QT_QPA_LIBINPUT_TOUCH_MATRIX | Especifica las dos primeras filas de la matriz de transformación 3x3 que se va a aplicar. Se espera que los valores estén separados por espacios. Consulte la documentación de libinput para obtener más detalles. |
Entrada en eglfs y linuxfb sin libinput
Parámetros como el nombre del nodo del dispositivo se pueden configurar en las variables de entorno QT_QPA_EVDEV_MOUSE_PARAMETERS, QT_QPA_EVDEV_KEYBOARD_PARAMETERS y QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS; separe las entradas con dos puntos. Estos parámetros son una alternativa a pasar la configuración en el argumento de línea de comandos -plugin y, con algunos backends, son esenciales. Sin embargo, eglfs y linuxfb utilizan controladores de entrada integrados, por lo que no se utiliza ningún argumento -plugin independiente.
Además, los controladores de entrada integrados se pueden desactivar configurando QT_QPA_EGLFS_DISABLE_INPUT (para eglfs) o QT_QPA_FB_DISABLE_INPUT (para linuxfb) en 1.
Ratón
El cursor del ratón aparece siempre que no se haya establecido QT_QPA_EGLFS_HIDECURSOR (para eglfs) o QT_QPA_FB_HIDECURSOR (para linuxfb) y el sistema de detección de dispositivos de Qt basado en libudev indique que hay al menos un ratón disponible. Cuando no hay soporte para libudev, el cursor del ratón se muestra siempre, a menos que se desactive explícitamente mediante la variable de entorno.
Si Qt se ha configurado con soporte para « libudev », se admite la conexión o desconexión de un dispositivo de entrada mientras la aplicación está en ejecución (conexión en caliente). En ese caso, los encabezados de desarrollo de « libudev » están presentes en el sysroot en el momento de la configuración.
El controlador de ratón « evdev » admite los siguientes parámetros adicionales:
| Parámetro | Descripción |
|---|---|
/dev/input/... | Especifica el nombre del dispositivo de entrada. Si no se especifica, Qt busca un dispositivo adecuado a través de libudev o recorriendo los nodos disponibles. |
nocompress | Por defecto, los eventos de entrada que no provocan un cambio de posición con respecto al último evento de ratón de Qt se comprimen. Solo se envía un nuevo evento de ratón de Qt tras un cambio en la posición o en el estado de los botones. Para desactivar este comportamiento, configura el parámetro ` nocompress `. |
dejitter | Especifica un límite de fluctuación; desactivado por defecto. |
grab | Cuando se establece en ` 1`, Qt se apropia del dispositivo para su uso exclusivo. |
abs | Algunas pantallas táctiles informan de coordenadas absolutas y no se pueden diferenciar de los paneles táctiles. En este caso, pasa abs para indicar que el dispositivo utiliza eventos absolutos. |
Teclado
El controlador de teclado « evdev » admite los siguientes parámetros adicionales:
| Parámetro | Descripción |
|---|---|
/dev/input/... | Especifica el nombre del dispositivo de entrada. Si no se especifica, Qt busca un dispositivo adecuado a través de libudev o recorriendo los nodos disponibles. |
grab | Habilita la captura del dispositivo de entrada. |
disable-zap | Desactiva la combinación de teclas «zap». Consulta la nota sobre « Ctrl+Alt+Backspace » más abajo. |
keymap | Especifica el nombre de un archivo de mapa de teclado personalizado. |
enable-compose | Habilita la composición. |
repeat-delay | Establece un retardo de repetición de teclas personalizado. |
repeat-rate | Establece una frecuencia de repetición de teclas personalizada. |
En sistemas Linux embebidos en los que no se han desactivado las sesiones de terminal, el comportamiento al pulsar una tecla puede resultar confuso, ya que el evento de entrada es procesado tanto por la aplicación Qt como por el tty. Para solucionar esto, se dispone de las siguientes opciones:
- Al iniciar la aplicación,
EGLFSyLinuxFBintentan desactivar el teclado de la terminal estableciendo el modo de teclado del tty enK_OFF. Esto evita que las pulsaciones de teclas se envíen a la terminal. Si se requiere el comportamiento estándar, establece la variable de entornoQT_QPA_ENABLE_TERMINAL_KEYBOARDen1. Ten en cuenta que esto solo funciona cuando la aplicación se inicia desde una consola remota, por ejemplo, a través dessh, y la entrada del teclado de la terminal permanece habilitada. - Una alternativa es utilizar el parámetro `
grab` del controlador de teclado `evdev`, pasando `grab=1` en `QT_QPA_EVDEV_KEYBOARD_PARAMETERS`. Esto da lugar a un intento de tomar el control del dispositivo de entrada. Si la `grab` tiene éxito, ningún otro componente del sistema recibirá eventos procedentes de él, siempre y cuando la aplicación Qt esté en ejecución. Este enfoque resulta más adecuado para aplicaciones que se inician de forma remota, ya que no requiere acceso al dispositivo tty. - Por último, en muchas imágenes especializadas de Linux embebido no tiene sentido tener habilitadas las sesiones de terminal estándar en primer lugar. Para obtener más detalles sobre cómo desactivar estas sesiones de terminal, consulta la documentación de tu entorno de compilación. Por ejemplo, al generar imágenes con Yocto Project, al desactivar `
SYSVINIT_ENABLED_GETTYS` se evita que se ejecute el proceso `getty`. Esto significa que no habrá entrada en ninguna de las terminales virtuales.
Si el mapa de teclas integrado por defecto no es suficiente, puede especificar uno diferente mediante el parámetro keymap.
Nota: Al igual que con otros archivos de configuración para eglfs, estos archivos de mapa de teclado heredados se consideran contenido de confianza que está totalmente controlado y gestionado por el creador del dispositivo o la plataforma. No está previsto que estén expuestos a los usuarios finales del dispositivo, ni están pensados para permitir la carga de archivos de mapa de teclado proporcionados por el usuario.
Advertencia: Con el mapa de teclas integrado, la combinación «zap» (Ctrl+Alt+Backspace) cierra la aplicación. La combinación es procesada por el controlador del teclado, por lo que la aplicación nunca recibe notificación al respecto y no puede impedirla. En un dispositivo en el que cualquier dispositivo de entrada similar a un teclado pueda, por lo tanto, apagar la interfaz de usuario, se debe pasar disable-zap en QT_QPA_EVDEV_KEYBOARD_PARAMETERS.
Nota: El cambiode consola (Ctrl+Alt+Fx) y el acorde de reinicio son reconocidos por el controlador del teclado, pero no se les da curso, por lo que, en la práctica, se ignoran.
Para generar un mapa de teclas personalizado, utiliza la utilidad kmap2qmap, que se encuentra en el módulo qttools. Los archivos fuente deben estar en el formato estándar de Linux kmap, que es compatible con el comando loadkeys del núcleo. Los archivos qmap se pueden generar de una de las siguientes formas:
- El proyecto Linux Console Tools (LCT).
- Los mapas de tecladoX.org X11 se pueden convertir al formato
kmapcon la utilidadckbcomp. - Dado que los archivos «
kmap» son archivos de texto plano, también se pueden crear manualmente.
kmap2qmap es un programa de línea de comandos que necesita al menos dos archivos como parámetros. El último parámetro es el archivo « .qmap » generado, mientras que todos los demás se interpretan como archivos « .kmap » de entrada. Por ejemplo:
kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmapNota: « kmap2qmap » no admite todos los (pseudo)símbolos que admite el núcleo de Linux. Por consiguiente, al convertir un mapa de teclado estándar, aparecerán varias advertencias relacionadas con « Show_Registers », « Hex_A », etc.; estos mensajes pueden ignorarse.
Táctil
Aunque no es necesario para las pantallas táctiles modernas, algunas pantallas táctiles resistivas más antiguas que solo admiten un único toque pueden requerir que se recurra al uso de tslib, en lugar de basarse en el protocolo multitáctil de Linux y los dispositivos de eventos.
Para habilitar la compatibilidad con tslib, establece la variable de entorno QT_QPA_EGLFS_TSLIB (para eglfs) o QT_QPA_FB_TSLIB (para linuxfb) en 1. Para cambiar el dispositivo, establece la variable de entorno TSLIB_TSDEVICE o indica el nombre del dispositivo en la línea de comandos. Ten en cuenta que el controlador de entrada tslib genera eventos de ratón y solo admite un único toque, a diferencia de evdevtouch, que también genera eventos QTouchEvent multitáctiles reales.
Nota: La selección y el filtradode dispositivos se delegan íntegramente a tslib. Esto significa que el propio archivo de configuración de tslib determina qué módulos de filtro se cargan en el proceso de la aplicación; Qt no los selecciona ni los enumera. Se recomienda utilizar libinput para los nuevos dispositivos.
El controlador táctil de evdev admite los siguientes parámetros adicionales:
| Parámetro | Descripción |
|---|---|
/dev/input/... | Especifica el nombre del dispositivo de entrada. Si no se especifica, Qt busca un dispositivo adecuado a través de ` libudev ` o recorriendo los nodos disponibles. |
rotate | En algunas pantallas táctiles, es necesario rotar las coordenadas estableciendo rotate en 90, 180 o 270. |
invertx y inverty | Especifica los parámetros para invertir las coordenadas X o Y en los eventos de entrada. |
Por ejemplo, si se pasan los siguientes valores a ` QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS ` antes de iniciar las aplicaciones, se dispondrá de un dispositivo táctil especificado explícitamente con las coordenadas invertidas. Esto resulta útil cuando la orientación de la pantalla real y la de la pantalla táctil no coinciden.
export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS=/dev/input/event5:rotate=180Tabletas con lápiz
El complemento « evdevtablet » ofrece compatibilidad básica con tabletas con lápiz de Wacom y similares. Solo genera eventos « QTabletEvent ». Para habilitarlo, introduce « QT_QPA_GENERIC_PLUGINS=evdevtablet » en el entorno o, alternativamente, pasa el argumento « -plugin evdevtablet » en la línea de comandos.
El complemento puede aceptar un parámetro de nodo de dispositivo, como QT_QPA_GENERIC_PLUGINS=evdevtablet:/dev/event1, si la detección automática de dispositivos de Qt (basada en libudev o en el recorrido de /dev/input/event*) no funciona o presenta un comportamiento anómalo.
Dispositivos de entrada de depuración
Es posible mostrar cierta información en la salida de depuración activando la regla de registro « qt.qpa.input », por ejemplo, estableciendo la variable de entorno « QT_LOGGING_RULES » en « qt.qpa.input=true ». Esto resulta útil para detectar qué dispositivo se está utilizando o para solucionar problemas relacionados con la detección de dispositivos.
Para obtener un registro más detallado de los subsistemas de entrada (ratón, teclado, pantalla táctil), habilita todas las categorías de registro relacionadas con la entrada mediante:
export QT_LOGGING_RULES="qt.qpa.input.*=true;qt.qpa.events=true"Utilizar imágenes de cursor de ratón personalizadas
eglfs incluye su propio conjunto de imágenes de cursores de ratón de 32x32. Si estas no son suficientes, puedes proporcionar un atlas de cursores personalizado estableciendo la variable de entorno ` QT_QPA_EGLFS_CURSOR ` con el nombre de un archivo JSON. Este archivo también se puede integrar en la aplicación a través del sistema de recursos de Qt.
Por ejemplo, un atlas de cursores integrado con 8 imágenes de cursor por fila se puede especificar de la siguiente manera:
{
"image": ":/cursor-atlas.png",
"cursorsPerRow": 8,
"hotSpots": [
[7, 2],
[12, 3],
[12, 12],
...
]
}Ten en cuenta que se espera que las imágenes estén muy compactadas en el atlas; la anchura y la altura de los cursores se determinan en función del tamaño total de la imagen y de la configuración de ` cursorsPerRow `. Los atlas también deben proporcionar una imagen para todos los cursores compatibles.
Nota: Al igual que con otros archivos de configuración de eglfs, el atlas de cursores se considera contenido de confianza que está totalmente controlado y gestionado por el creador del dispositivo o la plataforma. No está previsto que se muestre a los usuarios finales del dispositivo.
Las claves « image » y « hotSpots », así como un valor distinto de cero para « cursorsPerRow », son obligatorias, y « hotSpots » debe contener una entrada para cada forma de cursor compatible. Un archivo en el que falte alguno de estos elementos se rechaza con una advertencia y el cursor queda desactivado.
© 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.