|
|
|
/**
|
|
|
|
@mainpage The KDE Graphics API Reference
|
|
|
|
|
|
|
|
The kviewshell is a document viewing application contained in the
|
|
|
|
tdegraphics 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.
|
|
|
|
|
|
|
|
|
|
|
|
@section refimpl 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 tdegraphics source tree under
|
|
|
|
<a
|
|
|
|
href="http://websvn.kde.org/trunk/KDE/tdegraphics/kfaxview">kfaxview</a>. If
|
|
|
|
you are looking for a plugin with more functionality, you might
|
|
|
|
consider the DJVU plugin, contained in <a
|
|
|
|
href="http://websvn.kde.org/trunk/KDE/tdegraphics/kviewshell/plugins/djvu">kviewshell/plugins/kdjview</a>.
|
|
|
|
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 <a
|
|
|
|
href="http://developer.kde.org">KDE Developer's corner</a>.
|
|
|
|
|
|
|
|
|
|
|
|
@section req 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 tdelibs 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().
|
|
|
|
|
|
|
|
@section help Further information
|
|
|
|
|
|
|
|
This document describes only the most basic methods of the most
|
|
|
|
important classes used in kviewshell, which we expect to be of
|
|
|
|
interest for authors of kviewshell plugins. If you need more advanced
|
|
|
|
classes or functionalities, there is some chance that they are already
|
|
|
|
implemented or can easily be provided. Thus, please do not hesitate to
|
|
|
|
contact Stefan Kebekus <kebekus@kde.org> or Wilfried Huss
|
|
|
|
<wilfried.huss@gmx.at>. No-one profits if you spend hours duplicating
|
|
|
|
existing code.
|
|
|
|
|
|
|
|
*/
|
|
|
|
|