Update copyright headers
[qt:qt.git] / doc / src / painting-and-printing / printing.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
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 */