Encapsulation is not Information Hiding

As food for thought and in reply to Why Encapsulation is a Good Thing it's interesting to take a closer look. What does encapsulation mean exactly, and what can you do with it? Maybe what you really want is Information Hiding? ...and encapsulation is just a way of possibly achieving it? If you are interested in the details/differences, read the article Encapsulation is not Information Hiding.

To all TechBase Contributors

I've just added a new page which lists the KDE TechBase contributors. The idea is to have contact data for quick questions as well as build teams for different maintenance tasks. If you are active in the techbase wiki, please add yourself to the list - be it as a reviewer reading the RSS feed, translator or article writer...

Memory Leak Continued

There was some confusion with regard to my last blog about leaking memory. Suppose the ui_mywidget.h files looks like this:

class Ui_Widget
{
public:
   QGridLayout *gridLayout;
   QGroupBox *groupBox;
   QGridLayout *gridLayout1;
   QListWidget *listWidget;
   QSpacerItem *spacerItem;
   QPushButton *pushButton;

   void setupUi(QWidget *Widget);
   void retranslateUi(QWidget *Widget);
};

Of course, those 6 QObject derived classes are deleted. But the sizeof(Ui_Widget) = 6 * sizeof(void*) = 24 bytes are not deleted. As Ui_Widget is not QObject derived those 24 bytes leak. Confirmed by valgrind.

In a comment to my last blog Paolo suggested to use auto_ptr or scoped_ptr, which is more elegant than an extra wrapper class :)

Memory leak: Ui files and direct approach

The KDE codebase often uses a forward declaration in the .h-file to speedup compilation. The code often looks like this:

// header file
namespace Ui { class MyWidget; }
class MyDialog : public KDialog {
// ...
private:
Ui::MyWidget *ui;
};

The impl looks like this:

// source file
#include "mydialog.h"
#include "ui_mywidget.h"
MyDialog::MyDialog() : KDialog()
{
QWidget *w = new QWidget(this);
setMainWidget(w);
ui = new Ui::MyWidget(); // allocation
ui->setupUi(w);
// ui->...
}

See the memory leak? You have to call »delete ui;« in the destructor if you use the »direct approach«. Searching in lxr.kde.org shows lots of results, and in some places this delete is missing indeed. Happy fixing :)

---

Update: The really correct fix is to guard the pointer with an auto_ptr or scoped_ptr. For further details read the comments below. Or use another approach to include your ui-file.

---

If you do not want to delete it manually, you can for instance use a workaround like this:

// header file
namespace Ui { class MyWidget; }
class MyWidget;
class MyDialog : public KDialog {
// ...
private:
Ui::MyWidget *ui;
};

Source file:

// source file
#include "mydialog.h"
#include "ui_mywidget.h"

class MyWidget : public QWidget, public Ui::MyWidget {
public:
    MyWidget( QWidget * parent = 0 ) : QWidget( parent )
    { setupUi(this); }
};

MyDialog::MyDialog() : KDialog()
{
ui = new MyWidget(this);
setMainWidget(ui);
QWidget *w = new QWidget(this);
setMainWidget(w);
ui = new Ui::MyDialog(); // allocation
ui->setupUi(w);
// ui->...
}

Once in a while...

...I simply don't get it.
Recently there was this article on linux.com about [...]. Well, did you know that Konqueror can do all this, too, and much more? Launch Konqueror, split the view and you can transfer data right away with EVERY protocol KDE supports. ftp, fish, webdav and a lot other protocols. No need for an extra ftp client... In short, Konqueror is the best - and you can even use it on the Linux desktop.
...now I stumbled over this article on linux.com about [...]. In Konqueror you can do this for ages, too, the concept is called service menus. And it is very mighty and at the same time very simple to extend. And - if you have a look - there are thousands of context menus available, of course with the slight difference that contributors at kde-apps.org don't get 100$ for their work ;)
I wonder why such articles make it to linux.com at all. This is a drop of quality, imo. This is not about KDE vs. Gnome. It's about that articles should be objective and consider several alternatives. The first solution you read about isn't always the Holy Grail. Sorry for the rant.

PS: Maybe ed is the best text editor, I still prefer Kate, though. *blah* :-)

Kate Highlighting Power

Kate's highlighting capabilities are amazing. If you want you can highlight really complex syntax, without having to hardcode rules in C++. As an example, we'll take a look at how Lua comments can be realized:

