source: trunk/doc/src/emb-pointer.qdoc@ 172

Last change on this file since 172 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

File size: 8.7 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
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, NEC Vr41XX, Linux Touch Panel and Yopy
68 protocols as well as the universal touch screen library,
69 tslib. Run the \c configure script to list the available drivers:
70
71 \if defined(QTOPIA_PHONE)
72
73 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 0
74
75 \bold{Note:} By default only the PC mouse driver is enabled.
76
77 The various drivers can be enabled and disabled using the \c
78 configure script. For example:
79
80 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 1
81
82 \else
83
84 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 2
85
86 In the default Qt configuration, only the "pc" mouse driver is
87 enabled. The various drivers can be enabled and disabled using
88 the \c configure script. For example:
89
90 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 3
91 \endif
92
93 Custom mouse drivers can be implemented by subclassing the
94 QWSMouseHandler class and creating a mouse driver plugin (derived
95 from the QMouseDriverPlugin class). The default implementation of the
96 QMouseDriverFactory class will automatically detect the plugin,
97 loading the driver into the server application at run-time.
98
99 If you are creating a driver for a device that needs calibration
100 or noise reduction, such as a touchscreen, derive from the
101 QWSCalibratedMouseHandler subclass instead to take advantage of
102 its calibration functionality.
103
104 \if defined(QTOPIA_PHONE)
105 For a tutorial on how to add a new keyboard driver plug-in
106 see: \l {Tutorial: Implementing a Device Plug-in}.
107 \endif
108
109 \section1 Specifying a Driver
110
111 Provided that the "pc" mouse driver is enabled, \l{Qt for Embedded Linux} will
112 try to auto-detect the mouse device if it is one of the supported
113 types on \c /dev/psaux or one of the \c /dev/ttyS? serial
114 lines. If multiple mice are detected, all may be used
115 simultaneously.
116
117 Note that \l{Qt for Embedded Linux} does not support auto-detection of \e
118 {touch panels} in which case the driver must be specified
119 explicitly to determine which device to use.
120
121 To manually specify which driver to use, set the QWS_MOUSE_PROTO
122 environment variable. For example (if the current shell is bash,
123 ksh, zsh or sh):
124
125 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 4
126
127 The valid values for the \c <driver> argument are \c MouseMan, \c
128 IntelliMouse, \c Microsoft, \c VR41xx, \c LinuxTP, \c Yopy, \c
129 Tslib and \l {QMouseDriverPlugin::keys()}{keys} identifying custom
130 drivers, and the driver specific options are typically a device,
131 e.g., \c /dev/mouse for mouse devices and \c /dev/ts for touch
132 panels.
133
134 Multiple mouse drivers can be specified in one go:
135
136 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 5
137
138 Input will be read from all specified drivers.
139
140 Note that the \c Vr41xx driver also accepts two optional
141 arguments: \c press=<value> defining a mouse click (the default
142 value is 750) and \c filter=<value> specifying the length of the
143 filter used to eliminate noise (the default length is 3). For
144 example:
145
146 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 6
147
148 \table
149 \header \o The Tslib Mouse Driver
150 \row
151 \o
152
153 The tslib mouse driver inherits the QWSCalibratedMouseHandler
154 class, providing calibration and noise reduction functionality in
155 addition to generating mouse events for devices using the
156 Universal Touch Screen Library.
157
158 To be able to compile this mouse handler, \l{Qt for Embedded Linux} must be
159 configured with the \c -qt-mouse-tslib option as described
160 above. In addition, the tslib headers and library must be present
161 in the build environment.
162
163 The tslib sources can be downloaded from \l
164 http://tslib.berlios.de. Use the \c configure script's -L and
165 -I options to explicitly specify the location of the library and
166 its headers:
167
168 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 7
169
170 In order to use this mouse driver, tslib must also be correctly
171 installed on the target machine. This includes providing a \c
172 ts.conf configuration file and setting the neccessary environment
173 variables (see the README file provided with tslib for details).
174
175 The \c ts.conf file will usually contain the following two lines:
176
177 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 8
178
179 To make \l{Qt for Embedded Linux} explicitly choose the tslib mouse
180 handler, set the QWS_MOUSE_PROTO environment variable as explained
181 above.
182
183 \endtable
184
185 \section1 Troubleshooting
186
187 \section2 Device Files
188
189 Make sure you are using the correct device file.
190
191 As a first step, you can test whether the device file actually gives any
192 output. For instance, if you have specified the mouse driver with
193 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 9
194 then try examining
195 the output from the device by entering the following command in a console:
196 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 10
197
198 If you see output from the device printed on the console when you move
199 the mouse, you are probably using the correct device file; otherwise, you
200 will need to experiment to find the correct device file.
201
202 \section2 File Permissions
203
204 Make sure you have sufficient permissions to access the device file.
205
206 The Qt for Embedded Linux server process needs at least read permission for the
207 device file. Some drivers also require write access to the device file.
208 For instance, if you have specified the mouse driver with
209 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 11
210 then examine the permissions of the device file by entering the following
211 command in a console:
212 \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 12
213
214 If the device file is actually a symbolic link to another file, you must
215 change the permissions of the actual file instead.
216*/
Note: See TracBrowser for help on using the repository browser.