1 /* This file is part of the KDE project 2 * Copyright (C) 2007, 2009 Thomas Zander <zander@kde.org> 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Library General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Library General Public License for more details. 13 * 14 * You should have received a copy of the GNU Library General Public License 15 * along with this library; see the file COPYING.LIB. If not, write to 16 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 17 * Boston, MA 02110-1301, USA. 18 */ 19 #ifndef KOPRINTINGDIALOG_H 20 #define KOPRINTINGDIALOG_H 21 22 #include <KoPrintJob.h> 23 #include <QList> 24 #include "komain_export.h" 25 26 class KoShapeManager; 27 class KoShape; 28 class KoPrintingDialogPrivate; 29 30 /** 31 * Dialog that will allow you to print any flake-based document, with full interaction and ability to stop. 32 * Using this class allows any application to print a set of shapes that are contained in the shapeManager() 33 * in a thread-safe manner, while ensuring that the full content is present before printing. A requirement 34 * for any shape that may use the network or simply use a lot of processing power to prepare its content 35 * before it can be painted. 36 * This class is of the type of 'create and forget'. Meaning that you create the dialog, initialize it with 37 * data and then call show() on it. It then continues to print and delete itself when ready. 38 * @code 39 KoPrintingDialog *dia = new KoPrintingDialog(myWidget); 40 dia->printer().setOutputFormat(QPrinter::PdfFormat); 41 dia->printer().setOutputFileName("output.pdf"); 42 dia->printer().setResolution(600); 43 dia->printer().setFullPage(true); // ignore printer margins 44 dia->setShapeManager(m_canvas->shapeManager()) 45 QList<int> pages; 46 pages.append(1); 47 dia->setPageRange(pages); 48 dia->startPrinting(); 49 @endcode 50 * The dialog works by looping over all pages in the page-range and sequentially calling preparePage(int) and 51 * then using the shapeManager() to actually print the shapes. 52 * 53 * Since preparePage(int) is pure virtual the application wanting to implement printing should inherit from 54 * this class and make sure that after the preparePage returns a simple paint can be called on the shapeManager 55 * with the painter(). 56 * 57 * XXX: preparePage(int) is no longer pure virtual! Only Calligra Sheets reimplements it -- what should be changed 58 * to the docs? (BSAR) 59 * 60 * This typically means that the preparePage() makes sure the shapeManager is updated and the correct cliprect 61 * is set on the painter(). 62 */ 63 class KOMAIN_EXPORT KoPrintingDialog : public KoPrintJob { 64 Q_OBJECT 65 public: 66 /** 67 * Create a new dialog. 68 * @param parent the widget this dialog will use as a child. 69 */ 70 explicit KoPrintingDialog(QWidget *parent); 71 ~KoPrintingDialog() override; 72 73 /** 74 * Set the shape manager that should be used to print. 75 * @param sm the shapeManager used for the next page(s) 76 */ 77 void setShapeManager(KoShapeManager *sm); 78 /** 79 * Set a list of all the pages that should be used to loop over and print. 80 * Note that any calls made to this method after printing started are ignored. 81 * @param pages a list of page numbers that the preparePage() gets passed. 82 */ 83 void setPageRange(const QList<int> &pages); 84 85 /** 86 * Return the printer used to print. 87 * @return the printer used to print. 88 */ 89 QPrinter &printer() override; 90 91 public Q_SLOTS: 92 93 /** 94 * @see KoPrintJob::startPrinting 95 */ 96 void startPrinting(RemovePolicy removePolicy = DoNotDelete) override; 97 98 protected: 99 /** 100 * Reimplement this method to setup the shapeManager and painter and maybe the shapes for 101 * printing the passed in page number. The printing itself will not happen in this method. 102 * This method will be called in a thread that is not the main-thread. So the processing can take 103 * a reasonably long time within posing problems for user interaction. 104 * @param pageNumber the number of the page to prepare. 105 * @see isStopped() printPage() 106 * @returns a cliprect. If the rect is valid then it will be set on the painter right after 107 * newPage is called. 108 */ 109 virtual QRectF preparePage(int pageNumber); 110 111 /** 112 * This is a similar method to preparePage(), but is guaranteed to be called in the Ui thread. 113 * @param pageNumber the number of the page to prepare. 114 * @param painter the painter. 115 * @see isStopped() 116 */ 117 virtual void printPage(int pageNumber, QPainter &painter); 118 119 /** 120 * Implement to return the shapes on the requested page. 121 */ 122 virtual QList<KoShape*> shapesOnPage(int pageNumber) = 0; 123 124 /** 125 * @returns the shapeManager. 126 * Returns the shapeManager as it has been set on the setShapeManager() 127 * @see setShapeManager 128 */ 129 KoShapeManager *shapeManager() const; 130 131 /** 132 * Return the painter that will be used to print the shape data. 133 */ 134 QPainter &painter() const; 135 136 /** 137 * Return true if the user pressed stop. 138 * It is suggested to query this setting in long loops and abort the process as soon at it returns yes. 139 */ 140 bool isStopped() const; 141 142 /** 143 * This virtual hook is called at the end of the printing process, either on success of on failure. 144 * The method is empty by default. 145 */ printingDone()146 virtual void printingDone() { } 147 148 private: 149 KoPrintingDialogPrivate * const d; 150 friend class KoPrintingDialogPrivate; 151 Q_PRIVATE_SLOT(d, void preparePage(const QVariant &page)) 152 Q_PRIVATE_SLOT(d, void printPage(const QVariant &page)) 153 Q_PRIVATE_SLOT(d, void stopPressed()) 154 }; 155 156 157 158 159 160 #endif 161 162