The KDE Library Reference Guide: Classes of KDE Applications

Next Previous Table of Contents

### 3. Classes of KDE Applications

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

- Application design with GUI components
- Application parts
- Widget construction
- Inter-widget communication (Signals and slots)

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:

- the most needed objects of a KDE application
- the difference between your code and the application framework
- KDE application classes that encapsulate the window manager communication
- the class `QWidget` that all GUI components inherit
- graphical objects
- the system clipboard

More information about KDE applications can be found in the following sections:

- The KDevelop Programming Handbook
- KDE Application Tutorials Handbook

For information about Qt application design, see the Qt online reference documentation.

### 3.1 The Application Instance

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:

KConfig

  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()`

KIconLoader

  an object that loads icons into `QPixmap`s 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

KLocale

  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()`.

KCharsets

  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:

- create the `KApplication` object at the beginning of the `main()` function
- execute the application with `exec()` at the end of the `main()` function
- terminate the application with calling the `quit()` slot function.

Using `KApplication`, you are able to catch the following event signals:

- kdisplayPaletteChanged()
- kdisplayStyleChanged()
- kdisplayFontChanged()
- appearanceChanged()
- saveYourself()
- shutDown()

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`.

### 3.2 Commandline Argument Processing

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`)

- -nograb, tells Qt to never grab the mouse or the keyboard. (If you are running your program in a debugger, this option is automatically enabled).
- -sync (only under X11), switches to synchronous mode for debugging.
- -display display, sets the X display (default is $DISPLAY).
- -geometry geometry, sets the client geometry of the main widget.
- -fn or -font font, defines the application font.
- -bg or -background color, sets the default background color and an application palette (light and dark shades are calculated).
- -fg or -foreground color, sets the default foreground color.
- -name name, sets the application name.
- -title title, sets the application title (caption).
- -style= style, sets the application GUI style. Possible values are motif and windows. By default, the global KDE style setting is used.
- -visual TrueColor, forces the application to use a TrueColor visual on an 8-bit display.
- -ncols count, limits the number of colors allocated in the color cube on a 8-bit display, if the application is using the QApplication::ManyColor color specification. If count is 216 then a 6x6x6 color cube is used (ie. 6 levels of red, 6 of green, and 6 of blue); for 108, a 3x3x3, and for other values, a cube approximately proportional to a 2x3x1 cube is used.
- -cmap causes the application to install a private color map on an 8-bit display.

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.

#### Comment

The `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()`.

### 3.3 Other Application Classes

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`.

#### KControlApplication

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:

- uses `-init` as commandline option to call the method `init()`. This one has to be overwritten to initialize the dialog settings.
- the caption of the dialog has to be set independently of the `KApplication` way with `setTitle()`
- provides a complete widget frameset already where your control widgets have to be inserted.

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

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()`

#### Docking of Windows

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()`).

### 3.4 The Main Window

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.

#### General Rules

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()));

#### Using KTMainWindow

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:

- session management support
- a main widget
- a menu bar
- as many toolbars as your application may require
- a statusbar

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