Long live Qt 4.5!

1 files changed, 168 insertions, 0 deletions

diff --git a/doc/src/examples/analogclock.qdoc b/doc/src/examples/analogclock.qdoc
new file mode 100644
index 0000000..d5f7273
--- /dev/null
+++ b/doc/src/examples/analogclock.qdoc
@@ -0,0 +1,168 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example widgets/analogclock
+    \title Analog Clock Example
+
+    The Analog Clock example shows how to draw the contents of a custom
+    widget.
+
+    \image analogclock-example.png Screenshot of the Analog Clock example
+
+    This example also demonstrates how the transformation and scaling
+    features of QPainter can be used to make drawing custom widgets
+    easier.
+
+    \section1 AnalogClock Class Definition
+
+    The \c AnalogClock class provides a clock widget with hour and minute
+    hands that is automatically updated every few seconds.
+    We subclass \l QWidget and reimplement the standard
+    \l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face:
+
+    \snippet examples/widgets/analogclock/analogclock.h 0
+
+    \section1 AnalogClock Class Implementation
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 1
+
+    When the widget is constructed, we set up a one-second timer to
+    keep track of the current time, and we connect it to the standard
+    \l{QWidget::update()}{update()} slot so that the clock face is
+    updated when the timer emits the \l{QTimer::timeout()}{timeout()}
+    signal.
+
+    Finally, we resize the widget so that it is displayed at a
+    reasonable size.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 8
+    \snippet examples/widgets/analogclock/analogclock.cpp 10
+
+    The \c paintEvent() function is called whenever the widget's
+    contents need to be updated. This happens when the widget is
+    first shown, and when it is covered then exposed, but it is also
+    executed when the  widget's \l{QWidget::update()}{update()} slot
+    is called. Since we connected the timer's
+    \l{QTimer::timeout()}{timeout()} signal to this slot, it will be
+    called at least once every five seconds.
+
+    Before we set up the painter and draw the clock, we first define
+    two lists of \l {QPoint}s and two \l{QColor}s that will be used
+    for the hour and minute hands. The minute hand's color has an
+    alpha component of 191, meaning that it's 75% opaque.
+
+    We also determine the length of the widget's shortest side so that we
+    can fit the clock face inside the widget. It is also useful to determine
+    the current time before we start drawing.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 11
+    \snippet examples/widgets/analogclock/analogclock.cpp 12
+    \snippet examples/widgets/analogclock/analogclock.cpp 13
+    \snippet examples/widgets/analogclock/analogclock.cpp 14
+
+    The contents of custom widgets are drawn with a QPainter.
+    Painters can be used to draw on any QPaintDevice, but they are
+    usually used with widgets, so we pass the widget instance to the
+    painter's constructor.
+
+    We call QPainter::setRenderHint() with QPainter::Antialiasing to
+    turn on antialiasing. This makes drawing of diagonal lines much
+    smoother.
+
+    The translation moves the origin to the center of the widget, and
+    the scale operation ensures that the following drawing operations
+    are scaled to fit within the widget. We use a scale factor that
+    let's us use x and y coordinates between -100 and 100, and that
+    ensures that these lie within the length of the widget's shortest
+    side.
+
+    To make our code simpler, we will draw a fixed size clock face that will
+    be positioned and scaled so that it lies in the center of the widget.
+
+    The painter takes care of all the transformations made during the
+    paint event, and ensures that everything is drawn correctly. Letting
+    the painter handle transformations is often easier than performing
+    manual calculations just to draw the contents of a custom widget.
+
+    \img analogclock-viewport.png
+
+    We draw the hour hand first, using a formula that rotates the coordinate
+    system counterclockwise by a number of degrees determined by the current
+    hour and minute. This means that the hand will be shown rotated clockwise
+    by the required amount.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 15
+    \snippet examples/widgets/analogclock/analogclock.cpp 16
+
+    We set the pen to be Qt::NoPen because we don't want any outline,
+    and we use a solid brush with the color appropriate for
+    displaying hours. Brushes are used when filling in polygons and
+    other geometric shapes.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 17
+    \snippet examples/widgets/analogclock/analogclock.cpp 19
+
+    We save and restore the transformation matrix before and after the
+    rotation because we want to place the minute hand without having to
+    take into account any previous rotations.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 20
+    \codeline
+    \snippet examples/widgets/analogclock/analogclock.cpp 21
+
+    We draw markers around the edge of the clock for each hour. We
+    draw each marker then rotate the coordinate system so that the
+    painter is ready for the next one.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 22
+    \snippet examples/widgets/analogclock/analogclock.cpp 23
+
+    The minute hand is rotated in a similar way to the hour hand.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 25
+    \codeline
+    \snippet examples/widgets/analogclock/analogclock.cpp 26
+
+    Again, we draw markers around the edge of the clock, but this
+    time to indicate minutes. We skip multiples of 5 to avoid drawing
+    minute markers on top of hour markers.
+*/