From a8e95f73a9eb51f000fa464cfd853ae1316e1cf6 Mon Sep 17 00:00:00 2001 From: Kavindra Palaraja Date: Tue, 1 Oct 2019 15:56:23 +0200 Subject: Docs: Restructure the Embedded Linux article to improve readability * Split out the Inputs chapter into its own page * Cleanup the Inputs page to improve readability * Remove outdated bits of info from the Embedded Linux article itself Task-number: QTBUG-75725 Change-Id: Ia1031da92c302d78903d22199f7f13cde3a512bc Reviewed-by: Andy Shaw Reviewed-by: Laszlo Agocs --- doc/src/external-resources.qdoc | 20 ++ doc/src/platforms/configure-linux-device.qdoc | 2 +- doc/src/platforms/emb-linux.qdoc | 237 +---------------------- doc/src/platforms/inputs-linux-device.qdoc | 267 ++++++++++++++++++++++++++ 4 files changed, 289 insertions(+), 237 deletions(-) create mode 100644 doc/src/platforms/inputs-linux-device.qdoc diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc index 51a5bc1b8..9ca177d3b 100644 --- a/doc/src/external-resources.qdoc +++ b/doc/src/external-resources.qdoc @@ -375,3 +375,23 @@ \externalpage https://webassembly.org \title WebAssembly Resource site */ + +/*! + \externalpage https://www.freedesktop.org/wiki/Software/libinput + \title libinput +*/ + +/*! + \externalpage https://www.yoctoproject.org + \title Yocto Project +*/ + +/*! + \externalpage http://lct.sourceforge.net/ + \title Linux Console Tools (LCT) +*/ + +/*! + \externalpage https://www.x.org/ + \title X.org +*/ diff --git a/doc/src/platforms/configure-linux-device.qdoc b/doc/src/platforms/configure-linux-device.qdoc index 201e22ac5..06955f882 100644 --- a/doc/src/platforms/configure-linux-device.qdoc +++ b/doc/src/platforms/configure-linux-device.qdoc @@ -28,7 +28,7 @@ /*! \page configure-linux-device.html \title Configure an Embedded Linux Device - \brief Provides information about how to configure an embedded Linux device in Qt. + \brief Provides information about how to configure an Embedded Linux device in Qt. Building Qt for a given device requires a toolchain and a \c sysroot. Additionally, some devices require vendor-specific adaptation code for EGL and OpenGL ES 2.0 support. This is diff --git a/doc/src/platforms/emb-linux.qdoc b/doc/src/platforms/emb-linux.qdoc index 19816f85c..586079f05 100644 --- a/doc/src/platforms/emb-linux.qdoc +++ b/doc/src/platforms/emb-linux.qdoc @@ -318,238 +318,6 @@ set the \c{QT_QPA_FB_FORCE_FULLSCREEN} environment variable to \c 0 to restore the behavior from earlier Qt versions. - \section1 Input - - When no windowing system is present, the mouse, keyboard, and touch input are - read directly via \c evdev or using helper libraries such as \c libinput or - \c tslib. Note that this requires that device nodes \c {/dev/input/event*} are - readable by the user. \c eglfs and \c linuxfb have all the input handling code - compiled-in. - - \section2 Using libinput - - \l{http://www.freedesktop.org/wiki/Software/libinput}{libinput} is a library - to handle input devices. It offers an alternative to the Qt's own \c evdev - input support. To enable using \c libinput, make sure the development files - for \c libudev and \c libinput are available when configuring and building - Qt. \c xkbcommon is also necessary if keyboard support is desired. With - \c eglfs and \c linuxfb no further actions are necessary as these plugins use - \c libinput by default. If \c libinput support is not available or the - environment variable \c QT_QPA_EGLFS_NO_LIBINPUT is set, Qt's own evdev - handlers come in to play. - - \section2 Input on eglfs and linuxfb without libinput - - Parameters like the device node name can be set in the environment variables - \c QT_QPA_EVDEV_MOUSE_PARAMETERS, \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS and - \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS. Separate the entries with colons. These - parameters act as an alternative to passing the settings in the \c{-plugin} - command-line argument, and with some backends they are essential: eglfs and - linuxfb use built-in input handlers so there is no separate \c {-plugin} - argument in use. - - Additionally, the built-in input handlers can be disabled by setting - \c QT_QPA_EGLFS_DISABLE_INPUT or \c QT_QPA_FB_DISABLE_INPUT to \c 1. - - \section2 Mouse - - The mouse cursor shows up whenever \c QT_QPA_EGLFS_HIDECURSOR (for eglfs) - or \c QT_QPA_FB_HIDECURSOR (for linuxfb) is not set and Qt's libudev-based - device discovery reports that at least one mouse is available. When \c libudev - support is not present, the mouse cursor always show up unless explicitly - disabled via the environment variable. - - Hot plugging is supported, but only if Qt was configured with \c libudev support - (that is, if the \e libudev development headers are present in the sysroot at - configure time). This allows connecting or disconnecting an input device while - the application is running. - - The \e evdev mouse handler supports the following extra parameters: - - \list - - \li \c {/dev/input/...} - Specifies the name of the input device. When not - given, Qt looks for a suitable device either via \e libudev or by walking - through the available nodes. - - \li \c nocompress - By default, input events that do not 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. This can - be disabled by setting the \c nocompress parameter. - - \li \c dejitter - Specifies a jitter limit. By default dejittering is disabled. - - \li \c grab - When 1, Qt will grab the device for exclusive use. - - \li \c abs - Some touchscreens report absolute coordinates and cannot be - differentiated from touchpads. In this special situation pass \c abs to - indicate that the device is using absolute events. - - \endlist - - \section2 Keyboard - - The \e evdev keyboard handler supports the following extra parameters: - - \list - - \li \c {/dev/input/...} - Specifies the name of the input device. When not - given, Qt looks for a suitable device either via \e libudev or by walking - through the available nodes. - \li \c {grab} - Enables grabbing the input device. - \li \c {keymap} - Specifies the name of a custom keyboard map file. - \li \c {enable-compose} - Enables compositing. - \li \c {repeat-delay} - Sets a custom key repeat delay. - \li \c {repeat-rate} - Sets a custom key repeat rate. - \endlist - - On Embedded Linux systems that do not have their terminal sessions disabled, - the behavior on a key press can be confusing as input event is processed by - the Qt application and the tty. To overcome this, the following options are - available: - - \list - - \li \e EGLFS and \e LinuxFB attempt to disable the terminal keyboard on - application startup by setting the tty's keyboard mode to \c K_OFF. This - prevents keystrokes from going to the terminal. If the standard behavior needs - to be restored for some reason, set the environment variable - \c QT_QPA_ENABLE_TERMINAL_KEYBOARD to \c 1. Note that this works only when the - application is launched from a remote console (for example, via \c ssh) and - the terminal keyboard input remains enabled. - - \li An alternative approach is to use the \e evdev keyboard handler's \c grab - parameter by passing \e{grab=1} in \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS. This - results in trying to get a grab on the input device. If the \c 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 - started remotely as it does not need access to the tty device. - - \li Finally, for many specialized Embedded Linux images it does not make sense - to have the standard terminal sessions enabled in the first place. Refer to - your build environment's documentation on how to disable them. For example, - when generating images using the \l {http://www.yoctoproject.org}{Yocto - Project}, unsetting \c SYSVINIT_ENABLED_GETTYS results in having no - \c getty process running, and thus no input, on any of the virtual terminals. - - \endlist - - If the default built-in keymap is not sufficient, a different one can be - specified either via the \c keymap parameter or by using the eglfs-specific - \l{QEglFSFunctions::loadKeymap()}{loadKeymap()} function. The latter allows - switching the keymap at runtime. Note however that this requires using eglfs' - built-in keyboard handler; it is not supported when the keyboard handler is - loaded via the \c -plugin command-line parameter. - - \note Special system key combinations, such as console switching - (\e{Ctrl+Alt+Fx}) or zap (\e{Ctrl+Alt+Backspace}) are not currently supported - and are ignored. - - To generate a custom keymap, the \e kmap2qmap utility can be used. This can be - found in the \e qttools module. The source files have to be in standard Linux - \c kmap format, which is understood by the kernel's \c loadkeys command. - This means one can use the following sources to generate \c qmap files: - - \list - \li The \l {http://lct.sourceforge.net/}{Linux Console Tools (LCT)} project. - \li \l {http://www.x.org/}{Xorg} X11 keymaps can be converted to the - \c kmap format with the \c ckbcomp utility. - \li As \c kmap files are plain-text files, they can also be hand crafted. - \endlist - - \c kmap2qmap is a command line program, that needs at least 2 files as - parameters. The last one is the generated \c .qmap file, while all the - others are parsed as input \c .kmap files. For example: - - \badcode - kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap - \endcode - - \note \c kmap2qmap does not support all the (pseudo) symbols that the Linux - kernel supports. When converting a standard keymap, a number of warnings will - be shown regarding \c Show_Registers, \c Hex_A, and so on; these messages can - safely be ignored. - - \section2 Touch - - For some resistive, single-touch touch screens it may be necessary to fall - back to using \c tslib instead of relying on the Linux multi-touch protocol and - the event devices. For modern touch screens this is not necessary. \c tslib - support can be enabled by setting the environment variable - \c QT_QPA_EGLFS_TSLIB or \c QT_QPA_FB_TSLIB to 1. To change the device, set the - environment variable \c TSLIB_TSDEVICE or pass the device name on the - command-line. Note that the \c tslib input handler generates mouse events and - supports single touch only, as opposed to \c evdevtouch which generates true - multi-touch QTouchEvent events too. - - The \e evdev touch handler supports the following extra parameters: - - \list - - \li \c {/dev/input/...} - Specifies the name of the input device. When not - given, Qt looks for a suitable device either via \e libudev or by walking - through the available nodes. - - \li \c rotate - On some touch screens the coordinates must be rotated, which - is done by setting \c rotate to 90, 180, or 270. - - \li \c invertx and \c inverty - To invert the X or Y coordinates in the input - events, pass \c invertx or \c inverty. - - \endlist - - For example, doing \c{export - QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS=/dev/input/event5:rotate=180} before - launching applications results in an explicitly specified touch device and - flipping the coordinates - useful when the orientation of the actual - screen and the touch screen do not match. - - \section2 Pen-based tablets - - The \c evdevtablet plugin provides basic support for Wacom and similar, - pen-based tablets. It generates QTabletEvent events only. To enable it, - pass \c {QT_QPA_GENERIC_PLUGINS=evdevtablet} in the environment or, - alternatively, pass \c {-plugin evdevtablet} argument on the command-line. - The plugin can take a device node parameter, for example - \c{QT_QPA_GENERIC_PLUGINS=evdevtablet:/dev/event1}, in case the Qt's automatic - device discovery (based either on \e libudev or a walkthrough of - \c{/dev/input/event*}) is not functional or misbehaving. - - \section2 Debugging Input Devices - - It is possible to print some information to the debug output by enabling - the \c qt.qpa.input logging rule, for example by setting the \c QT_LOGGING_RULES - environment variable to \c{qt.qpa.input=true}. This is useful for detecting - which device is being used, or to troubleshoot device discovery issues. - - \section2 Using Custom Mouse Cursor Images - - \c eglfs comes with its own set of 32x32 sized mouse cursor images. If these are - not sufficient, a custom cursor atlas can be provided by setting the \c - QT_QPA_EGLFS_CURSOR environment variable to the name of a JSON file. The file - can also be embedded into the application via Qt's resource system. - - For example, an embedded cursor atlas with 8 cursor images per row can be - specified like the following: - - \badcode - { - "image": ":/cursor-atlas.png", - "cursorsPerRow": 8, - "hotSpots": [ - [7, 2], - [12, 3], - [12, 12], - ... - ] - } - \endcode - - Note that the images are expected to be tightly packed in the atlas: the - width and height of the cursors are decided based on the total image size and - the \c cursorsPerRow setting. Atlases have to provide an image for all the - supported cursors. - \section1 Display Output When having multiple displays connected, the level of support for targeting @@ -1050,15 +818,12 @@ For more details, see \l{Wayland and Qt}. - \note You may experience issues with touch screen input while using the - \l{http://wayland.freedesktop.org/}{Weston} reference compositor. For more - information, see \l{https://wiki.qt.io/WestonTouchScreenIssues}. - \section1 Related Topics \list \li \l{Qt for Device Creation} \li \l{Configure an Embedded Linux Device} + \li \l{Inputs on an Embedded Linux Device} \li \l Emulator \li \l{Qt Virtual Keyboard} \li \l{Qt Quick WebGL} diff --git a/doc/src/platforms/inputs-linux-device.qdoc b/doc/src/platforms/inputs-linux-device.qdoc new file mode 100644 index 000000000..9cb85dcee --- /dev/null +++ b/doc/src/platforms/inputs-linux-device.qdoc @@ -0,0 +1,267 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page inputs-linux-device.html + \title Inputs on an Embedded Linux Device + \brief Provides information about working with inputs on an Embedded Linux device in Qt. + + On your Embedded Linux device, when there's no windowing system present, the mouse, keyboard, + and touch input are read directly via \c evdev or using helper libraries such as \c libinput or + \c tslib. However, this behavior requires that device nodes \c {/dev/input/event*} are readable + by the user. \c eglfs and \c linuxfb have all the input handling code compiled-in. + + \section2 Use libinput + + \l{libinput} is a library to handle input devices that offers an alternative to the Qt's own + \c evdev input support. To enable using \c libinput, when you configure and build Qt, make sure + that the development files for \c libudev and \c libinput are available. If you require keyboard + support, then \c xkbcommon is also necessary. With \c eglfs and \c linuxfb, no further actions + are necessary as these plugins use \c libinput by default. If \c libinput support is not + available or the \c QT_QPA_EGLFS_NO_LIBINPUT environment variable is set, then Qt's own \c evdev + handlers are used instead. + + \section2 Input on eglfs and linuxfb without libinput + + Parameters like the device node name can be set in the \c QT_QPA_EVDEV_MOUSE_PARAMETERS, + \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS and \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS environment + variables; separate your entries with colons. These parameters are an alternative to passing + the settings in the \c{-plugin} command-line argument, and with some backends they are essential. + But \c eglfs and \c linuxfb use built-in input handlers so there's no separate \c {-plugin} + argument in use. + + Additionally, the built-in input handlers can be disabled by setting + \c QT_QPA_EGLFS_DISABLE_INPUT (for \c eglfs) or \c QT_QPA_FB_DISABLE_INPUT (for \c linuxfb) to + \c 1. + + \section2 Mouse + + The mouse cursor shows up whenever \c QT_QPA_EGLFS_HIDECURSOR (for \c eglfs) or + \c QT_QPA_FB_HIDECURSOR (for \c linuxfb) isn't set and Qt's libudev-based device discovery + reports that at least one mouse is available. When \c 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 \c libudev support, connecting or disconnecting an input device while + the application is running (hot plugging) is supported. Then \c libudev development headers + are present in the sysroot at configure time. + + The \c evdev mouse handler supports the following extra parameters: + + \table + \header + \li Parameter + \li Description + \row + \li \c {/dev/input/...} + \li Specifies the name of the input device. If unspecified, Qt looks for a suitable device + either via \c libudev or by traversing the available nodes. + \row + \li \c nocompress + \li 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 \c nocompress parameter. + \row + \li \c dejitter + \li Specifies a jitter limit; disabled by default. + \row + \li \c grab + \li When set to \c 1, Qt grabs the device for exclusive use. + \row + \li \c abs + \li Some touchscreens report absolute coordinates and can't be differentiated from touchpads. + In this case, pass \c abs to indicate that the device is using absolute events. + \endtable + + \section2 Keyboard + + The \c evdev keyboard handler supports the following extra parameters: + + \table + \header + \li Parameter + \li Description + \row + \li \c {/dev/input/...} + \li Specifies the name of the input device. If unspecified, Qt looks for a suitable device + either via \c libudev or by traversing the available nodes. + \row + \li \c {grab} + \li Enables grabbing the input device. + \row + \li \c {keymap} + \li Specifies the name of a custom keyboard map file. + \row + \li \c {enable-compose} + \li Enables compositing. + \row + \li \c {repeat-delay} + \li Sets a custom key repeat delay. + \row + \li \c {repeat-rate} + \li Sets a custom key repeat rate. + \endtable + + 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: + + \list + \li On application startup, \c EGLFS and \c LinuxFB attempt to disable the terminal keyboard + by setting the tty's keyboard mode to \c K_OFF. This prevents keystrokes from being sent to + the terminal. If the standard behavior is required, set the \c QT_QPA_ENABLE_TERMINAL_KEYBOARD + environment variable to \c 1. Note that this works only when the application is launched + from a remote console, via \c ssh for example, and the terminal keyboard input remains + enabled. + \li An alternative approach is to use the \c evdev keyboard handler's \c grab parameter by + passing \c{grab=1} in \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS. This results in trying to get a + grab on the input device. If the \c 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. + \li 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 \l{Yocto Project}, unsetting \c SYSVINIT_ENABLED_GETTYS results + in having no \c getty process running. This means, there's no input on any of the virtual + terminals. + \endlist + + If the default built-in keymap is not sufficient, you can specify a different one either via the + \c keymap parameter or via the eglfs-specific \l{QEglFSFunctions::loadKeymap()}{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 \c -plugin command-line parameter. + + \note Special system key combinations, such as console switching (\uicontrol{Ctrl+Alt+Fx}) or + zap (\uicontrol{Ctrl+Alt+Backspace}) are not currently supported and are ignored. + + To generate a custom keymap, use the \c kmap2qmap utility, that can be found in the \c qttools + module. The source files have to be in standard Linux \c kmap format, which is understood by the + kernel's \c loadkeys command. \c qmap files can be generated in one of the following ways: + + \list + \li The \l{Linux Console Tools (LCT)} project. + \li \l{X.org} X11 keymaps can be converted to the \c kmap format with the \c ckbcomp utility. + \li As \c kmap files are plain-text files, they can also be hand crafted. + \endlist + + \c kmap2qmap is a command line program, that needs at least 2 files as parameters. The last + parameter is the generated \c .qmap file, while all the others are parsed as input \c .kmap + files. For example: + + \badcode + kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap + \endcode + + \note \c 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 + \c Show_Registers, \c Hex_A, and so on; these messages can be ignored. + + \section2 Touch + + While it's not necessary for modern touch screens, some resistive, single-touch touch screens may + require that you fallback to using \c tslib instead of relying on the Linux multi-touch protocol + and the event devices. + + To enable \c tslib support, set the \c QT_QPA_EGLFS_TSLIB (for \c eglfs) or \c QT_QPA_FB_TSLIB + (for \c linuxfb) environment variable to 1. To change the device, set the \c TSLIB_TSDEVICE + environment variable or pass the device name on the command-line. Note that the \c tslib input + handler generates mouse events and supports single touch only, as opposed to \c evdevtouch which + generates true multi-touch QTouchEvent events too. + + The \c evdev touch handler supports the following extra parameters: + + \table + \header + \li Parameter + \li Description + \row + \li \c {/dev/input/...} + \li Specifies the name of the input device. If unspecified, Qt looks for a suitable device + either via \c libudev or by traversing the available nodes. + \row + \li \c rotate + \li On some touch screens the coordinates must be rotated by setting \c rotate to 90, 180, + or 270. + \row + \li \c invertx and \c inverty + \li Specifies the parameters to invert the X or Y coordinates in the input events. + \endtable + + For example, if you pass the following values to \c 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. + + \badcode + export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS=/dev/input/event5:rotate=180 + \endcode + + \section2 Pen-based Tablets + + The \c evdevtablet plugin provides basic support for Wacom and similar pen-based tablets. It + generates QTabletEvent events only. To enable it, pass \c {QT_QPA_GENERIC_PLUGINS=evdevtablet} + in the environment or, alternatively, pass the \c {-plugin evdevtablet} argument on the + command-line. + + The plugin can take a device node parameter, such as \c{QT_QPA_GENERIC_PLUGINS=evdevtablet:/dev/event1}, + if Qt's automatic device discovery (based either on \c libudev or traversing \c{/dev/input/event*}) + isn't functional or is misbehaving. + + \section2 Debug Input Devices + + It's possible to print some information to the debug output by enabling the \c qt.qpa.input + logging rule, for example by setting the \c QT_LOGGING_RULES environment variable to + \c{qt.qpa.input=true}. This is useful for detecting which device is being used, or for + troubleshooting device discovery issues. + + \section2 Use Custom Mouse Cursor Images + + \c 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 \c QT_QPA_EGLFS_CURSOR environment variable + to the name of a JSON file. This file can also be embedded into the application via + \l{The Qt Resource System}. + + For example, an embedded cursor atlas with 8 cursor images per row can be specified as follows: + + \badcode + { + "image": ":/cursor-atlas.png", + "cursorsPerRow": 8, + "hotSpots": [ + [7, 2], + [12, 3], + [12, 12], + ... + ] + } + \endcode + + 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 \c cursorsPerRow setting. Atlases + must also provide an image for all of the supported cursors. + +*/ -- cgit v1.2.3