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     \example qws/mousecalibration

    44     \title Mouse Calibration Example

    45 

    46     The Mouse Calibration example demonstrates how to write a simple

    47     program using the mechanisms provided by the QWSMouseHandler class

    48     to calibrate the mouse handler in \l{Qt for Embedded Linux}. 

    49 

    50     Calibration is the process of mapping between physical

    51     (i.e. device) coordinates and logical coordinates.

    52 

    53     The example consists of two classes in addition to the main program:

    54 

    55     \list

    56         \o \c Calibration is a dialog widget that retrieves the device coordinates.

    57         \o \c ScribbleWidget is a minimal drawing program used to let the user

    58             test the new mouse settings.

    59     \endlist

    60 

    61     First we will review the main program, then we will take a look at

    62     the \c Calibration class. The \c ScribbleWidget class is only a

    63     help tool in this context, and will not be covered here.

    64 

    65     \section1 The Main Program

    66 

    67     The program starts by presenting a message box informing the user

    68     of what is going to happen:

    69 

    70     \snippet examples/qws/mousecalibration/main.cpp 0

    71 

    72     The QMessageBox class provides a modal dialog with a range of

    73     different messages, roughly arranged along two axes: severity and

    74     complexity. The message box has a different icon for each of the

    75     severity levels, but the icon must be specified explicitly. In our

    76     case we use the default QMessageBox::NoIcon value. In addition we

    77     use the default complexity, i.e. a message box showing the given

    78     text and an \gui OK button.

    79 

    80     At this stage in the program, the mouse could be completely

    81     uncalibrated, making the user unable to press the \gui OK button. For

    82     that reason we use the static QTimer::singleShot() function to

    83     make the message box disappear after 10 seconds. The QTimer class

    84     provides repetitive and single-shot timers: The single shot

    85     function calls the given slot after the specified interval.

    86 

    87     \snippet examples/qws/mousecalibration/main.cpp 1

    88 

    89     Next, we create an instance of the \c Calibration class which is a

    90     dialog widget retrieving the required sample coordinates: The

    91     dialog sequentially presents five marks for the user to press,

    92     storing the device coordinates for the mouse press events.

    93 

    94     \snippet examples/qws/mousecalibration/main.cpp 2

    95 

    96     When the calibration dialog returns, we let the user test the new

    97     mouse settings by drawing onto a \c ScribbleWidget object. Since

    98     the mouse still can be uncalibrated, we continue to use the

    99     QMessageBox and QTimer classes to inform the user about the

   100     program's progress.

   101 

   102     An improved calibration tool would let the user choose between

   103     accepting the new calibration, reverting to the old one, and

   104     restarting the calibration.

   105 

   106     \section1 Calibration Class Definition

   107 

   108     The \c Calibration class inherits from QDialog and is responsible

   109     for retrieving the device coordinates from the user.

   110 

   111     \snippet examples/qws/mousecalibration/calibration.h 0

   112 

   113     We reimplement QDialog's \l {QDialog::exec()}{exec()} and \l

   114     {QDialog::accept()}{accept()} slots, and QWidget's \l

   115     {QWidget::paintEvent()}{paintEvent()} and \l

   116     {QWidget::mouseReleaseEvent()}{mouseReleaseEvent()} functions.

   117 

   118     In addition, we declare a couple of private variables, \c data and

   119     \c pressCount, holding the \c Calibration object's number of mouse

   120     press events and current calibration data. The \c pressCount

   121     variable is a convenience variable, while the \c data is a

   122     QWSPointerCalibrationData object (storing the physical and logical

   123     coordinates) that is passed to the mouse handler. The

   124     QWSPointerCalibrationData class is simply a container for

   125     calibration data.

   126 

   127     \section1 Calibration Class Implementation

   128 

   129     In the constructor we first ensure that the \c Calibration dialog

   130     fills up the entire screen, has focus and will receive mouse

   131     events (the latter by making the dialog modal):

   132 

   133     \snippet examples/qws/mousecalibration/calibration.cpp 0

   134 

   135     Then we initialize the \l{QWSPointerCalibrationData::}{screenPoints}

   136     array:

   137 

   138     \snippet examples/qws/mousecalibration/calibration.cpp 1

   139 

   140     In order to specify the calibration, the 

   141     \l{QWSPointerCalibrationData::screenPoints}{screenPoints} array must

   142     contain the screen coordinates for the logical positions

   143     represented by the QWSPointerCalibrationData::Location enum

   144     (e.g. QWSPointerCalibrationData::TopLeft).  Since non-linearity is

   145     expected to increase on the edge of the screen, all points are

   146     kept 10 percent within the screen. The \c qt_screen pointer is a

   147     reference to the screen device. There can only be one screen

   148     device per application.

   149 

   150     \snippet examples/qws/mousecalibration/calibration.cpp 2

   151 

   152     Finally, we initialize the variable which keeps track of the number of

   153     mouse press events we have received.

   154 

   155     \snippet examples/qws/mousecalibration/calibration.cpp 3

   156 

   157     The destructor is trivial.

   158 

   159     \snippet examples/qws/mousecalibration/calibration.cpp 4

   160 

   161     The reimplementation of the QDialog::exec() slot is called from

   162     the main program.

   163 

   164     First we clear the current calibration making the following mouse

   165     event delivered in raw device coordinates. Then we call the

   166     QWidget::grabMouse() function to make sure no mouse events are

   167     lost, and the QWidget::activateWindow() function to make the

   168     top-level widget containing this dialog, the active window. When

   169     the call to the QDialog::exec() base function returns, we call

   170     QWidget::releaseMouse() to release the mouse grab before the

   171     function returns.

   172 

   173     \snippet examples/qws/mousecalibration/calibration.cpp 5

   174 

   175     The QWidget::paintEvent() function is reimplemented to receive the

   176     widget's paint events. A paint event is a request to repaint all

   177     or parts of the widget. It can happen as a result of

   178     QWidget::repaint() or QWidget::update(), or because the widget was

   179     obscured and has now been uncovered, or for many other reasons.

   180     In our reimplementation of the function we simply draw a cross at

   181     the next point the user should press.

   182 

   183     \snippet examples/qws/mousecalibration/calibration.cpp 6

   184 

   185     We then reimplement the QWidget::mouseReleaseEvent() function to

   186     receive the widget's move events, using the QMouseEvent object

   187     passed as parameter to find the coordinates the user pressed, and

   188     update the QWSPointerCalibrationData::devPoints array.

   189 

   190     In order to complete the mapping between logical and physical

   191     coordinates, the \l

   192     {QWSPointerCalibrationData::devPoints}{devPoints} array must

   193     contain the raw device coordinates for the logical positions

   194     represented by the QWSPointerCalibrationData::Location enum

   195     (e.g. QWSPointerCalibrationData::TopLeft)

   196 

   197     We continue by drawing the next cross, or close the dialog by

   198     calling the QDialog::accept() slot if we have collected all the

   199     required coordinate samples.

   200 

   201     \snippet examples/qws/mousecalibration/calibration.cpp 7

   202 

   203     Our reimplementation of the QDialog::accept() slot simply activate

   204     the new calibration data using the QWSMouseHandler::calibrate()

   205     function. We also use the Q_ASSERT() macro to ensure that the number

   206     of required samples are present.

   207 */