/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://www.qtsoftware.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qt-embedded-charinput.html

    \title Qt for Embedded Linux Character Input
    \ingroup qt-embedded-linux

    When running a \l {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 \l {How to Create Qt Plugins}{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.

    \table
    \header \o Input Widgets
    \row
    \o

    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 \l{Qt Extended} environment contains various input widgets such as
    Handwriting Recognition and Virtual Keyboard.

    \endtable

    \tableofcontents

    \section1 Available Keyboard Drivers

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

    \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 0

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

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

    \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 1

    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.

    \section1 Keymaps

    Starting with 4.6, \l {Qt for Embedded Linux} has gained support for
    user defined keymaps.  Keymap handling is supported by the builtin
    keyboard drivers \c TTY and \c 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.

    \section1 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):

    \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 2

    The \c <driver> argument are \c TTY, \c LinuxInput and \l
    {QKbdDriverPlugin::keys()}{keys} identifying custom drivers, and the
    driver specific options are typically a device, e.g., \c /dev/tty0.

    Multiple keyboard drivers can be specified in one go:

    \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 3

    Input will be read from all specified drivers.

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

    \table
    \header \o Option \o Description
    \row \o \c /dev/xxx \o
    Open the specified device, instead of the driver's default device.
    \row \o \c repeat-delay=<d> \o
    Time in milliseconds until auto-repeat kicks in.
    \row \o \c repeat-rate=<r> \o
    Time in milliseconds specifying interval between auto-repeats.
    \row \o \c keymap=xx.qmap \o
    File name of a keymap file in Qt's \c qmap format. See \l {kmap2qmap}
    for instructions on how to create thoes files.\br Please note that the
    file name can of course also be the name of a QResource.
    \row \o \c disable-zap \o
    Disable the QWS server "Zap" shortcut \bold{Ctrl+Alt+Backspace}
    \row \o \c enable-compose \o
    Activate Latin-1 composing features in the builtin US keymap. You can
    use the right \c AltGr or right \c Alt is used as a dead key modifier,
    while \c AltGr+.  is the compose key.  For example:
    \list
    \o \c AltGr + \c " + \c u = \uuml (u with diaeresis / umlaut u)
    \o \c AltGr + \c . + \c / + \c o = \oslash (slashed o)
    \endlist
    \endtable

*/