diff options
Diffstat (limited to 'doc/src/examples/concentriccircles.qdoc')
| -rw-r--r-- | doc/src/examples/concentriccircles.qdoc | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/doc/src/examples/concentriccircles.qdoc b/doc/src/examples/concentriccircles.qdoc new file mode 100644 index 0000000000..315469b6eb --- /dev/null +++ b/doc/src/examples/concentriccircles.qdoc @@ -0,0 +1,231 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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 Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/concentriccircles + \title Concentric Circles Example + + The Concentric Circles example shows the improved rendering + quality that can be obtained using floating point precision and + anti-aliasing when drawing custom widgets. The example also shows + how to do simple animations. + + The application's main window displays several widgets which are + drawn using the various combinations of precision and + anti-aliasing. + + \image concentriccircles-example.png + + Anti-aliasing is one of QPainter's render hints. The + QPainter::RenderHints are used to specify flags to QPainter that + may, or may not, be respected by any given + engine. QPainter::Antialiasing indicates that the engine should + anti-alias the edges of primitives if possible, i.e. put + additional pixels around the original ones to smooth the edges. + + The difference between floating point precision and integer + precision is a matter of accuracy, and is visible in the + application's main window: Even though the logic that is + calculating the circles' geometry is the same, floating points + ensure that the white spaces between each circle are of the same + size, while integers make two and two circles appear as if they + belong together. The reason is that the integer based precision + rely on rounding off non-integer calculations. + + The example consists of two classes: + + \list + \o \c CircleWidget is a custom widget which renders several animated + concentric circles. + \o \c Window is the application's main window displaying four \c + {CircleWidget}s drawn using different combinations of precision + and aliasing. + \endlist + + First we will review the CircleWidget class, then we will take a + look at the Window class. + + \section1 CircleWidget Class Definition + + The CircleWidget class inherits QWidget, and is a custom widget + which renders several animated concentric circles. + + \snippet examples/painting/concentriccircles/circlewidget.h 0 + + We declare the \c floatBased and \c antialiased variables to hold + whether an instance of the class should be rendered with integer + or float based precision, and whether the rendering should be + anti-aliased or not. We also declare functions setting each of + these variables. + + In addition we reimplement the QWidget::paintEvent() function to + apply the various combinations of precision and anti-aliasing when + rendering, and to support the animation. We reimplement the + QWidget::minimumSizeHint() and QWidget::sizeHint() functions to + give the widget a reasonable size within our application. + + We declare the private \c nextAnimationFrame() slot, and the + associated \c frameNo variable holding the number of "animation + frames" for the widget, to facilitate the animation. + + \section1 CircleWidget Class Implementation + + In the constructor we make the widget's rendering integer based + and aliased by default: + + \snippet examples/painting/concentriccircles/circlewidget.cpp 0 + + We initialize the widget's \c frameNo variable, and set the + widget's background color using the QWidget::setBackgroundColor() + function which takes a \l {QPalette::ColorRole}{color role} as + argument; the QPalette::Base color role is typically white. + + Then we set the widgets size policy using the + QWidget::setSizePolicy() function. QSizePolicy::Expanding means + that the widget's \l {QWidget::sizeHint()}{sizeHint()} is a + sensible size, but that the widget can be shrunk and still be + useful. The widget can also make use of extra space, so it should + get as much space as possible. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 1 + \codeline + \snippet examples/painting/concentriccircles/circlewidget.cpp 2 + + The public \c setFloatBased() and \c setAntialiased() functions + update the widget's rendering preferences, i.e. whether the widget + should be rendered with integer or float based precision, and + whether the rendering should be anti-aliased or not. + + The functions also generate a paint event by calling the + QWidget::update() function, forcing a repaint of the widget with + the new rendering preferences. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 3 + \codeline + \snippet examples/painting/concentriccircles/circlewidget.cpp 4 + + The default implementations of the QWidget::minimumSizeHint() and + QWidget::sizeHint() functions return invalid sizes if there is no + layout for the widget, otherwise they return the layout's minimum and + preferred size, respectively. + + We reimplement the functions to give the widget minimum and + preferred sizes which are reasonable within our application. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 5 + + The nextAnimationFrame() slot simply increments the \c frameNo + variable's value, and calls the QWidget::update() function which + schedules a paint event for processing when Qt returns to the main + event loop. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 6 + + A paint event is a request to repaint all or part of the + widget. The \c paintEvent() function is an event handler that can + be reimplemented to receive the widget's paint events. We + reimplement the event handler to apply the various combinations of + precision and anti-aliasing when rendering the widget, and to + support the animation. + + First, we create a QPainter for the widget, and set its + antialiased flag to the widget's preferred aliasing. We also + translate the painters coordinate system, preparing to draw the + widget's cocentric circles. The translation ensures that the + center of the circles will be equivalent to the widget's center. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 7 + + When painting a circle, we use the number of "animation frames" to + determine the alpha channel of the circle's color. The alpha + channel specifies the color's transparency effect, 0 represents a + fully transparent color, while 255 represents a fully opaque + color. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 8 + + If the calculated alpha channel is fully transparent, we don't + draw anything since that would be equivalent to drawing a white + circle on a white background. Instead we skip to the next circle + still creating a white space. If the calculated alpha channel is + fully opaque, we set the pen (the QColor passed to the QPen + constructor is converted into the required QBrush by default) and + draw the circle. If the widget's preferred precision is float + based, we specify the circle's bounding rectangle using QRectF and + double values, otherwise we use QRect and integers. + + The animation is controlled by the public \c nextAnimationFrame() + slot: Whenever the \c nextAnimationFrame() slot is called the + number of frames is incremented and a paint event is + scheduled. Then, when the widget is repainted, the alpha-blending + of the circles' colors change and the circles appear as animated. + + \section1 Window Class Definition + + The Window class inherits QWidget, and is the application's main + window rendering four \c {CircleWidget}s using different + combinations of precision and aliasing. + + \snippet examples/painting/concentriccircles/window.h 0 + + We declare the various components of the main window, i.e., the text + labels and a double array that will hold reference to the four \c + {CircleWidget}s. In addition we declare the private \c + createLabel() function to simplify the constructor. + + \section1 Window Class Implementation + + \snippet examples/painting/concentriccircles/window.cpp 0 + + In the constructor, we first create the various labels and put + them in a QGridLayout. + + \snippet examples/painting/concentriccircles/window.cpp 1 + + Then we create a QTimer. The QTimer class is a high-level + programming interface for timers, and provides repetitive and + single-shot timers. + + We create a timer to facilitate the animation of our concentric + circles; when we create the four CircleWidget instances (and add + them to the layout), we connect the QTimer::timeout() signal to + each of the widgets' \c nextAnimationFrame() slots. + + \snippet examples/painting/concentriccircles/window.cpp 2 + + Before we set the layout and window title for our main window, we + make the timer start with a timeout interval of 100 milliseconds, + using the QTimer::start() function. That means that the + QTimer::timeout() signal will be emitted, forcing a repaint of the + four \c {CircleWidget}s, every 100 millisecond which is the reason + the circles appear as animated. + + \snippet examples/painting/concentriccircles/window.cpp 3 + + The private \c createLabel() function is implemented to simlify + the constructor. +*/ |