All posts by Dominik

Dominik is a PhD student at the Control Theory and Robotics Lab, TU Darmstadt, as part of the Research Training Group GKMM (GRK1362). My research focuses on state estimation in distributed systems. As hobby, I contribute to the KDE project and work on the Kate application and editor component.

Kate Scripting Updates & Zen-like Quick Coding

In KDE >= 4.10, Kate Part’s scripting changed a bit. The changes are already documented in the Kate handbook, but we’ll quickly have a look into it now anyway.

Prior to KDE SC 4.10, scripts in Kate Part always had to contain the “type” in the scripting header, like indentation or command. This was changed to simply using different folders (system wide or in your $HOME kde folder) as follows:

  • indenters are located in share/apps/katepart/script/indentation
  • commands are located in share/apps/katepart/script/commands
  • api is located in share/apps/katepart/script/libraries

Further, the API is not loaded automatically anymore. Instead, we introduced the function require(“file.js”), which takes one argument. For instance, if you want to use the Cursor and Range API, you just write

require("cursor.js");
require("range.js");

In this example, it would even suffice to just write require(“range.js”); since range.js itself contains the line require(“cursor.js”); Kate Part tracks, which files are already included through require, so you don’t have to worry about include guards like in C/C++.

Now as we are able to just load the libraries that we really need, we can add as many libraries as wanted. For instance, the author of zen-coding wrote a thin wrapper to make all the zen-coding goodies available to Kate Part. It’s included in the emmet subfolder in the script/libraries folder. So if you need this stuff, you just write require(“emmet/desired-file.js”);

It’s a bit unfortunate that we still break how the scripting works from time to time, but it’s better to fix and improve the scripting instead of living with limited capabilities. So if you have own scripts, it’s the best time to contribute them to Kate!

Generic Quick Coding Features

Further, we have some new command line script called quickcoding.js that already uses the zen-coding idea: If you for instance write

 c#n:Test#p:Parent

and press Ctrl+Alt+# in C++ files (the Mode must be C++!), it will automatically expand to

/**
 * Class Test
 */
class Test : public Parent
{
  public:
    /**
     * Constructor of Test
     */
    Test ();

    /**
     * Destructor of Test
     */
    ~Test ();
};

So how does it work? Since the file mode is C++, the quick coding command will read files from katepart/script/files/quickcoding/cpp/. The first character of this cryptic string is ‘c’, which tells the quick coding command to look into c.template. This template now expands according to the specified arguments: n:Test sets the class name to Test, and the optional p:Parent derives Test from Parent.

This is just a proof of concept, and you can do the same with Text Snippts in Kate. But still, this is another way adding support for quick coding for arbitrary languges, and the implementation is completely in JavaScript, so it is rather easy to extend and customize it to your needs. We’ll probably extend/change this feature a bit more over time, let’s see :-) It’s also not yet documented in the Kate Handbook. We’ll probably add ‘official’ documentation for this in later Kate releases. Happy coding!

Passive Notifications in Kate Part

In KDE 4.10, Kate Part got a new MessageInterface. The idea of this interface is to have a standardized way of showing notifications in a non-intrusive way, similar to how KMessageWidget in kdelibs works. Using the MessageInterface is extremly easy, for instance to show a quick notification, you write

KTextEditor::Message *message = new KTextEditor::Message(KTextEditor::Message::Positive,
                                                         "Code successfully reformated.");
document->postMessage(message);

That’s basically it! The result looks like this (with a nice fade-in and fade-out animation):

As developer, once you called postMessage(), you can safely forget the message pointer. It’s automatically deleted either if the user closes the notification, or if the document is closed or reloaded. The API for more tricks. You can add multiple actions through KTextEditor::Message::addAction(), which then appear as buttons. For each added action, you can control whether triggering the action should close the widget or not.

Further, you can set an auto hide timer through Message::setAutoHide(int timeInMilliSeconds).

If you want a message to only appear in one specific KTextEditor::View of the Document, you just call Message::setView() before calling postMessage(). If several messages are in the queue, the one with the highest Message::priority() is shown first.

This notification system is already used in Kate Part by the data recovery (swap files), or to show a notification when loading remote files, and in some other places.

The cool thin is that this solution requires no special code in KateView or other classes, hence, it’s a perfectly clean solution with an easy-to-use API. You as KTextEditor user (developer) should definitely consider using it when it’s public.

