1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
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.
*/
|
