doc/src/examples/mousecalibration.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example qws/mousecalibration
  30     \title Mouse Calibration Example
  31
  32     \brief The Mouse Calibration example demonstrates how to write a simple
  33     program using the mechanisms provided by the QWSMouseHandler class
  34     to calibrate the mouse handler in \l{Qt for Embedded Linux}.
  35
  36     Calibration is the process of mapping between physical
  37     (i.e. device) coordinates and logical coordinates.
  38
  39     The example consists of two classes in addition to the main program:
  40
  41     \list
  42         \o \c Calibration is a dialog widget that retrieves the device coordinates.
  43         \o \c ScribbleWidget is a minimal drawing program used to let the user
  44             test the new mouse settings.
  45     \endlist
  46
  47     First we will review the main program, then we will take a look at
  48     the \c Calibration class. The \c ScribbleWidget class is only a
  49     help tool in this context, and will not be covered here.
  50
  51     \section1 The Main Program
  52
  53     The program starts by presenting a message box informing the user
  54     of what is going to happen:
  55
  56     \snippet examples/qws/mousecalibration/main.cpp 0
  57
  58     The QMessageBox class provides a modal dialog with a range of
  59     different messages, roughly arranged along two axes: severity and
  60     complexity. The message box has a different icon for each of the
  61     severity levels, but the icon must be specified explicitly. In our
  62     case we use the default QMessageBox::NoIcon value. In addition we
  63     use the default complexity, i.e. a message box showing the given
  64     text and an \gui OK button.
  65
  66     At this stage in the program, the mouse could be completely
  67     uncalibrated, making the user unable to press the \gui OK button. For
  68     that reason we use the static QTimer::singleShot() function to
  69     make the message box disappear after 10 seconds. The QTimer class
  70     provides repetitive and single-shot timers: The single shot
  71     function calls the given slot after the specified interval.
  72
  73     \snippet examples/qws/mousecalibration/main.cpp 1
  74
  75     Next, we create an instance of the \c Calibration class which is a
  76     dialog widget retrieving the required sample coordinates: The
  77     dialog sequentially presents five marks for the user to press,
  78     storing the device coordinates for the mouse press events.
  79
  80     \snippet examples/qws/mousecalibration/main.cpp 2
  81
  82     When the calibration dialog returns, we let the user test the new
  83     mouse settings by drawing onto a \c ScribbleWidget object. Since
  84     the mouse still can be uncalibrated, we continue to use the
  85     QMessageBox and QTimer classes to inform the user about the
  86     program's progress.
  87
  88     An improved calibration tool would let the user choose between
  89     accepting the new calibration, reverting to the old one, and
  90     restarting the calibration.
  91
  92     \section1 Calibration Class Definition
  93
  94     The \c Calibration class inherits from QDialog and is responsible
  95     for retrieving the device coordinates from the user.
  96
  97     \snippet examples/qws/mousecalibration/calibration.h 0
  98
  99     We reimplement QDialog's \l {QDialog::exec()}{exec()} and \l
 100     {QDialog::accept()}{accept()} slots, and QWidget's \l
 101     {QWidget::paintEvent()}{paintEvent()} and \l
 102     {QWidget::mouseReleaseEvent()}{mouseReleaseEvent()} functions.
 103
 104     In addition, we declare a couple of private variables, \c data and
 105     \c pressCount, holding the \c Calibration object's number of mouse
 106     press events and current calibration data. The \c pressCount
 107     variable is a convenience variable, while the \c data is a
 108     QWSPointerCalibrationData object (storing the physical and logical
 109     coordinates) that is passed to the mouse handler. The
 110     QWSPointerCalibrationData class is simply a container for
 111     calibration data.
 112
 113     \section1 Calibration Class Implementation
 114
 115     In the constructor we first ensure that the \c Calibration dialog
 116     fills up the entire screen, has focus and will receive mouse
 117     events (the latter by making the dialog modal):
 118
 119     \snippet examples/qws/mousecalibration/calibration.cpp 0
 120
 121     Then we initialize the \l{QWSPointerCalibrationData::}{screenPoints}
 122     array:
 123
 124     \snippet examples/qws/mousecalibration/calibration.cpp 1
 125
 126     In order to specify the calibration, the
 127     \l{QWSPointerCalibrationData::screenPoints}{screenPoints} array must
 128     contain the screen coordinates for the logical positions
 129     represented by the QWSPointerCalibrationData::Location enum
 130     (e.g. QWSPointerCalibrationData::TopLeft).  Since non-linearity is
 131     expected to increase on the edge of the screen, all points are
 132     kept 10 percent within the screen. The \c qt_screen pointer is a
 133     reference to the screen device. There can only be one screen
 134     device per application.
 135
 136     \snippet examples/qws/mousecalibration/calibration.cpp 2
 137
 138     Finally, we initialize the variable which keeps track of the number of
 139     mouse press events we have received.
 140
 141     \snippet examples/qws/mousecalibration/calibration.cpp 3
 142
 143     The destructor is trivial.
 144
 145     \snippet examples/qws/mousecalibration/calibration.cpp 4
 146
 147     The reimplementation of the QDialog::exec() slot is called from
 148     the main program.
 149
 150     First we clear the current calibration making the following mouse
 151     event delivered in raw device coordinates. Then we call the
 152     QWidget::grabMouse() function to make sure no mouse events are
 153     lost, and the QWidget::activateWindow() function to make the
 154     top-level widget containing this dialog, the active window. When
 155     the call to the QDialog::exec() base function returns, we call
 156     QWidget::releaseMouse() to release the mouse grab before the
 157     function returns.
 158
 159     \snippet examples/qws/mousecalibration/calibration.cpp 5
 160
 161     The QWidget::paintEvent() function is reimplemented to receive the
 162     widget's paint events. A paint event is a request to repaint all
 163     or parts of the widget. It can happen as a result of
 164     QWidget::repaint() or QWidget::update(), or because the widget was
 165     obscured and has now been uncovered, or for many other reasons.
 166     In our reimplementation of the function we simply draw a cross at
 167     the next point the user should press.
 168
 169     \snippet examples/qws/mousecalibration/calibration.cpp 6
 170
 171     We then reimplement the QWidget::mouseReleaseEvent() function to
 172     receive the widget's move events, using the QMouseEvent object
 173     passed as parameter to find the coordinates the user pressed, and
 174     update the QWSPointerCalibrationData::devPoints array.
 175
 176     In order to complete the mapping between logical and physical
 177     coordinates, the \l
 178     {QWSPointerCalibrationData::devPoints}{devPoints} array must
 179     contain the raw device coordinates for the logical positions
 180     represented by the QWSPointerCalibrationData::Location enum
 181     (e.g. QWSPointerCalibrationData::TopLeft)
 182
 183     We continue by drawing the next cross, or close the dialog by
 184     calling the QDialog::accept() slot if we have collected all the
 185     required coordinate samples.
 186
 187     \snippet examples/qws/mousecalibration/calibration.cpp 7
 188
 189     Our reimplementation of the QDialog::accept() slot simply activate
 190     the new calibration data using the QWSMouseHandler::calibrate()
 191     function. We also use the Q_ASSERT() macro to ensure that the number
 192     of required samples are present.
 193 */