Kate plugin tutorial

Learn how to write a Kate plugin

The plugin we will write will basically be a Markdown previewer. It will do something like

  • Once a file opens, check if the file is a Markdown file

  • If it is, then create and show a preview for it in right the sidebar

We'll call this plugin Markdown Previewer.

This tutorial assumes that you have a basic understanding of C++ and Qt concepts and that you have development versions of Qt and KDE Framework libraries installed, as well as extra-cmake-modules.

Initial directory structure:

myplugin
├─ CMakeLists.txt  # the build file, this is needed to build the plugin
├─ plugin.cpp      # the actual plugin code
├─ plugin.h
└─ plugin.json     # plugin type, description and name

Let's start by writing our cmake file:

cmake_minimum_required(VERSION 3.16)
project(markdownpreview VERSION 1.0)

find_package(ECM ${KF5_DEP_VERSION} QUIET REQUIRED NO_MODULE)

list(APPEND CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)

find_package(Qt${QT_MAJOR_VERSION}Widgets CONFIG REQUIRED)

set(KF5_DEP_VERSION "5.90")
find_package(KF5 ${KF5_DEP_VERSION}
    REQUIRED COMPONENTS
        CoreAddons # Core addons on top of QtCore
        I18n # For localization
        TextEditor # The editor component
)

# This line defines the actual target
kcoreaddons_add_plugin(markdownpreview # your plugin name here
    INSTALL_NAMESPACE "ktexteditor")

target_sources(
  markdownpreview
  PRIVATE
  plugin.h
  plugin.cpp
)

# This makes the plugin translatable
target_compile_definitions(markdownpreview PRIVATE TRANSLATION_DOMAIN="markdownpreview")

target_link_libraries(markdownpreview
    PRIVATE
    KF5::CoreAddons KF5::I18n KF5::TextEditor
)

Ok, CMake is done. Let's write the plugin.json file:

Finally, let's start writing the actual code for the plugin.

Before I start, let's go through a couple of basic things first. Every Kate plugin consists of at least two classes

  • Plugin class

  • Plugin View class

The plugin class creates a global instance of the plugin only once. The plugin view class will be created once for each new MainWindow. Your UI code will always go into the plugin view class. The plugin class usually stores stuff that will be same across multiple plugin views for e.g., the configuration.

Below is the code for both of the classes. At this point, the classes are empty and don't do anything at all

plugin.h

plugin.cpp

With this, we should now be able to compile and install it. For testing purposes, we will be installing it to our home directory.

You should now see the installed plugin in ~/kde/usr/lib64/plugins/ktexteditor/markdowpreview.so.

To test the local plugin with our system-installed Kate, we can use the generated prefix.sh inside our build folder:

Note If we were to install the plugin to the root directory where Kate plugins are deployed, it would have been installed in /usr/lib/qt/plugins/ktexteditor/markdowpreview.so. To do that, you'd need to remove the -D CMAKE_INSTALL_PREFIX call and run the install command with sudo, and sourcing prefix.sh would no longer be necessary.

With Kate now running, go to Settings, Configure Kate..., Plugins, and verify that the "Markdown Previewer" plugin is present.

Next we will create a toolview in the right sidebar. This toolview will be the GUI component that appears on the right side of Kate that, when clicked, opens the Markdown preview.

First add two new member variables to the MarkdownPreviewPluginView class in plugin.h:

Now let's create the toolview by adding the following to the constructor in plugin.cpp:

Before proceeding further, make sure the code compiles. Then install the plugin, enable it in Kate and verify that the toolview is visible in the right sidebar. If the toolview isn't visible, make sure the plugin is enabled and recheck your code.

Note If you didn't use an icon and your sidebar settings are set to "icon-only", you won't see the button for the toolview and it will appear as if there is no toolview because of the non existent icon. To disable this setting, check the option "Show text for left and right sidebar buttons".

Now to the actual previewing. To be able to tell when the active document changes the MainWindow class emits a viewChanged() signal. We will connect to this signal and then check if the new document is of Markdown type. If it is, we will load the document's text into the preview widget which will take care of the rest.

So, in the constructor of the MarkdownPreviewPluginView class add the following:

Next, we will define the onViewChanged() function. Let's add its declaration in MarkdownPreviewPluginView in plugin.h:

And definition in the plugin.cpp file:

Compile and install it. You should now be able to see the preview of markdown files in the toolview we created.

Full code

CMakeLists.txt

plugin.json

plugin.h

plugin.cpp

Since this is a very basic tutorial and likely doesn't explain a lot of things or shows other APIs that we have, the following resources may be of more help:

  • https://api.kde.org/frameworks/ktexteditor/html/ - Here you will find the list of all classes and methods available in the API

  • https://invent.kde.org/utilities/kate/-/tree/master/addons - The list of existing plugins can be an extremely useful resource if you want to find how to do a particular thing

  • https://kate-editor.org/support/ - You can find links to our mailing-list, chat here. We also have telegram and matrix groups where you can ask questions

PreviousKateNextKMines

Last updated