Advanced Page Selection

In the basic usage of KDEPrint, your application is requested to print the whole document everytime you print something. KDEPrint will then take itself care of the page selection, the page ordering, the number of copies, and so on. This is of course very handy on the application side as the code needed is minimal. On the other hand, this can become inefficient on large documents, if for example you only want to print a single page. Moreover if your application is page-based (like KWord), then printing on a page basis should be fairly simple to implement and much more efficient.

KDEPrint provides a framework to handle those situations much more efficiently, by letting the application perform the actual page selection, hence only the requested pages are effectively printed by your application. To do that you must tell KDEPrint that your application is able to perform page selection itself by calling KPrinter::setPageSelection(). This method accepts an argument of type KPrinter::PageSelectionType that can have 2 values:

• ApplicationSide : your application can do page selection
• SystemSide : you let KDEPrint do the page selection (default)

Additionally, you must also tell KDEPrint about the minimum and maximum page numbers, to make KDEPrint able to effectively compute the requested page list. This is done by calling KPrinter::setMinMax().

As an option, you can also make use of KPrinter::setCurrentPage(), to tell KDEPrint that you print the current page shown by your application. By defining the current page, the widget "Current" in the print dialog will be enabled, thus giving proper hint to the user. The user will still be able to select between: all pages, the current page or a specified page range. If the current page is undefined, then the "Current" widget is disabled.

(Click to enlarge)

Finally, after the print dialog has been closed, you can access the pages requested for printing using KPrinter::pageList(). This list contains the set of pages to print (all pages, current page, range, even pages, odd pages, ...) as well as the page ordering. The only thing your application has to do is to walk through the page list starting from the beginning and print the requested pages.

The following code illustrates the advanced page selection mechanism (Note: this feature is not used in the demo application).

void MyDocumentView::slotPrint()
{
	// create the KPrinter object
	KPrinter	printer;

	// tell KDEPrint about page selection
	printer.setPageSelection(KPrinter::ApplicationSide);

	// tell KDEPrint about the current page (imagine there's
	// a method to know the current page)
	printer.setCurrentPage(currentPage());

	// start the print dialog
	if (printer.setup(this))
	{
		// create the painter
		QPainter	painter(&printer);

		// retrieve the page list to print
		QValueList<int>	pages = printer.pageList();

		// print each page
		for (QValueList<int>::ConstIterator it=pages.begin(); it!=pages.end();)
		{
			doPrintPage(&painter, *it);

			// call newPage() if needed
			++it;
			if (it != pages.end())
				printer.newPage();
		}
	}
}