1 files changed, 161 insertions, 0 deletions
diff --git a/src/gui/doc/examples/rasterwindow.qdoc b/src/gui/doc/examples/rasterwindow.qdoc
new file mode 100644
index 0000000000..fd69d6d9f9
--- /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.
+
+  */