Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegraphics@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 92 insertions, 0 deletions

diff --git a/kviewshell/Mainpage.dox b/kviewshell/Mainpage.dox
new file mode 100644
index 00000000..160f34e2
--- /dev/null
+++ b/kviewshell/Mainpage.dox
@@ -0,0 +1,92 @@
+/**
+@mainpage 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.
+
+
+@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 kdegraphics source tree under
+<a
+href="http://websvn.kde.org/trunk/KDE/kdegraphics/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/kdegraphics/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 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().
+
+@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.
+
+*/
+