Move the module qdoc files from qtdoc and split up doc/src.

Change-Id: I7d992889379d78e07a0b7023facebd7421cf6d22
Reviewed-on: http://codereview.qt-project.org/5092
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Jerome Pasion <jerome.pasion@nokia.com>

3 files changed, 1033 insertions, 0 deletions

diff --git a/doc/src/gui/coordsys.qdoc b/doc/src/gui/coordsys.qdoc
new file mode 100644
index 0000000000..96eebd01e0
--- /dev/null
+++ b/doc/src/gui/coordsys.qdoc
@@ -0,0 +1,461 @@
+/****************************************************************************
+**
+** 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$
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \page coordsys.html
+    \title Coordinate System
+    \ingroup qt-graphics
+	\ingroup best-practices
+    \brief Information about the coordinate system used by the paint
+    system.
+
+    The coordinate system is controlled by the QPainter
+    class. Together with the QPaintDevice and QPaintEngine classes,
+    QPainter form the basis of Qt's painting system, Arthur. QPainter
+    is used to perform drawing operations, QPaintDevice is an
+    abstraction of a two-dimensional space that can be painted on
+    using a QPainter, and QPaintEngine provides the interface that the
+    painter uses to draw onto different types of devices.
+
+    The QPaintDevice class is the base class of objects that can be
+    painted: Its drawing capabilities are inherited by the QWidget,
+    QPixmap, QPicture, QImage, and QPrinter classes. The default
+    coordinate system of a paint device has its origin at the top-left
+    corner. The \e x values increase to the right and the \e y values
+    increase downwards. The default unit is one pixel on pixel-based
+    devices and one point (1/72 of an inch) on printers.
+
+    The mapping of the logical QPainter coordinates to the physical
+    QPaintDevice coordinates are handled by QPainter's transformation
+    matrix, viewport and "window". The logical and physical coordinate
+    systems coincide by default. QPainter also supports coordinate
+    transformations (e.g. rotation and scaling).
+
+    \tableofcontents
+
+    \section1 Rendering
+
+    \section2 Logical Representation
+
+    The size (width and height) of a graphics primitive always
+    correspond to its mathematical model, ignoring the width of the
+    pen it is rendered with:
+
+    \table
+    \row
+    \o \inlineimage coordinatesystem-rect.png
+    \o \inlineimage coordinatesystem-line.png
+    \row
+    \o QRect(1, 2, 6, 4)
+    \o QLine(2, 7, 6, 1)
+    \endtable
+
+    \section2 Aliased Painting
+
+    When drawing, the pixel rendering is controlled by the
+    QPainter::Antialiasing render hint.
+
+    The \l {QPainter::RenderHint}{RenderHint} enum is used to specify
+    flags to QPainter that may or may not be respected by any given
+    engine. The QPainter::Antialiasing value indicates that the engine
+    should antialias edges of primitives if possible, i.e. smoothing
+    the edges by using different color intensities.
+
+    But by default the painter is \e aliased and other rules apply:
+    When rendering with a one pixel wide pen the pixels will be
+    rendered to the \e {right and below the mathematically defined
+    points}. For example:
+
+    \table
+    \row
+    \o \inlineimage coordinatesystem-rect-raster.png
+    \o \inlineimage coordinatesystem-line-raster.png
+
+    \row
+    \o
+    \snippet doc/src/snippets/code/doc_src_coordsys.cpp 0
+
+    \o
+    \snippet doc/src/snippets/code/doc_src_coordsys.cpp 1
+    \endtable
+
+    When rendering with a pen with an even number of pixels, the
+    pixels will be rendered symetrically around the mathematical
+    defined points, while rendering with a pen with an odd number of
+    pixels, the spare pixel will be rendered to the right and below
+    the mathematical point as in the one pixel case. See the QRectF
+    diagrams below for concrete examples.
+
+    \table
+    \header
+    \o {3,1} QRectF
+    \row
+    \o \inlineimage qrect-diagram-zero.png
+    \o \inlineimage qrectf-diagram-one.png
+    \row
+    \o Logical representation
+    \o One pixel wide pen
+    \row
+    \o \inlineimage qrectf-diagram-two.png
+    \o \inlineimage qrectf-diagram-three.png
+    \row
+    \o Two pixel wide pen
+    \o Three pixel wide pen
+    \endtable
+
+    Note that for historical reasons the return value of the
+    QRect::right() and QRect::bottom() functions deviate from the true
+    bottom-right corner of the rectangle.
+
+    QRect's \l {QRect::right()}{right()} function returns \l
+    {QRect::left()}{left()} + \l {QRect::width()}{width()} - 1 and the
+    \l {QRect::bottom()}{bottom()} function returns \l
+    {QRect::top()}{top()} + \l {QRect::height()}{height()} - 1.  The
+    bottom-right green point in the diagrams shows the return
+    coordinates of these functions.
+
+    We recommend that you simply use QRectF instead: The QRectF class
+    defines a rectangle in the plane using floating point coordinates
+    for accuracy (QRect uses integer coordinates), and the
+    QRectF::right() and QRectF::bottom() functions \e do return the
+    true bottom-right corner.
+
+    Alternatively, using QRect, apply \l {QRect::x()}{x()} + \l
+    {QRect::width()}{width()} and \l {QRect::y()}{y()} + \l
+    {QRect::height()}{height()} to find the bottom-right corner, and
+    avoid the \l {QRect::right()}{right()} and \l
+    {QRect::bottom()}{bottom()} functions.
+
+    \section2 Anti-aliased Painting
+
+    If you set QPainter's \l {QPainter::Antialiasing}{anti-aliasing}
+    render hint, the pixels will be rendered symetrically on both
+    sides of the mathematically defined points:
+
+    \table
+    \row
+    \o \inlineimage coordinatesystem-rect-antialias.png
+    \o \inlineimage coordinatesystem-line-antialias.png
+    \row
+    \o
+
+    \snippet doc/src/snippets/code/doc_src_coordsys.cpp 2
+
+    \o
+    \snippet doc/src/snippets/code/doc_src_coordsys.cpp 3
+    \endtable
+
+    \section1 Transformations
+
+    By default, the QPainter operates on the associated device's own
+    coordinate system, but it also has complete support for affine
+    coordinate transformations.
+
+    You can scale the coordinate system by a given offset using the
+    QPainter::scale() function, you can rotate it clockwise using the
+    QPainter::rotate() function and you can translate it (i.e. adding
+    a given offset to the points) using the QPainter::translate()
+    function.
+
+    \table
+    \row
+    \o \inlineimage qpainter-clock.png
+    \o \inlineimage qpainter-rotation.png
+    \o \inlineimage qpainter-scale.png
+    \o \inlineimage qpainter-translation.png
+    \row
+    \o nop
+    \o \l {QPainter::rotate()}{rotate()}
+    \o \l {QPainter::scale()}{scale()}
+    \o \l {QPainter::translate()}{translate()}
+    \endtable
+
+    You can also twist the coordinate system around the origin using
+    the QPainter::shear() function. See the \l {painting/affine}{Affine
+    Transformations} example for a visualization of a sheared coordinate
+    system. All the transformation operations operate on QPainter's
+    transformation matrix that you can retrieve using the
+    QPainter::worldTransform() function. A matrix transforms a point
+    in the plane to another point.
+
+    If you need the same transformations over and over, you can also
+    use QTransform objects and the QPainter::worldTransform() and
+    QPainter::setWorldTransform() functions. You can at any time save the
+    QPainter's transformation matrix by calling the QPainter::save()
+    function which saves the matrix on an internal stack. The
+    QPainter::restore() function pops it back.
+
+    One frequent need for the transformation matrix is when reusing
+    the same drawing code on a variety of paint devices. Without
+    transformations, the results are tightly bound to the resolution
+    of the paint device. Printers have high resolution, e.g. 600 dots
+    per inch, whereas screens often have between 72 and 100 dots per
+    inch.
+
+    \table 100%
+    \header
+    \o {2,1} Analog Clock Example
+    \row
+    \o \inlineimage coordinatesystem-analogclock.png
+    \o
+    The Analog Clock example shows how to draw the contents of a
+    custom widget using QPainter's transformation matrix.
+
+    Qt's example directory provides a complete walk-through of the
+    example. Here, we will only review the example's \l
+    {QWidget::paintEvent()}{paintEvent()} function to see how we can
+    use the transformation matrix (i.e. QPainter's matrix functions)
+    to draw the clock's face.
+
+    We recommend compiling and running this example before you read
+    any further. In particular, try resizing the window to different
+    sizes.
+
+    \row
+    \o {2,1}
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 9
+
+    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.
+
+    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
+    the largest possible square that will fit in the widget.
+
+    See also the \l {Window-Viewport Conversion} section.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 18
+
+    We draw the clock's hour hand by rotating the coordinate system
+    and calling QPainter::drawConvexPolygon(). Thank's to the
+    rotation, it's drawn pointed in the right direction.
+
+    The polygon is specified as an array of alternating \e x, \e y
+    values, stored in the \c hourHand static variable (defined at the
+    beginning of the function), which corresponds to the four points
+    (2, 0), (0, 2), (-2, 0), and (0, -25).
+
+    The calls to QPainter::save() and QPainter::restore() surrounding
+    the code guarantees that the code that follows won't be disturbed
+    by the transformations we've used.
+
+    \snippet examples/widgets/analogclock/analogclock.cpp 24
+
+    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 examples/widgets/analogclock/analogclock.cpp 27
+
+    Finally, we draw the clock face, which consists of twelve short
+    lines at 30-degree intervals. At the end of that, the painter is
+    rotated in a way which isn't very useful, but we're done with
+    painting so that doesn't matter.
+    \endtable
+
+    For a demonstation of Qt's ability to perform affine
+    transformations on painting operations, see the \l
+    {painting/affine}{Affine Transformations} example which allows the user
+    to experiment with the transformation operations.  See also the \l
+    {painting/transformations}{Transformations} example which shows
+    how transformations influence the way that QPainter renders
+    graphics primitives. In particular, it shows how the order of
+    transformations affects the result.
+
+    For more information about the transformation matrix, see the
+    QTransform documentation.
+
+    \section1 Window-Viewport Conversion
+
+    When drawing with QPainter, we specify points using logical
+    coordinates which then are converted into the physical coordinates
+    of the paint device.
+
+    The mapping of the logical coordinates to the physical coordinates
+    are handled by QPainter's world transformation \l
+    {QPainter::worldTransform()}{worldTransform()} (described in the \l
+    Transformations section), and QPainter's \l
+    {QPainter::viewport()}{viewport()} and \l
+    {QPainter::window()}{window()}.  The viewport represents the
+    physical coordinates specifying an arbitrary rectangle. The
+    "window" describes the same rectangle in logical coordinates. By
+    default the logical and physical coordinate systems coincide, and
+    are equivalent to the paint device's rectangle.
+
+    Using window-viewport conversion you can make the logical
+    coordinate system fit your preferences. The mechanism can also be
+    used to make the drawing code independent of the paint device. You
+    can, for example, make the logical coordinates extend from (-50,
+    -50) to (50, 50) with (0, 0) in the center by calling the
+    QPainter::setWindow() function:
+
+    \snippet doc/src/snippets/code/doc_src_coordsys.cpp 4
+
+    Now, the logical coordinates (-50,-50) correspond to the paint
+    device's physical coordinates (0, 0). Independent of the paint
+    device, your painting code will always operate on the specified
+    logical coordinates.
+
+    By setting the "window" or viewport rectangle, you perform a
+    linear transformation of the coordinates. Note that each corner of
+    the "window" maps to the corresponding corner of the viewport, and
+    vice versa. For that reason it normally is a good idea to let the
+    viewport and "window" maintain the same aspect ratio to prevent
+    deformation:
+
+    \snippet doc/src/snippets/code/doc_src_coordsys.cpp 5
+
+    If we make the logical coordinate system a square, we should also
+    make the viewport a square using the QPainter::setViewport()
+    function. In the example above we make it equivalent to the
+    largest square that fit into the paint device's rectangle. By
+    taking the paint device's size into consideration when setting the
+    window or viewport, it is possible to keep the drawing code
+    independent of the paint device.
+
+    Note that the window-viewport conversion is only a linear
+    transformation, i.e. it does not perform clipping. This means that
+    if you paint outside the currently set "window", your painting is
+    still transformed to the viewport using the same linear algebraic
+    approach.
+
+    \image coordinatesystem-transformations.png
+
+    The viewport, "window" and transformation matrix determine how
+    logical QPainter coordinates map to the paint device's physical
+    coordinates. By default the world transformation matrix is the
+    identity matrix, and the "window" and viewport settings are
+    equivalent to the paint device's settings, i.e. the world,
+    "window" and device coordinate systems are equivalent, but as we
+    have seen, the systems can be manipulated using transformation
+    operations and window-viewport conversion. The illustration above
+    describes the process.
+
+    \omit
+    \section1 Related Classes
+
+    Qt's paint system, Arthur, is primarily based on the QPainter,
+    QPaintDevice, and QPaintEngine classes:
+
+    \table
+    \header \o Class \o Description
+    \row
+    \o QPainter
+    \o
+    The QPainter class performs low-level painting on widgets and
+    other paint devices.  QPainter can operate on any object that
+    inherits the QPaintDevice class, using the same code.
+    \row
+    \o QPaintDevice
+    \o
+    The QPaintDevice class is the base class of objects that can be
+    painted. Qt provides several devices: QWidget, QImage, QPixmap,
+    QPrinter and QPicture, and other devices can also be defined by
+    subclassing QPaintDevice.
+    \row
+    \o QPaintEngine
+    \o
+    The QPaintEngine class provides an abstract definition of how
+    QPainter draws to a given device on a given platform.  Qt 4
+    provides several premade implementations of QPaintEngine for the
+    different painter backends we support; it provides one paint
+    engine for each supported window system and painting
+    frameworkt. You normally don't need to use this class directly.
+    \endtable
+
+    The 2D transformations of the coordinate system are specified
+    using the QTransform class:
+
+    \table
+    \header \o Class \o Description
+    \row
+    \o QTransform
+    \o
+    A 3 x 3 transformation matrix. Use QTransform to rotate, shear,
+    scale, or translate the coordinate system.
+    \endtable
+
+    In addition Qt provides several graphics primitive classes. Some
+    of these classes exist in two versions: an \c{int}-based version
+    and a \c{qreal}-based version. For these, the \c qreal version's
+    name is suffixed with an \c F.
+
+    \table
+    \header \o Class \o Description
+    \row
+    \o \l{QPoint}(\l{QPointF}{F})
+    \o
+    A single 2D point in the coordinate system. Most functions in Qt
+    that deal with points can accept either a QPoint, a QPointF, two
+    \c{int}s, or two \c{qreal}s.
+    \row
+    \o \l{QSize}(\l{QSizeF}{F})
+    \o
+    A single 2D vector. Internally, QPoint and QSize are the same, but
+    a point is not the same as a size, so both classes exist.  Again,
+    most functions accept either QSizeF, a QSize, two \c{int}s, or two
+    \c{qreal}s.
+    \row
+    \o \l{QRect}(\l{QRectF}{F})
+    \o
+    A 2D rectangle. Most functions accept either a QRectF, a QRect,
+    four \c{int}s, or four \c {qreal}s.
+    \row
+    \o \l{QLine}(\l{QLineF}{F})
+    \o
+    A 2D finite-length line, characterized by a start point and an end
+    point.
+    \row
+    \o \l{QPolygon}(\l{QPolygonF}{F})
+    \o
+    A 2D polygon. A polygon is a vector of \c{QPoint(F)}s. If the
+    first and last points are the same, the polygon is closed.
+    \row
+    \o QPainterPath
+    \o
+    A vectorial specification of a 2D shape. Painter paths are the
+    ultimate painting primitive, in the sense that any shape
+    (rectange, ellipse, spline) or combination of shapes can be
+    expressed as a path. A path specifies both an outline and an area.
+    \row
+    \o QRegion
+    \o
+    An area in a paint device, expressed as a list of
+    \l{QRect}s. In general, we recommend using the vectorial
+    QPainterPath class instead of QRegion for specifying areas,
+    because QPainterPath handles painter transformations much better.
+    \endtable
+    \endomit
+
+    \sa {Analog Clock Example}, {Transformations Example}
+*/
diff --git a/doc/src/gui/paintsystem.qdoc b/doc/src/gui/paintsystem.qdoc
new file mode 100644
index 0000000000..a567509186
--- /dev/null
+++ b/doc/src/gui/paintsystem.qdoc
@@ -0,0 +1,560 @@
+/****************************************************************************
+**
+** 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$
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \group painting
+    \title Painting Classes
+    \ingroup groups
+
+    \brief Classes that provide support for painting.
+
+    See also this introduction to the \link coordsys.html Qt
+    coordinate system. \endlink
+*/
+
+/*!
+    \group painting-3D
+    \title Rendering in 3D
+    \ingroup groups
+
+    \brief Classes that provide support for rendering in 3D.
+*/
+
+/*!
+    \page paintsystem.html
+    \title Paint System
+    \brief A system for painting on the screen or on print devices using the same API
+    \ingroup qt-graphics
+    \ingroup frameworks-technologies
+    \ingroup qt-basic-concepts
+	
+
+    Qt's paint system enables painting on screen and print devices
+    using the same API, and is primarily based on the QPainter,
+    QPaintDevice, and QPaintEngine classes.
+
+    QPainter is used to perform drawing operations, QPaintDevice is an
+    abstraction of a two-dimensional space that can be painted on
+    using a QPainter, and QPaintEngine provides the interface that the
+    painter uses to draw onto different types of devices. The
+    QPaintEngine class is used internally by QPainter and
+    QPaintDevice, and is hidden from application programmers unless
+    they create their own device type.
+
+    \image paintsystem-core.png
+
+    The main benefit of this approach is that all painting follows the
+    same painting pipeline making it easy to add support for new
+    features and providing default implementations for unsupported
+    ones.
+    
+    \section1 Topics
+    \list
+        \o \l{Classes for Painting}
+        \o \l{Paint Devices and Backends}
+        \o \l{Drawing and Filling}
+        \o \l{Coordinate System}
+        \o \l{Reading and Writing Image Files}
+        \o \l{Styling}
+        \o \l{Printing with Qt}
+    \endlist
+
+    \section1 Classes for Painting
+
+    These classes provide support for painting onto a paint device.
+
+    \annotatedlist painting
+
+    Alternatively, Qt provides the QtOpenGL module, offering classes
+    that makes it easy to use OpenGL in Qt applications. Among others,
+    the module provides an OpenGL widget class that can be used just
+    like any other Qt widget, except that it opens an OpenGL display
+    buffer where the OpenGL API can be used to render the contents.
+*/
+
+
+/*!
+    \page paintsystem-devices.html
+    \title Paint Devices and Backends
+
+	\contentspage The Paint System
+	\nextpage Drawing and Filling
+
+    \section1 Creating a Paint Device
+
+    The QPaintDevice class is the base class of objects that can be
+    painted, i.e. QPainter can draw on any QPaintDevice
+    subclass. QPaintDevice's drawing capabilities are currently
+    implemented by the QWidget, QImage, QPixmap, QGLWidget,
+    QGLPixelBuffer, QPicture and QPrinter subclasses.
+
+    \image paintsystem-devices.png
+
+    \table 100%
+    \row \o \bold Widget
+
+    The QWidget class is the base class of all user interface
+    objects. The widget is the atom of the user interface: it receives
+    mouse, keyboard and other events from the window system, and
+    paints a representation of itself on the screen.
+
+    \row \o \bold Image
+
+    The QImage class provides a hardware-independent image
+    representation which is designed and optimized for I/O, and for
+    direct pixel access and manipulation. QImage supports several
+    image formats including monochrome, 8-bit, 32-bit and
+    alpha-blended images.
+
+    One advantage of using QImage as a paint device is that it is
+    possible to guarantee the pixel exactness of any drawing operation
+    in a platform-independent way. Another benefit is that the
+    painting can be performed in another thread than the current GUI
+    thread.
+    
+    \row \o \bold Pixmap
+
+    The QPixmap class is an off-screen image representation which is
+    designed and optimized for showing images on screen. Unlike
+    QImage, the pixel data in a pixmap is internal and is managed by
+    the underlying window system, i.e. pixels can only be accessed
+    through QPainter functions or by converting the QPixmap to a
+    QImage.
+
+    To optimize drawing with QPixmap, Qt provides the QPixmapCache
+    class which can be used to store temporary pixmaps that are
+    expensive to generate without using more storage space than the
+    cache limit.
+
+    Qt also provides the QBitmap convenience class, inheriting
+    QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and
+    is mainly used for creating custom QCursor and QBrush objects,
+    constructing QRegion objects, and for setting masks for pixmaps
+    and widgets.
+
+    \row \o \bold {OpenGL Widget}
+
+    As mentioned previously, Qt provides the QtOpenGL module offering
+    classes that makes it easy to use OpenGL in Qt applications. For
+    example, the QGLWidget enables the OpenGL API for
+    rendering.
+
+    But QGLWidget is also a QWidget subclass, and can be used by
+    QPainter as any other paint device. One huge benefit from this is
+    that it enables Qt to utilize the high performance of OpenGL for
+    most drawing operations, such as transformations and pixmap
+    drawing.
+
+    \row \o \bold {Pixel Buffer}
+
+    The QtOpenGL module also provides the QGLPixelBuffer class which
+    inherits QPaintDevice directly.
+
+    QGLPixelBuffer encapsulates an OpenGL pbuffer. Rendering into a
+    pbuffer is normally done using full hardware acceleration which
+    can be significantly faster than rendering into a QPixmap.
+
+    \row \o \bold {Framebuffer Object}
+
+    The QtOpenGL module also provides the QGLFramebufferObject class
+    which inherits QPaintDevice directly.
+
+    QGLFramebufferObject encapsulates an OpenGL framebuffer object.
+    Framebuffer objects can also be used for off-screen rendering, and
+    offer several advantages over pixel buffers for this purpose.
+    These are described in the QGLFramebufferObject class documentation.
+
+    \row \o \bold {Picture}
+
+    The QPicture class is a paint device that records and replays
+    QPainter commands. A picture serializes painter commands to an IO
+    device in a platform-independent format. QPicture is also
+    resolution independent, i.e. a QPicture can be displayed on
+    different devices (for example svg, pdf, ps, printer and screen)
+    looking the same.
+
+    Qt provides the QPicture::load() and QPicture::save() functions
+    as well as streaming operators for loading and saving pictures.
+
+    \row \o \bold {Printer}
+
+    The QPrinter class is a paint device that paints on a printer. On
+    Windows or Mac OS X, QPrinter uses the built-in printer
+    drivers. On X11, QPrinter generates postscript and sends that to
+    lpr, lp, or another print program. QPrinter can also print to any
+    other QPrintEngine object.
+
+    The QPrintEngine class defines an interface for how QPrinter
+    interacts with a given printing subsystem. The common case when
+    creating your own print engine, is to derive from both
+    QPaintEngine and QPrintEngine.
+
+    The output format is by default determined by the platform the
+    printer is running on, but by explicitly setting the output format
+    to QPrinter::PdfFormat, QPrinter will generate its output as a PDF
+    file.
+
+    \row \o \bold {Custom Backends}
+
+    Support for a new backend can be implemented by deriving from the
+    QPaintDevice class and reimplementing the virtual
+    QPaintDevice::paintEngine() function to tell QPainter which paint
+    engine should be used to draw on this particular device. To
+    actually be able to draw on the device, this paint engine must be
+    a custom paint engine created by deriving from the QPaintEngine
+    class.
+    
+    \endtable
+
+    \section1 Selecting the Painting Backend
+
+    Since Qt 4.5, it is possible to replace the paint engines and paint
+    devices used for widgets, pixmaps and the offscreen double buffer. By
+    default the backends are:
+
+    \table
+        \row
+            \o Windows
+            \o Software Rasterizer
+        \row
+            \o X11
+            \o X11
+        \row
+            \o Mac OS X
+            \o CoreGraphics
+        \row
+            \o Embedded
+            \o Software Rasterizer
+    \endtable
+
+    Passing a command line parameter to the application, such as,
+    \c{-graphicssystem raster}, specifies that Qt should use the software
+    rasterizer for this application. The Software rasterizer is fully
+    supported on all platforms.
+
+    \code
+      > analogclock -graphicssystem raster
+    \endcode
+
+    There is also a \c{-graphicssystem opengl} mode that uses OpenGL for
+    all drawing. Currently, this engine is experimental as it does not draw
+    everything correctly.
+
+    Qt also supports being configured using \c {-graphicssystem
+    raster|opengl} in which case all applications will use the
+    specified graphics system for its graphics.
+*/
+
+/*!
+    \page paintsystem-drawing.html
+    \title Drawing and Filling
+    
+    \previouspage Paint Devices and Backends
+    \contentspage The Paint System
+    \nextpage Coordinate System
+
+    \section1 Drawing
+
+    QPainter provides highly optimized functions to do most of the
+    drawing GUI programs require. It can draw everything from simple
+    graphical primitives (represented by the QPoint, QLine, QRect,
+    QRegion and QPolygon classes) to complex shapes like vector
+    paths. In Qt vector paths are represented by the QPainterPath
+    class. QPainterPath provides a container for painting operations,
+    enabling graphical shapes to be constructed and reused.
+
+    \table 100%
+    \row
+    \o \image paintsystem-painterpath.png
+    \o \bold QPainterPath
+
+    A painter path is an object composed of lines and curves. For
+    example, a rectangle is composed by lines and an ellipse is
+    composed by curves.
+
+    The main advantage of painter paths over normal drawing operations
+    is that complex shapes only need to be created once; then they can
+    be drawn many times using only calls to the QPainter::drawPath()
+    function.
+
+    A QPainterPath object can be used for filling, outlining, and
+    clipping. To generate fillable outlines for a given painter path,
+    use the QPainterPathStroker class.
+
+    \endtable
+
+    Lines and outlines are drawn using the QPen class. A pen is
+    defined by its style (i.e. its line-type), width, brush, how the
+    endpoints are drawn (cap-style) and how joins between two
+    connected lines are drawn (join-style). The pen's brush is a
+    QBrush object used to fill strokes generated with the pen,
+    i.e. the QBrush class defines the fill pattern.
+
+    QPainter can also draw aligned text and pixmaps.
+
+    When drawing text, the font is specified using the QFont class. Qt
+    will use the font with the specified attributes, or if no matching
+    font exists, Qt will use the closest matching installed font. The
+    attributes of the font that is actually used can be retrieved
+    using the QFontInfo class. In addition, the QFontMetrics class
+    provides the font measurements, and the QFontDatabase class
+    provides information about the fonts available in the underlying
+    window system.
+
+    Normally, QPainter draws in a "natural" coordinate system, but it
+    is able to perform view and world transformations using the
+    QTransform class. For more information, see \l {Coordinate
+    System}, which also describes the rendering process, i.e. the
+    relation between the logical representation and the rendered
+    pixels, and the benefits of anti-aliased painting.
+
+    \table 100%
+    \row \o
+    \bold {Anti-Aliased Painting}
+
+    When drawing, the pixel rendering is controlled by the
+    QPainter::Antialiasing render hint. The QPainter::RenderHint enum
+    is used to specify flags to QPainter that may or may not be
+    respected by any given engine.
+
+    The QPainter::Antialiasing value indicates that the engine should
+    antialias edges of primitives if possible, i.e. smoothing the
+    edges by using different color intensities.
+
+    \o \image paintsystem-antialiasing.png
+
+    \endtable
+
+    \section1 Filling
+
+    Shapes are filled using the QBrush class. A brush is defined
+    by its color and its style (i.e. its fill pattern).
+
+    Any color in Qt is represented by the QColor class which supports
+    the RGB, HSV and CMYK color models. QColor also support
+    alpha-blended outlining and filling (specifying the transparency
+    effect), and the class is platform and device independent (the
+    colors are mapped to hardware using the QColormap class). For more
+    information, see the QColor class documentation.
+
+    When creating a new widget, it is recommend to use the colors in
+    the widget's palette rather than hard-coding specific colors. All
+    widgets in Qt contain a palette and use their palette to draw
+    themselves. A widget's palette is represented by the QPalette
+    class which contains color groups for each widget state.
+
+    The available fill patterns are described by the Qt::BrushStyle
+    enum. These include basic patterns spanning from uniform color to
+    very sparse pattern, various line combinations, gradient fills and
+    textures. Qt provides the QGradient class to define custom
+    gradient fills, while texture patterns are specified using the
+    QPixmap class.
+
+    \table 100%
+    \row
+    \o \image paintsystem-fancygradient.png
+    \o \bold QGradient
+
+    The QGradient class is used in combination with QBrush to specify
+    gradient fills.
+
+    \image paintsystem-gradients.png
+
+    Qt currently supports three types of gradient fills: Linear
+    gradients interpolate colors between start and end points, radial
+    gradients interpolate colors between a focal point and end points
+    on a circle surrounding it, and conical gradients interpolate
+    colors around a center point.
+
+    \endtable
+*/
+
+/*!
+    \page paintsystem-images.html
+    \title Reading and Writing Image Files
+
+    \previouspage Coordinate System
+    \contentspage The Paint System
+    \nextpage Styling
+
+    The most common way to read images is through QImage and QPixmap's
+    constructors, or by calling the QImage::load() and QPixmap::load()
+    functions. In addition, Qt provides the QImageReader class which
+    gives more control over the process. Depending on the underlying
+    support in the image format, the functions provided by the class
+    can save memory and speed up loading of images.
+
+    Likewise, Qt provides the QImageWriter class which supports
+    setting format specific options, such as the gamma level,
+    compression level and quality, prior to storing the image. If you
+    do not need such options, you can use QImage::save() or
+    QPixmap::save() instead.
+
+    \table 100%
+    \row
+    \o \bold QMovie
+
+    QMovie is a convenience class for displaying animations, using the
+    QImageReader class internally.  Once created, the QMovie class
+    provides various functions for both running and controlling the
+    given animation.
+
+    \o \image paintsystem-movie.png
+    \endtable
+
+    The QImageReader and QImageWriter classes rely on the
+    QImageIOHandler class which is the common image I/O interface for
+    all image formats in Qt. QImageIOHandler objects are used
+    internally by QImageReader and QImageWriter to add support for
+    different image formats to Qt.
+
+    A list of the supported file formats are available through the
+    QImageReader::supportedImageFormats() and
+    QImageWriter::supportedImageFormats() functions. Qt supports
+    several file formats by default, and in addition new formats can
+    be added as plugins. The currently supported formats are listed in
+    the QImageReader and QImageWriter class documentation.
+
+    Qt's plugin mechanism can also be used to write a custom image
+    format handler. This is done by deriving from the QImageIOHandler
+    class, and creating a QImageIOPlugin object which is a factory for
+    creating QImageIOHandler objects. When the plugin is installed,
+    QImageReader and QImageWriter will automatically load the plugin
+    and start using it.
+
+    \section1 Rendering SVG files
+
+    \table 100%
+    \row
+    \o \image paintsystem-svg.png
+    \o \bold {SVG Rendering}
+
+	Scalable Vector Graphics (SVG) is a language for describing two-dimensional
+	graphics and graphical applications in XML. SVG 1.1 is a W3C Recommendation
+	and forms the core of the current SVG developments in Qt. SVG 1.2 is the
+	specification currently being developed by the \l{SVG Working Group}, and it
+	is \l{http://www.w3.org/TR/SVG12/}{available in draft form}.
+	The \l{Mobile SVG Profiles} (SVG Basic and SVG Tiny) are aimed at
+	resource-limited devices and are part of the 3GPP platform for third generation
+	mobile phones. You can read more about SVG at \l{About SVG}.
+
+	Qt supports the \l{SVG 1.2 Tiny Static Features}{static features} of
+	\l{SVG 1.2 Tiny}. ECMA scripts and DOM manipulation are currently not
+	supported.
+
+    SVG drawings can be rendered onto any QPaintDevice subclass. This
+    approach gives developers the flexibility to experiment, in order
+    to find the best solution for each application.
+
+	The easiest way to render SVG files is to construct a QSvgWidget and
+	load an SVG file using one of the QSvgWidget::load() functions.
+
+	QSvgRenderer is the class responsible for rendering SVG files for
+	QSvgWidget, and it can be used directly to provide SVG support for
+	custom widgets.
+	To load an SVG file, construct a QSvgRenderer with a file name or the
+	contents of a file, or call QSvgRenderer::load() on an existing
+	renderer. If the SVG file has been loaded successfully the
+	QSvgRenderer::isValid() will return true.
+
+	Once you have loaded the SVG file successfully, you can render it
+	with the QSvgRenderer::render() function. Note that this scheme allows
+	you to render SVG files on all paint devices supported by Qt, including
+	QWidget, QGLWidget, and QImage. See the \l{SVG Viewer Example}{SVG Viewer}
+	example for more details.
+
+    \endtable
+*/
+
+/*!
+    \page paintsystem-styling.html
+    \title Styling
+
+    \previouspage Reading and Writing Image Files
+    \contentspage The Paint System
+    \nextpage Printing with Qt
+
+    Qt's built-in widgets use the QStyle class to perform nearly all
+    of their drawing.  QStyle is an abstract base class that
+    encapsulates the look and feel of a GUI, and can be used to make
+    the widgets look exactly like the equivalent native widgets or to
+    give the widgets a custom look.
+
+    Qt provides a set of QStyle subclasses that emulate the native
+    look of the different platforms supported by Qt (QWindowsStyle,
+    QMacStyle, QMotifStyle, etc.). These styles are built into the
+    QtGui library, other styles can be made available using Qt's
+    plugin mechansim.
+
+    Most functions for drawing style elements take four arguments:
+
+    \list
+    \o an enum value specifying which graphical element to draw
+    \o a QStyleOption object specifying how and where to render that element
+    \o a QPainter object that should be used to draw the element
+    \o a QWidget object on which the drawing is performed (optional)
+    \endlist
+
+    The style gets all the information it needs to render the
+    graphical element from the QStyleOption class. The widget is
+    passed as the last argument in case the style needs it to perform
+    special effects (such as animated default buttons on Mac OS X),
+    but it isn't mandatory. In fact, QStyle can be used to draw on any
+    paint device (not just widgets), in which case the widget argument
+    is a zero pointer.
+
+    \image paintsystem-stylepainter.png
+
+    The paint system also provides the QStylePainter class inheriting
+    from QPainter.  QStylePainter is a convenience class for drawing
+    QStyle elements inside a widget, and extends QPainter with a set
+    of high-level drawing functions implemented on top of QStyle's
+    API. The advantage of using QStylePainter is that the parameter
+    lists get considerably shorter.
+
+    \table 100%
+    \row
+    \o \inlineimage paintsystem-icon.png
+    \o \bold QIcon
+
+    The QIcon class provides scalable icons in different modes and states.
+
+    QIcon can generate pixmaps reflecting an icon's state, mode and
+    size. These pixmaps are generated from the set of pixmaps
+    made available to the icon, and are used by Qt widgets to show an
+    icon representing a particular action.
+
+    The rendering of a QIcon object is handled by the QIconEngine
+    class. Each icon has a corresponding icon engine that is
+    responsible for drawing the icon with a requested size, mode and
+    state.
+
+    \endtable
+    
+    For more information about widget styling and appearance, see the
+    \l{Styles and Style Aware Widgets}.
+*/
diff --git a/doc/src/gui/qtgui.qdoc b/doc/src/gui/qtgui.qdoc
new file mode 100644
index 0000000000..fd3bcac5a1
--- /dev/null
+++ b/doc/src/gui/qtgui.qdoc
@@ -0,0 +1,12 @@
+/*!
+    \module QtGui
+    \title QtGui Module
+    \ingroup modules
+
+    \brief The QtGui module extends QtCore with GUI functionality.
+
+    To include the definitions of both modules' classes, use the
+    following directive:
+
+    \snippet doc/src/snippets/code/doc_src_qtgui.pro 0
+*/