diff options
Diffstat (limited to 'doc/src/painting-and-printing')
| -rw-r--r-- | doc/src/painting-and-printing/coordsys.qdoc | 477 | ||||
| -rw-r--r-- | doc/src/painting-and-printing/paintsystem.qdoc | 570 | ||||
| -rw-r--r-- | doc/src/painting-and-printing/printing.qdoc | 191 |
3 files changed, 1238 insertions, 0 deletions
diff --git a/doc/src/painting-and-printing/coordsys.qdoc b/doc/src/painting-and-printing/coordsys.qdoc new file mode 100644 index 0000000..5269ea2 --- /dev/null +++ b/doc/src/painting-and-printing/coordsys.qdoc @@ -0,0 +1,477 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** 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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page coordsys.html + \title The Coordinate System + \brief Information about the coordinate system used by the paint + system. + + \previouspage Drawing and Filling + \contentspage The Paint System + \nextpage Reading and Writing Image Files + + 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.qdoc 0 + + \o + \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 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.qdoc 2 + + \o + \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 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 {demos/affine}{Affine + Transformations} demo 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 + {demos/affine}{Affine Transformations} demo 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.qdoc 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.qdoc 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/painting-and-printing/paintsystem.qdoc b/doc/src/painting-and-printing/paintsystem.qdoc new file mode 100644 index 0000000..4fd29d5 --- /dev/null +++ b/doc/src/painting-and-printing/paintsystem.qdoc @@ -0,0 +1,570 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** 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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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}. +*/ diff --git a/doc/src/painting-and-printing/printing.qdoc b/doc/src/painting-and-printing/printing.qdoc new file mode 100644 index 0000000..291286e --- /dev/null +++ b/doc/src/painting-and-printing/printing.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** 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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group printing + \title Printer and Printing APIs + \brief Classes for producing printed output + \ingroup groups +*/ + +/*! + \page printing.html + \title Printing with Qt + + \previouspage Styling + \contentspage The Paint System + + \brief A guide to producing printed output with Qt's paint system and widgets. + + Qt provides extensive cross-platform support for printing. Using the printing + systems on each platform, Qt applications can print to attached printers and + across networks to remote printers. Qt's printing system also enables PostScript + and PDF files to be generated, providing the foundation for basic report + generation facilities. + + \tableofcontents + + \section1 Classes Supporting Printing + + The following classes support the selecting and setting up of printers and + printing output. + + \annotatedlist printing + + \section1 Paint Devices and Printing + + In Qt, printers are represented by QPrinter, a paint device that provides + functionality specific to printing, such as support for multiple pages and + double-sided output. As a result, printing involves using a QPainter to paint + onto a series of pages in the same way that you would paint onto a custom + widget or image. + + \section2 Creating a QPrinter + + Although QPrinter objects can be constructed and set up without requiring user + input, printing is often performed as a result of a request by the user; + for example, when the user selects the \gui{File|Print...} menu item in a GUI + application. In such cases, a newly-constructed QPrinter object is supplied to + a QPrintDialog, allowing the user to specify the printer to use, paper size, and + other printing properties. + + \snippet examples/richtext/orderform/mainwindow.cpp 18 + + It is also possible to set certain default properties by modifying the QPrinter + before it is supplied to the print dialog. For example, applications that + generate batches of reports for printing may set up the QPrinter to + \l{QPrinter::setOutputFileName()}{write to a local file} by default rather than + to a printer. + + \section2 Painting onto a Page + + Once a QPrinter object has been constructed and set up, a QPainter can be used + to perform painting operations on it. We can construct and set up a painter in + the following way: + + \snippet doc/src/snippets/printing-qprinter/object.cpp 0 + + Since the QPrinter starts with a blank page, we only need to call the + \l{QPrinter::}{newPage()} function after drawing each page, except for the + last page. + + The document is sent to the printer, or written to a local file, when we call + \l{QPainter::}{end()}. + + \section2 Coordinate Systems + + QPrinter provides functions that can be used to obtain information about the + dimensions of the paper (the paper rectangle) and the dimensions of the + printable area (the page rectangle). These are given in logical device + coordinates that may differ from the physical coordinates used by the device + itself, indicating that the printer is able to render text and graphics at a + (typically higher) resolution than the user's display. + + Although we do not need to handle the conversion between logical and physical + coordinates ourselves, we still need to apply transformations to painting + operations because the pixel measurements used to draw on screen are often + too small for the higher resolutions of typical printers. + + \table + \row \o \bold{Printer and Painter Coordinate Systems} + + The \l{QPrinter::}{paperRect()} and \l{QPrinter::}{pageRect()} functions + provide information about the size of the paper used for printing and the + area on it that can be painted on. + + The rectangle returned by \l{QPrinter::}{pageRect()} usually lies inside + the rectangle returned by \l{QPrinter::}{paperRect()}. You do not need to + take the positions and sizes of these area into account when using a QPainter + with a QPrinter as the underlying paint device; the origin of the painter's + coordinate system will coincide with the top-left corner of the page + rectangle, and painting operations will be clipped to the bounds of the + drawable part of the page. + + \o \inlineimage printer-rects.png + \endtable + + The paint system automatically uses the correct device metrics when painting + text but, if you need to position text using information obtained from + font metrics, you need to ensure that the print device is specified when + you construct QFontMetrics and QFontMetricsF objects, or ensure that each QFont + used is constructed using the form of the constructor that accepts a + QPaintDevice argument. + + \section1 Printing from Complex Widgets + + Certain widgets, such as QTextEdit and QGraphicsView, display rich content + that is typically managed by instances of other classes, such as QTextDocument + and QGraphicsScene. As a result, it is these content handling classes that + usually provide printing functionality, either via a function that can be used + to perform the complete task, or via a function that accepts an existing + QPainter object. Some widgets provide convenience functions to expose underlying + printing features, avoiding the need to obtain the content handler just to call + a single function. + + The following table shows which class and function are responsible for + printing from a selection of different widgets. For widgets that do not expose + printing functionality directly, the content handling classes containing this + functionality can be obtained via a function in the corresponding widget's API. + + \table + \header \o Widget \o Printing function \o Accepts + \row \o QGraphicsView \o QGraphicsView::render() \o QPainter + \row \o QSvgWidget \o QSvgRenderer::render() \o QPainter + \row \o QTextEdit \o QTextDocument::print() \o QPrinter + \row \o QTextLayout \o QTextLayout::draw() \o QPainter + \row \o QTextLine \o QTextLine::draw() \o QPainter + \endtable + + QTextEdit requires a QPrinter rather than a QPainter because it uses information + about the configured page dimensions in order to insert page breaks at the most + appropriate places in printed documents. +*/ + +/*! + \page pdf-licensing.html + \title Notes about PDF Licensing + \ingroup licensing + \brief Details of restrictions on the use of PDF-related trademarks. + + Please note that Adobe\reg places restrictions on the use of its trademarks + (including logos) in conjunction with PDF; e.g. "Adobe PDF". Please refer + to \l{http://www.adobe.com}{www.adobe.com} for guidelines. +*/ |