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 widgets/wiggly

    44     \title Wiggly Example

    45 

    46     The Wiggly example shows how to animate a widget using

    47     QBasicTimer and \l{QObject::timerEvent()}{timerEvent()}. In

    48     addition, the example demonstrates how to use QFontMetrics to

    49     determine the size of text on screen.

    50 

    51     \image wiggly-example.png Screenshot of the Wiggly example

    52 

    53     QBasicTimer is a low-level class for timers. Unlike QTimer,

    54     QBasicTimer doesn't inherit from QObject; instead of emitting a

    55     \l{QTimer::timeout()}{timeout()} signal when a certain amount of

    56     time has passed, it sends a QTimerEvent to a QObject of our

    57     choice. This makes QBasicTimer a more lightweight alternative to

    58     QTimer. Qt's built-in widgets use it internally, and it is

    59     provided in Qt's API for highly-optimized applications (e.g.,

    60     \l{Qt for Embedded Linux} applications).

    61 

    62     The example consists of two classes:

    63 

    64     \list

    65     \o \c WigglyWidget is the custom widget displaying the text

    66         in a wiggly line.

    67 

    68     \o \c Dialog is the dialog widget allowing the user to enter a

    69         text. It combines a \c WigglyWidget and a \c QLineEdit.

    70     \endlist

    71 

    72     We will first take a quick look at the \c Dialog class, then we

    73     will review the \c WigglyWidget class.

    74 

    75     \section1 Dialog Class Definition

    76 

    77     \snippet examples/widgets/wiggly/dialog.h 0

    78 

    79     The \c Dialog class provides a dialog widget that allows the user

    80     to enter a text. The text is then rendered by \c WigglyWidget.

    81 

    82     \section1 Dialog Class Implementation

    83 

    84     \snippet examples/widgets/wiggly/dialog.cpp 0

    85 

    86     In the constructor we create a wiggly widget along with a

    87     \l{QLineEdit}{line edit}, and we put the two widgets in a

    88     vertical layout. We connect the line edit's \l

    89     {QLineEdit::textChanged()}{textChanged()} signal to the wiggly

    90     widget's \c setText() slot to obtain the real time interaction

    91     with the wiggly widget. The widget's default text is "Hello

    92     world!".

    93 

    94     \section1 WigglyWidget Class Definition

    95 

    96     \snippet examples/widgets/wiggly/wigglywidget.h 0

    97 

    98     The \c WigglyWidget class provides the wiggly line displaying the

    99     text. We subclass QWidget and reimplement the standard \l

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

   101     {QObject::timerEvent()}{timerEvent()} functions to draw and update

   102     the widget. In addition we implement a public \c setText() slot

   103     that sets the widget's text.

   104 

   105     The \c timer variable, of type QBasicTimer, is used to update the

   106     widget at regular intervals, making the widget move. The \c text

   107     variable is used to store the currently displayed text, and \c

   108     step to calculate position and color for each character on the

   109     wiggly line.

   110 

   111     \section1 WigglyWidget Class Implementation

   112 

   113     \snippet examples/widgets/wiggly/wigglywidget.cpp 0

   114 

   115     In the constructor, we make the widget's background slightly

   116     lighter than the usual background using the QPalette::Midlight

   117     color role. The background role defines the brush from the

   118     widget's palette that Qt uses to paint the background. Then we

   119     enlarge the widget's font with 20 points.

   120 

   121     Finally we start the timer; the call to QBasicTimer::start()

   122     makes sure that \e this particular wiggly widget will receive the

   123     timer events generated when the timer times out (every 60

   124     milliseconds).

   125 

   126     \snippet examples/widgets/wiggly/wigglywidget.cpp 1

   127     \snippet examples/widgets/wiggly/wigglywidget.cpp 2

   128 

   129     The \c paintEvent() function is called whenever a QPaintEvent is

   130     sent to the widget. Paint events are sent to widgets that need to

   131     update themselves, for instance when part of a widget is exposed

   132     because a covering widget was moved. For the wiggly widget, a

   133     paint event will also be generated every 60 milliseconds from

   134     the \c timerEvent() slot.

   135 

   136     The \c sineTable represents y-values of the sine curve,

   137     multiplied by 100. It is used to make the wiggly widget move

   138     along the sine curve.

   139 

   140     The QFontMetrics object provides information about the widget's

   141     font. The \c x variable is the horizontal position where we start

   142     drawing the text. The \c y variable is the vertical position of

   143     the text's base line. Both variables are computed so that the

   144     text is horizontally and vertically centered. To compute the base

   145     line, we take into account the font's ascent (the height of the

   146     font above the base line) and font's descent (the height of the

   147     font below the base line). If the descent equals the ascent, they

   148     cancel out each other and the base line is at \c height() / 2.

   149 

   150     \snippet examples/widgets/wiggly/wigglywidget.cpp 3

   151     \snippet examples/widgets/wiggly/wigglywidget.cpp 4

   152 

   153     Each time the \c paintEvent() function is called, we create a

   154     QPainter object \c painter to draw the contents of the widget.

   155     For each character in \c text, we determine the color and the

   156     position on the wiggly line based on \c step. In addition, \c x

   157     is incremented by the character's width.

   158 

   159     For simplicity, we assume that QFontMetrics::width(\c text)

   160     returns the sum of the individual character widths

   161     (QFontMetrics::width(\c text[i])). In practice, this is not

   162     always the case because QFontMetrics::width(\c text) also takes

   163     into account the kerning between certain letters (e.g., 'A' and

   164     'V'). The result is that the text isn't perfectly centered. You

   165     can verify this by typing "AVAVAVAVAVAV" in the line edit.

   166 

   167     \snippet examples/widgets/wiggly/wigglywidget.cpp 5

   168     \snippet examples/widgets/wiggly/wigglywidget.cpp 6

   169 

   170     The \c timerEvent() function receives all the timer events that

   171     are generated for this widget. If a timer event is sent from the

   172     widget's QBasicTimer, we increment \c step to make the text move,

   173     and call QWidget::update() to refresh the display. Any other

   174     timer event is passed on to the base class's implementation of

   175     the \l{QWidget::timerEvent()}{timerEvent()} function.

   176 

   177     The QWidget::update() slot does not cause an immediate repaint;

   178     instead the slot schedules a paint event for processing when Qt

   179     returns to the main event loop. The paint events are then handled

   180     by \c{WigglyWidget}'s \c paintEvent() function.

   181 */