A KDE4 template: to get you started in KDE4 development

September 2006
Anne-Marie Mahfouf

This page explains you how to get started in KDE4 development by giving you a small template which you can use as a start.

Setting up KDE4 on your system

You need to create a new user that you will use only for KDE4 development.
All this procedure is nicely explained on http://techbase.kde.org/Getting_Started/Build/KDE4. Be sure to first get the latest CMake version. Follow exactly this tutorial and get at least qt-copy and kdelibs. For kdebase, kdepimlibs is needed.

Each time you will work on your kde4 project, you will have to log in Konsole as your KDE4 user with (I suppose kdedev is your KDE4 user):

su - kdedev

You also will need those 2 lines each time you will run the template or your project (the first one is needed once only):

eval `dbus-launch --auto-syntax`
DISPLAY=:0 <your-app-name>

Getting the template

Get the template as your KDE4 user by issuying in Konsole or by downloading it here: kapp4.tar.gz

wget
http://women.kde.org/articles/tutorials/kde4_template/kapp4.tar.gz

then unpack it

tar zxvf kapp4.tar.gz

cd in the template and create a build directory:

cd kapp4
mkdir build

You then generate Makefiles with CMake, assuming cmake is in your PATH (please note that the use of the KDEDIR variable is not compulsory, it is used for convenience):

cd build
cmake -DCMAKE_INSTALL_PREFIX=$KDEDIR ..

The end of the output should be like that:

-- Configuring done
-- Generating done
-- Build files have been written to: /home/kde4/kapp4/build

Then you use the make command to build your project and install it:

make
make install

You run it with:

eval `dbus-launch --auto-syntax`
DISPLAY=:0 kapp4

and you should get the following: kapp4

Explaining the template

You have 2 classes in the template, the KApp4 one and the KApp4View one. KApp4 is essentially to implement actions while KApp4View inherits from an .ui file to display the GUI of the program.

It is interesting for you to read this Qt doc page about using a .ui file in your project. It explains three different approaches and it is very useful as .ui files should never be hardcoded in another file (like copy-paste code from designer). It's way cleaner to use designer to build your GUI whenever possible and to use one of those 3 approaches to inherit.

Here the main widget on the form is a QLabel. If you are a newcomer in Qt/KDE development, I invite you te read the API doc for the widget/class you will use. This will give you some examples and maybe you'll find some methods you did not think existed which will do the job for you. A nice tip is to type:

qt:Qt_class_name
kde:KDE_class_name

in Konqueror and the page will be displayed (provided you are connected to the internet and you did not change these default shortcuts).

Moving on to your own project

So, how to get your own project from the template? First thing is to find a name for your project (I suggest using Google to see if the name you have in mind is not copyrighted). When you have a good name, change all KApp4 for your project name (usually we capitalize the first letter or the first 2 letters (KWord, Amarok,...). Change the filename as well. Remember to never use special characters in filenames and to always save your files as UTF-8.
Then change all copyright names and in the main.cpp, change the relevant strings.
Then don't forget to change the CMakelists.txt file which will allow CMake to generate Makefiles. Have a close look at it, it is pretty straightforward! You probably have a mockup for your program. Check what new classes you want to create. Don't be afraid to add classes. Change the .ui file according to your GUI mockup. And you can create subdirs for icons, data or libs. Don't forget to write the API doc as long as you code and even start early the user manual in docbook!

kdelibs will evolve and you might see warnings when building your projects. You might also see errors. Always look at the API doc for the class and try to fix it yourself. If you are stuck, ask on IRC in #kde4-devel to enquire what new method replaces the deprecated one.

Another very useful tool is http://lxr.kde.org which allows you to navigate through existing code for one class. For example, type KNewStuff in the identifier box and all KDE lines of code containing this class will be displayed. You'll be then able to look for implementation of methods you don't fully understand.

If your program is good enough to be in KDE repository: you will start by importing it in a playground module. Do a 'make clean' before importing it as it should contain only code files and no files resulting from the built. Be sure to amend the CMakeLists.txt as now your project belongs to a module and is not on its own. Look at other programs in the same module to see what you need to remove. Try to compile several times in the same conditions of the import. After the import, get the whole module in a new fresh location and build it to be sure you did not forget to commit files, which is the most common error!

 

---

Last update: 2007-04-14

[ Edit ]