Automatic Preview

An advanced feature available to applications in the KDEPrint framework is the possibility to add application specific print options and thus to customize the print dialog. Indeed, it may be useful for an application to have its own print options, for example whether or not to print images for an HTML page, or adding configurable page header/footer to the printout of a text file. These are application specific options which of course couldn't (and shouldn't) be provided by KDEPrint. What KDEPrint provides is a generic mechanism for plugging additional tabs in the main print dialog. These tabs are the full responsability of the application, thus containing whatever the application's developer finds useful.

(Click to enlarge)

To use this feature of KDEPrint, you need to subclass KPrintDialogPage, and reimplement the methods getOptions(), setOptions() and isValid() (optional). The definitions of these methods are:

void getOptions(QMap<QString,QString>& opts, bool include_def = false);
void setOptions(const QMap<QString,QString>& opts);
bool isValid(QString& msg);

As you can notice, the options values are set and retrieved using a map. KDEPrint uses a map internally to keep all print options. This means that your application specific print options must have the form <key>=<value>. For internal reasons, the options' key must have the form app-<appname>-<keyname> (for example app-khtml-printimages). The method setOptions() is called by KDEPrint when your page must update its content according to the option map given as argument. The counterpart getOptions() is called to request your page to fill the map with the option values. The additional argument include_def is specified when default values should also be inserted in the map. If false, then just don't insert those options that have the default value. Finally the method isValid() is called before closing the print dialog to check if the current settings are valid. If they aren't, then a message box is shown and the print dialog is not closed.

The class KPrintDialogPage also contains two utility functions: setTitle() and setOnlyRealPrinters(). The first one defines the page title that will appear in the tabbed widget, and the second one tells KDEPrint that your page contains options that are only compatible with real printers, hence meaningless for special printers. In that case, KDEPrint will automatically disable your page when the user selects a special printer in the combo box of the print dialog.

Once the print dialog has been closed, you can access your application specific options in your code by using the method KPrinter::option(), giving the option key as argument. A code example is given below.

class ImageSettings : public KPrintDialogPage
{
public:
	...
	void setOptions(const QMap<QString,QString>& opts);
	void getOptions(QMap<QString,QString>& opts, bool include_def = false);
	bool isValid(QString& msg);
	...
private:
	QCheckBox	*m_autofit;
}

void ImageSettings::setOptions(const QMap<QString,QString>& opts)
{
	m_autofit->setChecked(opts["app-img-autofit"] == "1");
}

void ImageSettings::getOptions(QMap<QString,QString>& opts, bool include_def)
{
	// let's imagine that autofit == false is the default
	if (m_autofit->isChecked() || include_def)
		opts["app-img-autofit"] = (m_autofit->isChecked() ? "1" : "-1");
}

bool ImageSettings::isValid(QString& msg)
{
	// let's imagine that autofit is not allowed for whatever reason
	if (m_autofit->isChecked())
	{
		msg = i18n("You cannot print with AutoFit mode on.");
		return false;
	}
	return true;
}

...

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

	// plug the additional page
	printer.addDialogPage(new ImageSettings);

	// start the print dialog
	if (printer.setup(this))
	{
		// do the actual printing job
		doPrint(&printer);
	}
}

void ViewerWidget::doPrint(KPrinter *printer)
{
	// create the painter object
	QPainter	painter(printer);

	// retrieve the autofit setting from KPrinter object
	int	autofit = printer->option("app-img-autofit").toInt();

	// do the actual painting
	doPaint(&painter, autofit, -1, -1);
}