KDE 3.5 API Reference kviewshell
The KDE Graphics API Reference
The kviewshell is a document viewing application contained in the kdegraphics package. It cannot load documents itself, but relies on plugins that support various document formats. Currently, there are plugins for TeX DVI, for FAX, and for AT&T's DJVU format. Some of the plugins come with clones of the kviewshell programm (kdvi, kfaxview) to maintain compatibility with older shell scripts.
This document contains the kviewshell library API documentation. It is primarily aimed at programmers who wish to write plugins to the kviewshell application. It documents the few classes that the programmer will have to deal with.
kviewshell Example Plugins and Reference Implementation
Writing KDE libraries and the associated makefiles can be rather complicated. We have therefore provided a well-documented reference implementation, the FAX plugin. This is a fine example for a simple kviewshell plugin, and a very good starting point for your own implementation. It can be found in the kdegraphics source tree under kfaxview. If you are looking for a plugin with more functionality, you might consider the DJVU plugin, contained in kviewshell/plugins/kdjview. The DVI plugin is, for historical reasons, rather involved and cannot be recommended as an example.More information about the KDE architecture in form of tutorials, HOWTOs, and FAQs can be found at the KDE Developer's corner.
Plugin Author's TODO List
For a basic kviewshell plugin, you must as a minimum do the following:
- Produce a KDE library that contains as a minimum implementations of two core classes, the KMultiPage and the DocumentRenderer classes. The DocumentRenderer class loads and renderes files, while the KMultiPage class provides plugin-specific GUI elements. The reference implementation contains a good example for a library that you can tailor to suit your needs.
- If your file type is not known to KDE, then you need to provide a .desktop file for the mime type you wish to support. Search the KDE control center for "mime type" to get a list of known types. Since the list of mime types that are contained in the kdelibs package is quite long, it is quite likely that your file type is already known.
- Provide one or more .desktop files that relate mime-types with your library. After the file is installed, the file dialog of the kviewshell application will show files that match the mime-types. The kviewshell will then use your library to load and display these files. Again, the reference implementation contains examples.
With these data provided, you can produce a perfectly working plugin. To support more advanced features of your document format, you can optionally also do the following:
- You can add GUI elements. This is most often done by providing an .rc-file file, and by calling setXMLFile() in the constructor. Re-implement KMultiPage::setFile() in order to update the GUI after a file was loaded or closed.
- You can add pages to the preferences dialog by re-implementing KMultiPage::addConfigDialogs()
- If your plugin offers functionality to modify the document (e.g. remove or add pages), you should re-implement KMultiPage::isModified() and KMultiPage::isModified().
- If you have good code to convert your document to PostScript, you can improve printing performance tremendously if you re-implement KMultiPage::print().
