diff options
Diffstat (limited to 'doc/src/examples/mousecalibration.qdoc')
| -rw-r--r-- | doc/src/examples/mousecalibration.qdoc | 193 |
1 files changed, 0 insertions, 193 deletions
diff --git a/doc/src/examples/mousecalibration.qdoc b/doc/src/examples/mousecalibration.qdoc deleted file mode 100644 index 39b9140f28..0000000000 --- a/doc/src/examples/mousecalibration.qdoc +++ /dev/null @@ -1,193 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example qws/mousecalibration - \title Mouse Calibration Example - - The Mouse Calibration example demonstrates how to write a simple - program using the mechanisms provided by the QWSMouseHandler class - to calibrate the mouse handler in \l{Qt for Embedded Linux}. - - Calibration is the process of mapping between physical - (i.e. device) coordinates and logical coordinates. - - The example consists of two classes in addition to the main program: - - \list - \li \c Calibration is a dialog widget that retrieves the device coordinates. - \li \c ScribbleWidget is a minimal drawing program used to let the user - test the new mouse settings. - \endlist - - First we will review the main program, then we will take a look at - the \c Calibration class. The \c ScribbleWidget class is only a - help tool in this context, and will not be covered here. - - \section1 The Main Program - - The program starts by presenting a message box informing the user - of what is going to happen: - - \snippet examples/qws/mousecalibration/main.cpp 0 - - The QMessageBox class provides a modal dialog with a range of - different messages, roughly arranged along two axes: severity and - complexity. The message box has a different icon for each of the - severity levels, but the icon must be specified explicitly. In our - case we use the default QMessageBox::NoIcon value. In addition we - use the default complexity, i.e. a message box showing the given - text and an \gui OK button. - - At this stage in the program, the mouse could be completely - uncalibrated, making the user unable to press the \gui OK button. For - that reason we use the static QTimer::singleShot() function to - make the message box disappear after 10 seconds. The QTimer class - provides repetitive and single-shot timers: The single shot - function calls the given slot after the specified interval. - - \snippet examples/qws/mousecalibration/main.cpp 1 - - Next, we create an instance of the \c Calibration class which is a - dialog widget retrieving the required sample coordinates: The - dialog sequentially presents five marks for the user to press, - storing the device coordinates for the mouse press events. - - \snippet examples/qws/mousecalibration/main.cpp 2 - - When the calibration dialog returns, we let the user test the new - mouse settings by drawing onto a \c ScribbleWidget object. Since - the mouse still can be uncalibrated, we continue to use the - QMessageBox and QTimer classes to inform the user about the - program's progress. - - An improved calibration tool would let the user choose between - accepting the new calibration, reverting to the old one, and - restarting the calibration. - - \section1 Calibration Class Definition - - The \c Calibration class inherits from QDialog and is responsible - for retrieving the device coordinates from the user. - - \snippet examples/qws/mousecalibration/calibration.h 0 - - We reimplement QDialog's \l {QDialog::exec()}{exec()} and \l - {QDialog::accept()}{accept()} slots, and QWidget's \l - {QWidget::paintEvent()}{paintEvent()} and \l - {QWidget::mouseReleaseEvent()}{mouseReleaseEvent()} functions. - - In addition, we declare a couple of private variables, \c data and - \c pressCount, holding the \c Calibration object's number of mouse - press events and current calibration data. The \c pressCount - variable is a convenience variable, while the \c data is a - QWSPointerCalibrationData object (storing the physical and logical - coordinates) that is passed to the mouse handler. The - QWSPointerCalibrationData class is simply a container for - calibration data. - - \section1 Calibration Class Implementation - - In the constructor we first ensure that the \c Calibration dialog - fills up the entire screen, has focus and will receive mouse - events (the latter by making the dialog modal): - - \snippet examples/qws/mousecalibration/calibration.cpp 0 - - Then we initialize the \l{QWSPointerCalibrationData::}{screenPoints} - array: - - \snippet examples/qws/mousecalibration/calibration.cpp 1 - - In order to specify the calibration, the - \l{QWSPointerCalibrationData::screenPoints}{screenPoints} array must - contain the screen coordinates for the logical positions - represented by the QWSPointerCalibrationData::Location enum - (e.g. QWSPointerCalibrationData::TopLeft). Since non-linearity is - expected to increase on the edge of the screen, all points are - kept 10 percent within the screen. The \c qt_screen pointer is a - reference to the screen device. There can only be one screen - device per application. - - \snippet examples/qws/mousecalibration/calibration.cpp 2 - - Finally, we initialize the variable which keeps track of the number of - mouse press events we have received. - - \snippet examples/qws/mousecalibration/calibration.cpp 3 - - The destructor is trivial. - - \snippet examples/qws/mousecalibration/calibration.cpp 4 - - The reimplementation of the QDialog::exec() slot is called from - the main program. - - First we clear the current calibration making the following mouse - event delivered in raw device coordinates. Then we call the - QWidget::grabMouse() function to make sure no mouse events are - lost, and the QWidget::activateWindow() function to make the - top-level widget containing this dialog, the active window. When - the call to the QDialog::exec() base function returns, we call - QWidget::releaseMouse() to release the mouse grab before the - function returns. - - \snippet examples/qws/mousecalibration/calibration.cpp 5 - - The QWidget::paintEvent() function is reimplemented to receive the - widget's paint events. A paint event is a request to repaint all - or parts of the widget. It can happen as a result of - QWidget::repaint() or QWidget::update(), or because the widget was - obscured and has now been uncovered, or for many other reasons. - In our reimplementation of the function we simply draw a cross at - the next point the user should press. - - \snippet examples/qws/mousecalibration/calibration.cpp 6 - - We then reimplement the QWidget::mouseReleaseEvent() function to - receive the widget's move events, using the QMouseEvent object - passed as parameter to find the coordinates the user pressed, and - update the QWSPointerCalibrationData::devPoints array. - - In order to complete the mapping between logical and physical - coordinates, the \l - {QWSPointerCalibrationData::devPoints}{devPoints} array must - contain the raw device coordinates for the logical positions - represented by the QWSPointerCalibrationData::Location enum - (e.g. QWSPointerCalibrationData::TopLeft) - - We continue by drawing the next cross, or close the dialog by - calling the QDialog::accept() slot if we have collected all the - required coordinate samples. - - \snippet examples/qws/mousecalibration/calibration.cpp 7 - - Our reimplementation of the QDialog::accept() slot simply activate - the new calibration data using the QWSMouseHandler::calibrate() - function. We also use the Q_ASSERT() macro to ensure that the number - of required samples are present. -*/ |