1 files changed, 138 insertions, 0 deletions
diff --git a/examples/gui/doc/src/analogclockwindow.qdoc b/examples/gui/doc/src/analogclockwindow.qdoc
new file mode 100644
index 0000000000..ff361a27b1
--- /dev/null
+++ b/examples/gui/doc/src/analogclockwindow.qdoc
@@ -0,0 +1,138 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example analogclock
+    \title Analog Clock Window Example
+
+    \brief The Analog Clock Window example shows how to draw the contents of
+    a custom window.
+
+    \image analogclock-window-example.png Screenshot of the Analog
+    Clock Window example
+
+    This example demonstrates how the transformation and scaling
+    features of QPainter can be used to make drawing easier.
+
+    \section1 AnalogClockWindow Class Definition
+
+    The \c AnalogClockWindow class provides a clock with hour and
+    minute hands that is automatically updated every few seconds.  We
+    make use of the RasterWindow from the \l {Raster Window Example}
+    and reimplement the \c render function to draw the clock face:
+
+    \snippet analogclock/main.cpp 5
+
+    \section1 AnalogClock Class Implementation
+
+    \snippet analogclock/main.cpp 6
+
+    We set a title on the window and resize to a reasonable size. Then
+    we start a timer which we will use to redraw the clock every
+    second.
+
+    \snippet analogclock/main.cpp 7
+
+    The timerEvent function is called every second as a result of
+    our startTimer call. Making use of the convenience in the base
+    class, we schedule the window to be repainted.
+
+    Checking the timer's id is not strictly needed as we only have
+    one active timer in this instance, but it is good practice to do
+    so.
+
+    \snippet analogclock/main.cpp 14
+    \snippet analogclock/main.cpp 8
+
+    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.
+
+    \snippet analogclock/main.cpp 9
+
+    We call QPainter::setRenderHint() with QPainter::Antialiasing to
+    turn on antialiasing. This makes drawing of diagonal lines much
+    smoother.
+
+    \snippet analogclock/main.cpp 10
+
+    The translation moves the origin to the center of the window, and
+    the scale operation ensures that the following drawing operations
+    are scaled to fit within the window. 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 window'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 window.
+
+    We also determine the length of the window's shortest side so that we
+    can fit the clock face inside the window.
+
+    The painter takes care of all the transformations made during the
+    rendering, and ensures that everything is drawn correctly. Letting
+    the painter handle transformations is often easier than performing
+    manual calculations.
+
+    \image analogclockwindow-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 analogclock/main.cpp 11
+
+    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 analogclock/main.cpp 2
+
+    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 analogclock/main.cpp 12
+
+    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 analogclock/main.cpp 13
+    \snippet analogclock/main.cpp 3
+
+    The minute hand is rotated in a similar way to the hour hand.
+
+    \snippet analogclock/main.cpp 4
+
+    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.
+*/