From: Gunnar Sletta <gunnar.sletta@nokia.com>
Date: Fri, 15 Jun 2012 11:41:18 +0000 (+0200)
Subject: Analog clock and raster window examples
X-Git-Tag: v5.0.0-beta1~819
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=c97104f31e23315807fe24f1424b99438f91e37a;p=profile%2Fivi%2Fqtbase.git

Analog clock and raster window examples

Change-Id: I36586fbaa7da25208bbc1964d2708f094d0d5c98
Reviewed-by: Gunnar Sletta <gunnar.sletta@nokia.com>
---

diff --git a/examples/gui/analogclock/analogclock.pro b/examples/gui/analogclock/analogclock.pro
new file mode 100644
index 0000000..7e0360d
--- /dev/null
+++ b/examples/gui/analogclock/analogclock.pro
@@ -0,0 +1,4 @@
+include(../rasterwindow/rasterwindow.pri)
+
+SOURCES += \
+    main.cpp
diff --git a/examples/gui/analogclock/main.cpp b/examples/gui/analogclock/main.cpp
new file mode 100644
index 0000000..6e5c597
--- /dev/null
+++ b/examples/gui/analogclock/main.cpp
@@ -0,0 +1,160 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtGui>
+
+#include "rasterwindow.h"
+
+//! [5]
+class AnalogClockWindow : public RasterWindow
+{
+public:
+    AnalogClockWindow();
+
+protected:
+    void timerEvent(QTimerEvent *);
+    void render(QPainter *p);
+
+private:
+    int m_timerId;
+};
+//! [5]
+
+
+//! [6]
+AnalogClockWindow::AnalogClockWindow()
+{
+    setWindowTitle("Analog Clock");
+    resize(200, 200);
+
+    m_timerId = startTimer(1000);
+}
+//! [6]
+
+//! [7]
+void AnalogClockWindow::timerEvent(QTimerEvent *event)
+{
+    if (event->timerId() == m_timerId)
+        renderLater();
+}
+//! [7]
+
+//! [1] //! [14]
+void AnalogClockWindow::render(QPainter *p)
+{
+//! [14]
+//! [8]
+    static const QPoint hourHand[3] = {
+        QPoint(7, 8),
+        QPoint(-7, 8),
+        QPoint(0, -40)
+    };
+    static const QPoint minuteHand[3] = {
+        QPoint(7, 8),
+        QPoint(-7, 8),
+        QPoint(0, -70)
+    };
+
+    QColor hourColor(127, 0, 127);
+    QColor minuteColor(0, 127, 127, 191);
+//! [8]
+
+//! [9]
+    p->setRenderHint(QPainter::Antialiasing);
+//! [9] //! [10]
+    p->translate(width() / 2, height() / 2);
+
+    int side = qMin(width(), height());
+    p->scale(side / 200.0, side / 200.0);
+//! [1] //! [10]
+
+//! [11]
+    p->setPen(Qt::NoPen);
+    p->setBrush(hourColor);
+//! [11]
+
+//! [2]
+    QTime time = QTime::currentTime();
+
+    p->save();
+    p->rotate(30.0 * ((time.hour() + time.minute() / 60.0)));
+    p->drawConvexPolygon(hourHand, 3);
+    p->restore();
+//! [2]
+
+//! [12]
+    p->setPen(hourColor);
+
+    for (int i = 0; i < 12; ++i) {
+        p->drawLine(88, 0, 96, 0);
+        p->rotate(30.0);
+    }
+//! [12] //! [13]
+    p->setPen(Qt::NoPen);
+    p->setBrush(minuteColor);
+//! [13]
+
+//! [3]
+    p->save();
+    p->rotate(6.0 * (time.minute() + time.second() / 60.0));
+    p->drawConvexPolygon(minuteHand, 3);
+    p->restore();
+//! [3]
+
+//! [4]
+    p->setPen(minuteColor);
+
+    for (int j = 0; j < 60; ++j) {
+        if ((j % 5) != 0)
+            p->drawLine(92, 0, 96, 0);
+        p->rotate(6.0);
+    }
+//! [4]
+}
+
+int main(int argc, char **argv)
+{
+    QGuiApplication app(argc, argv);
+
+    AnalogClockWindow clock;
+    clock.show();
+
+    app.exec();
+}
diff --git a/examples/gui/gui.pro b/examples/gui/gui.pro
new file mode 100644
index 0000000..168379b
--- /dev/null
+++ b/examples/gui/gui.pro
@@ -0,0 +1,5 @@
+TEMPLATE     = subdirs
+
+SUBDIRS += analogclock
+SUBDIRS += rasterwindow
+
diff --git a/examples/gui/rasterwindow/main.cpp b/examples/gui/rasterwindow/main.cpp
new file mode 100644
index 0000000..4f39a02
--- /dev/null
+++ b/examples/gui/rasterwindow/main.cpp
@@ -0,0 +1,53 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "rasterwindow.h"
+
+//! [1]
+int main(int argc, char **argv)
+{
+    QGuiApplication app(argc, argv);
+
+    RasterWindow window;
+    window.show();
+
+    return app.exec();
+}
+//! [1]
diff --git a/examples/gui/rasterwindow/rasterwindow.cpp b/examples/gui/rasterwindow/rasterwindow.cpp
new file mode 100644
index 0000000..e999ed9
--- /dev/null
+++ b/examples/gui/rasterwindow/rasterwindow.cpp
@@ -0,0 +1,124 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "rasterwindow.h"
+
+//! [1]
+RasterWindow::RasterWindow(QWindow *parent)
+    : QWindow(parent)
+    , m_update_pending(false)
+{
+    create();
+
+    setGeometry(100, 100, 300, 200);
+
+    m_backingStore = new QBackingStore(this);
+}
+//! [1]
+
+
+//! [7]
+bool RasterWindow::event(QEvent *event)
+{
+    if (event->type() == QEvent::UpdateRequest) {
+        m_update_pending = false;
+        renderNow();
+        return true;
+    }
+    return QWindow::event(event);
+}
+//! [7]
+
+//! [6]
+void RasterWindow::renderLater()
+{
+    if (!m_update_pending) {
+        m_update_pending = true;
+        QCoreApplication::postEvent(this, new QEvent(QEvent::UpdateRequest));
+    }
+}
+//! [6]
+
+
+//! [5]
+void RasterWindow::resizeEvent(QResizeEvent *resizeEvent)
+{
+    m_backingStore->resize(resizeEvent->size());
+    if (isExposed())
+        renderNow();
+}
+//! [5]
+
+//! [2]
+void RasterWindow::exposeEvent(QExposeEvent *)
+{
+    if (isExposed()) {
+        renderNow();
+    }
+}
+//! [2]
+
+
+//! [3]
+void RasterWindow::renderNow()
+{
+    if (!isExposed())
+        return;
+
+    QRect rect(0, 0, width(), height());
+    m_backingStore->beginPaint(rect);
+
+    QPaintDevice *device = m_backingStore->paintDevice();
+    QPainter painter(device);
+
+    painter.fillRect(0, 0, width(), height(), Qt::white);
+    render(&painter);
+
+    m_backingStore->endPaint();
+    m_backingStore->flush(rect);
+}
+//! [3]
+
+//! [4]
+void RasterWindow::render(QPainter *painter)
+{
+    painter->drawText(QRectF(0, 0, width(), height()), Qt::AlignCenter, QStringLiteral("QWindow"));
+}
+//! [4]
diff --git a/examples/gui/rasterwindow/rasterwindow.h b/examples/gui/rasterwindow/rasterwindow.h
new file mode 100644
index 0000000..8421727
--- /dev/null
+++ b/examples/gui/rasterwindow/rasterwindow.h
@@ -0,0 +1,70 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef RASTERWINDOW_H
+#define RASTERWINDOW_H
+
+//! [1]
+#include <QtGui>
+
+class RasterWindow : public QWindow
+{
+    Q_OBJECT
+public:
+    explicit RasterWindow(QWindow *parent = 0);
+
+    virtual void render(QPainter *painter);
+
+public slots:
+    void renderLater();
+    void renderNow();
+
+protected:
+    bool event(QEvent *event);
+
+    void resizeEvent(QResizeEvent *event);
+    void exposeEvent(QExposeEvent *event);
+
+private:
+    QBackingStore *m_backingStore;
+    bool m_update_pending;
+};
+//! [1]
+#endif // RASTERWINDOW_H
diff --git a/examples/gui/rasterwindow/rasterwindow.pri b/examples/gui/rasterwindow/rasterwindow.pri
new file mode 100644
index 0000000..8f71765
--- /dev/null
+++ b/examples/gui/rasterwindow/rasterwindow.pri
@@ -0,0 +1,3 @@
+INCLUDEPATH += $$PWD
+SOURCES += $$PWD/rasterwindow.cpp
+HEADERS += $$PWD/rasterwindow.h
diff --git a/examples/gui/rasterwindow/rasterwindow.pro b/examples/gui/rasterwindow/rasterwindow.pro
new file mode 100644
index 0000000..a767166
--- /dev/null
+++ b/examples/gui/rasterwindow/rasterwindow.pro
@@ -0,0 +1,7 @@
+include(rasterwindow.pri)
+
+OTHER_FILES += \
+    rasterwindow.pri
+
+SOURCES += \
+    main.cpp
diff --git a/src/gui/doc/examples/analogclockwindow.qdoc b/src/gui/doc/examples/analogclockwindow.qdoc
new file mode 100644
index 0000000..0fdad48
--- /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.
+*/
diff --git a/src/gui/doc/examples/rasterwindow.qdoc b/src/gui/doc/examples/rasterwindow.qdoc
new file mode 100644
index 0000000..fd69d6d
--- /dev/null
+++ b/src/gui/doc/examples/rasterwindow.qdoc
@@ -0,0 +1,161 @@
+****************************************************************************
+**
+** 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/rasterwindow
+    \title Raster Window Example
+
+    This example shows how to create a minimal QWindow based
+    application using QPainter for rendering.
+
+
+    \section1 Application Entry Point
+
+    \snippet gui/rasterwindow/main.cpp 1
+
+    The entry point for a QWindow based application is the \l
+    QGuiApplication class. It manages the GUI application's control
+    flow and main settings. We pass the command line arguments which
+    can be used to pick up certain system wide options.
+
+    From there, we go on to create our window instance and then call
+    the \l QWindow::show() function to tell the windowing system that
+    this window should now be made visible on screen.
+
+    Once this is done, we enter the application's event loop so the
+    application can run.
+
+
+    \section1 RasterWindow Declaration
+
+    \snippet gui/rasterwindow/rasterwindow.h 1
+
+    We first start by including the the QtGui headers. This means we
+    can use all classes in the Qt GUI module. Classes can also be
+    included individually if that is preferred.
+
+    The RasterWindow class subclasses QWindow directly and provides a
+    constructor which allows the window to be a sub-window of another
+    QWindow. Parent-less QWindows show up in the windowing system as
+    top-level windows.
+
+    The class declares a QBackingStore which is what we use to manage
+    the window's back buffer for QPainter based graphics.
+
+    \e {The raster window is also reused in a few other examples and adds
+    a few helper functions, like renderLater().}
+
+
+    \section1 RasterWindow Implementation
+
+    \snippet gui/rasterwindow/rasterwindow.cpp 1
+
+    The constructor first of all calls \l QWindow::create(). This will
+    create the window in the windowing system. Without calling create,
+    the window will not get events and will not be visible in the
+    windowing system. The call to create does not show the window. We
+    then set the geometry to be something resonable.
+
+    Then we create the backingstore and pass it the window instance it
+    is supposed to manage.
+
+    \snippet gui/rasterwindow/rasterwindow.cpp 2
+
+    Shortly after calling \l QWindow::show() on a created window, the
+    virtual function \l QWindow::exposeEvent() will be called to
+    notify us that the window's exposure in the windowing system has
+    changed. The event contains the exposed sub-region, but since we
+    will anyway draw the entire window every time, we do not make use
+    of that.
+
+    The function \l QWindow::isExposed() will tell us if the window is
+    showing or not. We need this as the exposeEvent is called also
+    when the window becomes obscured in the windowing system. If the
+    window is showing, we call renderNow() to draw the window
+    immediately. We want to draw right away so we can present the
+    system with some visual content.
+
+
+    \snippet gui/rasterwindow/rasterwindow.cpp 5
+
+    The resize event is guaranteed to be called prior to the window
+    being shown on screen and will also be called whenever the window
+    is resized while on screen. We use this to resize the back buffer
+    and call renderNow() if we are visible to immediately update the
+    visual representation of the window on screen.
+
+    \snippet gui/rasterwindow/rasterwindow.cpp 3
+
+    The renderNow function sets up what is needed for a \l QWindow to
+    render its content using QPainter. As obscured windows have will
+    not be visible, we abort if the window is not exposed in the
+    windowing system. This can for instance happen when another window
+    fully obscures this window.
+
+    We start the drawing by calling \l QBackingStore::beginPaint() on
+    the region we want to draw. Then we get the \l QPaintDevice of the
+    back buffer and create a QPainter to render to that paint device.
+
+    To void leaving traces from the previous rendering and start with a
+    clean buffer, we fill the entire buffer with the color white. Then
+    we call the virtual render() function which does the actual
+    drawing of this window.
+
+    After drawing is complete, we call endPaint() to signal that we
+    are done rendering and present the contents in the back buffer
+    using \l QBackingStore::flush().
+
+
+    \snippet gui/rasterwindow/rasterwindow.cpp 4
+
+    The render function contains the drawing code for the window. In
+    this minial example, we only draw the string "QWindow" in the
+    center.
+
+
+    \section1 Rendering Asynchronously
+
+
+    \snippet gui/rasterwindow/rasterwindow.cpp 6
+
+    We went through a few places where the window needed to repainted
+    immediately. There are some cases where this is not desierable,
+    but rather let the application return to the event loop and
+    later. We acheive this by posting an even to ourself which will
+    then be delivered when the application returns to the \l
+    QGuiApplication event loop. To avoid posting new requests when one
+    is already pending, we store this state in the \c m_update_pending
+    variable.
+
+    \snippet gui/rasterwindow/rasterwindow.cpp 7
+
+    We reimplement the virtual \l QObject::event() function to handle
+    the update event we posted to ourselves. When the event comes in
+    we reset the pending update flag and call renderNow() to render
+    the window right away.
+
+  */
diff --git a/src/gui/doc/images/analogclock-window-example.png b/src/gui/doc/images/analogclock-window-example.png
new file mode 100644
index 0000000..ffd7baa
Binary files /dev/null and b/src/gui/doc/images/analogclock-window-example.png differ
diff --git a/src/gui/doc/images/analogclockwindow-viewport.png b/src/gui/doc/images/analogclockwindow-viewport.png
new file mode 100644
index 0000000..31ce0c3
Binary files /dev/null and b/src/gui/doc/images/analogclockwindow-viewport.png differ
diff --git a/src/gui/doc/src/coordsys.qdoc b/src/gui/doc/src/coordsys.qdoc
index c0e33c9..b4be1c0 100644
--- a/src/gui/doc/src/coordsys.qdoc
+++ b/src/gui/doc/src/coordsys.qdoc
@@ -230,14 +230,13 @@
     \row
     \li {2,1}
 
