summaryrefslogtreecommitdiffstats
path: root/src/gui/doc/examples/analogclockwindow.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'src/gui/doc/examples/analogclockwindow.qdoc')
-rw-r--r--src/gui/doc/examples/analogclockwindow.qdoc138
1 files changed, 138 insertions, 0 deletions
diff --git a/src/gui/doc/examples/analogclockwindow.qdoc b/src/gui/doc/examples/analogclockwindow.qdoc
new file mode 100644
index 0000000000..0fdad483c6
--- /dev/null
+++ b/src/gui/doc/examples/analogclockwindow.qdoc
@@ -0,0 +1,138 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \example gui/analogclock
+ \title Analog Clock Window Example
+
+ 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 gui/analogclock/main.cpp 5
+
+ \section1 AnalogClock Class Implementation
+
+ \snippet gui/analogclock/main.cpp 6
+
+ We set a title on the window and resize to a resonable size. Then
+ we start a timer which we will use to redraw the clock every
+ second.
+
+ \snippet gui/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 gui/analogclock/main.cpp 14
+ \snippet gui/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 gui/analogclock/main.cpp 9
+
+ We call QPainter::setRenderHint() with QPainter::Antialiasing to
+ turn on antialiasing. This makes drawing of diagonal lines much
+ smoother.
+
+ \snippet gui/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 gui/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 gui/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 gui/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 gui/analogclock/main.cpp 13
+ \snippet gui/analogclock/main.cpp 3
+
+ The minute hand is rotated in a similar way to the hour hand.
+
+ \snippet gui/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.
+*/