Long live Qt 4.5!

1 files changed, 216 insertions, 0 deletions

diff --git a/doc/src/emb-pointer.qdoc b/doc/src/emb-pointer.qdoc
new file mode 100644
index 0000000..d52abfb
--- /dev/null
+++ b/doc/src/emb-pointer.qdoc
@@ -0,0 +1,216 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qt-embedded-pointer.html
+
+    \title Qt for Embedded Linux Pointer Handling
+    \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 mouse 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 pointer events, are passed to the server
+    application which then propagates the event to the appropriate
+    client. Note that pointer handling in \l{Qt for Embedded Linux} works for
+    both mouse and mouse-like devices such as touch panels and
+    trackballs.
+
+    Contents:
+
+    \tableofcontents
+
+    \section1 Available Drivers
+
+    \l{Qt for Embedded Linux} provides ready-made drivers for the MouseMan,
+    IntelliMouse, Microsoft, NEC Vr41XX, Linux Touch Panel and Yopy
+    protocols as well as the universal touch screen library,
+    tslib. Run the \c configure script to list the available drivers:
+
+    \if defined(QTOPIA_PHONE)
+
+        \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 0
+
+        \bold{Note:} By default only the PC mouse 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-pointer.qdoc 1
+
+    \else
+
+        \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 2
+
+        In the default Qt configuration, only the "pc" mouse 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-pointer.qdoc 3
+    \endif
+
+    Custom mouse drivers can be implemented by subclassing the
+    QWSMouseHandler class and creating a mouse driver plugin (derived
+    from the QMouseDriverPlugin class). The default implementation of the
+    QMouseDriverFactory class will automatically detect the plugin,
+    loading the driver into the server application at run-time.
+
+    If you are creating a driver for a device that needs calibration
+    or noise reduction, such as a touchscreen, derive from the
+    QWSCalibratedMouseHandler subclass instead to take advantage of
+    its calibration functionality.
+
+    \if defined(QTOPIA_PHONE)
+        For a tutorial on how to add a new keyboard driver plug-in
+        see: \l {Tutorial: Implementing a Device Plug-in}.
+    \endif
+
+    \section1 Specifying a Driver
+
+    Provided that the "pc" mouse driver is enabled, \l{Qt for Embedded Linux} will
+    try to auto-detect the mouse device if it is one of the supported
+    types on \c /dev/psaux or one of the \c /dev/ttyS?  serial
+    lines. If multiple mice are detected, all may be used
+    simultaneously.
+
+    Note that \l{Qt for Embedded Linux} does not support auto-detection of \e
+    {touch panels} in which case the driver must be specified
+    explicitly to determine which device to use.
+
+    To manually specify which driver to use, set the QWS_MOUSE_PROTO
+    environment variable. For example (if the current shell is bash,
+    ksh, zsh or sh):
+
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 4
+
+    The valid values for the \c <driver> argument are \c MouseMan, \c
+    IntelliMouse, \c Microsoft, \c VR41xx, \c LinuxTP, \c Yopy, \c
+    Tslib and \l {QMouseDriverPlugin::keys()}{keys} identifying custom
+    drivers, and the driver specific options are typically a device,
+    e.g., \c /dev/mouse for mouse devices and \c /dev/ts for touch
+    panels.
+
+    Multiple mouse drivers can be specified in one go:
+
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 5
+
+    Input will be read from all specified drivers.
+
+    Note that the \c Vr41xx driver also accepts two optional
+    arguments: \c press=<value> defining a mouse click (the default
+    value is 750) and \c filter=<value> specifying the length of the
+    filter used to eliminate noise (the default length is 3). For
+    example:
+
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 6
+
+    \table
+    \header \o The Tslib Mouse Driver
+    \row
+    \o
+
+    The tslib mouse driver inherits the QWSCalibratedMouseHandler
+    class, providing calibration and noise reduction functionality in
+    addition to generating mouse events for devices using the
+    Universal Touch Screen Library.
+
+    To be able to compile this mouse handler, \l{Qt for Embedded Linux} must be
+    configured with the \c -qt-mouse-tslib option as described
+    above. In addition, the tslib headers and library must be present
+    in the build environment.
+
+    The tslib sources can be downloaded from \l
+    http://tslib.berlios.de. Use the \c configure script's -L and
+    -I options to explicitly specify the location of the library and
+    its headers:
+
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 7
+
+    In order to use this mouse driver, tslib must also be correctly
+    installed on the target machine. This includes providing a \c
+    ts.conf configuration file and setting the neccessary environment
+    variables (see the README file provided with tslib for details).
+
+    The \c ts.conf file will usually contain the following two lines:
+
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 8
+
+    To make \l{Qt for Embedded Linux} explicitly choose the tslib mouse
+    handler, set the QWS_MOUSE_PROTO environment variable as explained
+    above.
+
+    \endtable
+
+    \section1 Troubleshooting
+
+    \section2 Device Files
+
+    Make sure you are using the correct device file.
+
+    As a first step, you can test whether the device file actually gives any
+    output. For instance, if you have specified the mouse driver with
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 9
+    then try examining
+    the output from the device by entering the following command in a console:
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 10
+
+    If you see output from the device printed on the console when you move
+    the mouse, you are probably using the correct device file; otherwise, you
+    will need to experiment to find the correct device file.
+
+    \section2 File Permissions
+
+    Make sure you have sufficient permissions to access the device file.
+
+    The Qt for Embedded Linux server process needs at least read permission for the 
+    device file. Some drivers also require write access to the device file. 
+    For instance, if you have specified the mouse driver with
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 11
+    then examine the permissions of the device file by entering the following
+    command in a console:
+    \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 12
+
+    If the device file is actually a symbolic link to another file, you must
+    change the permissions of the actual file instead.
+*/