/****************************************************************************

**

** Copyright (C) 2009 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:LGPL$

** 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 Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $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 The Paint System

    \ingroup frameworks-technologies

    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{The 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 The 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 {The Coordinate

    System} documentation 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 The 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)