• --[=[ starts a multiline comment (the '=' chars are optional)
• ]=] ends the multiline comment
• the number of '=' chars in ]=] must match the number of --[=[
  

That means: When the highlighting processor matches the end of a multiline comment, it has to know how many '=' chars started the comment. Thanks to the concept of dynamic rules and contexts Kate is able to do that. The highlighting file looks like this. First comes the header

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "language.dtd" >
<language name="Test" version="1.0" kateversion="2.4" section="Markup" extensions="" mimetype="">
  <highlighting>

Then the body with the contexts. We start in the first context called "Normal Text". When the regular expression --[(=*)[ matches it switches to the context Comment.

    <contexts>
      <context attribute="Normal Text" lineEndContext="#stay" name="Normal">
        <RegExpr attribute="Comment" context="Comment" String="--\[(=*)\[" dynamic="true"/>
      </context>

The part (=*) is now available as %1 in the rule below:

      <context name="Comment" attribute="Comment" lineEndContext="#stay" dynamic="true" >
        <RegExpr attribute="Comment" context="#pop" String="\]%1\]" dynamic="true" />
      </context>
    </contexts>

The last part is the footer:

    <itemDatas>
      <itemData name="Normal Text" defStyleNum="dsNormal" />
      <itemData name="Comment"     defStyleNum="dsComment" />
    </itemDatas>
  </highlighting>
</language>

If you want to know more about Kate's highlighting, have a look at the documentation :) There are also lots of bug reports, so if you want to contribute you can fix them!

PS: As I don't know much about Lua, comments might work differently. That does not really matter, as the example still shows what you can do :)

List of new KDE features

Hi, our list of KDE features heavily lacks updates :)
So everyone checkout

trunk/www/sites/developer/development-versions

and update kde-features.xml :) At some point we'll enable the techbase extension so the list shows up there as well.

OT: T-Online Software

I had to install the "T-Online Software 5" recently on a Win98 box. Starting the T-Online setup a message popped up:

You need at least Internet Explorer 5.5. Setup terminated!

Sigh, I found a IE5.5 offline setup. Next try:

You need at least a resolution of 800x600. Setup terminated!

I found the graphics card chip, installed the drivers and switched the resolution. Next try:

The language version of the OS is not German. Setup terminated!

Now that is clearly how software should not work. It seems to be impossible to install the T-Online software. I would install Linux, but it's quite a change for a ~90 years old user :(

Extending Kate by Scripts

We have seen how scripting basically works for indentation. It's also possible to register commandline functions (The command line is bound to F7 by default, or invoke View > Switch to Command Line). We will consider a small example again: sort the selected text.

/* kate-script
 * name: unused
 * author: foo bar
 * license: LGPL
 * version: 1
 * kate-version: 3.0
 * functions: sorter
 */

function sorter ()
{
    if (view.hasSelection()) {
        var start = view.startOfSelection().line;
        var end = view.endOfSelection().line;

        var text = document.textRange(start, 0, end, document.lineLength(end));

        var lines = text.split("\n");
        lines.sort();
        text = lines.join("\n");

        view.clearSelection();

        document.editBegin();
        document.removeText(start, 0, end, document.lineLength(end));
        document.insertText(start, 0, text);
        document.editEnd();
    }
}

The header line functions: sorter makes Kate Part aware of the function in the script. A list of functions is supported, separated by white spaces. You can use the function by typing 'sorter' in the commandline.
Some todo items:

• provide better JavaScript API. For example: document.textRange() takes 4 parameters. It would be more elegant to take one range or two cursors, just like we do in the KTextEditor interfaces in kdelibs/interfaces/ktexteditor
  
• make is possible to bind scripts to shortcuts. This could be done by e.g. binding commandline functions to shortcuts or implementing a vim-like command-mode in Kate's commandline. How to configure the shortcuts is unclear, though.
• then, think about replacing the C++ implementations of 'uppercase', 'lowercase', 'capitalize' etc. with scripts
• things I forgot...

If you are interested subscribe to kwrite-devel@kde.org and contribute :) We also need indentation scripts, of course!

Kate: More on Indentation Scripting

My last blog was about the theory of how indentation works by using javascripts. Now we will look at a concrete example: a LISP-style indenter. (LISP indentation is easy, that's why it's a good example).
The rules:

• comments starting with ;;; always have indentation 0
• comments starting with ;; should be aligned with the next line
• comments starting with ; should only appear behind code, so they are simply ignored
• every '(' indents and every ')' unindents

lisp.js looks like this:

/** kate-script
 * name: LISP
 * license: LGPL
 * author: foo bar
 * version: 1
 * kate-version: 3.0
 * type: indentation
 */
// indent should be called when ; is pressed
triggerCharacters = ";";
function indent(line, indentWidth, ch)
{
    // special rules: ;;; -> indent 0
    //                ;;  -> align with next line, if possible
    //                ;   -> usually on the same line as code -> ignore
    textLine = document.line(line);
    if (textLine.search(/^\s*;;;/) != -1) {
        return 0;
    } else if (textLine.search(/^\s*;;/) != -1) {
        // try to align with the next line
        nextLine = document.nextNonEmptyLine(line + 1);
        if (nextLine != -1) {
            return document.firstVirtualColumn(nextLine);
        }
    }

    cursor = document.anchor(line, 0, '(');
    if (cursor) {
        return document.toVirtualColumn(cursor.line, cursor.column) + indentWidth;
    } else {
        return 0;
    }
}

The result:

;;; fib : number -> number
(define (fib n)
  (if (< n 2)
    1
    (+ (fib (- n 1)) (fib (- n 2)))))

As this indenter is scripted, everybody can adapt the style to the own needs.

Kate Scripting: Indentation

Kate Part in KDE4 supports the ECMAScript (JavaScript) language by using kjs. In KDE3 we had several hard-coded indenters in C++, the idea is to let scripts do all the indentation in KDE4.
How does it work? It is similar to vim: You simply create a script in the directory $KDEDIR/share/apps/katepart/jscript. An indentation script has to follow several rules:

1. it must have a valid script header (the first line must include the string kate-script and indentation scripts must have the type: indentation)
   
2. it must define some variables and functions

Whenever the user types a character, the flow in Kate Part works like this

1. check the indentation script's trigger characters, i.e. whether the script wants to indent code for the typed character
2. if yes, call the indentation function
3. the return value of the indentation function is an integer value representing the new indentation depth in spaces.

In the 3rd step there are 2 special cases for the return value:

1. return value = -1: Kate keeps the indentation, that is it searches for the last non-empty line and uses its indentation for the current line
2. return value < -1 tells Kate to do nothing

So how does a script look like exactly?
The name does not really matter, so let's call it foobar.js:

/* kate-script
* name: MyLanguage Indenter
* license: LGPL
* author: Foo Bar
* version: 1
* kate-version: 3.0
* type: indentation
*
* optional bla bla here
*/

// specifies the characters which should trigger indent() beside the default '\n'
triggerCharacters = "{}";

// called for the triggerCharacters {} and
function indent(line, indentWidth, typedChar)
{
// do calculations here
// if typedChar is an empty string, the user hit enter/return

// todo: Implement your indentation algorithms here.
return -1; // keep indentation
}

More details on the header:

• name [required]: the name will appear in Kate's menus
• license [optional]: not visible in gui, but should be specified in js-files. it is always better to have a defined license
• author [optional]: name
• version [optional]: recommended. an integer
• kate-version [required]: the minimum required kate-version (e.g. for api changes)
• type [required]: must be set to indentation

The only missing part is the API which Kate Part exports to access the document and the view. Right now, there is no API documentation, so you have to look at the code:

• kdelibs/kate/jscript/katejscript.cpp search for "@Begin" tags
  

You will find, that the current document exports functions like

• document.fileName()
• document.isModified()
• document.charAt(line, column)
• etc...

The view exports functions like

• view.cursorPosition()
• view.hasSelection()
• view.clearSelection()
• ...

That's the boring part of this blog. The interesting one is unfortunately shorter: we are looking for contributors who want to write scripts or help in the C++ implementation :)

Luggage continued

Quick notice: I have my bag back. It was wet inside -- probably for 2 weeks, no wonder it started to get moldy inside, and I'm not sure yet whether I can use some of the clothes. Well done BA & Heathrow.

Deeply impressed...

Hey, I wasn't aware there was another one who did not get his luggage at all in Glasgow. I traveled from Frankfurt(Germany) to London (Heathrow) and then on to Glasgow. When I arrived, my luggage was missing. British Airways told me it would still be in London but it should arrive the same day and they would bring it to the Euro Hostel - cool :) How naive! Of course it did not arrive... and it didn't arrive the whole week.
The online status always said "Still tracing, check back later". When I flew back I asked at the Glasgow airport again and was told they can not see more than what I see online. When I asked whether they could call London/Heathrow by phone they said in London/Heathrow 20.000 bags are missing so it would be pointless. If the system is so unreliable, why don't they simply close the airport. moo
When I arrived in London I asked again, and a BA-service guy told me he could see that my luggage was being sent to Glasgow by road. By road??? Hell, it takes them 1 hour by plane, so what? And I even told them that I would leave this day. So why to Glasgow at all now?
Well, finally I sat in the plane... which ironically had a delay because it had one bag too much. Hey, that could have been mine... :)
Back in Frankfurt I asked again, and at least this time they were capable of changing the destination address to where I live in Germany. Strange, I told them in Glasgow in the first place, but they seem to be pretty much incapable... :)
So here we go: Back in Germany... in the meanwhile I wondered whether I'd see my bag ever again. Today, almost 2 weeks later, the state incredibly changed to "Received at the airport, delivery in progress". Wow, I'm deeply impressed... really great job. Wait: at which airport? Glasgow? London? Frankfurt? Or somewhere else in the world? *sigh*
So in short: I still don't have my luggage back... :)

