Development/Tutorials/Writing kontact plugins

    From KDE TechBase

    Introduction

    Kontact is a KDE PIM (personal information management) framework that allows embedding several pim applications like kmail and korganizer as plugins into one window. Kontact plugins are KParts that get loaded at runtime. So, this is a good time to learn how to write a kPart... Read on.

    Writing a KPart

    We will write a "hello world"-KPart here. And we will write a MainWindow to hold this KPart. A KPart also gives you the flexibility to be integrated into kontact or konqueror, but we will do this later. So, the "hello world"-KPart only consists of a label "hello world". We chose a pushbutton because it is the easiest viewable thing to create. It does not trigger an action on your click. The following is what you do

    • write a subclass mypart of KParts::Part
      • because setWidget is protected
      • use a Widget in it and use setWidget to get your widget into the KPart
    • write a subclass mypartmainwindow of KParts::MainWindow
      • because createGUI is protected (and you may want createGUI later)
    • write main.cpp
      • use new mypart(mw) to get your part into your main window

    We will use 4 files to do this:

    • CMakeLists.txt to ease building work
    • mypart.h to declare our classes
    • mypart.cpp to implement our classes

    Create a directory hello in a fresh checkout of kdepim. In it, add the following files:

    CMakeLists.txt

    project(hello)
    find_package (KDE4 REQUIRED)
    INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )
    
    include_directories( ${KDE4_INCLUDE_DIR}/kcal ${CMAKE_SOURCE_DIR}/kresources/remote  )
    
    set(hello_shared_SRCS 
    	hello_part.cpp
     )
    
    
    set(hellopart_PART_SRCS hello_part.cpp)
    
    kde4_add_plugin(hellopart ${hellopart_PART_SRCS})
    
    target_link_libraries(hellopart ${KDE4_KPARTS_LIBS} ${KDE4_KCAL_LIBS}  ${KDE4_KIO_LIBS} kdepim kcal_resourceremote)
    if(X11_Xscreensaver_LIB)
    	target_link_libraries(hellopart  ${X11_Xscreensaver_LIB} )
    endif(X11_Xscreensaver_LIB)
    
    install(TARGETS hellopart  DESTINATION ${PLUGIN_INSTALL_DIR})
    
    install( FILES hello_part.desktop  DESTINATION ${SERVICES_INSTALL_DIR})
    

    hello_part.h

    1. ifndef _HELLOPART_H_
    2. define _HELLOPART_H_
    1. include <kparts/part.h>
    2. include <kparts/factory.h>
    3. include <QLabel>

    /**

    * This is a "Part".  It that does all the real work in a KPart
    * application.
    */
    

    class helloPart : public KParts::ReadWritePart {

     Q_OBJECT
    
     private:
       QLabel *mMainWidget;
    

    public:

       helloPart(QWidget *parentWidget, QObject *parent, const QVariantList&);
    
       QLabel* MainWidget() { return mMainWidget; };
    
       virtual ~helloPart();
       bool openFile(){};
       bool saveFile(){};
    

    };

    1. endif // _HELLOPART_H_

    hello_part.cpp

    1. include "hello_part.h"
    1. include <kdemacros.h>
    2. include <kparts/genericfactory.h>

    K_PLUGIN_FACTORY(helloPartFactory, registerPlugin<helloPart>();) // produce a factory K_EXPORT_PLUGIN(helloPartFactory("hello","hello") )

    helloPart::helloPart( QWidget *parentWidget, QObject *parent, const QVariantList& )

       : KParts::ReadWritePart(parent)
    

    {

     KGlobal::locale()->insertCatalog("hello");
     // we need an instance
     setComponentData( helloPartFactory::componentData() );
    
     mMainWidget = new QLabel();
     mMainWidget->setText("hello");
     setWidget( mMainWidget );
    

    }

    helloPart::~helloPart() { }

    1. include "hello_part.moc"

    hello_part.desktop

    [Desktop Entry]
    Name=Friendly Component
    MimeType=text/calendar;
    X-KDE-ServiceTypes=KParts/ReadOnlyPart,KParts/ReadWritePart
    X-KDE-Library=hellopart
    Type=Service
    

    Compiling your KPart

    To compile, link and install the code above, use

    cmake . && make && make install
    

    Now you can find your kpart in the local lib folder:

    tweedleburg:~/svn/kdepim/hello # ll lib
    total 468
    -rwxr-xr-x 1 root root 471554 May 28 22:42 hellopart.so
    

    And after compilation e.g. in /usr/local/lib/kde4/hellopart.so

    And you can find your kpart in the services folder (${SERVICES_INSTALL_DIR} from CMakeLists.txt):

    $ ll $(kde4-config --install services)hello*
    -rw-r--r-- 1 root root 161 May 28 23:33 /usr/local/share/kde4/services/hello_part.desktop
    

    Kontact integration

    To integrate your KPart into kontact, you will need to create a subclass of Kontact::Plugin

    So, go to your checkout of kdepim, create a folder kdepim/kontact/plugins/hello. Continue there.

    CMakeLists.txt

    include_directories(${CMAKE_SOURCE_DIR}/hello)
    
    set(kontact_hello_PART_SRCS hello_plugin.cpp)
    
    kde4_add_plugin(kontact_helloplugin ${kontact_hello_PART_SRCS})
    
    kdepim4_link_unique_libraries(kontact_helloplugin ${KDE4_KDECORE_LIBS} kontactinterfaces)
    
    install(TARGETS kontact_helloplugin  DESTINATION ${PLUGIN_INSTALL_DIR})
    
    install(FILES helloplugin.desktop  DESTINATION ${SERVICES_INSTALL_DIR}/kontact)
    

    hello_plugin.desktop

    [Desktop Entry]
    Type=Service
    Icon=whatever
    X-KDE-ServiceTypes=Kontact/Plugin,KPluginInfo
    
    X-KDE-Library=kontact_helloplugin
    X-KDE-KontactPluginVersion=7
    X-KDE-KontactPartLibraryName=hellopart
    X-KDE-KontactPluginHasSummary=false
    
    X-KDE-PluginInfo-Name=kontact_helloplugin
    X-KDE-PluginInfo-Version=0.1
    X-KDE-PluginInfo-License=GPL
    X-KDE-PluginInfo-EnabledByDefault=true
    
    Comment=The friendly Plugin
    Name=hello
    

    See also