source: trunk/doc/src/examples/analogclock.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: 6.4 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
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
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
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.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example widgets/analogclock
30 \title Analog Clock Example
31
32 The Analog Clock example shows how to draw the contents of a custom
33 widget.
34
35 \image analogclock-example.png Screenshot of the Analog Clock example
36
37 This example also demonstrates how the transformation and scaling
38 features of QPainter can be used to make drawing custom widgets
39 easier.
40
41 \section1 AnalogClock Class Definition
42
43 The \c AnalogClock class provides a clock widget with hour and minute
44 hands that is automatically updated every few seconds.
45 We subclass \l QWidget and reimplement the standard
46 \l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face:
47
48 \snippet examples/widgets/analogclock/analogclock.h 0
49
50 \section1 AnalogClock Class Implementation
51
52 \snippet examples/widgets/analogclock/analogclock.cpp 1
53
54 When the widget is constructed, we set up a one-second timer to
55 keep track of the current time, and we connect it to the standard
56 \l{QWidget::update()}{update()} slot so that the clock face is
57 updated when the timer emits the \l{QTimer::timeout()}{timeout()}
58 signal.
59
60 Finally, we resize the widget so that it is displayed at a
61 reasonable size.
62
63 \snippet examples/widgets/analogclock/analogclock.cpp 8
64 \snippet examples/widgets/analogclock/analogclock.cpp 10
65
66 The \c paintEvent() function is called whenever the widget's
67 contents need to be updated. This happens when the widget is
68 first shown, and when it is covered then exposed, but it is also
69 executed when the widget's \l{QWidget::update()}{update()} slot
70 is called. Since we connected the timer's
71 \l{QTimer::timeout()}{timeout()} signal to this slot, it will be
72 called at least once every five seconds.
73
74 Before we set up the painter and draw the clock, we first define
75 two lists of \l {QPoint}s and two \l{QColor}s that will be used
76 for the hour and minute hands. The minute hand's color has an
77 alpha component of 191, meaning that it's 75% opaque.
78
79 We also determine the length of the widget's shortest side so that we
80 can fit the clock face inside the widget. It is also useful to determine
81 the current time before we start drawing.
82
83 \snippet examples/widgets/analogclock/analogclock.cpp 11
84 \snippet examples/widgets/analogclock/analogclock.cpp 12
85 \snippet examples/widgets/analogclock/analogclock.cpp 13
86 \snippet examples/widgets/analogclock/analogclock.cpp 14
87
88 The contents of custom widgets are drawn with a QPainter.
89 Painters can be used to draw on any QPaintDevice, but they are
90 usually used with widgets, so we pass the widget instance to the
91 painter's constructor.