source: trunk/doc/src/examples/wiggly.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 7.1 KB
RevLine 
[2]1/****************************************************************************
2**
[846]3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
[561]4** All rights reserved.
5** Contact: Nokia Corporation (qt-info@nokia.com)
[2]6**
7** This file is part of the documentation of the Qt Toolkit.
8**
[846]9** $QT_BEGIN_LICENSE:FDL$
[2]10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
[846]13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
[2]15**
[846]16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
[2]21**
[561]22** If you have questions regarding the use of this file, please contact
23** Nokia at qt-info@nokia.com.
[2]24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example widgets/wiggly
30 \title Wiggly Example
31
32 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*/
Note: See TracBrowser for help on using the repository browser.