-    \snippet widgets/analogclock/analogclock.cpp 9
+    \snippet gui/analogclock/main.cpp 1
 
-    First, we set up the painter. We translate the coordinate system
-    so that point (0, 0) is in the widget's center, instead of being
-    at the top-left corner. We also scale the system by \c side / 100,
-    where \c side is either the widget's width or the height,
-    whichever is shortest. We want the clock to be square, even if the
-    device isn't.
+    We translate the coordinate system so that point (0, 0) is in the
+    widget's center, instead of being at the top-left corner. We also
+    scale the system by \c side / 100, where \c side is either the
+    widget's width or the height, whichever is shortest. We want the
+    clock to be square, even if the device isn't.
 
     This will give us a 200 x 200 square area, with the origin (0, 0)
     in the center, that we can draw on. What we draw will show up in
@@ -245,7 +244,7 @@
 
     See also the \l {Window-Viewport Conversion} section.
 
-    \snippet widgets/analogclock/analogclock.cpp 18
+    \snippet gui/analogclock/main.cpp 2
 
     We draw the clock's hour hand by rotating the coordinate system
     and calling QPainter::drawConvexPolygon(). Thank's to the
@@ -260,14 +259,14 @@
     the code guarantees that the code that follows won't be disturbed
     by the transformations we've used.
 
