Difference between revisions of "Development/Tutorials/Kate/KTextEditor Plugins"

<Menu name="tools"><Text>&Tools</Text>
   <separator group="tools_operations" />
   <Action name="tools_insert_timedate" group="tools_operations"/>
</Menu>

1. ifndef TIMEDATE_H
2. define TIMEDATE_H

// Include the basics

1. include <ktexteditor/plugin.h>
2. include <ktexteditor/view.h>
3. include <kxmlguiclient.h>
4. include <klocalizedstring.h>

1. include <QtCore/QEvent>
2. include <QtCore/QObject>
3. 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;

};

1. endif // TIMEDATE_H

1. include "timedate.h"

// Include the basics

1. include <ktexteditor/document.h>

1. include <kpluginfactory.h>
2. include <kpluginloader.h>
3. include <klocale.h>
4. include <kaction.h>
5. include <kactioncollection.h>
6. 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.

1. include "timedate.moc"

1. We are calling our plugin "ktexteditor_timedate", and it contains only
2. one source file: timedate.cpp.

kde4_add_plugin(ktexteditor_timedate timedate.cpp)

1. 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)

1. Well, we want to install our plugin on the plugin directory

install(TARGETS ktexteditor_timedate DESTINATION ${PLUGIN_INSTALL_DIR})

1. We also want to install the resource contents file on the data directory, at
2. the subdirectory of our plugin name, so it does not mix up with other resource
3. contents files.

install(FILES timedateui.rc DESTINATION ${DATA_INSTALL_DIR}/ktexteditor_timedate)

1. We want to install the desktop file that describes our plugin too. It will go
2. on the services directory.