/****************************************************************************
**
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation. In
** addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.2, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/. If
** you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech, as the sole
** copyright holder for Qt Designer, grants users of the Qt/Eclipse
** Integration plug-in the right for the Qt/Eclipse Integration to
** link to functionality provided by Qt Designer and its related
** libraries.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not expressly
** granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \page qtopiacore-charinput.html

    \title Qtopia Core Character Input
    \ingroup qtopiacore

    When running a \l {Qtopia Core} 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 appropiate 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{Qtopia} environment contains various input widgets such as
    Handwriting Recognition and Virtual Keyboard.

    \endtable

    \tableofcontents

    \section1 Available Keyboard Drivers

    \l {Qtopia Core} provides ready-made drivers for the SL5000, Yopy,
    Vr41XX, console (TTY) and USB protocols. Run the \c configure
    script to list the available drivers:

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

    Note that the console keyboard driver also 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). \l {Qtopia Core}'s
    implementation of the QKbdDriverFactory class will automatically
    detect the plugin, loading the driver into the server application
    at runtime.

    \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 SL5000, \c Yopy, \c VR41xx, \c
    TTY, \c USB 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.
*/
