doc/src/printsupport/printing.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29   \group printing
  30   \title Printer and Printing APIs
  31   \brief Classes for producing printed output
  32   \ingroup groups
  33 */
  34
  35 /*!
  36   \page printing.html
  37   \title Printing with Qt
  38   \ingroup qt-graphics
  39
  40   \previouspage Styling
  41   \contentspage The Paint System
  42
  43   \brief A guide to producing printed output with Qt's paint system and widgets.
  44
  45   Qt provides extensive cross-platform support for printing. Using the printing
  46   systems on each platform, Qt applications can print to attached printers and
  47   across networks to remote printers. Qt's printing system also enables PostScript
  48   and PDF files to be generated, providing the foundation for basic report
  49   generation facilities.
  50
  51   \tableofcontents
  52
  53   \section1 Classes Supporting Printing
  54
  55   The following classes support the selecting and setting up of printers and
  56   printing output.
  57
  58   \annotatedlist printing
  59
  60   \section1 Paint Devices and Printing
  61
  62   In Qt, printers are represented by QPrinter, a paint device that provides
  63   functionality specific to printing, such as support for multiple pages and
  64   double-sided output. As a result, printing involves using a QPainter to paint
  65   onto a series of pages in the same way that you would paint onto a custom
  66   widget or image.
  67
  68   \section2 Creating a QPrinter
  69
  70   Although QPrinter objects can be constructed and set up without requiring user
  71   input, printing is often performed as a result of a request by the user;
  72   for example, when the user selects the \gui{File|Print...} menu item in a GUI
  73   application. In such cases, a newly-constructed QPrinter object is supplied to
  74   a QPrintDialog, allowing the user to specify the printer to use, paper size, and
  75   other printing properties.
  76
  77   \snippet examples/richtext/orderform/mainwindow.cpp 18
  78
  79   It is also possible to set certain default properties by modifying the QPrinter
  80   before it is supplied to the print dialog. For example, applications that
  81   generate batches of reports for printing may set up the QPrinter to
  82   \l{QPrinter::setOutputFileName()}{write to a local file} by default rather than
  83   to a printer.
  84
  85   \section2 Painting onto a Page
  86
  87   Once a QPrinter object has been constructed and set up, a QPainter can be used
  88   to perform painting operations on it. We can construct and set up a painter in
  89   the following way:
  90
  91   \snippet doc/src/snippets/printing-qprinter/object.cpp 0
  92
  93   Since the QPrinter starts with a blank page, we only need to call the
  94   \l{QPrinter::}{newPage()} function after drawing each page, except for the
  95   last page.
  96
  97   The document is sent to the printer, or written to a local file, when we call
  98   \l{QPainter::}{end()}.
  99
 100   \section2 Coordinate Systems
 101
 102   QPrinter provides functions that can be used to obtain information about the
 103   dimensions of the paper (the paper rectangle) and the dimensions of the
 104   printable area (the page rectangle). These are given in logical device
 105   coordinates that may differ from the physical coordinates used by the device
 106   itself, indicating that the printer is able to render text and graphics at a
 107   (typically higher) resolution than the user's display.
 108
 109   Although we do not need to handle the conversion between logical and physical
 110   coordinates ourselves, we still need to apply transformations to painting
 111   operations because the pixel measurements used to draw on screen are often
 112   too small for the higher resolutions of typical printers.
 113
 114   \table
 115   \row \o \bold{Printer and Painter Coordinate Systems}
 116
 117   The \l{QPrinter::}{paperRect()} and \l{QPrinter::}{pageRect()} functions
 118   provide information about the size of the paper used for printing and the
 119   area on it that can be painted on.
 120
 121   The rectangle returned by \l{QPrinter::}{pageRect()} usually lies inside
 122   the rectangle returned by \l{QPrinter::}{paperRect()}. You do not need to
 123   take the positions and sizes of these area into account when using a QPainter
 124   with a QPrinter as the underlying paint device; the origin of the painter's
 125   coordinate system will coincide with the top-left corner of the page
 126   rectangle, and painting operations will be clipped to the bounds of the
 127   drawable part of the page.
 128
 129   \o \inlineimage printer-rects.png
 130   \endtable
 131
 132   The paint system automatically uses the correct device metrics when painting
 133   text but, if you need to position text using information obtained from
 134   font metrics, you need to ensure that the print device is specified when
 135   you construct QFontMetrics and QFontMetricsF objects, or ensure that each QFont
 136   used is constructed using the form of the constructor that accepts a
 137   QPaintDevice argument.
 138
 139   \section1 Printing Widgets
 140
 141   To print a widget, you can use the QWidget::render() function. As mentioned,
 142   the printer's resolution is usually higher than the screen resolution, so you
 143   will have to scale the painter. You may also want to position the widget on the
 144   page. The following code sample shows how this may look.
 145
 146   \snippet doc/src/snippets/widgetprinting.cpp 0
 147
 148   This will center the widget on the page and scale it so that it fits the page.
 149
 150   \section1 Printing from Complex Widgets
 151
 152   Certain widgets, such as QTextEdit and QGraphicsView, display rich content
 153   that is typically managed by instances of other classes, such as QTextDocument
 154   and QGraphicsScene. As a result, it is these content handling classes that
 155   usually provide printing functionality, either via a function that can be used
 156   to perform the complete task, or via a function that accepts an existing
 157   QPainter object. Some widgets provide convenience functions to expose underlying
 158   printing features, avoiding the need to obtain the content handler just to call
 159   a single function.
 160
 161   The following table shows which class and function are responsible for
 162   printing from a selection of different widgets. For widgets that do not expose
 163   printing functionality directly, the content handling classes containing this
 164   functionality can be obtained via a function in the corresponding widget's API.
 165
 166   \table
 167   \header \o Widget         \o Printing function        \o Accepts
 168   \row    \o QGraphicsView  \o QGraphicsView::render()  \o QPainter
 169   \row    \o QSvgWidget     \o QSvgRenderer::render()   \o QPainter
 170   \row    \o QTextEdit      \o QTextDocument::print()   \o QPrinter
 171   \row    \o QTextLayout    \o QTextLayout::draw()      \o QPainter
 172   \row    \o QTextLine      \o QTextLine::draw()        \o QPainter
 173   \endtable
 174
 175   QTextEdit requires a QPrinter rather than a QPainter because it uses information
 176   about the configured page dimensions in order to insert page breaks at the most
 177   appropriate places in printed documents.
 178 */
 179
 180 /*!
 181   \page pdf-licensing.html
 182   \title Notes about PDF Licensing
 183   \ingroup licensing
 184   \brief Details of restrictions on the use of PDF-related trademarks.
 185
 186   Please note that Adobe\reg places restrictions on the use of its trademarks
 187   (including logos) in conjunction with PDF; e.g. "Adobe PDF". Please refer
 188   to \l{http://www.adobe.com}{www.adobe.com} for guidelines.
 189 */