Qt Reference Documentation

Qt for Embedded Linux Character Input

When running a Qt for Embedded Linux application, it either runs as a server or connects to an existing server. The keyboard driver is loaded by the server application when it starts running, using Qt's plugin system.

Internally in the client/server protocol, all system generated events, including key events, are passed to the server application which then propagates the event to the appropriate client. Note that key events do not always come from a keyboard device, they can can also be generated by the server process using input widgets.

Input Widgets
The server process may call the static QWSServer::sendKeyEvent() function at any time. Typically, this is done by popping up a widget that enables the user specify characters with the pointer device.

Note that the key input widget should not take focus since the server would then just send the key events back to the input widget. One way to make sure that the input widget never takes focus is to set the Qt::Tool widget flag in the QWidget constructor.

The Qt Extended environment contains various input widgets such as Handwriting Recognition and Virtual Keyboard.

Available Keyboard Drivers

Qt for Embedded Linux provides ready-made drivers for the console (TTY) and the standard Linux Input Subsystem (USB, PS/2, ...). Run the configure script to list the available drivers:

 ./configure -help

Note that only the console (TTY) keyboard driver handles console switching (Ctrl+Alt+F1, ..., Ctrl+Alt+F10) and termination (Ctrl+Alt+Backspace).

In the default Qt configuration, only the "TTY" driver is enabled. The various drivers can be enabled and disabled using the configure script. For example:

 configure -qt-kbd-linuxinput

Custom keyboard drivers can be implemented by subclassing the QWSKeyboardHandler class and creating a keyboard driver plugin (derived from the QKbdDriverPlugin class). The default implementation of the QKbdDriverFactory class will automatically detect the plugin, loading the driver into the server application at run-time.


Starting with 4.6, Qt for Embedded Linux has gained support for user defined keymaps. Keymap handling is supported by the built-in keyboard drivers TTY and LinuxInput. Custom keyboard drivers can use the existing keymap handling code via QWSKeyboardHandler::processKeycode().

By default Qt will use an internal, compiled-in US keymap. See the options below for how to load a different keymap.

Specifying a Keyboard Driver

To specify which driver to use, set the QWS_KEYBOARD environment variable. For example (if the current shell is bash, ksh, zsh or sh):

 export QWS_KEYBOARD=<driver>[:<driver specific options>]

The <driver> arguments are TTY, LinuxInput and keys identifying custom drivers, and the driver specific options are typically a device, e.g., /dev/tty0.

Multiple keyboard drivers can be specified in one go:

 export QWS_KEYBOARD="<driver>[:<driver specific options>]
         <driver>[:<driver specific options>]
         <driver>[:<driver specific options>]"

Input will be read from all specified drivers.

Currently the following options are supported by both the TTY and LinuxInput driver:

/dev/xxxOpen the specified device, instead of the driver's default device.
repeat-delay=<d>Time (in milliseconds) until auto-repeat kicks in.
repeat-rate=<r>Time (in milliseconds) specifying the interval between auto-repeats.
keymap=xx.qmapFile name of a keymap file in Qt's qmap format. See kmap2qmap for instructions on how to create thoes files.
Note that the file name can of course also be the name of a QResource.
disable-zapDisable the QWS server "Zap" shortcut Ctrl+Alt+Backspace
enable-composeActivate Latin-1 composing features in the built-in US keymap. You can use the right AltGr or right Alt is used as a dead key modifier, while AltGr+. is the compose key. For example:
  • AltGr + " + u = ü (u with diaeresis / umlaut u)
  • AltGr + . + / + o = ø (slashed o)