From 1794c3b7a1f2b27aaadfc20cea587284e336080e Mon Sep 17 00:00:00 2001 From: Casper van Donderen Date: Tue, 8 May 2012 11:13:18 +0200 Subject: Doc: Modularize QtPrintSupport documentation. This change moves the snippets and images to the modularized directories. Change-Id: Ib8f8556bcef13593ee40ac1122d765ed307ecb93 Reviewed-by: Marius Storm-Olsen --- doc/src/printsupport/printing.qdoc | 189 --------------------- doc/src/printsupport/qtprintsupport.qdoc | 46 ----- .../code/src_gui_dialogs_qabstractprintdialog.cpp | 46 ----- doc/src/snippets/printing-qprinter/errors.cpp | 65 ------- doc/src/snippets/printing-qprinter/object.cpp | 71 -------- doc/src/snippets/widgetprinting.cpp | 93 ---------- 6 files changed, 510 deletions(-) delete mode 100644 doc/src/printsupport/printing.qdoc delete mode 100644 doc/src/printsupport/qtprintsupport.qdoc delete mode 100644 doc/src/snippets/code/src_gui_dialogs_qabstractprintdialog.cpp delete mode 100644 doc/src/snippets/printing-qprinter/errors.cpp delete mode 100644 doc/src/snippets/printing-qprinter/object.cpp delete mode 100644 doc/src/snippets/widgetprinting.cpp (limited to 'doc') diff --git a/doc/src/printsupport/printing.qdoc b/doc/src/printsupport/printing.qdoc deleted file mode 100644 index 5447032a2b..0000000000 --- a/doc/src/printsupport/printing.qdoc +++ /dev/null @@ -1,189 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \ingroup qt-graphics - - \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 \li \b{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. - - \li \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 Widgets - - To print a widget, you can use the QWidget::render() function. As mentioned, - the printer's resolution is usually higher than the screen resolution, so you - will have to scale the painter. You may also want to position the widget on the - page. The following code sample shows how this may look. - - \snippet doc/src/snippets/widgetprinting.cpp 0 - - This will center the widget on the page and scale it so that it fits the page. - - \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 \li Widget \li Printing function \li Accepts - \row \li QGraphicsView \li QGraphicsView::render() \li QPainter - \row \li QSvgWidget \li QSvgRenderer::render() \li QPainter - \row \li QTextEdit \li QTextDocument::print() \li QPrinter - \row \li QTextLayout \li QTextLayout::draw() \li QPainter - \row \li QTextLine \li QTextLine::draw() \li 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. -*/ diff --git a/doc/src/printsupport/qtprintsupport.qdoc b/doc/src/printsupport/qtprintsupport.qdoc deleted file mode 100644 index 7eea8203aa..0000000000 --- a/doc/src/printsupport/qtprintsupport.qdoc +++ /dev/null @@ -1,46 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtPrintSupport - \title QtPrintSupport Module - \ingroup modules - - \brief The QtPrintSupport module provides classes to make printing - easier and portable. - - To include the definitions of the module's classes, use the - following directive: - - \snippet doc/src/snippets/code/doc_src_qtprintsupport.cpp 1 - - To link against the module, add this line to your \l qmake \c - .pro file: - - \snippet doc/src/snippets/code/doc_src_qtprintsupport.pro 0 -*/ - diff --git a/doc/src/snippets/code/src_gui_dialogs_qabstractprintdialog.cpp b/doc/src/snippets/code/src_gui_dialogs_qabstractprintdialog.cpp deleted file mode 100644 index 41a6e1e622..0000000000 --- a/doc/src/snippets/code/src_gui_dialogs_qabstractprintdialog.cpp +++ /dev/null @@ -1,46 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [0] -QPrintDialog printDialog(printer, parent); -if (printDialog.exec() == QDialog::Accepted) { - // print ... -} -//! [0] diff --git a/doc/src/snippets/printing-qprinter/errors.cpp b/doc/src/snippets/printing-qprinter/errors.cpp deleted file mode 100644 index f202d4f6a1..0000000000 --- a/doc/src/snippets/printing-qprinter/errors.cpp +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include - -int main(int argc, char **argv) -{ - QApplication app(argc, argv); - -//! [0] - QPrinter printer; - printer.setOutputFormat(QPrinter::PdfFormat); - printer.setOutputFileName("/foobar/nonwritable.pdf"); - QPainter painter; - if (! painter.begin(&printer)) { // failed to open file - qWarning("failed to open file, is it writable?"); - return 1; - } - painter.drawText(10, 10, "Test"); - if (! printer.newPage()) { - qWarning("failed in flushing page to disk, disk full?"); - return 1; - } - painter.drawText(10, 10, "Test 2"); - painter.end(); -//! [0] - return 0; -} diff --git a/doc/src/snippets/printing-qprinter/object.cpp b/doc/src/snippets/printing-qprinter/object.cpp deleted file mode 100644 index 4125c9757c..0000000000 --- a/doc/src/snippets/printing-qprinter/object.cpp +++ /dev/null @@ -1,71 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include -#include "object.h" - -Object::Object(QObject *parent) - : QObject(parent) -{ -} - -void Object::print() -{ - int numberOfPages = 10; - int lastPage = numberOfPages - 1; - -//! [0] - QPrinter printer(QPrinter::HighResolution); - printer.setOutputFileName("print.ps"); - QPainter painter; - painter.begin(&printer); - - for (int page = 0; page < numberOfPages; ++page) { - - // Use the painter to draw on the page. - - if (page != lastPage) - printer.newPage(); - } - - painter.end(); -//! [0] - qApp->quit(); -} diff --git a/doc/src/snippets/widgetprinting.cpp b/doc/src/snippets/widgetprinting.cpp deleted file mode 100644 index bf0f005ba2..0000000000 --- a/doc/src/snippets/widgetprinting.cpp +++ /dev/null @@ -1,93 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include - -class Window : public QWidget -{ - Q_OBJECT - -public: - Window() { - myWidget = new QPushButton("Print Me"); - connect(myWidget, SIGNAL(clicked()), this, SLOT(print())); - - QVBoxLayout *layout = new QVBoxLayout; - layout->addWidget(myWidget); - setLayout(layout); - } - -private slots: - void print() { - QPrinter printer(QPrinter::HighResolution); - - printer.setOutputFileName("test.pdf"); - -//! [0] - QPainter painter; - painter.begin(&printer); - double xscale = printer.pageRect().width()/double(myWidget->width()); - double yscale = printer.pageRect().height()/double(myWidget->height()); - double scale = qMin(xscale, yscale); - painter.translate(printer.paperRect().x() + printer.pageRect().width()/2, - printer.paperRect().y() + printer.pageRect().height()/2); - painter.scale(scale, scale); - painter.translate(-width()/2, -height()/2); - - myWidget->render(&painter); -//! [0] - } - -private: - QPushButton *myWidget; -}; - -int main(int argv, char **args) -{ - QApplication app(argv, args); - - Window window; - window.show(); - - return app.exec(); -} - -#include "main.moc" - -- cgit v1.2.3