--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/painting-and-printing/paintsystem.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,570 @@
+/****************************************************************************
+**
+** 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)
+ \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
+ documentation about \l{Implementing Styles and Style Aware Widgets}.
+*/