Inputs on an Embedded Linux Device
On your Embedded Linux device, when there's no windowing system present, the mouse, keyboard, and touch input are read directly via evdev or using helper libraries such as libinput or tslib. However, this behavior requires that device nodes
/dev/input/event* are readable by the user. eglfs and linuxfb have all the input handling code compiled-in.
Use libinput
libinput is a library to handle input devices that offers an alternative to the Qt's own evdev input support. To enable using libinput, when you configure and build Qt, make sure that the development files for libudev and libinput are available. If you require keyboard support, then xkbcommon is also necessary. With eglfs and linuxfb, no further actions are necessary as these plugins use libinput by default. If libinput support is not available or the QT_QPA_EGLFS_NO_LIBINPUT environment variable is set, then Qt's own evdev handlers are used instead.
Input on eglfs and linuxfb without libinput
Parameters like the device node name can be set in the QT_QPA_EVDEV_MOUSE_PARAMETERS, QT_QPA_EVDEV_KEYBOARD_PARAMETERS and QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS environment variables; separate your entries with colons. These parameters are an alternative to passing the settings in the -plugin command-line argument, and with some backends they are essential. But eglfs and linuxfb use built-in input handlers so there's no separate -plugin argument in use.
Additionally, the built-in input handlers can be disabled by setting QT_QPA_EGLFS_DISABLE_INPUT (for eglfs) orQT_QPA_FB_DISABLE_INPUT(for linuxfb) to 1.
Mouse
The mouse cursor shows up whenever QT_QPA_EGLFS_HIDECURSOR (for eglfs) or QT_QPA_FB_HIDECURSOR (for linuxfb) isn't set and Qt's libudev-based device discovery reports that at least one mouse is available. When libudev support is not present, the mouse cursor is always displayed; unless it's explicitly disabled via the environment variable.
If Qt was configured with libudev support, connecting or disconnecting an input device while the application is running (hot plugging) is supported. Then libudev development headers are present in the sysroot at configure time.
The evdev mouse handler supports the following extra parameters:
| Parameter | Description |
|---|---|
| /dev/input/... | Specifies the name of the input device. If unspecified, Qt looks for a suitable device either via libudev or by traversing the available nodes. |
| nocompress | By default, input events that don't lead to changing the position compared to the last Qt mouse event are compressed. A new Qt mouse event is sent only after a change in the position or button state. To disable this behavior, set the nocompress parameter. |
| dejitter | Specifies a jitter limit; disabled by default. |
| grab | When set to 1, Qt grabs the device for exclusive use. |
| abs | Some touchscreens report absolute coordinates and can't be differentiated from touchpads. In this case, pass abs to indicate that the device is using absolute events. |
Keyboard
The evdev keyboard handler supports the following extra parameters:
| Parameter | Description |
|---|---|
| /dev/input/... | Specifies the name of the input device. If unspecified, Qt looks for a suitable device either via libudev or by traversing the available nodes. |
| grab | Enables grabbing the input device. |
| keymap | Specifies the name of a custom keyboard map file. |
| enable-compose | Enables compositing. |
| repeat-delay | Sets a custom key repeat delay. |
| repeat-rate | Sets a custom key repeat rate. |
On Embedded Linux systems that don't have their terminal sessions disabled, the behavior on a key press can be confusing, as the input event is processed by the Qt application and the tty. To overcome this, the following options are available:
-
On application startup, EGLFS and LinuxFB attempt to disable the terminal keyboard by setting the tty's keyboard mode to K_OFF. This prevents keystrokes from being sent to the terminal. If the standard behavior is required, set the
QT_QPA_ENABLE_TERMINAL_KEYBOARDenvironment variable to 1. Note that this works only when the application is launched from a remote console, via ssh for example, and the terminal keyboard input remains enabled. -
An alternative approach is to use the evdev keyboard handler's grab parameter by passing grab=1 in
QT_QPA_EVDEV_KEYBOARD_PARAMETERS. This results in trying to get a grab on the input device. If the grab is successful, no other components in the system receive events from it, as long as the Qt application is running. This approach is more suitable for applications that start remotely as it doesn't need access to the tty device. -
Finally, for many specialized Embedded Linux images it doesn't make sense to have the standard terminal sessions enabled in the first place. For more details on how to disable these terminal sessions, refer to your build environment's Documentation. For example, when generating images using the Yocto Project, unsetting SYSVINIT_ENABLED_GETTYS results in having no getty process running. This means, there's no input on any of the virtual terminals.
If the default built-in keymap is not sufficient, you can specify a different one either via the keymap parameter or via the eglfs-specific loadKeymap() function. The latter allows for switching the keymap at runtime. However, this behavior requires using eglfs' built-in keyboard handler; it is not supported when the keyboard handler is loaded via the -plugin command-line parameter.
Note: Special system key combinations, such as console switching (Ctrl+Alt+Fx) or zap (Ctrl+Alt+Backspace) are not currently supported and are ignored.
To generate a custom keymap, use the kmap2qmap utility, that can be found in the qttools module. The source files have to be in standard Linux kmap format, which is understood by the kernel's loadkeys command. qmap files can be generated in one of the following ways:
- The Linux Console Tools (LCT) project.
- X.org X11 keymaps can be converted to the kmap format with the ckbcomp utility.
- As kmap files are plain-text files, they can also be hand crafted.
kmap2qmap is a command line program, that needs at least 2 files as parameters. The last parameter is the generated .qmap file, while all the others are parsed as input .kmap files. For example:
kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap
Note: kmap2qmap doesn't support all the (pseudo) symbols that the Linux kernel supports. Consequently, when you convert a standard keymap, there'll be a number of warnings regarding Show_Registers, Hex_A, and so on; these messages can be ignored.
Touch
While it's not necessary for modern touch screens, some resistive, single-touch touch screens may require that you fallback to using tslib instead of relying on the Linux multi-touch protocol and the event devices.
To enable tslib support, set the QT_QPA_EGLFS_TSLIB (for eglfs) or QT_QPA_FB_TSLIB (for linuxfb) environment variable to 1. To change the device, set the TSLIB_TSDEVICE environment variable or pass the device name on the command-line. Note that the tslib input handler generates mouse events and supports single touch only, as opposed to evdevtouch which generates true multi-touch QTouchEvent events too.
The evdev touch handler supports the following extra parameters:
| Parameter | Description |
|---|---|
| /dev/input/... | Specifies the name of the input device. If unspecified, Qt looks for a suitable device either via libudev or by traversing the available nodes. |
| rotate | On some touch screens the coordinates must be rotated by setting rotate to 90, 180, or 270. |
| invertx and inverty | Specifies the parameters to invert the X or Y coordinates in the input events. |
For example, if you pass the following values to QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS before launching applications, you'd have an explicitly specified touch device with the coordinates flipped. This is useful when the orientation of the actual screen and the touch screen don't match.
export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS=/dev/input/event5:rotate=180
Pen-based Tablets
The evdevtablet plugin provides basic support for Wacom and similar pen-based tablets. It generates QTabletEvent events only. To enable it, pass QT_QPA_GENERIC_PLUGINS=evdevtablet in the environment or, alternatively, pass the -plugin evdevtablet argument on the command-line.
The plugin can take a device node parameter, such as QT_QPA_GENERIC_PLUGINS=evdevtablet:/dev/event1, if Qt's automatic device discovery (based either on libudev or traversing /dev/input/event*) isn't functional or is misbehaving.
Debug Input Devices
It's possible to print some information to the debug output by enabling the qt.qpa.input logging rule, for example by setting the QT_LOGGING_RULES environment variable to qt.qpa.input=true. This is useful for detecting which device is being used, or for troubleshooting device discovery issues.
export QT_LOGGING_RULES=qt.qpa.*=true
Use Custom Mouse Cursor Images
eglfs comes with its own set of 32x32-sized mouse cursor images. If these are insufficient, you can provide a custom cursor atlas by setting the QT_QPA_EGLFS_CURSOR environment variable to the name of a JSON file. This file can also be embedded into the application via The Qt Resource System.
For example, an embedded cursor atlas with 8 cursor images per row can be specified as follows:
{
"image": ":/cursor-atlas.png",
"cursorsPerRow": 8,
"hotSpots": [
[7, 2],
[12, 3],
[12, 12],
...
]
}
Note that the images are expected to be tightly packed in the atlas; the width and height of the cursors are determined based on the total image size and the cursorsPerRow setting. Atlases must also provide an image for all of the supported cursors.
BROWSER
BT_TEST_DEVICE
COMPUTERNAME
COMSPEC
DBUS_SESSION_BUS_ADDRESS
DEBUG
DEFAULT_BROWSER
DESKTOP_SESSION
DESKTOP_STARTUP_ID
DEVICE_IP
DISABLE_NI_WARNING
DISPLAY
DXSDK_DIR
DYLD_LIBRARY_PATH
EGLFS_X11_FULLSCREEN
EGLFS_X11_SIZE
EGL_PLATFORM
ENGINIO_API_URL
ENGINIO_CREDENTIALS_FILE_PATH
ENGINIO_EMAIL_ADDRESS
ENGINIO_LOGIN_PASSWORD
ExtensionSdkDir
GIT_BRANCH
HOME
HOMEDRIVE
HOMEPATH
INCLUDE
JAVA_HOME
JENKINS_HOME
KDEDIRS
KDEHOME
KDE_SESSION_VERSION
LANG
LANGUAGE
LC_ALL
LC_CTYPE
LC_MEASUREMENT
LC_MESSAGES
LC_MONETARY
LC_NUMERIC
LC_TIME
LD_LIBRARY_PATH
LIB
MINISTRO_ANDROID_STYLE_PATH
MINISTRO_SSL_CERTS_PATH
NATIVEDEBUG
NATIVEDEBUGSPEED
NEMO_RESOURCE_CLASS_OVERRIDE
ORIENTATION
PATH
PATHEXT
PROMPT
PULSE_GIT_BRANCH
PULSE_TESTR_BRANCH
PlatformToolset
QDBUS_DEBUG
QDECLARATIVELANGUAGE_UPDATEERRORS
QMAKE
QMAKEFLAGS
QML2_IMPORT_PATH
QMLSCENE_DEVICE
QMLSCENE_IMPORT_NAME
QMLVISUAL_ALL
QML_IMPORT_PATH
QML_LEAK_CHECK
QML_NO_THREADED_RENDERER
QQNX_DISABLE_POWER_SAVE
QQNX_DISPLAY_DEPTH
QQNX_PHYSICAL_SCREEN_SIZE
QQNX_RENDERER_DEFAULT_AUDIO_SINK
QSG_ANTIALIASING_METHOD
QSG_DISTANCEFIELD_ANTIALIASING
QSG_FIXED_ANIMATION_STEP
QSG_RENDERER_BATCH_NODE_THRESHOLD
QSG_RENDERER_BATCH_VERTEX_THRESHOLD
QSG_RENDERER_BUFFER_STRATEGY
QSG_RENDERER_DEBUG
QSG_RENDER_LOOP
QSG_SANITY_CHECK
QSG_VISUALIZE
QT3D_DEBUG_MODEL
QT3D_LOG_EVENTS
QT3D_OPTIONS
QTCOMPOSE
QTCONTACTS_MANAGER_OVERRIDE
QTEST_ENABLE_EXTRA_SELFTESTS
QTEST_EVENT_DELAY
QTEST_EXTERNAL_DEBUG
QTEST_EXTERNAL_RUN
QTEST_KEEP_IMAGEDATA
QTEST_KEYEVENT_DELAY
QTEST_MOUSEEVENT_DELAY
QTEST_SERIALPORT_RECEIVER
QTEST_SERIALPORT_SENDER
QTSCRIPT_TEST_CONFIG_DIR
QTSCRIPT_TEST_CONFIG_SUFFIX
QTSCRIPT_TEST_DIR
QTTESTBROWSER_USE_ARGB_VISUALS
QTWEBENGINEPROCESS_PATH
QTWEBKIT_INSPECTOR_SERVER
QTWEBKIT_PLUGIN_PATH
QT_ACCEL_DATADIVISOR
QT_ACCEL_DELIMITER
QT_ACCEL_FILEPATH
QT_ANCHORLAYOUT_NO_SIMPLIFICATION
QT_ANDROID_APP_ICON_SIZE
QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND
QT_ANDROID_FONTS
QT_ANDROID_FONTS_MONOSPACE
QT_ANDROID_FONTS_SERIF
QT_ANDROID_FONT_LOCATION
QT_ANDROID_MAX_ASSETS_CACHE_SIZE
QT_ANDROID_MAX_PREPOPULATED_ASSETS_CACHE_SIZE
QT_ANDROID_MINIMUM_MOUSE_DOUBLE_CLICK_DISTANCE
QT_ANDROID_RASTER_IMAGE_DEPTH
QT_ANDROID_THEME
QT_ANDROID_THEME_DISPLAY_DPI
QT_ANGLE_PLATFORM
QT_AUTH_PASSWORD
QT_AUTH_URL
QT_AUTH_USER
QT_BLOCK_EVENT_LOOPS_WHEN_SUSPENDED
QT_COMPOSITOR_NEGATE_INVERTED_Y
QT_DBL_CLICK_DIST
QT_DEBUG_FPS
QT_DEBUG_PLUGINS
QT_DEVICE_PIXEL_RATIO
QT_DF_BASE
QT_DF_BASEDEVIATION
QT_DF_RANGE
QT_DF_SCALEFORMAXDEV
QT_DF_SCALEFORNODEV
QT_DIRECTFB_BLITTER_DEBUGPAINT
QT_DRAW_SCENE_ITEM_RECTS
QT_ENABLE_REGEXP_JIT
QT_FACEBOOK_ACCESS_TOKEN
QT_FILE_SELECTORS
QT_FLUSH_PAINT
QT_FLUSH_PAINT_EVENT
QT_FLUSH_UPDATE
QT_GRAPHICSLAYOUT_DEBUG
QT_GSTREAMER_CAMERABIN_FLAGS
QT_GSTREAMER_CAMERABIN_SRC
QT_GSTREAMER_CAMERABIN_VIDEOSRC
QT_GSTREAMER_PLAYBIN_FLAGS
QT_GSTREAMER_USE_PLAYBIN_VOLUME
QT_HARFBUZZ
QT_HASH_SEED
QT_HAVE_TEST_FONTS
QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING
QT_IM_MODULE
QT_LANCELOT_DIR
QT_LANCELOT_SERVER
QT_LAYOUT_DEBUG
QT_LOGGING_CONF
QT_LOGGING_RULES
QT_LOGGING_TO_CONSOLE
QT_MESSAGE_PATTERN
QT_MODULE_TO_TEST
QT_NECESSITAS_COMPATIBILITY_LONG_PRESS
QT_NO_ANTIALIASING
QT_NO_CPU_FEATURE
QT_NO_FAST_MOVE
QT_NO_FAST_SCROLL
QT_NO_FT_CACHE
QT_NO_SFW_BACKGROUND_OPERATION
QT_NO_SUBTRACTOPAQUESIBLINGS
QT_ONSCREEN_PAINT
QT_OPENGL
QT_OPENGL_DLL
QT_PAINT_FALLBACK_OVERLAY
QT_PLUGIN_PATH
QT_PROXY_HOST
QT_PROXY_PASSWORD
QT_PROXY_PORT
QT_PROXY_USER
QT_QPA_EGLFS_CURSOR
QT_QPA_EGLFS_DEBUG
QT_QPA_EGLFS_DEPTH
QT_QPA_EGLFS_DISABLE_INPUT
QT_QPA_EGLFS_FB
QT_QPA_EGLFS_FORCE888
QT_QPA_EGLFS_FORCEVSYNC
QT_QPA_EGLFS_HEIGHT
QT_QPA_EGLFS_HIDECURSOR
QT_QPA_EGLFS_NO_SURFACEFLINGER
QT_QPA_EGLFS_PHYSICAL_HEIGHT
QT_QPA_EGLFS_PHYSICAL_WIDTH
QT_QPA_EGLFS_SWAPINTERVAL
QT_QPA_EGLFS_WIDTH
QT_QPA_ENABLE_TERMINAL_KEYBOARD
QT_QPA_EVDEV_DEBUG
QT_QPA_EVDEV_KEYBOARD_PARAMETERS
QT_QPA_EVDEV_MOUSE_PARAMETERS
QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS
QT_QPA_FB_HIDECURSOR
QT_QPA_FONTDIR
QT_QPA_GENERIC_PLUGINS
QT_QPA_KMS_HIDECURSOR
QT_QPA_PLATFORM
QT_QPA_PLATFORMTHEME
QT_QPA_PLATFORM_PLUGIN_PATH
QT_QPA_VERBOSE
QT_QUICK_CONTROLS_STYLE
QT_QUICK_CORE_PROFILE
QT_SENSORS_LOAD_PLUGINS
QT_STYLE_OVERRIDE
QT_TEST_CI
QT_TEST_EXAMPLE_PRIORITY
QT_TEST_NOEXAMPLES
QT_TEST_NOTOOLS
QT_USE_ANDROID_NATIVE_DIALOGS
QT_USE_ANDROID_NATIVE_STYLE
QT_USE_NATIVE_WINDOWS
QT_USE_WINRT_NATIVE_DIALOGS
QT_VIDEONODE
QT_WAYLAND_CLIENT_BUFFER_INTEGRATION
QT_WAYLAND_DECORATION
QT_WAYLAND_DISABLE_WINDOWDECORATION
QT_WAYLAND_FORCE_DPI
QT_WAYLAND_HARDWARE_INTEGRATION
QT_WAYLAND_IGNORE_BIND_DISPLAY
QT_WAYLAND_SERVER_BUFFER_INTEGRATION
QT_WAYLAND_SHELL_INTEGRATION
QT_WEBENGINE_USE_EXPERIMENTAL_SCREEN_CAPTURE
QT_WEBKIT2_DEBUG
QT_WEBKIT2_PP_CMD_PREFIX
QT_WEBKIT2_WP_CMD_PREFIX
QT_WEBKIT_DISABLE_UIPROCESS_DUMPPIXELS
QT_WEBKIT_FORCE_FULLSCREEN_VIDEO
QT_WEBKIT_LOG
QT_WEBKIT_PAUSE_UI_PROCESS
QT_WEBKIT_PAUSE_WEB_PROCESS
QT_WEBKIT_SUPPRESS_WEB_PROCESS_OUTPUT
QT_WEBKIT_THEME_NAME
QT_WINVER_OVERRIDE
QT_XCB_NO_GRAB_SERVER
QT_XKB_CONFIG_ROOT
QUERY_STRING
QV4_FORCE_INTERPRETER
QV4_MM_AGGRESSIVE_GC
QV4_MM_MAXBLOCK_SHIFT
QV4_MM_MAX_CHUNK_SIZE
QV4_MM_STATS
QV4_NO_INTERPRETER_STACK_SLOT_ALLOCATION
QV4_NO_OPT
QV4_NO_REGALLOC
QV4_NO_SSA
QV4_SHOW_ASM
QV4_SHOW_IR
Q_DBUS_BLOCKING_CALL_MAIN_THREAD_WARNING_MS
Q_DBUS_BLOCKING_CALL_OTHER_THREAD_WARNING_MS
Q_WARN_EMPTY_MESH
SENSORLOG
SHOW_EXIT_VALUE
STRESSDEBUG
SystemDrive
SystemRoot
TEMP
TEST_TMPDIR
TMP
TMPDIR
TSLIB_TSDEVICE
TZ
UNICODEMAP_JP
USER
USERPROFILE
VCINSTALLDIR
VCInstallDir
WEBKIT_SHOW_COMPOSITING_DEBUG_VISUALS
WindowsSdkDir
XCOMPOSEFILE
XCURSOR_SIZE
XCURSOR_THEME
XDG_CACHE_HOME
XDG_CONFIG_DIRS
XDG_CONFIG_HOME
XDG_CURRENT_DESKTOP
XDG_DATA_DIRS
XDG_DATA_HOME
XDG_RUNTIME_DIR
all_proxy
ftp_proxy
http_proxy
https_proxy
no_proxy
qgetenv(#var)
qgetenv()
qgetenv(const char *varName)
qgetenv(debugBackingStoreEnvironmentVariable)
qgetenv(devicePixelRatioEnvVar)
qgetenv(envVar)
qgetenv(env_override)
qgetenv(environment)
qgetenv(envname)
qgetenv(libraryPath)
qgetenv(name)
qgetenv(resourceNameVar)
qgetenv(string.mid(1, string.size()
qgetenv(string.mid(rep + 2, reg_var.matchedLength()
qgetenv(var.toLatin1()
qgetenv(var.toLocal8Bit()
qgetenv(varName)
qgetenv(variable)
qgetenv(vcDirVar)
tst_QProcess
windir