source: trunk/doc/src/examples/analogclock.qdoc@ 534

Last change on this file since 534 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 7.2 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at qt-sales@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example widgets/analogclock
44 \title Analog Clock Example
45
46 The Analog Clock example shows how to draw the contents of a custom
47 widget.
48
49 \image analogclock-example.png Screenshot of the Analog Clock example
50
51 This example also demonstrates how the transformation and scaling
52 features of QPainter can be used to make drawing custom widgets
53 easier.
54
55 \section1 AnalogClock Class Definition
56
57 The \c AnalogClock class provides a clock widget with hour and minute
58 hands that is automatically updated every few seconds.
59 We subclass \l QWidget and reimplement the standard
60 \l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face:
61
62 \snippet examples/widgets/analogclock/analogclock.h 0
63
64 \section1 AnalogClock Class Implementation
65
66 \snippet examples/widgets/analogclock/analogclock.cpp 1
67
68 When the widget is constructed, we set up a one-second timer to
69 keep track of the current time, and we connect it to the standard
70 \l{QWidget::update()}{update()} slot so that the clock face is
71 updated when the timer emits the \l{QTimer::timeout()}{timeout()}
72 signal.
73
74 Finally, we resize the widget so that it is displayed at a
75 reasonable size.
76
77 \snippet examples/widgets/analogclock/analogclock.cpp 8
78 \snippet examples/widgets/analogclock/analogclock.cpp 10
79
80 The \c paintEvent() function is called whenever the widget's
81 contents need to be updated. This happens when the widget is
82 first shown, and when it is covered then exposed, but it is also
83 executed when the widget's \l{QWidget::update()}{update()} slot
84 is called. Since we connected the timer's
85 \l{QTimer::timeout()}{timeout()} signal to this slot, it will be
86 called at least once every five seconds.
87
88 Before we set up the painter and draw the clock, we first define
89 two lists of \l {QPoint}s and two \l{QColor}s that will be used
90 for the hour and minute hands. The minute hand's color has an
91 alpha component of 191, meaning that it's 75% opaque.
92
93 We also determine the length of the widget's shortest side so that we
94 can fit the clock face inside the widget. It is also useful to determine
95 the current time before we start drawing.
96
97 \snippet examples/widgets/analogclock/analogclock.cpp 11
98 \snippet examples/widgets/analogclock/analogclock.cpp 12
99 \snippet examples/widgets/analogclock/analogclock.cpp 13
100 \snippet examples/widgets/analogclock/analogclock.cpp 14
101
102 The contents of custom widgets are drawn with a QPainter.
103 Painters can be used to draw on any QPaintDevice, but they are
104 usually used with widgets, so we pass the widget instance to the
105 painter's constructor.
106
107 We call QPainter::setRenderHint() with QPainter::Antialiasing to
108 turn on antialiasing. This makes drawing of diagonal lines much
109 smoother.
110
111 The translation moves the origin to the center of the widget, and
112 the scale operation ensures that the following drawing operations
113 are scaled to fit within the widget. We use a scale factor that
114 let's us use x and y coordinates between -100 and 100, and that
115 ensures that these lie within the length of the widget's shortest
116 side.
117
118 To make our code simpler, we will draw a fixed size clock face that will
119 be positioned and scaled so that it lies in the center of the widget.
120
121 The painter takes care of all the transformations made during the
122 paint event, and ensures that everything is drawn correctly. Letting
123 the painter handle transformations is often easier than performing
124 manual calculations just to draw the contents of a custom widget.
125
126 \img analogclock-viewport.png
127
128 We draw the hour hand first, using a formula that rotates the coordinate
129 system counterclockwise by a number of degrees determined by the current
130 hour and minute. This means that the hand will be shown rotated clockwise
131 by the required amount.
132
133 \snippet examples/widgets/analogclock/analogclock.cpp 15
134 \snippet examples/widgets/analogclock/analogclock.cpp 16
135
136 We set the pen to be Qt::NoPen because we don't want any outline,
137 and we use a solid brush with the color appropriate for
138 displaying hours. Brushes are used when filling in polygons and
139 other geometric shapes.
140
141 \snippet examples/widgets/analogclock/analogclock.cpp 17
142 \snippet examples/widgets/analogclock/analogclock.cpp 19
143
144 We save and restore the transformation matrix before and after the
145 rotation because we want to place the minute hand without having to
146 take into account any previous rotations.
147
148 \snippet examples/widgets/analogclock/analogclock.cpp 20
149 \codeline
150 \snippet examples/widgets/analogclock/analogclock.cpp 21
151
152 We draw markers around the edge of the clock for each hour. We
153 draw each marker then rotate the coordinate system so that the
154 painter is ready for the next one.
155
156 \snippet examples/widgets/analogclock/analogclock.cpp 22
157 \snippet examples/widgets/analogclock/analogclock.cpp 23
158
159 The minute hand is rotated in a similar way to the hour hand.
160
161 \snippet examples/widgets/analogclock/analogclock.cpp 25
162 \codeline
163 \snippet examples/widgets/analogclock/analogclock.cpp 26
164
165 Again, we draw markers around the edge of the clock, but this
166 time to indicate minutes. We skip multiples of 5 to avoid drawing
167 minute markers on top of hour markers.
168*/
Note: See TracBrowser for help on using the repository browser.