doc/src/examples/wiggly.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 widgets/wiggly
  30     \title Wiggly Example
  31
  32     \brief The Wiggly example shows how to animate a widget using
  33     QBasicTimer and \l{QObject::timerEvent()}{timerEvent()}. In
  34     addition, the example demonstrates how to use QFontMetrics to
  35     determine the size of text on screen.
  36
  37     \image wiggly-example.png Screenshot of the Wiggly example
  38
  39     QBasicTimer is a low-level class for timers. Unlike QTimer,
  40     QBasicTimer doesn't inherit from QObject; instead of emitting a
  41     \l{QTimer::timeout()}{timeout()} signal when a certain amount of
  42     time has passed, it sends a QTimerEvent to a QObject of our
  43     choice. This makes QBasicTimer a more lightweight alternative to
  44     QTimer. Qt's built-in widgets use it internally, and it is
  45     provided in Qt's API for highly-optimized applications (e.g.,
  46     \l{Qt for Embedded Linux} applications).
  47
  48     The example consists of two classes:
  49
  50     \list
  51     \o \c WigglyWidget is the custom widget displaying the text
  52         in a wiggly line.
  53
  54     \o \c Dialog is the dialog widget allowing the user to enter a
  55         text. It combines a \c WigglyWidget and a \c QLineEdit.
  56     \endlist
  57
  58     We will first take a quick look at the \c Dialog class, then we
  59     will review the \c WigglyWidget class.
  60
  61     \section1 Dialog Class Definition
  62
  63     \snippet examples/widgets/wiggly/dialog.h 0
  64
  65     The \c Dialog class provides a dialog widget that allows the user
  66     to enter a text. The text is then rendered by \c WigglyWidget.
  67
  68     \section1 Dialog Class Implementation
  69
  70     \snippet examples/widgets/wiggly/dialog.cpp 0
  71
  72     In the constructor we create a wiggly widget along with a
  73     \l{QLineEdit}{line edit}, and we put the two widgets in a
  74     vertical layout. We connect the line edit's \l
  75     {QLineEdit::textChanged()}{textChanged()} signal to the wiggly
  76     widget's \c setText() slot to obtain the real time interaction
  77     with the wiggly widget. The widget's default text is "Hello
  78     world!".
  79
  80     \section1 WigglyWidget Class Definition
  81
  82     \snippet examples/widgets/wiggly/wigglywidget.h 0
  83
  84     The \c WigglyWidget class provides the wiggly line displaying the
  85     text. We subclass QWidget and reimplement the standard \l
  86     {QWidget::paintEvent()}{paintEvent()} and \l
  87     {QObject::timerEvent()}{timerEvent()} functions to draw and update
  88     the widget. In addition we implement a public \c setText() slot
  89     that sets the widget's text.
  90
  91     The \c timer variable, of type QBasicTimer, is used to update the
  92     widget at regular intervals, making the widget move. The \c text
  93     variable is used to store the currently displayed text, and \c
  94     step to calculate position and color for each character on the
  95     wiggly line.
  96
  97     \section1 WigglyWidget Class Implementation
  98
  99     \snippet examples/widgets/wiggly/wigglywidget.cpp 0
 100
 101     In the constructor, we make the widget's background slightly
 102     lighter than the usual background using the QPalette::Midlight
 103     color role. The background role defines the brush from the
 104     widget's palette that Qt uses to paint the background. Then we
 105     enlarge the widget's font with 20 points.
 106
 107     Finally we start the timer; the call to QBasicTimer::start()
 108     makes sure that \e this particular wiggly widget will receive the
 109     timer events generated when the timer times out (every 60
 110     milliseconds).
 111
 112     \snippet examples/widgets/wiggly/wigglywidget.cpp 1
 113     \snippet examples/widgets/wiggly/wigglywidget.cpp 2
 114
 115     The \c paintEvent() function is called whenever a QPaintEvent is
 116     sent to the widget. Paint events are sent to widgets that need to
 117     update themselves, for instance when part of a widget is exposed
 118     because a covering widget was moved. For the wiggly widget, a
 119     paint event will also be generated every 60 milliseconds from
 120     the \c timerEvent() slot.
 121
 122     The \c sineTable represents y-values of the sine curve,
 123     multiplied by 100. It is used to make the wiggly widget move
 124     along the sine curve.
 125
 126     The QFontMetrics object provides information about the widget's
 127     font. The \c x variable is the horizontal position where we start
 128     drawing the text. The \c y variable is the vertical position of
 129     the text's base line. Both variables are computed so that the
 130     text is horizontally and vertically centered. To compute the base
 131     line, we take into account the font's ascent (the height of the
 132     font above the base line) and font's descent (the height of the
 133     font below the base line). If the descent equals the ascent, they
 134     cancel out each other and the base line is at \c height() / 2.
 135
 136     \snippet examples/widgets/wiggly/wigglywidget.cpp 3
 137     \snippet examples/widgets/wiggly/wigglywidget.cpp 4
 138
 139     Each time the \c paintEvent() function is called, we create a
 140     QPainter object \c painter to draw the contents of the widget.
 141     For each character in \c text, we determine the color and the
 142     position on the wiggly line based on \c step. In addition, \c x
 143     is incremented by the character's width.
 144
 145     For simplicity, we assume that QFontMetrics::width(\c text)
 146     returns the sum of the individual character widths
 147     (QFontMetrics::width(\c text[i])). In practice, this is not
 148     always the case because QFontMetrics::width(\c text) also takes
 149     into account the kerning between certain letters (e.g., 'A' and
 150     'V'). The result is that the text isn't perfectly centered. You
 151     can verify this by typing "AVAVAVAVAVAV" in the line edit.
 152
 153     \snippet examples/widgets/wiggly/wigglywidget.cpp 5
 154     \snippet examples/widgets/wiggly/wigglywidget.cpp 6
 155
 156     The \c timerEvent() function receives all the timer events that
 157     are generated for this widget. If a timer event is sent from the
 158     widget's QBasicTimer, we increment \c step to make the text move,
 159     and call QWidget::update() to refresh the display. Any other
 160     timer event is passed on to the base class's implementation of
 161     the \l{QWidget::timerEvent()}{timerEvent()} function.
 162
 163     The QWidget::update() slot does not cause an immediate repaint;
 164     instead the slot schedules a paint event for processing when Qt
 165     returns to the main event loop. The paint events are then handled
 166     by \c{WigglyWidget}'s \c paintEvent() function.
 167 */