Translation of TechBase

As contributors started to translate articles in TechBase to other languages I wrote a quick howto which explains the translation system. It is pretty easy since danimo simplified it with a nifty template :)

Quickies: classmapper, tb

api.kde.org got an overhaul, the redirect of the old class mapper does not work yet, so just edit your web shortcuts and change the one for 'kde:' to point to

• http://api.kde.org/classmapper.php?class=\{@}
• appending &version=3.5 will search in KDE3.5
  

Thanks to Bram, we have a new article called How to create useful crash reports in our tb. It is mainly aimed at users who fill in bug reports in KDE's bug tracking system.

svn up qt-copy...

...and only 1 hour, 35 minutes later it was finished! Enough said.
Update (disambiguation): svn via https took the time, not the compiling itself :-)

KDE@CeBIT: first two days

Carsten was already faster and blogged about day 3@CeBIT - so it's time to talk about the first two days :)
The first two days we had a rather small booth compared to other projects in the LinuxPark (Hall 5): Placed in the corner next to the Debian booth (see photo). However, we managed to attract many interested eyes, and that's after all what's important (see photo).
The CeBIT is very much a business event: many people are wearing suits which is not really surprising as the audience is of course different to for example the LinuxTag. As such they have another background: Sometimes they never even saw KDE. That's good as we could show step by step the power of KDE: the desktop itself (kicker, K-button, desktop), applications like KMail users usually need or Amarok with iPod support.
Sometimes the questions were more detailed, amongst others -- of course -- What will KDE4 look like? This one is very important and we tried to promote the difference between KDE4 and KDE4.0, the very first KDE4 release. In short, KDE4.0 is the first release in the whole KDE4 lifetime. As such will ship new technologies and cleaned up APIs. Many work went into the core of KDE which is not even visible to the user. When KDE4.0 is released applications will first have to use it. It does not make *plop* and we have a full blown KDE4 which can be compared to the thousands of applications available for KDE3.5. Even the KDE4 components itself (like plasma) probably will not contain all the features and be perfect right from the start.
This is even good to some degree: It is perfectly fine if plasma is basically the same as what we know from the KDE3.5 workspace - it's a well and long tested behaviour after all. I think we did a good job with regard to issues like this and the interested parties understood that. We demonstrated KDE4 versions of Kate, Dolphin, KRunner and KSysGuard including the new Oxygen icon theme and the general feedback was positive :)
Besides that, we gave lots of KDE-T-shirts, pins and bags for free (iff they made a small donation). I'm sure I forgot something, but it's a way too late now and I have to be at the decibel hackathon in some hours again *tired* :)

Quickies: D-Bus, TechBase

• DBUS D-Bus
• techbase.kde.org finally has a name
• KDE contributors with an svn account are in the group KDEDevelopers, they additionally have the right to delete pages in techbase... if you are not in this group but have a svn account please let us know (#kde-www)
  
• ...todo: they also should be able to protect pages so that they are only editable for users in the KDEDevelopers group
• techbase uses subpages - please avoid adding toplevel pages :)
  

Developer Wiki Structure

The last friday we had 20 people on IRC in #kde-www, that is a lot compared to the 2-5 people usually sticking around there. Some of those 20 are quite active in the techbase wiki so that we have a constant flow of commits. However, there is still a lot of work to do: Migrating tutorials, architecture pages, and more. As you probably know MediaWiki is usually a flat wiki, that is all pages are usually placed in the top. For instance, this is how Wikipedia works. On KDE's techbase wiki we wanted to have a structure even in the URL if possible. It turned out we were lucky because MediaWiki has a features called sub-pages. In short, a sub-page is something like a parent-child relation (like a sub-folder), and the benefits for us are

• they automatically provide us with a hierarchy which is reflected in the URL itself
• automatically generated backlinks provide easy navigation

For further information, read the page about our wiki structure.