Note: The MessageInterface is a KTextEditor interface; however, since the 4.10 branch is frozen for BIC changes, we cannot just add this interface for KDE 4.10. Instead, for Kate Part users (Kile, KDevelop, …) this interface will only be available in KDE5.

Finally, an example of all four message types: Positive, Information, Warning and Error:

Using the Projects Plugin in Kate

Introducing the Projects Plugin for KDE SC 4.10

The basic idea of the Projects plugin is to have a structured list of files belonging to the  project with the following properties:

  1. provide a structured view of the files
  2. make it easy and very fast to open and switch projects
  3. support search & replace for a project
  4. provide simple auto completion
  5. make it simple to quickly open files in the project
  6. support for building the project

We’re going to address all these points now.

1. Provide a Structured View of the Files

Once the “Projects Plugin” is loaded in the Kate config page, a sidebar appears that lists all projects as well as the projects files as follows:

As you can see, the currently active project is “Kate”, and it’s contents is listed in the tree view. Clicking on files in the tree view opens the file in the editor. Further, a context menu is provided with which you can open files with other applications, such as a .ui file with Qt Designer.

2. Switching Projects

The idea is that you never have to open a project manually, this is even not supported at all. Hence, what happens if you open a file, the Project Plugin quickly scans the folder and its parent folders for a .kateproject file. If found, the project is automatically loaded. Very simple and efficient.

Further, if you open another document in Kate, that belongs to another project, the Project plugin automatically switches the current project. So intuitively, always the correct project is active. Of course, you can also switch the currently active project through the combo box.

3. Search & Replace in Projects

Kate has a “Search & Replace” plugin that shows up in the bottom sidebar. If a project is loaded and you open the “Search & Replace” sidebar, it automatically switches to the mode to search & replace in the current project, which usually is exactly what you want:

4. Simple Auto Completion

With the knowledge of all files belonging to a project, the Project plugin provides simple auto completion facilities based on ctags. If a project is initially opened, ctags parses all project files in a background thread and saves the ctags information to /tmp. This file then is used to populate the auto completion popup in Kate. In contrast, without this auto completion, Kate was only capable of showing auto completion items based on the words in the current file. So the auto completion provided by the Project plugin is much more powerful.

If ctags is missing, a passive popup warns you about this. It is also noteworthy, that the ctags file in /tmp is cleaned up when Kate exists, so you the plugin does not pollute any folder with unwanted files.

5. Quick Opening Files

As clicking on files in the tree view is not the fastest way to open a file, Kate provides a built-in quick open mechanism you can activate with CTRL+ALT+o. What you the get is a list like this:

You can filter by typing parts of the file name you are looking for, and you can also navigate with the arrow keys and page up/down through the list. Hitting enter activates the selected file, while escape hides the quick open view again.

Further, the quick open remembers the previous file. So when you change to the quick open view the previously activated  file is automatically selected and you just need to hit enter, which comes very handy at times.

6. Support for Building the Project

Another feature is to have support in the Build plugin, so that it automatically is configured correctly.

Creating Projects

Currently, creating a project requires some manual work, although it is really not much. You just have to create a .kateproject file in the root folder of the project. For instance, the Kate .kateproject file looks like this:

{
  "name": "Kate"
, "files": [ { "git": 1 } ]
}

As you may have noted, this is JSON syntax (because there is a nice jason library for Qt to parse this). The project name is “Kate”, and the files contained in should be read from git.

What’s also supported instead of “git” is subversion through “svn” and mercurial through “hg” (btw, it would be nice to have support for other version control systems as well *hint*). If you do not want to read from a version control system, you can tell it to recursively load files from directories as follows:

{
  "name": "Kate"
, "files": [ { "directory": "kate", "filters": ["*.cpp", "*.h", "*.ui", "CMakeLists.txt", "Find*.cmake"], "recursive": 1 } ]
}

Here, subfolders and filters define what’s part of the project. You can also mix version control and files based on filters.

If you want to add support for the Build plugin, you could write a .kateconfig like this:

{
  "name": "Kate"
, "files": [ { "git": 1 } ]
, "build": {
    "directory": "build"
  , "build": "make all"
  , "clean": "make clean"
  , "install": "make install"
  }
}

Hopefully, these examples help you to setup your own project.

Kudos

Kudos go to Christoph, he implemented all the features in here. The Project plugin will be shipped with  KDE SC 4.10, and you should really try it out :-)