Next Previous Table of Contents
The KDE libraries, in conjunction with the Qt library, are providing developers a complete framework for application design. As KDE is targeted towards Unix Operating Systems running the graphical X11 System, you would think you would have to understand Unix and X11 - but as the libraries are already encapsulating the complex graphics subsystem, you don't have to know about that in most cases. If you're already familiar with Qt, KDE won't make too much difference in regards of using classes and widgets.
Beginners, on the other hand, have a lot of problems in the sections of
The following will help you to understand, where you will generally find classes used in KDE applications, including the according replacements of Qt classes for those developers that are familiar with Qt, but didn't make use of KDE libraries. These will be the application objects, their behavior and creation.You will learn about:
QWidget that all GUI components inheritMore information about KDE applications can be found in the following sections:
For information about Qt application design, see the Qt online reference documentation.
Generally, a KDE application has to be started by creating an instance (and only one!) of the class KApplication, which is
provided by the kdecore library. The class KApplication is derived from the according Qt class QApplication.
What happens exactly is that QApplication manages the application event queue, which means it processes events from the underlying
window system to its child objects, such as mouse movements or keyboard events. This is also the reason, why only one instance of
KApplication can be declared and why this has to be the first thing the main() function executes.
The KApplication class extends the Qt class in terms of providing additional functionality for a unique-looking application that
integrates into other desktop components and can therefore be influenced in its behavior by control applications (in KDE generally
collected in the KDE Control Center) such as keyboard accelerator configuration and GUI style.
Corresponding to the Qt class, the KApplication class provides a static function to access the application object within the
application, KApplication::getKApplication(). This solves the problem to pass the pointer to the application object. Further, the
include file kapp.h provides a macro that can be used instead of the static function, kapp. Whenever you need to access the
application object, use this macro.
In KDE 2, the application object can be retrieved with KApplication::kApplication().
The KApplication object itself provides a set of instances that are commonly used in KDE applications and lets the programmer
access them by functions. You will make extensive use of them as they avoid creating own instances. The following objects are
provided by their purpose:
a configuration object that is used to read and store configuration settings in a resource file. Use the
according methods of KConfigBase to read and write values. The configuration object is retrieved by
kapp->getConfig()
For KDE 2 use KGlobal::config() to retrieve the config object
, the session managment
configuration by kapp->getSessionConfig()
an object that loads icons into QPixmaps by using the KDE File System. This takes away the need to
search for any pixmap on the file system completely as only the filename has to be entered. Use the macro Icon("icon.xpm") to load
an icon easily. The iconloader instance can be addressed by kapp->getIconLoader()
KDE 2 uses KGlobal::iconLoader()
to access the icon loader instance
an object that returns the actual localization settings. This makes applications appear in the language on the
desktop chosen by the user globally. Use the macro klocale to access the application locale object. The klocale instance can be
addressed by using kapp->getLocale() (as the macro klocale does already)
Again, KDE 2 changes this with a static method
of KGlobal::locale().
the charset object currently set globally by the user. This translates key events to the correctly set
charset. Retrieve the charsets instance with kapp->getCharsets().
Replaced by KGlobal::charsets() in KDE2.
Furthermore, the KApplication class provides you with the needed methods to access files according to the KDE File System Standard. This will prevent you from problems that will always occur when hard-coding any directories into the code (see The KDevelop Programming Handbook for information about the KDE-FSS). The class also provides the needed access for the application icon and mini icon, current KDE fonts and session management support.
To use the clipboard, the according QApplication class already provides a clipboard object, QApplication::clipboard(), which
can be used to exchange text and image data between applications (see QClipboard).
Internationalization is another keyword for KDE applications. This is supported by the KLocale object already mentioned above and
is always used with the macro i18n() of kapp.h.
It just shortens the call of the KApplication pointer to the KLocale pointer and is read by gettext to extract all macro-embraced strings into an application message file that then can be translated.
At least, the KApplication already constructs a help menu that can be inserted into a menu bar the application may contain with a
predefined (can be turned on/off) KDE hint dialog and your application's about dialog.
The following advice should be taken into account when dealing with the KApplication class:
KApplication object at the beginning of the main() functionexec() at the end of the main() functionquit() slot function.Using KApplication, you are able to catch the following event signals:
As the widgets of your application will receive these signals, they will normally update themselves. The important signals for you will
be in most cases saveYourself() and shutDown() (whereby KTMainWindow already catches saveYourself() to call
KTMainWindow::saveData()).
You will be able to communicate with the KWM window manager as well by the according static methods of kwm.h.
An application usually wants to be able to process command line options. Those are entered by the user if he started the application from
a console or from within a kdelnk file. Command line options are very often used to start an application with a certain file.
This also enables filemanagers to call your application properly and use the mime-type mechanism included in KDE.
To be able to process command line options, the main() function should be constructed with the declaration
int main(int argc(), const char* argv[])
Here, argc() is the number of commandline options and the array argv[] actually contains the commandline option's texts.
As the QApplication constructor is executed before the KApplication, it is sufficient to know what is processed by possible
options first. The already read options are automatically removed from the array and cannot be read after the KApplication
instance is declared:
(taken from the Qt 1.42 online reference of QApplication)
Then, the KApplication processes commands whose values can be set within a .kdelnk file. Usually, those link files contain
internationalized versions for the application description and the application name as well as some other values such as the icon and
miniicon name. The commandline options to use these values are:
foo %i %m -caption \"%c\"
This will start the application with the value -icon something.xpm for %i and -miniicon for %m. The application caption can be set with
the -caption value %c. The class KApplication also provides the according methods who return the values for these commandline
arguments.
Now, when it comes to your own processing of commandlines, you can either access them directly after the application object is declared
to exclude any of the above values in the main() function. Within the application itself (e.g. the mainwindow class),
QApplication provides the methods argc() and argv() to process any other options given at the commandline. These can be
accessed by the argument number, whereby the argument kapp->argv()[0] is the application name; any other following arguments can
be processed with kapp->argv()[number].
KDE 2 has an additional class, KCmdLineArgs, to parse additional
command-line parameters, which is already used by KDevelop´s KDE 2 frameworks.
KApplication class uses different methods to change the application's style, fonts and colors by X11 Atoms which
call all open KDE applications to change their values recursively throughout all widgets. This is done automatically when the user
changes values through using the KDE control center which causes these X11 events. The method x11eventFilter() emits the
according signals to change all values. As far as I know of, the only value not changed by KDE 1.x is the double click interval, which
is set to 400 ms by default in QApplication. Changes on this can be made using QApplication::setDoubleClickInterval().
By "Other Application Classes" we would describe any replacements of the KApplication class. The KDE library kdeui offers two
more classes that inherit KApplication for more specific use in KDE applications. Those are the class KControlApplication and
KWMModuleApplication.
The KControlApplication is a class for specific applications that are intended to serve as setup modules. By providing a
tab dialog, control modules can easily be created. The differences to KApplication are:
-init as commandline option to call the method init(). This one has to be overwritten to initialize the dialog
settings.KApplication way with setTitle()To overwrite the virtual methods like init(), you have to derive an application specific KControlApplication class from
KControlApplication. The class is generally used for control applications such as used in the KDE as separate programs.
KWMModuleApplication is another class that inherits KApplication for a certain purpose: the class provides methods that allow
interaction with the window manager. An example for a KWMModuleApplication is the kpager, who uses the signals that the
window manager sends out to manage the windows with the static methods of KWM.
To create a KWMModuleApplication, you first have to create your application instance and then call the method connectToKWM()
Another issue to general KDE application design is the use of kpanel to display your running application symbolized. KDE users are
probably familiar with the display settings symbol left of the clock in kpanel.
The way it runs is rather simple: You have to provide a widget that is the docked widget in the panel; therefore has to be a top-level window by calling the constructor with 0 as parent. Include the kwm.h header file and call
KWM::setDockWindow(mywidget->winID());
Mind that for undocking hiding the widget is not enough, you have to call destroy() (see QWidget for destroy() and
create()).
As stated above, the first object to create for a KDE application is one instance of KApplication. Indeed, it doesn't provide any
widgets (visible user interfaces) except the about dialog similar to the QApplication class as a popup menu, but that isn't seen
anywhere. Therefore, any application needs a top-widget to make itself visible.
When it comes to the visible parts, the programmer generally is free to choose which widget he wants to derive from or use directly as
his main window. It can be a simple QLabel as well as the advanced KTMainWindow that supplies all needed objects for a usual
desktop application.
Generally it can be said that you probably would like to use ready components that are specialized. KDE supports this with the class
KTMainWindow as a pendant to the Qt class QMainWindow. Before describing the general guideline, we have a look at the
exceptional: using any other widget.
When using QApplication as the base application class, you would first create the application instance, then create the main
widget. Now, it is safe to register the widget as the top widget with the method setMainWidget(), because the user can use the
close button of the window to exit the window. He expects the application to be terminated, if the last window is closed, but to do so,
you have to call the QApplication slot quit(). You could do this in a derived class by a re-implementation of
QWidget::closeEvent(), but with the method setMainWidget() this is already done. Now, in any case of using widgets with
KApplication, things are almost the same with the difference that the according method of KDE is setTopWidget().
The only exception is when using the class KTMainWindow which automatically does this in its constructor (if there is no other
topwidget).
Another way would be to set no window explicitely as a top widget or main widget at all when using several top-level widgets. As the
application object still has to terminate with quit(), you can as well use a connect() to call it automatically if the last
application window is closed (using QApplication's lastWindowClosed() signal):
QObject::connect(kapp, SIGNAL(lastWindowClosed()), kapp, SLOT(quit()));
As usual desktop applications provide a complete user interface following a common design rule for GUI programs, KDE provides a class
that already is capable of all needed functions that an application may make use of, KTMainWindow, which is located in the
kdeui library. It is strongly connected to KApplication and therefore very easy to use. The class provides:
The elements of the Widget themselves are already managed by KTMainWindow's geometry implementation, therefore you usually don't
have to take care of that to re-implement an application specific instance for your program.
Next Previous Table of Contents