by Thorsten Stärk
This documentation is intended for developers programming on - or writing plugins for - Kontact. Kontact is a KDE program uniting several KDE components for personal information management under one roof. Personal information management is e.g. writing mails, planning your calendar dates or tracking your time. If you want to learn how to use Kontact, you are actually wrong here, visit <a href="http://www.kontact.org"> the Kontact homepage</a> for user documentation then. If you think, a chapter is missing in this documentation, you can offer to write it on the KDE-PIM mailing list.
|without this tutorial
This chapter demonstrates how to turn an existing KDE program into a Kontact plugin. This is done on the example of the program KArm from KDE 3.4.1. First, we will create a KPart out of the program, then, we will use this for a Kontact plugin. Then, we will look at some errors that may occur with that work. A KPart is a KDE component that can be used as a program, with the difference that it cannot run alone, because it needs a program building a "mainwindow" for it.
To turn our KDE Program into a KPart, we create a verbatim KPart with KDevelop and copy it over to our program's source directory. For this, I assume, you want to modify the program karm from KDE 3.4.1 and it can be found in /home/user/svn/3.4.1/kdepim/karm. I assume your home directory is /home/user and you are on KDevelop 3.2.0.
Start KDevelop, close all open projects (Project | close), then chose Project | New Project -> C++ -> KDE -> Application Framework (KParts). Set "Application Name" to "karm", continue as instructed. Now test your verbatim KPart by executing it in KDevelop. Expected result is a "Could not find our part".
This is because you do not yet have the KPart installed. KDevelop will store your work in /home/user/karm/, so test your verbatim KPart by doing a make install in /home/user/karm/ and executing the KDevelop project. Expected result is a text-editing window, the verbatim KPart.
KDevelop has created karm.h, karm.cpp, karm_part.h, karm_part.cpp, karm_part.desktop and Makefile.am in /home/user/karm/src/. karm.h and karm.cpp just open a mainwindow and display the karm_part in it. We do not need them, as we already have a mainwindow for our program. So copy the files karm_part.* to /home/user/svn/3.4.1/kdepim/karm and adapt the files to display your main widget instead of a text editor. You may want to replace QMultiLineEdit by your main widget. Finally adapt the Makefile /home/user/svn/3.4.1/kdepim/karm/Makefile.am to include the added files. This is hard to generalize, I show it here for the KArm program.</tt>
You may want to have a look at <a href="http://websvn.kde.org/trunk/KDE/kdepim/karm/Makefile.am?rev=412382&r1=409203&r2=412382">the diff</a> between the old and the new Makefile.am. Now replace karm_SOURCES by libkarm_shared_la_SOURCES. Add a noinst_LTLIBRARIES = libkarm_shared.la before that line. That causes that all the karm files will not be bound to a binary karm, but to a library libkarm_shared.la. This binary can then be used to link as well karm as our KPart. Add libkarm_shared.la to karm_LDADD before that line, place a karm_SOURCES=main.cpp. These lines now draw the library libkarm_shared.la. Finally, add a kpart section as from /home/user/karm/src/Makefile.am to karm's Makefile.am. This should look like this:
################## # KPART SECTION ################## kde_module_LTLIBRARIES = libkarmpart.la # the Part's source, library search path, and link libraries libkarmpart_la_SOURCES = karm_part.cpp libkarmpart_la_LDFLAGS = -module -avoid-version -no-undefined $(KDE_PLUGIN) $(all_libraries) libkarmpart_la_LIBADD = libkarm_shared.la $(LIB_KPARTS) $(LIB_KFILE) \ -lkdeprint $(top_builddir)/libkcal/libkcal.la \ $(top_builddir)/kresources/remote/libkcal_resourceremote.la \ $(top_builddir)/libkdepim/libkdepim.la $(LIBXSS) # this is where the desktop file will go partdesktopdir = $(kde_servicesdir) partdesktop_DATA = karm_part.desktop # this is where the part's XML-GUI resource file goes partrcdir = $(kde_datadir)/karmpart partrc_DATA = karmui.rc
After that, test your changes of Makefile.am. You have to do make -f Makefile.cvs && ./configure && make in /home/user/svn/3.4.1/kdepim/.
Warning: running ./configure && make<tt> is not enough. Makefile.am's are processed by <tt>make -f Makefile.cvs.<tt>
Install your KPart, e.g. with make install. Then test your KPart:
File Associations | text -> calendar. File name patterns are
"*.ics". Chose Embedding -> Show files in embedded viewer -> Add
-> karmPart -> Apply.
viewer -> karmPart"
Konqueror will show what was shown by your application before.
How to get the Kontact plugin
You best clone a little Kontact plugin and then adapt it to your program.
Warning: Do not copy any directory within your svn working copy, change it and re-commit. Every folder in the working copy contains a subfolder <tt>.svn/ which will direct your commits to the original folder. Better do it that way:
<p>You see, the deciding step is to tell a desktop-file to use the libs of a KPart. The only modification on the plugin's code is related torenaming the files. That is elegant.
SUBDIRS = $(KPILOT_KONTACTPLUGIN) kaddressbook kmail knotes korganizer \ summary weather knode newsticker multisynk specialdates akregator karm