-    \snippet widgets/analogclock/analogclock.cpp 24
+    \snippet gui/analogclock/main.cpp 3
 
     We do the same for the clock's minute hand, which is defined by
     the four points (1, 0), (0, 1), (-1, 0), and (0, -40). These
     coordinates specify a hand that is thinner and longer than the
     minute hand.
 
-    \snippet widgets/analogclock/analogclock.cpp 27
+    \snippet gui/analogclock/main.cpp 4
 
     Finally, we draw the clock face, which consists of twelve short
     lines at 30-degree intervals. At the end of that, the painter is
@@ -440,9 +439,5 @@
     \endtable
     \endomit
 
-    \sa {Analog Clock Example}
+    \sa {Analog Clock Window Example}
 */
-
-/*
-    ### DOC-TODO: rewrite analog clock to be QWindow based
- */
\ No newline at end of file
diff --git a/src/gui/doc/src/qtgui.qdoc b/src/gui/doc/src/qtgui.qdoc
index 64d9cb6..0421b17 100644
--- a/src/gui/doc/src/qtgui.qdoc
+++ b/src/gui/doc/src/qtgui.qdoc
@@ -63,9 +63,10 @@
     For application developers writing user interfaces, Qt provides
     higher level API's, like Qt Quick, that are much more suitable
     than the enablers found in the Qt GUI module. 
