Commit 1565cb63 authored by Thomas Zander's avatar Thomas Zander

Api docs

svn path=/trunk/koffice/; revision=689977
parent 0756ad0c
......@@ -28,29 +28,104 @@ class KoShapeManager;
class KoShape;
/**
* Dialog that will allow you to print any flake-based document, with full interaction and ability to cancel.
* Using this class allows any application to print a set of shapes that are contained in the shapeManager()
* in a thread-safe manner, while ensuring that the full content is present before printing. A requirement
* for any shape that may use the network or simply use a lot of processing power to prepare its content
* before it can be painted.
* This class is of the type of 'create and forget'. Meaning that you create the dialog, initialize it with
* data and then call show() on it. It then continues to print and delete itself when ready.
* @code
QPrinter printer;
KWPrintingDialog *dia = new KWPrintingDialog(myWidget);
dia->printer().setOutputFormat(QPrinter::PdfFormat);
dia->printer().setOutputFileName("output.pdf");
dia->printer().setResolution(600);
dia->printer().setFullPage(true); // ignore printer margins
dia->setShapeManager(m_canvas->shapeManager())
QList<int> pages;
pages.append(1);
dia->setPageRange(pages);
dia->show();
@endcode
* The dialog works by looping over all pages in the page-range and sequentially calling preparePage(int) and
* then using the shapeManager() to actually print the shapes.
* Since preparePage(int) is pure virtual the application wanting to implement printing should inherit from
* this class and make sure that after the preparePage returns a simple paint can be called on the shapeManager
* with the painter().
* This typically means that the preparePage() makes sure the shapeManager is updated and the correct cliprect
* is set on the painter().
*/
class KOGUIUTILS_EXPORT KoPrintingDialog : public QDialog {
Q_OBJECT
public:
/**
* Create a new dialog.
* @param parent the widget this dialog will use as a child.
*/
KoPrintingDialog(QWidget *parent);
virtual ~KoPrintingDialog();
/**
* Set the shape manager that should be used to print.
* @param sm the shapeManager used for the next page(s)
*/
void setShapeManager(KoShapeManager *sm);
/**
* Set a list of all the pages that should be used to loop over and print.
* Note that any calls made to this method after printing started are ignored.
* @param pages a list of page numbers that the preparePage() gets passed.
*/
void setPageRange(const QList<int> &pages);
/**
* Return the printer used to print.
* @return the printer used to print.
*/
QPrinter &printer();
protected:
/**
* Reimplement this method to setup the shapeManager and painter and maybe the shapes for
* printing the passed in page number. The printing itself will not happen in this method.
* This method will be called in a thread that is not the main-thread. So the processing can take
* a reasonably long time withing posing problems for user interaction.
* @param pageNumber the number of the page to prepare.
* @see isCancelled()
*/
virtual void preparePage(int pageNumber) = 0;
/**
* Implement to return the shapes on the requested page.
*/
virtual QList<KoShape*> shapesOnPage(int pageNumber) = 0;
/**
* @returns the shapeManager.
* Retuns the shapeManager as it has been set on the setShapeManager()
* @see setShapeManager
*/
KoShapeManager *shapeManager() const;
/**
* Return the painter that will be used to print the shape data.
*/
QPainter &painter() const;
/**
* Return true if the user pressed cancel.
* It is suggested to query this setting in long loops and abort the process as soon at it retuns yes.
*/
bool isCancelled() const;
/// reimplemented
virtual void showEvent(QShowEvent *event);
/**
* This virtual hook is called at the end of the printing process, either on success of on failure.
* The method is empty by default.
*/
virtual void printingDone() { }
private:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment