Development/Tutorials/Kate/KTextEditor Plugins: Difference between revisions

From KDE TechBase
(New page: {{TutorialBrowser| series=Kate Plugin Tutorial| name=Creating your first Kate Plugin| pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://www.trolltech.com/products/...)
 
(Mark for updating)
 
(23 intermediate revisions by 8 users not shown)
Line 5: Line 5:
name=Creating your first Kate Plugin|
name=Creating your first Kate Plugin|


pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://www.trolltech.com/products/qt/ Qt], [[Getting_Started/Build/KDE4|KDE4 development environment]]|
pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://www.trolltech.com/products/qt/ Qt], [[Getting_Started/Build|KDE development environment]]|


next=Add a configuration dialog for it (Work in progress)|
next=[[Development/Tutorials/Kate/KTextEditor_Plugins_Advanced|Add a configuration dialog for it]]|


reading=[[Development/Tutorials/CMake|CMake]], [http://websvn.kde.org/trunk/KDE/kdelibs/kate/plugins/timedate The actual plugin code]
reading=[[Development/Tutorials/CMake|CMake]], [http://websvn.kde.org/trunk/KDE/kdelibs/kate/plugins/timedate The actual plugin code]
}}
}}
{{Review|Port to KF5}}
==Abstract==
==Abstract==
We are going to create a dummy plugin for Kate in this tutorial. Our plugin will be able to insert current Date & Time. For now, our plugin will add on the cursor position on the active document the next information:
We are going to create a dummy plugin for Kate in this tutorial. Our plugin will be able to insert current Date & Time. For now, our plugin will add on the cursor position on the active document the next information:
Line 23: Line 26:


'''ktexteditor_timedate.desktop'''
'''ktexteditor_timedate.desktop'''
<code ini>
<syntaxhighlight lang="ini">
[Desktop Entry]
[Desktop Entry]
Encoding=UTF-8
Encoding=UTF-8
Line 37: Line 40:
X-KDE-PluginInfo-EnabledByDefault=false
X-KDE-PluginInfo-EnabledByDefault=false
X-KDE-ParentApp=kate
X-KDE-ParentApp=kate
X-KDE-Version=4.0
ServiceTypes=KTextEditor/Plugin
ServiceTypes=KTextEditor/Plugin
Type=Service
Type=Service
Line 42: Line 46:
Name=Time & Date
Name=Time & Date
Comment=Insert current Time & Date
Comment=Insert current Time & Date
</code>
</syntaxhighlight>


There are important parts on this file:
There are important parts on this file:
Line 52: Line 56:
* '''X-KDE-PluginInfo-EnabledByDefault''': whether the plugin is enabled by default. Applied when clicking on "Defaults" button on the plugin selector.
* '''X-KDE-PluginInfo-EnabledByDefault''': whether the plugin is enabled by default. Applied when clicking on "Defaults" button on the plugin selector.
* '''X-KDE-ParentApp''': you want here always "kate".
* '''X-KDE-ParentApp''': you want here always "kate".
* '''X-KDE-Version''': KWrite/Kate does a check for only loading 4 series plugins.
* '''ServiceTypes''': you will always need here "KTextEditor/Plugin".
* '''ServiceTypes''': you will always need here "KTextEditor/Plugin".
* '''Type''': in order to load it properly this is needed as "Service".
* '''Type''': in order to load it properly this is needed as "Service".
Line 59: Line 64:


'''timedateui.rc'''
'''timedateui.rc'''
<code>
<syntaxhighlight lang="xml">
<!DOCTYPE kpartgui>
<!DOCTYPE kpartgui>
<kpartplugin name="ktexteditor_timedate" library="ktexteditor_timedate" version="2">
<kpartplugin name="ktexteditor_timedate" library="ktexteditor_timedate" version="2">
Line 69: Line 74:
</MenuBar>
</MenuBar>
</kpartplugin>
</kpartplugin>
</code>
</syntaxhighlight>


=== The header file ===
=== The header file ===
'''timedate.h'''
'''timedate.h'''
<code cppqt>
<syntaxhighlight lang="cpp-qt">
// Avoid multiple header inclusion
// Avoid multiple header inclusion
#ifndef TIMEDATE_H
#ifndef TIMEDATE_H
Line 87: Line 92:
#include <QtCore/QObject>
#include <QtCore/QObject>
#include <QtCore/QList>
#include <QtCore/QList>
// This is the default string that will be printed out. As not everybody prints
// it by default as: MM-DD-YYYY HH:MM, but for example, on other cultures we can
// find DD-MM-YYYY HH:MM, we mark this default string for translators to translate
// it. With this macro I18N_NOOP2 we are able to add comments for making the translation
// easier and in context. If a translator sees "%m-%e-%Y %H:%M" can think: "what is this
// guy talking about?". So we add the explanation on the first parameter.
// Anyway, this is not important, do not get stucked here. If you do not understand
// this declaration, think of it as:
//
// static QString localizedTimeDate = "%m-%e-%Y %H:%M";
static QString localizedTimeDate =
    I18N_NOOP2("This is a localized string for default time & date printing on kate document."
              "%e means day in XX format."
              "%m means month in XX format."
              "%Y means year in XXXX format."
              "%H means hours in XX format."
              "%M means minutes in XX format."
              "Please, if in your language time or date is written in a different order, change it here",
              "%m-%e-%Y %H:%M");


/**
/**
Line 119: Line 102:
   public:
   public:
     // Constructor
     // Constructor
     explicit TimeDatePlugin(QObject *parent = 0,
     explicit TimeDatePlugin(QObject *parent,
                             const QStringList &args = QStringList());
                             const QVariantList &args);
     // Destructor
     // Destructor
     virtual ~TimeDatePlugin();
     virtual ~TimeDatePlugin();
Line 136: Line 119:
     void readConfig();
     void readConfig();
     void writeConfig();
     void writeConfig();
    virtual void readConfig (KConfig *) {}
    virtual void writeConfig (KConfig *) {}


   private:
   private:
Line 164: Line 144:


#endif // TIMEDATE_H
#endif // TIMEDATE_H
</code>
</syntaxhighlight>


=== The source file ===
=== The source file ===
'''timedate.cpp'''
'''timedate.cpp'''
<code cppqt>
<syntaxhighlight lang="cpp-qt">
// Own includes
// Own includes
#include "timedate.h"
#include "timedate.h"
Line 175: Line 155:
#include <ktexteditor/document.h>
#include <ktexteditor/document.h>


#include <kgenericfactory.h>
#include <kpluginfactory.h>
#include <kpluginloader.h>
#include <klocale.h>
#include <klocale.h>
#include <kaction.h>
#include <kaction.h>
Line 181: Line 162:
#include <kdatetime.h>
#include <kdatetime.h>


// Without this macro call, the library loader won't find our plugin when trying
// This macro defines a KPluginFactory subclass named TimeDatePluginFactory. The second
// to load it. This macro adds code automagically that will let our plugin
// argument to the macro is code that is inserted into the constructor of the class.
// be loaded on runtime.
// I our case all we need to do is register one plugin. If you want to have more
// The first parameter is the X-KDE-FactoryName on the .desktop file.
// than one plugin in the same library then you can register multiple plugin classes
// As we haven't provided such parameter, in this case (because our library is only
// here. The registerPlugin function takes an optional QString parameter which is a
// exporting one symbol, this plugin), we put here the X-KDE-LibraryName.
// keyword to uniquely identify the plugin then (it maps to X-KDE-PluginKeyword in the
// The second parameter will determine which type is our class, in this case it is
// .desktop file).
// a TimeDatePlugin and the name of the X-KDE-FactoryName again. Same as before,
K_PLUGIN_FACTORY(TimeDatePluginFactory,
// as we do not have X-KDE-FactoryName, we put there the X-KDE-LibraryName.
                registerPlugin<TimeDatePlugin>();
                )
 
// With the next macro call, the library exports version information about the
// Qt and KDE libraries being used and (most important) the entry symbol to get at
// the factory we defined above.
// The argument this macro takes is the constructor call of the above factory which
// provides two constructors. One which takes a KAboutData* and another one
// that takes two (optional) const char* parameters (Same as for KComponentData
// constructors).
// We put there the X-KDE-LibraryName.
// Is important to provide as last parameter "ktexteditor_plugins".
// Is important to provide as last parameter "ktexteditor_plugins".
K_EXPORT_COMPONENT_FACTORY(ktexteditor_timedate, KGenericFactory<TimeDatePlugin>("ktexteditor_timedate", "ktexteditor_plugins"))
K_EXPORT_PLUGIN(TimeDatePluginFactory("ktexteditor_timedate", "ktexteditor_plugins"))


// Constructor
// Constructor
TimeDatePlugin::TimeDatePlugin(QObject *parent, const QStringList &args)
TimeDatePlugin::TimeDatePlugin(QObject *parent, const QVariantList &args)
     : KTextEditor::Plugin(parent)
     : KTextEditor::Plugin(parent)
{
{
Line 243: Line 234:
   , m_view(view)
   , m_view(view)
{
{
    // Insert the plugin
     setComponentData(TimeDatePluginFactory::componentData());
    view->insertChildClient(this);
     setComponentData(KGenericFactory<TimeDatePlugin>::componentData());


     KAction *action = new KAction(i18n("Insert Time && Date"), this);
     KAction *action = new KAction(i18n("Insert Time && Date"), this);
Line 271: Line 260:
void TimeDatePluginView::slotInsertTimeDate()
void TimeDatePluginView::slotInsertTimeDate()
{
{
    QString localizedTimeDate = i18nc("This is a localized string for default time & date printing on kate document."
                                      "%e means day in XX format."
                                      "%m means month in XX format."
                                      "%Y means year in XXXX format."
                                      "%H means hours in XX format."
                                      "%M means minutes in XX format."
                                      "Please, if in your language time or date is written in a different order, change it here",
                                      "%m-%e-%Y %H:%M");
     // We create a KDateTime object with the current time & date.
     // We create a KDateTime object with the current time & date.
     KDateTime dt(QDateTime::currentDateTime());
     KDateTime dt(QDateTime::currentDateTime());
Line 281: Line 279:
// the Q_OBJECT macro on the TimeDatePluginView class.
// the Q_OBJECT macro on the TimeDatePluginView class.
#include "timedate.moc"
#include "timedate.moc"
</code>
</syntaxhighlight>


=== Building it all, the CMakeLists.txt ===
=== Building it all, the CMakeLists.txt ===
Line 288: Line 286:
For more details on CMake please read [[Development/Tutorials/CMake]]
For more details on CMake please read [[Development/Tutorials/CMake]]


<code bash>
<syntaxhighlight lang="cmake">
find_package(KDE4 REQUIRED)
include (KDE4Defaults)
include_directories(${KDE4_INCLUDES})
 
# We are calling our plugin "ktexteditor_timedate", and it contains only
# We are calling our plugin "ktexteditor_timedate", and it contains only
# one source file: timedate.cpp.
# one source file: timedate.cpp.
Line 294: Line 296:


# We need to link our plugin against kdecore libs, as well as ktexteditor
# We need to link our plugin against kdecore libs, as well as ktexteditor
target_link_libraries(ktexteditor_timedate ${KDE4_KDECORE_LIBS} ktexteditor)
target_link_libraries(ktexteditor_timedate ${KDE4_KDECORE_LIBS} ${KDE4_KDEUI_LIBS} ktexteditor)


# Well, we want to install our plugin on the plugin directory
# Well, we want to install our plugin on the plugin directory
Line 307: Line 309:
# on the services directory.
# on the services directory.
install(FILES ktexteditor_timedate.desktop DESTINATION ${SERVICES_INSTALL_DIR})
install(FILES ktexteditor_timedate.desktop DESTINATION ${SERVICES_INSTALL_DIR})
</code>
</syntaxhighlight>


=== The next part ===
=== The next part ===
Now you are ready for adding to this plugin a configuration dialog that lets the user customize the way the string is printed out on the screen.
Now you are ready for adding to this plugin a configuration dialog that lets the user customize the way the string is printed out on the screen.
[[Development/Tutorials/Kate/KTextEditor_Plugins_Advanced|Take me to the next part of this tutorial !!]]

Latest revision as of 12:24, 31 May 2019

Creating your first Kate Plugin
Tutorial Series   Kate Plugin Tutorial
Previous   C++, Qt, KDE development environment
What's Next   Add a configuration dialog for it
Further Reading   CMake, The actual plugin code
Warning
This page needs a review and probably holds information that needs to be fixed.

Parts to be reviewed:

Port to KF5

Abstract

We are going to create a dummy plugin for Kate in this tutorial. Our plugin will be able to insert current Date & Time. For now, our plugin will add on the cursor position on the active document the next information:

  • MM-DD-YYYY HH:MM (something like "08-22-2007 23:45")

On the next chapter we will learn how to customize this output string creating a configuration dialog for this plugin.

The Code

The .desktop file

Every plugin needs a .desktop file that describes it.

ktexteditor_timedate.desktop

[Desktop Entry]
Encoding=UTF-8
X-KDE-Library=ktexteditor_timedate
X-KDE-PluginInfo-Author=Konqui the Dragon
X-KDE-PluginInfo-Email=[email protected]
X-KDE-PluginInfo-Name=ktexteditortimedate
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=http://kate.kde.org
X-KDE-PluginInfo-Category=Editor
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=false
X-KDE-ParentApp=kate
X-KDE-Version=4.0
ServiceTypes=KTextEditor/Plugin
Type=Service
Icon=korganizer
Name=Time & Date
Comment=Insert current Time & Date

There are important parts on this file:

  • X-KDE-Library: will define the library that provides this plugin. It is _really_ important that this variable matches exactly the same with the actual name of the library being built. You will understand this better when getting to the finish of this tutorial on the part "Building it all, the CMakeLists.txt".
  • X-KDE-PluginInfo-Name: no special characters. The name of the plugin.
  • X-KDE-PluginInfo-Category: important when the plugin selector loads it. Usually here you want always to put "Editor".
  • X-KDE-PluginInfo-Depends: if your plugin depends on another, write here the corresponding X-KDE-PluginInfo-Name that is needed to be loaded too when loading this plugin.
  • X-KDE-PluginInfo-EnabledByDefault: whether the plugin is enabled by default. Applied when clicking on "Defaults" button on the plugin selector.
  • X-KDE-ParentApp: you want here always "kate".
  • X-KDE-Version: KWrite/Kate does a check for only loading 4 series plugins.
  • ServiceTypes: you will always need here "KTextEditor/Plugin".
  • Type: in order to load it properly this is needed as "Service".

The resource contents file

This file is the one that will let our plugin merge with the Kate environment (toolbars and/or menubars). In this case when our plugin is loaded this file tells the KDE XML classes that it will add a separator, and that there is an action named "tools_insert_timedate". We will need to interact with this action later.

timedateui.rc

<!DOCTYPE kpartgui>
<kpartplugin name="ktexteditor_timedate" library="ktexteditor_timedate" version="2">
<MenuBar>
 <Menu name="tools"><Text>&amp;Tools</Text>
    <separator group="tools_operations" />
    <Action name="tools_insert_timedate" group="tools_operations"/>
 </Menu>
</MenuBar>
</kpartplugin>

The header file

timedate.h

// Avoid multiple header inclusion
#ifndef TIMEDATE_H
#define TIMEDATE_H

// Include the basics
#include <ktexteditor/plugin.h>
#include <ktexteditor/view.h>
#include <kxmlguiclient.h>
#include <klocalizedstring.h>

#include <QtCore/QEvent>
#include <QtCore/QObject>
#include <QtCore/QList>

/**
  * This is the plugin class. There will be only one instance of this class.
  * We always want to inherit KTextEditor::Plugin here.
  */
class TimeDatePlugin
  : public KTextEditor::Plugin
{
  public:
    // Constructor
    explicit TimeDatePlugin(QObject *parent,
                            const QVariantList &args);
    // Destructor
    virtual ~TimeDatePlugin();

    // Overriden methods
    // This method is called when a plugin has to be added to a view. As there
    // is only one instance of this plugin, but it is possible for plugins to
    // behave in different ways in different opened views where it is loaded, in
    // Kate plugins are added to views. For that reason we have the plugin itself
    // (this class) and then the plugin view class.
    // In this methods we have to create/remove TimeDatePluginView classes.
    void addView (KTextEditor::View *view);
    void removeView (KTextEditor::View *view);

    void readConfig();
    void writeConfig();

  private:
    QList<class TimeDatePluginView*> m_views;
};

/**
  * This is the plugin view class. There can be as much instances as views exist.
  */
class TimeDatePluginView
   : public QObject, public KXMLGUIClient
{
  Q_OBJECT

  public:
    explicit TimeDatePluginView(KTextEditor::View *view = 0);
    ~TimeDatePluginView();

  private Q_SLOTS:
    void slotInsertTimeDate();

  private:
    KTextEditor::View *m_view;
};

#endif // TIMEDATE_H

The source file

timedate.cpp

// Own includes
#include "timedate.h"

// Include the basics
#include <ktexteditor/document.h>

#include <kpluginfactory.h>
#include <kpluginloader.h>
#include <klocale.h>
#include <kaction.h>
#include <kactioncollection.h>
#include <kdatetime.h>

// This macro defines a KPluginFactory subclass named TimeDatePluginFactory. The second
// argument to the macro is code that is inserted into the constructor of the class.
// I our case all we need to do is register one plugin. If you want to have more
// than one plugin in the same library then you can register multiple plugin classes
// here. The registerPlugin function takes an optional QString parameter which is a
// keyword to uniquely identify the plugin then (it maps to X-KDE-PluginKeyword in the
// .desktop file).
K_PLUGIN_FACTORY(TimeDatePluginFactory,
                 registerPlugin<TimeDatePlugin>();
                )

// With the next macro call, the library exports version information about the
// Qt and KDE libraries being used and (most important) the entry symbol to get at
// the factory we defined above.
// The argument this macro takes is the constructor call of the above factory which
// provides two constructors. One which takes a KAboutData* and another one
// that takes two (optional) const char* parameters (Same as for KComponentData
// constructors).
// We put there the X-KDE-LibraryName.
// Is important to provide as last parameter "ktexteditor_plugins".
K_EXPORT_PLUGIN(TimeDatePluginFactory("ktexteditor_timedate", "ktexteditor_plugins"))

// Constructor
TimeDatePlugin::TimeDatePlugin(QObject *parent, const QVariantList &args)
    : KTextEditor::Plugin(parent)
{
    // Avoid warning on compile time because of unused argument
    Q_UNUSED(args);
}

// Destructor
TimeDatePlugin::~TimeDatePlugin()
{
}

// Create the plugin view class and add it to the views list
void TimeDatePlugin::addView(KTextEditor::View *view)
{
    TimeDatePluginView *nview = new TimeDatePluginView(view);
    m_views.append(nview);
}

// Find the view where we want to remove the plugin from, and remove it.
// Do not forget to free the memory.
void TimeDatePlugin::removeView(KTextEditor::View *view)
{
    for (int z = 0; z < m_views.size(); z++)
    {
        if (m_views.at(z)->parentClient() == view)
        {
            TimeDatePluginView *nview = m_views.at(z);
            m_views.removeAll(nview);
            delete nview;
        }
    }
}

// We do nothing on this methods since our plugin is not configurable yet
void TimeDatePlugin::readConfig()
{
}

void TimeDatePlugin::writeConfig()
{
}

// Plugin view class
TimeDatePluginView::TimeDatePluginView(KTextEditor::View *view)
  : QObject(view)
  , KXMLGUIClient(view)
  , m_view(view)
{
    setComponentData(TimeDatePluginFactory::componentData());

    KAction *action = new KAction(i18n("Insert Time && Date"), this);
    // Here we need as first parameter the same we declared at the resource
    // contents file (timedateui.rc). We named the action "tools_insert_timedate".
    // Here is where we connect it to an actual KDE action.
    actionCollection()->addAction("tools_insert_timedate", action);
    action->setShortcut(Qt::CTRL + Qt::Key_D);
    // As usual, we connect the signal triggered() to a slot here. When the menu
    // element is clicked, we go to the slot slotInsertTimeDate().
    connect(action, SIGNAL(triggered()), this, SLOT(slotInsertTimeDate()));

    // This is always needed, tell the KDE XML GUI client that we are using
    // that file for reading actions from.
    setXMLFile("timedateui.rc");
}

// Destructor
TimeDatePluginView::~TimeDatePluginView()
{
}

// The slot that will be called when the menu element "Insert Time & Date" is
// clicked.
void TimeDatePluginView::slotInsertTimeDate()
{
    QString localizedTimeDate = i18nc("This is a localized string for default time & date printing on kate document."
                                      "%e means day in XX format."
                                      "%m means month in XX format."
                                      "%Y means year in XXXX format."
                                      "%H means hours in XX format."
                                      "%M means minutes in XX format."
                                      "Please, if in your language time or date is written in a different order, change it here",
                                      "%m-%e-%Y %H:%M");

    // We create a KDateTime object with the current time & date.
    KDateTime dt(QDateTime::currentDateTime());
    // We insert the information in the document at the current cursor position
    // with the default string declared on the header.
    m_view->document()->insertText(m_view->cursorPosition(), dt.toString(localizedTimeDate));
}

// We need to include the moc file since we have declared slots and we are using
// the Q_OBJECT macro on the TimeDatePluginView class.
#include "timedate.moc"

Building it all, the CMakeLists.txt

Finally, to put everything together you need to build everything, to tell cmake what needs to go where there is the CMakeLists.txt file.

For more details on CMake please read Development/Tutorials/CMake

find_package(KDE4 REQUIRED)
include (KDE4Defaults)
include_directories(${KDE4_INCLUDES})

# We are calling our plugin "ktexteditor_timedate", and it contains only
# one source file: timedate.cpp.
kde4_add_plugin(ktexteditor_timedate timedate.cpp)

# We need to link our plugin against kdecore libs, as well as ktexteditor
target_link_libraries(ktexteditor_timedate ${KDE4_KDECORE_LIBS} ${KDE4_KDEUI_LIBS} ktexteditor)

# Well, we want to install our plugin on the plugin directory
install(TARGETS ktexteditor_timedate DESTINATION ${PLUGIN_INSTALL_DIR})

# We also want to install the resource contents file on the data directory, at
# the subdirectory of our plugin name, so it does not mix up with other resource
# contents files.
install(FILES timedateui.rc DESTINATION ${DATA_INSTALL_DIR}/ktexteditor_timedate)

# We want to install the desktop file that describes our plugin too. It will go
# on the services directory.
install(FILES ktexteditor_timedate.desktop DESTINATION ${SERVICES_INSTALL_DIR})

The next part

Now you are ready for adding to this plugin a configuration dialog that lets the user customize the way the string is printed out on the screen.

Take me to the next part of this tutorial !!