+    than the enablers found in the Qt GUI module.
+
 
 
-    
     \section1 Application Windows
 
     The most important classes in the Qt GUI module are
@@ -73,7 +74,7 @@
     content on screen, will need to make use of these. QGuiApplication
     contains the main event loop, where all events from the window
     system and other sources are processed and dispatched. It also
-    handles the application's initialization and finalization. 
+    handles the application's initialization and finalization.
 
     The \l QWindow class represents a window in the underlying
     windowing system. It provides a number of virtual functions to
@@ -83,16 +84,16 @@
 
 
     \section1 2D Graphics
- 
+
     The Qt GUI module contains classes for 2D graphics, imaging, fonts
     and advanced typography.
-    
+
     A \l QWindow created with the surface type \l
     {QSurface::RasterSurface} can be used in combination with \l
     {QBackingStore} and \l {QPainter}, Qt's highly optimized 2D vector
     graphics API. QPainter supports drawing lines, polygons, vector
     paths, images and text. For more information, see \l{Paint
-    System}.
+    System} and \l {Raster Window Example}.
 
     Qt can load and save images using the \l QImage and \l QPixmap
     classes. By default, Qt supports the most common image formats
@@ -109,7 +110,7 @@
 
 
     \section1 OpenGL and OpenGL ES integration
-    
+
     QWindow supports rendering using desktop OpenGL, OpenGL ES 1.1 and
     OpenGL ES 2.0, depending on what the platform supports. OpenGL
     rendering is enabled by setting the QWindow's surface type to
@@ -126,7 +127,6 @@
     be used in combination with \l QPainter and \l QOpenGLPaintDevice
     to have OpenGL hardware accellerated 2D graphics, by sacrificing
     some of the visual quality.
-    
 
 
 
@@ -148,14 +148,6 @@
 
 /*
 
-    ### DOC-TODO: link under AppWindows to hello-world for QWindow in
-        examples/gui/windows/hello-qtgui. (Idea: QWindow which
-        reimplements mouseEvent() to exit)
-
-    ### DOC-TODO: link under Painting to hello-raster for QWindow
-        in examples/gui/graphics/rasterwindow. Idea: QWindow with BS
-        which draws a rotating rectangle with some text underneath.
-
     ### DOC-TODO: link under OpenGL to hello-opengl for QWindow in
         examples/gui/opengl/openglwindow. Idea: QWindow which draws a
         triangle using GLES 2.0 compatible shaders. Do not care about