KDEPrint Homepage
Basic Usage
This section describes the basic use of KDEPrint: you just want to print your document without taking care of anything. KDEPrint allows you to do this quite easily, all the printing stuff being handled by KDEPrint. Your application has just to produce the print data.
To do that, you just have to use a KPrinter object as a drawing area. Indeed the class KPrinter inherits from QPaintDevice and as such, you can paint on it as if it was a normal QWidget. The main differences with a normal QWidget are that the painting area size is the page size and that you need to call a specific function (KPrinter::newPage()) when you want to start a new page. The main operations are the following:
- create a KPrinter object
- initialize the KPrinter object, usually by using the print dialog
- paint your document on the KPrinter object using a QPainter
Here is a code example, extracted from the image viewer example. This code will be analyzed and commented in detail in the next subsections.
void ViewerWidget::slotPrint()
{
// create the KPrinter object with default options
KPrinter printer;
// start the print dialog to initialize the KPrinter object
if (printer.setup(this))
{
// do the actual printing job
doPrint(&printer);
}
}
void ViewerWidget::doPrint(KPrinter *printer)
{
// create the painter object
QPainter painter(printer);
// at this moment we print the image using default options,
// later we may want to customize printing.
// do the actual painting job
doPaint(&painter);
}
/*
* This function does the actual painting job. The image is scaled according
* to 'autofit':
* -1 : no scaling
* 0 : fit to page if too larg
* 1 : always fit to page
* 2 : scale to the given width and height
*/
void ViewerWidget::doPaint(QPainter *p, int autofit, int w, int h)
{
QImage img = m_image; // will contain the final image to print
QSize sz = img.size(); // the current image size
QPoint pt(0, 0); // the top-left corner (image will be centered)
// We use a QPaintDeviceMetrics to know the actual page size in pixel,
// this gives the real painting area
QPaintDeviceMetrics metrics(p->device());
// scale the image if needed
switch (autofit)
{
...
case 1:
// always fit to page
img = m_image.smoothScale(metrics.width(), metrics.height(), QImage::ScaleMin);
break;
...
}
sz = img.size();
// center the image on the paint device
pt.setX((metrics.width()-sz.width())/2);
pt.setY((metrics.height()-sz.height())/2);
// draw the image
p->drawImage(pt, img);
}
|
Note that the KPrinter class has been designed to be source compatible with the old QPrinter class, such that porting an application from Qt print system to KDEPrint should be as easy as replacing every occurence of QPrinter by KPrinter.
Creating the KPrinter object
The first thing to do when printing, is to create a KPrinter object. The constructor definition is the following:
KPrinter(bool restore = true, QPrinter::PrinterMode mode = QPrinter::ScreenResolution); |
The restore argument is used to tell to the new KPrinter object to restore its state from the previous KPrinter object that has been created within the same process. This is possible because, when a KPrinter object is destroyed, it stores its current state into a static object, such that this state can be restored later. Setting restore to true, you will use exactly the same print options as in the previous print operation. Note that if restore is false, not only the previous state isn't restored, but the state of the current KPrinter object will not be saved in the static object either.
The mode argument tells to KPrinter which resolution should be used. Note that this resolution is only used when generating the print data, and is mainly about placement accuracy when printing. It is not directly related to the real resolution that your printer will use. The possible values for that argument are:
- PrinterResolution : 75 dpi
- ScreenResolution : resolution of the screen (y-axis)
- HighResolution : 600 dpi
The default is ScreenResolution and corresponds to the Y-resolution of your screen. This mode is handy as the printed result will have approximatively the same size as on your screen.
For both restore and mode arguments, the default values are usually good for many situations.
Initialiazing the KPrinter object
This step is as easy as calling a single member of KPrinter, KPrinter::setup(). This function will bring up the print dialog and configure completely the KPrinter object for you. After this function has been called, you are not supposed to modify the KPrinter object anymore. This means that if you want to change some default values of the KPrinter object, you should do it before calling KPrinter::setup(). This is further needed because the print dialog content may depend on some setting of the KPrinter object. For example, if you do not want to use the built-in margin system of the KPrinter object (you want to print on the whole page, but then you should take care of the print margins yourself), you would do the following:
... // create the KPrinter object KPrinter printer; // set full-page to true: do not use built-in margin system printer.setFullPage(true); // call print dialog if (printer.setup(this)) ... |
Modifying the KPrinter object after KPrinter::setup() would result in undefined (thus unwanted) side-effects.
In the case you do not want to use the print dialog (for whatever reason), you can still create a KPrinter object, then call KPrinter::autoConfigure() to initialize the KPrinter object with the default settings of the printer whose name is given as argument. Once this is done, you can continue as in the normal situation by creating a QPainter and so on.
Painting the document
As explained previously, KPrinter inherits from QPaintDevice, such that you can draw on it as on a normal QWidget. The drawing primitives are then converted to PS code instead of shown on the screen. Consider the KPrinter object to be an usual drawing area.
To access the metric of this drawing area (i.e. the page metric), you can use the class QPaintDeviceMetrics and especially the methods width() and height(), which return the page size in pixels. You don't have to worry about stuff like orientation, page ordering, and so on. All these are handled internally by KDEPrint. For example, the page orientation is already managed by QPaintDeviceMetrics and KPrinter such that width() will return the paper's width in portrait mode, and the paper's height in landscape mode.
If you don't have enough space on the current page, you can start a new page by calling KPrinter::newPage(). After this call, you can start drawing again from the origin (0,0). Don't call this method to end a page but only to start a new one. And don't call it after QPainter::end() either.
By default, the KPrinter object is configured in non full-page mode. This means that KDEPrint will use the Qt's built-in margin system, and your applications don't have to worry about that. In other words, your drawing origin (0,0) does not correspond to the real paper top-left corner, but is shifted a bit to the right and down so that already accounts for some built-in print margins. If you call KPrinter::setFullPage(true) before, then those built-in margins are not used, meaning that your drawing origin really corresponds to the top-left corner of the paper. In this case, do take care of margins yourself.
 |
(Click to enlarge) |
While drawing on the KPrinter object, PostScript data is generated and saved into a temporary file. When QPainter::end() is called (or when the QPainter object is destroyed), this temporary file is effectively sent to the print spooler. Any print command after that point will have no effect and should be avoided.
[ Edit ]
