Difference between revisions of "Development/Tutorials/KDE3/How to write Kontact plugins"

Jump to: navigation, search
m
m (Add deletion proposal.)
 
(27 intermediate revisions by 10 users not shown)
Line 1: Line 1:
<h1>Kontact Plugin Howto</h1>
+
{{Template:Delete|KDE 3 content.}}
<!-- BEGIN CONTENT -->
+
''by Thorsten St&auml;rk''
  
<h2>How to create a Kontact plugin</h2>
 
<i>by Thorsten St&auml;rk</i>
 
<p>
 
 
This documentation is intended for developers programming on - or
 
This documentation is intended for developers programming on - or
 
writing plugins for - Kontact. Kontact is a KDE program uniting several
 
writing plugins for - Kontact. Kontact is a KDE program uniting several
Line 10: Line 7:
 
Personal information management is e.g. writing mails, planning your
 
Personal information management is e.g. writing mails, planning your
 
calendar dates or tracking your time. If you want to learn how to use
 
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">
+
Kontact, visit [http://www.kontact.org The Kontact homepage].
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.</p>
+
  
 +
== Tutorial FactBox ==
  
 +
{| border="1" style="text-align: left; width: 247px; height: 58px;"
 +
|-
 +
|style="vertical-align: top;"|lasts || style="vertical-align: top;"|3 hours
 +
|-
 +
|style="vertical-align: top;"|without this tutorial || style="vertical-align: top;"|3 weekends
 +
|}
  
 +
== How to write a plugin for Kontact ==
  
<h2>Tutorial FactBox</h2>
 
 
<table style="text-align: left; width: 247px; height: 58px;" border="1"
 
cellpadding="2" cellspacing="2">
 
    <tr>
 
      <td style="vertical-align: top;">lasts<br>
 
      </td>
 
    <td style="vertical-align: top;">3 hours<br>
 
    </td>
 
  </tr>
 
  <tr>
 
    <td style="vertical-align: top;">without this tutorial<br>
 
    </td>
 
    <td style="vertical-align: top;">3 weekends<br>
 
    </td>
 
  </tr>
 
</table>
 
 
<h2>How to write a plugin
 
for Kontact</h2>
 
 
<p>
 
 
This chapter demonstrates how to turn an existing KDE program into a
 
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
 
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
+
KDE 3.4.1. First, we will create a [[Development/Architecture/KDE4/KParts|KPart]] out of the program, then, we
 
will use this for a Kontact plugin. Then, we will look at some errors
 
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
 
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,
 
used as a program, with the difference that it cannot run alone,
 
because it needs a program building a "mainwindow" for it.
 
because it needs a program building a "mainwindow" for it.
</p>
 
  
<h2>How to create the KPart</h2>
+
== How to create the KPart ==
<p>To turn our KDE Program into a KPart, we create a verbatim KPart with
+
To turn our KDE Program into a [[Development/Architecture/KDE4/KParts|KPart]], we create a verbatim KPart with
 
KDevelop and copy it over to our program's source directory. For this,
 
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
 
I assume, you want to modify the program karm from KDE 3.4.1 and it can
be found in <tt>/home/user/svn/3.4.1/kdepim/karm</tt>. I assume your home
+
be found in {{path|/home/user/svn/3.4.1/kdepim/karm}}. I assume your home
directory is <tt>/home/user</tt> and you are on KDevelop 3.2.0.</p>
+
directory is {{path|/home/user}} and you are on KDevelop 3.2.0.
  
<p>Start KDevelop, close all open projects (Project | close), then chose
+
Start KDevelop, close all open projects (Project -> close), then chose
 
<tt>Project | New Project -&gt; C++ -&gt; KDE -&gt; Application Framework  
 
<tt>Project | New Project -&gt; C++ -&gt; KDE -&gt; Application Framework  
 
(KParts)</tt>. Set "Application Name" to "karm", continue as instructed.
 
(KParts)</tt>. Set "Application Name" to "karm", continue as instructed.
 
Now test your verbatim KPart by executing it in KDevelop. Expected result
 
Now test your verbatim KPart by executing it in KDevelop. Expected result
is a "Could not find our part".</p>
+
is a "Could not find our part".
  
<p>This is because you do not yet have the KPart installed. KDevelop will
+
This is because you do not yet have the KPart installed. KDevelop will
store your work in <tt>/home/user/karm/</tt>, so test your verbatim KPart  
+
store your work in {{path|/home/user/karm/}}, so test your verbatim KPart  
by doing a make install in <tt>/home/user/karm/</tt> and executing the  
+
by doing a make install in {{path|/home/user/karm/}} and executing the  
KDevelop project. Expected result is a text-editing window, the verbatim KPart.</p>
+
KDevelop project. Expected result is a text-editing window, the verbatim KPart.
  
<p>KDevelop has created karm.h, karm.cpp, karm_part.h,
+
KDevelop has created {{path|karm.h}}, {{path|karm.cpp}}, {{path|karm_part.h}},
<tt>karm_part.cpp</tt>, <tt>karm_part.desktop</tt> and <tt>Makefile.am</tt>
+
{{path|karm_part.cpp}}, {{path|karm_part.desktop}} and {{path|Makefile.am}}
in <tt>/home/user/karm/src/</tt>. <tt>karm.h</tt> and <tt>karm.cpp</tt>
+
in {{path|home/user/karm/src/}}. {{path|karm.h}} and {{path|karm.cpp}}
 
just open a mainwindow and display the karm_part in it. We do not need
 
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
 
them, as we already have a mainwindow for our program. So
copy the files karm_part.* to <tt>/home/user/svn/3.4.1/kdepim/karm</tt>
+
copy the files {{path|karm_part.*}} to {{path|/home/user/svn/3.4.1/kdepim/karm}}
 
and adapt the files to display your main widget instead of a text
 
and adapt the files to display your main widget instead of a text
editor. You may want to replace QMultiLineEdit by your main widget.
+
editor. You may want to replace {{qt3|QMultiLineEdit}} by your main widget.
Finally adapt the Makefile <tt>/home/user/svn/3.4.1/kdepim/karm/Makefile.am</tt>
+
Finally adapt the {{path|Makefile}} {{path|/home/user/svn/3.4.1/kdepim/karm/Makefile.am}}
 
to include the added files. This is hard to generalize, I show it here
 
to include the added files. This is hard to generalize, I show it here
for the KArm program.</tt></p>
+
for the KArm program.
  
<p>You may want to have a look at <a
+
You may want to have a look at [http://websvn.kde.org/trunk/KDE/kdepim/karm/Makefile.am?rev=412382&amp;r1=409203&amp;r2=412382 the diff]
href="http://websvn.kde.org/trunk/KDE/kdepim/karm/Makefile.am?rev=412382&amp;r1=409203&amp;r2=412382">the diff</a>
+
between the old and the new {{path|Makefile.am}}. Now replace <tt>karm_SOURCES</tt> by <tt>libkarm_shared_la_SOURCES</tt> and remove main.cpp from the list. Add a <tt>noinst_LTLIBRARIES = libkarm_shared.la</tt>
between the old and the new Makefile.am. Now replace <tt>karm_SOURCES</tt> by <tt>libkarm_shared_la_SOURCES</tt>. Add a <tt>noinst_LTLIBRARIES = libkarm_shared.la</tt>
+
 
before that line. That causes that all the karm files will not be bound to a binary karm,
 
before that line. That causes that all the karm files will not be bound to a binary karm,
 
but to a library <tt>libkarm_shared.la</tt>. This binary can then be used to
 
but to a library <tt>libkarm_shared.la</tt>. This binary can then be used to
 
link as well karm as our KPart. Add <tt>libkarm_shared.la</tt> to <tt>karm_LDADD</tt>  
 
link as well karm as our KPart. Add <tt>libkarm_shared.la</tt> to <tt>karm_LDADD</tt>  
 
before that line, place a <tt>karm_SOURCES=main.cpp</tt>. These lines now draw the library
 
before that line, place a <tt>karm_SOURCES=main.cpp</tt>. These lines now draw the library
<tt>libkarm_shared.la</tt>. Finally, add a kpart section as from  
+
<tt>libkarm_shared.la</tt>. Finally, add a kpart section as from {{path|/home/user/karm/src/Makefile.am}} to karm's {{path|Makefile.am}}. This should look like this:
<tt>/home/user/karm/src/Makefile.am</tt> to karm's <tt>Makefile.am</tt>. This should look like
+
 
this:
+
</p>
+
 
  ##################
 
  ##################
 
  # KPART SECTION
 
  # KPART SECTION
Line 110: Line 86:
 
       partrc_DATA = karmui.rc
 
       partrc_DATA = karmui.rc
  
<p>After that, test your changes of Makefile.am. You have to do <tt>make -f
+
After that, test your changes of {{path|Makefile.am}}. You have to do <tt>make -f
 
Makefile.cvs &amp;&amp; ./configure &amp;&amp; make</tt> in
 
Makefile.cvs &amp;&amp; ./configure &amp;&amp; make</tt> in
<tt>/home/user/svn/3.4.1/kdepim/</tt>.</p>
+
{{path|/home/user/svn/3.4.1/kdepim/}}.
  
<p><span style="color: #ff0000;">Warning:</span> running <tt>./configure &amp;&amp; make<tt> <b>is not enough</b>. Makefile.am's are processed by <tt>make -f Makefile.cvs.<tt>
+
<p><span style="color: #ff0000;">Warning:</span> running <tt>./configure &amp;&amp; make</tt> <b>is not enough</b>. {{path|Makefile.am}}'s are processed by <tt>make -f Makefile.cvs.</tt>
  
<p>Install your KPart, e.g. with make install. Then test your KPart:</p>
+
Install your KPart, e.g. with make install. Then test your KPart:
  
 
* Start Konqueror, chose <i>Settings | Configure Konqueror -&gt;
 
* Start Konqueror, chose <i>Settings | Configure Konqueror -&gt;
 
File Associations | text -&gt; calendar</i>. File name patterns are
 
File Associations | text -&gt; calendar</i>. File name patterns are
 
"*.ics". Chose <i>Embedding -&gt; Show files in embedded viewer -&gt; Add
 
"*.ics". Chose <i>Embedding -&gt; Show files in embedded viewer -&gt; Add
-&gt; karmPart -&gt; Apply</i>.</li>
+
-&gt; karmPart -&gt; Apply</i>.
 
* right-click onto a .ics-file and chose "preview in embedded
 
* right-click onto a .ics-file and chose "preview in embedded
viewer -&gt; karmPart"</li>
+
viewer -&gt; karmPart"
 
* verify that Konqueror now is the "mainwindow" for your KPart.
 
* verify that Konqueror now is the "mainwindow" for your KPart.
 
Konqueror will show what was shown by your application before.
 
Konqueror will show what was shown by your application before.
  
<h2>How to get the Kontact plugin</h2>
+
== How to get the Kontact plugin ==
  
<p>You best clone a little Kontact plugin and then adapt it to your
+
You best clone a little Kontact plugin and then adapt it to your
program.</p>
+
program.
  
<p><span style="color: rgb(255, 0, 0);">Warning:</span> Do <b>not</b> copy
+
<span style="color: rgb(255, 0, 0);">Warning:</span> Do <b>not</b> copy
 
any directory within your svn working copy, change it and re-commit.
 
any directory within your svn working copy, change it and re-commit.
 
Every folder in the working copy contains a subfolder <tt>.svn/</tt> which
 
Every folder in the working copy contains a subfolder <tt>.svn/</tt> which
will direct your commits to the original folder. Better do it that way:</p>
+
will direct your commits to the original folder. Better do it that way:
  
<span style="text-align:left;">
+
* create a folder {{path|/home/user/svn/3.4.1/kdepim/kontact/plugins/karm}}
<ul>
+
* copy ''only'' {{path|Makefile.am}}, {{path|multisynk_plugin.cpp}}, {{path|multisynk_plugin.h}}, {{path|multisynkplugin.desktop}} from {{path|/home/user/svn/3.4.1/kdepim/kontact/plugins/multisynk/}} to {{path|../karm/}}
  <li>create a folder <tt>/home/user/svn/3.4.1/kdepim/kontact/plugins/karm</tt></li>
+
* rename the four files and adapt them to their new names
  <li>copy <i>only</i> <tt>Makefile.am</tt>, <tt>multisynk_plugin.cpp</tt>,  
+
* adapt the {{path|karmplugin.desktop}} file to point to your KPart's library, in this case <tt>X-KDE-KontactPartLibraryName=libkarmpart</tt>
  <tt>multisynk_plugin.h</tt>, <tt>multisynkplugin.desktop</tt> from
+
 
  <tt>/home/user/svn/3.4.1/kdepim/kontact/plugins/multisynk/</tt> to <tt>../karm/</tt></li>
+
You see, the deciding step is to tell a {{path|.desktop}} file to use the libs of a KPart. The only modification on the plugin's code is related to
  <li>rename the four files and adapt them to their new names</li>
+
renaming the files. That is elegant.
  <li>adapt the karmplugin.desktop-file to point to your KPart's
+
* give your plugin a distinct name
library, in this case <tt>X-KDE-KontactPartLibraryName=libkarmpart</tt></li>
+
* add your plugin folder (karm) to the makefile for kontact plugins (in your kdepim folder under {{path|kontact/plugins/Makefile.am}}):
</ul>
+
<syntaxhighlight lang="bash">
</span>
+
<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 to
+
renaming the files. That is elegant.</p>
+
<ul>
+
  <li>give your plugin a distinct name</li>
+
  <li>add your plugin folder (karm) to the makefile for kontact plugins (in your kdepim folder under kontact/plugins/Makefile.am):
+
  <div class="shellcode">
+
 
   SUBDIRS = $(KPILOT_KONTACTPLUGIN) kaddressbook kmail knotes korganizer \
 
   SUBDIRS = $(KPILOT_KONTACTPLUGIN) kaddressbook kmail knotes korganizer \
 
           summary weather knode newsticker multisynk specialdates akregator karm
 
           summary weather knode newsticker multisynk specialdates akregator karm
  </div>
+
</syntaxhighlight>
  </li>
+
* <tt>make -f Makefile.cvs &amp;&amp; ./configure &amp;&amp; make &amp;&amp; make install</tt> your kdepim
<li><tt>make -f Makefile.cvs &amp;&amp; ./configure &amp;&amp; make
+
* test your plugin
&amp;&amp; make install</tt> your kdepim</li>
+
** start Kontact, chose <i>Settings|Configure Kontact -&gt; Configure</i>
  <li>test your plugin</li>
+
** verify that you find your program's plugin to be chosen there.
  <ul>
+
 
    <li>start Kontact, chose <i>Settings|Configure Kontact -&gt; Configure</i></li>
+
== Pitfalls ==
    <li>verify that you find your program's plugin to be chosen there.</li>
+
* the program no longer sets it icons correctly
  </ul>
+
** this pitfall occurred as well in the plugin as in the KPart due to the fact that my program was using UserIcon to load the Icons instead of the {{class|KIconLoader}}. UserIcon looks for the application name to find out the icons' path. As there was no application (only a KPart), it gave up on searching the icons.
</ul>
+
 
<h2>Pitfalls</h2>
+
== Suggested readings ==
<ul>
+
  <li>the program no longer sets it icons correctly</li>
+
  <ul>
+
    <li>this pitfall occurred as well in the plugin as in the KPart due
+
to the fact that my program was using UserIcon to load the Icons
+
instead of the KIconLoader. UserIcon looks for the application name to
+
find out the icons' path. As there was no application (only a KPart),
+
it gave up on searching the icons.<br>
+
    </li>
+
  </ul>
+
</ul>
+
<h2>Suggested readings</h2>
+
 
* http://www-106.ibm.com/developerworks/linux/edu/l-dw-linuxkp1-i.html : DeveloperWorks article from David Faure on the KPart technology
 
* http://www-106.ibm.com/developerworks/linux/edu/l-dw-linuxkp1-i.html : DeveloperWorks article from David Faure on the KPart technology
 
*  http://websvn.kde.org/trunk/KDE/kdepim/karm/Makefile.am?rev=412382&amp;r1=409203&amp;r2=412382 : Code example showing the integration of the karm part, file Makefile.am
 
*  http://websvn.kde.org/trunk/KDE/kdepim/karm/Makefile.am?rev=412382&amp;r1=409203&amp;r2=412382 : Code example showing the integration of the karm part, file Makefile.am
 +
 +
[[Category:Tutorial]]
 +
[[Category:C++]]
 +
[[Category:PIM]]

Latest revision as of 11:57, 30 June 2011

noframe
 
Warning
This page has been nominated for deletion.

Reason: KDE 3 content.

If you disagree with its deletion, remove the template and discuss it on its talk page.

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, visit The Kontact homepage.

Contents

[edit] Tutorial FactBox

lasts 3 hours
without this tutorial 3 weekends

[edit] How to write a plugin for Kontact

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.

[edit] How to create the KPart

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.

You may want to have a look at the diff between the old and the new Makefile.am. Now replace karm_SOURCES by libkarm_shared_la_SOURCES and remove main.cpp from the list. 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 is not enough. Makefile.am's are processed by make -f Makefile.cvs. Install your KPart, e.g. with make install. Then test your KPart:

  • Start Konqueror, chose Settings | Configure Konqueror ->
File Associations | text -> calendar. File name patterns are "*.ics". Chose Embedding -> Show files in embedded viewer -> Add -> karmPart -> Apply.
  • right-click onto a .ics-file and chose "preview in embedded
viewer -> karmPart"
  • verify that Konqueror now is the "mainwindow" for your KPart.
Konqueror will show what was shown by your application before.

[edit] 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 .svn/ which will direct your commits to the original folder. Better do it that way:

  • create a folder /home/user/svn/3.4.1/kdepim/kontact/plugins/karm
  • copy only Makefile.am, multisynk_plugin.cpp, multisynk_plugin.h, multisynkplugin.desktop from /home/user/svn/3.4.1/kdepim/kontact/plugins/multisynk/ to ../karm/
  • rename the four files and adapt them to their new names
  • adapt the karmplugin.desktop file to point to your KPart's library, in this case X-KDE-KontactPartLibraryName=libkarmpart

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 to renaming the files. That is elegant.

  • give your plugin a distinct name
  • add your plugin folder (karm) to the makefile for kontact plugins (in your kdepim folder under kontact/plugins/Makefile.am):
  SUBDIRS = $(KPILOT_KONTACTPLUGIN) kaddressbook kmail knotes korganizer \
          summary weather knode newsticker multisynk specialdates akregator karm
  • make -f Makefile.cvs && ./configure && make && make install your kdepim
  • test your plugin
    • start Kontact, chose Settings|Configure Kontact -> Configure
    • verify that you find your program's plugin to be chosen there.

[edit] Pitfalls

  • the program no longer sets it icons correctly
    • this pitfall occurred as well in the plugin as in the KPart due to the fact that my program was using UserIcon to load the Icons instead of the KIconLoader. UserIcon looks for the application name to find out the icons' path. As there was no application (only a KPart), it gave up on searching the icons.

[edit] Suggested readings


This page was last modified on 30 June 2011, at 11:57. This page has been accessed 8,415 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal