You are missing an option in your favorite KDE application? You want to change the default behavior? Then this tutorial could be helpful for you.

I often read users complaining about less possibilities of configuration in KDE 4. This tutorial guides the user to find features in the source code, which are already implemented but in a static way. In this tutorial we will add a background image to the dolphin places view.



I am using the current KDE 4.1 branch, because most of the development packages can be installed with the package manager of your distribution. And you can of course install the modified application to replace the standard implementation. If you want to write a patch you should do this against the trunk version of KDE and contact the maintainer of the application.

[size=large]Preparation[/size]
So first we start by downloading the stable dolphin branch from SVN:

Code: Select all

svn co svn://anonsvn.kde.org/home/kde/branches/KDE/4.1/kdebase/apps/


In the case of dolphin we have to download the whole apps directory because dolphin is depending on some files, which are not shipped with my distribution.

Now we create a build directory, where we build dolphin, so we do not have to change anything in the source directory (apps), so it stays clean. In our build directory, we first run cmake to create all the Makefiles and to check whether we have installed all dependencies.

Code: Select all

mkdir apps-build
cd apps-build
cmake ../apps


Since we only want to build dolphin, we change to that directory and run make there.

Code: Select all

cd dolphin
make


If nothing fails, you can start dolphin by typing:

Code: Select all

src/dolphin


You can install it by running:

Code: Select all

sudo make install


[size=large]Hacking[/size]
Go back to the directory where you run subversion to checkout the apps directory. Open the file apps/dolphin/src/dolphinfileplacesview.cpp with your favorite text editor and add the next three lines (taken from http://doc.trolltech.com/4.4/qwidget-qt3.html#setBackgroundPixmap) in the constructor right before the setDropOnPlaceEnabled(true) command:

Code: Select all

QPalette palette;
palette.setBrush(viewport()->backgroundRole(), QBrush(QPixmap("/path/to/picture")));
viewport()->setPalette(palette);


First I set a static picture. Now we want to do it configurable. So first, we add a new Option called PlacesBackgroundImage to the file apps/dolphin/src/dolphin_generalsettings.kcfg. Place the following three lines below the last entry element (Have a look to http://techbase.kde.org/Development/Tutorials/Using_KConfig_XT for more details on KConfig XT):

Code: Select all


  Background image in Places View



Now we replace our code from above in apps/dolphin/src/dolphinfileplacesview.cpp with this more dynamic one. You have to include two header files to access to the settings objects:

Code: Select all

...
#include "dolphinsettings.h"
#include "dolphin_generalsettings.h"
...

QString backgroundImage = DolphinSettings::instance().generalSettings()->placesBackgroundImage().path();
if (!backgroundImage.isNull() && !backgroundImage.isEmpty()) {
    QPalette palette;
    palette.setBrush(viewport()->backgroundRole(), QBrush(QPixmap(backgroundImage)));
    viewport()->setPalette(palette);
}


This code loads the path value from the configation object PlacesBackgroundImage into a QString. If it is not empty and not null it is used to set the background image. In the next step we will add a possibility to change the value of the option in the settings dialog. We need a widget to enter a Url. This is the KUrlRequester. Add a pointer of type KUrlRequester to the file apps/dolphin/src/generalsettingspage.h. You have to forward declarate it after class QCheckBox; and add the pointer after QCheckBox* m_renameInLine;:

Code: Select all

...
class QCheckBox;
class KUrlRequester; // this is a new line
...
QCheckBox* m_renameInLine;
KUrlRequester* m_backgroundImage; // this is a new line
...


After that we have to integrate in to the user widget by adding the following lines to the file apps/dolphin/src/generalsettingspage.cpp:

Code: Select all

...
#include
#include  // this is a new line
...
connect(m_renameInline, SIGNAL(toggled(bool)), this, SIGNAL(changed()));
// here starts the new stuff to integrate the KUrlRequester
KHBox *backgroundImageBox = new KHBox(vBox);
backgroundImageBox->setSpacing(spacing);

new QLabel(i18n("Places Image"), backgroundImageBox);
m_backgroundImage = new KUrlRequester(backgroundImageBox);
connect(m_backgroundImage, SIGNAL(textChanged(const QString&)), this, SIGNAL(changed()));


Now the code to write the settings. Put the next line as last command in the applySettings function in apps/dolphin/src/generalsettingspage.cpp:

Code: Select all

settings->setPlacesBackgroundImage(m_backgroundImage->url());


And the code to load the settings. Put the next line as last command in the loadSettings function in apps/dolphin/src/generalsettingspage.cpp:

Code: Select all

m_backgroundImage->setUrl(settings->placesBackgroundImage());


That's it! Compile dolphin, install it and then run it. Now you can set an image as the background to the places view.

[size=large]Comments[/size]

• Sadly the GeneralSettingsPage is not designed via an UI file. Then it would be more easy and we could use the full power of KConfigXT. Have a look at the URL I wrote some lines ago. KConfigXT can automatically load and write settings from config files.
• With this example you have to restart dolphin to see the effects. It would be more complicated to change this after changing the settings. I tried it with signals emitted from the KConfigSkeleton, but this did not work for me.

You can download the patch at http://informatik.uni-bremen.de/~msoeken/patch.diff.gz

So, now it's your turn. If you have any questions or comments, then please let me know. If you create a patch for yourself, it would be could if you post it as respond to this thread.

Cheers, m.