1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \page qt-embedded-pointer.html

    44 

    45     \title Qt for Embedded Linux Pointer Handling

    46     \ingroup qt-embedded-linux

    47 

    48     When running a \l{Qt for Embedded Linux} application, it either runs as a

    49     server or connects to an existing server. The mouse driver is

    50     loaded by the server application when it starts running, using

    51     Qt's \l {How to Create Qt Plugins}{plugin system}.

    52 

    53     Internally in the client/server protocol, all system generated

    54     events, including pointer events, are passed to the server

    55     application which then propagates the event to the appropriate

    56     client. Note that pointer handling in \l{Qt for Embedded Linux} works for

    57     both mouse and mouse-like devices such as touch panels and

    58     trackballs.

    59 

    60     Contents:

    61 

    62     \tableofcontents

    63 

    64     \section1 Available Drivers

    65 

    66     \l{Qt for Embedded Linux} provides ready-made drivers for the MouseMan,

    67     IntelliMouse, Microsoft and Linux Touch Panel protocols, for the

    68     standard Linux Input Subsystem as well as the universal touch screen

    69     library, tslib.  Run the \c configure script to list the available

    70     drivers:

    71 

    72     \if defined(QTOPIA_PHONE)

    73 

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

    75 

    76         \bold{Note:} By default only the PC mouse driver is enabled.

    77 

    78         The various drivers can be enabled and disabled using the \c

    79         configure script. For example:

    80 

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

    82 

    83     \else

    84 

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

    86 

    87         In the default Qt configuration, only the "pc" mouse driver is

    88         enabled. The various drivers can be enabled and disabled using

    89         the \c configure script. For example:

    90 

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

    92     \endif

    93 

    94     Custom mouse drivers can be implemented by subclassing the

    95     QWSMouseHandler class and creating a mouse driver plugin (derived

    96     from the QMouseDriverPlugin class). The default implementation of the

    97     QMouseDriverFactory class will automatically detect the plugin,

    98     loading the driver into the server application at run-time.

    99 

   100     If you are creating a driver for a device that needs calibration

   101     or noise reduction, such as a touchscreen, derive from the

   102     QWSCalibratedMouseHandler subclass instead to take advantage of

   103     its calibration functionality.

   104 

   105     \if defined(QTOPIA_PHONE)

   106         For a tutorial on how to add a new keyboard driver plug-in

   107         see: \l {Tutorial: Implementing a Device Plug-in}.

   108     \endif

   109 

   110     \section1 Specifying a Driver

   111 

   112     Provided that the "pc" mouse driver is enabled, \l{Qt for Embedded Linux} will

   113     try to auto-detect the mouse device if it is one of the supported

   114     types on \c /dev/psaux or one of the \c /dev/ttyS?  serial

   115     lines. If multiple mice are detected, all may be used

   116     simultaneously.

   117 

   118     Note that \l{Qt for Embedded Linux} does not support auto-detection of \e

   119     {touch panels} in which case the driver must be specified

   120     explicitly to determine which device to use.

   121 

   122     To manually specify which driver to use, set the QWS_MOUSE_PROTO

   123     environment variable. For example (if the current shell is bash,

   124     ksh, zsh or sh):

   125 

   126     \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 4

   127 

   128     The valid values for the \c <driver> argument are \c MouseMan, \c

   129     IntelliMouse, \c Microsoft, \c LinuxTP, \c LinuxInput, \c

   130     Tslib and \l {QMouseDriverPlugin::keys()}{keys} identifying custom

   131     drivers, and the driver specific options are typically a device,

   132     e.g., \c /dev/mouse for mouse devices and \c /dev/ts for touch

   133     panels.

   134 

   135     Multiple mouse drivers can be specified in one go:

   136 

   137     \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 5

   138 

   139     Input will be read from all specified drivers.

   140 

   141     \table

   142     \header \o The Tslib Mouse Driver

   143     \row

   144     \o

   145 

   146     The tslib mouse driver inherits the QWSCalibratedMouseHandler

   147     class, providing calibration and noise reduction functionality in

   148     addition to generating mouse events for devices using the

   149     Universal Touch Screen Library.

   150 

   151     To be able to compile this mouse handler, \l{Qt for Embedded Linux} must be

   152     configured with the \c -qt-mouse-tslib option as described

   153     above. In addition, the tslib headers and library must be present

   154     in the build environment.

   155 

   156     The tslib sources can be downloaded from \l

   157     http://tslib.berlios.de. Use the \c configure script's -L and

   158     -I options to explicitly specify the location of the library and

   159     its headers:

   160 

   161     \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 7

   162 

   163     In order to use this mouse driver, tslib must also be correctly

   164     installed on the target machine. This includes providing a \c

   165     ts.conf configuration file and setting the neccessary environment

   166     variables (see the README file provided with tslib for details).

   167 

   168     The \c ts.conf file will usually contain the following two lines:

   169 

   170     \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 8

   171 

   172     To make \l{Qt for Embedded Linux} explicitly choose the tslib mouse

   173     handler, set the QWS_MOUSE_PROTO environment variable as explained

   174     above.

   175 

   176     \endtable

   177 

   178     \section1 Troubleshooting

   179 

   180     \section2 Device Files

   181 

   182     Make sure you are using the correct device file.

   183 

   184     As a first step, you can test whether the device file actually gives any

   185     output. For instance, if you have specified the mouse driver with

   186     \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 9

   187     then try examining

   188     the output from the device by entering the following command in a console:

   189     \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 10

   190 

   191     If you see output from the device printed on the console when you move

   192     the mouse, you are probably using the correct device file; otherwise, you

   193     will need to experiment to find the correct device file.

   194 

   195     \section2 File Permissions

   196 

   197     Make sure you have sufficient permissions to access the device file.

   198 

   199     The Qt for Embedded Linux server process needs at least read permission for the 

   200     device file. Some drivers also require write access to the device file. 

   201     For instance, if you have specified the mouse driver with

   202     \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 11

   203     then examine the permissions of the device file by entering the following

   204     command in a console:

   205     \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 12

   206 

   207     If the device file is actually a symbolic link to another file, you must

   208     change the permissions of the actual file instead.

   209 */