The KDE Library Reference Guide: Class Categories

Next Previous Table of Contents

### 2. Class Categories

The KDE/Qt C++ class libraries offer easy solutions to extend applications dramatically with a minimum amount of coding on the side of the application programmer. This chapter sorts the classes provided towards their usage by certain categories:

- Baseclass
- Application architecture classes
  - Application objects of KDE
  - Application configuration
  - Main Windows
- User Interface Objects
  - Views
  - Dialogs
  - Control Elements
  - Menus
- General purpose classes
  - Files
  - Data objects
  - Graphics
  - Processes

### 2.1 Baseclass

Most of the KDE/Qt classes have `QObject` as their baseclass in their inheritance hierarchy. `QObject` can be described as a baseclass because it offers the usage of Qt's signal/slot mechanism which allows object interaction within the application and should be used as the baseclass for any self-created classes that are supposed to emit signals or can connect to signals by slots.

### 2.2 Application Architecture Classes

KDE applications usually consist of a set of objects that interact with each other. The programmer has to use the provided classes to create a KDE application either by creating a class instance or by inheritance. A typical application contains:

- One application object of `KApplication`
- One main window class derived from `KTMainWindow`
- A class derived from `QWidget` to create the view area

#### Application objects of KDE

The K Desktop Environment provides functionality that an application can use to integrate into the KDE. This functionality is implemented in the class `KApplication` and should therefore be the baseclass for any application that targets KDE. A KDE application only contains one object of the class `KApplication`. This is created in the application's `main()` function. The `KApplication` object is responsible for providing the basic interfaces and objects towards the desktop and interprets the command-line arguments of an application. As the instance is a non-visible, but the main application object, the following rules have to be watched:

- the application is terminated by `kapp->quit()`.
- the object that is representing the graphical interface has to be set the main widget with `setTopWidget()` (for widgets not inherited by `KTMainWindow`)

The `KApplication` object provides:

- access to the KDE File System
- a session configuration object
- a configuration object
- internationalization by the locale object
- changing of the visible application objects by signals

> KDE 2 accesses the according instances by static methods provided by `KGlobal`.

Dependencies: -lkdecore -lqt

Includes: `#include <kapp.h>`

The `kdeui` library additionally offers two classes that inherit `KApplication` for specialized purposes:

#### KWMModuleApplication

Includes: `#include <kwmmapp.h>`

Dependencies: -lkdeui -lkdecore -lqt

The class KWMModuleApplication is the base class for KDE window-manager modules. It mainly informs a module about all currently managed windows and changes to them (via Qt signals). There are no methods to manipulate windows. These are defined in the class KWM (see kwm.h). An example for using KWMModuleApplication is kcontrol.

#### KControlApplication

Includes: `#include <kcontrol.h>`

Dependencies: -lkdeui -lkdecore -lqt

KControlApplication is the common base for setup applications. It provides a tab dialog and functionality common to most setup programs. The configuration dialogs for the KDE are examples of KControlApplications.

#### KWM

Includes: `#include <kwm.h>`

Dependencies: -lkdeui -lkdecore -lqt

The KWM class provides a set of static methods to interact with the window and session-manager. Therefore, call any member with

KWM::<method()>

depending on the purpose of the desired functionality.

#### Application Configuration

The class `KConfig` provides the usage of a configuration object which can write its entries into configuration files. Dependent of the values to read and write you have to call the methods of the class `KConfigBase`.

The `KApplication` object provides an application configuration object with a resource file by default which is stored in the user's kde-directory as well as the session management file to store information between sessions.

For internationalization, the `KApplication` object uses the class `KLocale` to translate localized entries dependent on the selected language. Instead of using the `klocale->translate()` method, KDE applications should use the `i18n()` macro that contains the string to be translated as the message extraction depends on this macro.

#### Main Windows

As the application's `KApplication` instance is non-visible, it only provides the basic means to create a KDE application. Therefore a KDE application needs to have a main window representing the application towards the user graphically. The main window usually consists of a widget which can be as simple as a pure button up to the complex `KTMainWindow` widget, offering the means to create a full-featured main window with geometry management, session management support, menu bar, toolbars and statusbar.

Generally, every main window has to be set main widget with `KApplication`'s `setTopWidget()` method. An exception is a main window that inherits `KTMainWindow`.

The main window usually takes the responsibility to terminate the application by providing a user interface that is connected to `KApplication::quit()`, easily used by `kapp->quit()`.

Most KDE applications will use `KTMainWindow` to represent the application graphically.

### 2.3 User Interface Objects

This section covers the user interface object the KDE libraries provide. By category, these can be divided by their purpose. A user interface can be:

- a view area widget, representing the data an application is intended to produce and allowing the methods to manipulate the contents.
- dialogs, used to retrieve user input, e.g. a file dialog
- control elements to compose application specific widgets
- menus, providing user interfaces to invoke application commands.

#### Views

View are generally the content area of an application. Therefore it can be the main widget or a part of a main widget that additionally offers a set of functionality such as `KTMainWindow`

The KDE libraries offer a set of ready to use views which can be inherited to advance the desired functionality:

- KTabListBox: offers a multi-column list box where the user can change the rows with drag'n drop.
- KEdit: the base classes for the KEdit application offered with KDE. This could be used instead of QMultiLineEdit.
- KNewPanner: manages two child widgets like QSplitter.

  > Removed in KDE 2. Use QSplitter instead.

- KHTMLView: a HTML-interpreting widget (khtmlw)

For use with `KTMainWindow`, create your view instance and call `setView(QWidget*)` to enable the management by the `KTMainWindow` instance.

Individual views are usually created by inheritance of `QWidget` or any provided widget that comes closest to the desired functionality the view should offer. For widgets that want to offer scrolling facilities, you could inherit from `QScrollView` or create a `QScrollView` instance and set the view widget as the managed area with `addChild()`.

#### Dialogs

Dialogs are a main part of the user interaction wherever the application requires parameters that have to be set by the user. Fortunately, the KDE library already offers a set of dialogs that are ready to use for standard parameters such as fonts and colors. In any case where these types of information is requested by the user, the application should make use of these standard dialogs.

In cases where the given dialogs don't fit the requirements, you have to inherit from `QWidget` or `QDialog` and create your own dialog either directly coded with geometry management or by creating it visually with KDevelop's dialogeditor.

The KDE libraries offer the following dialogs:

- KColorDialog: selects a color value
- KWizard: base dialog class to create wizards
- KEdGotoLine: Go-to-Line dialog for editors
- KEdReplace: Search and replace dialog for editors
- KEdSrch: search dialog for editors
- KFontDialog: font selection dialog
- KIconLoaderDialog: Icon selection dialog
- KKeyDialog: keyboard accelerator configuration dialog
- KMsgBox: message box dialog with up to four configurable buttons
- KFileDialog: (kfile) file dialog to open and save files
- KSpellDlg: (kspell) spell-checking dialog for use with Ispell
- DatePickerDialog: (kab) date selection dialog

Additionally, the Qt library offers:

- QFileDialog
- QMessageBox
- QPrintDialog
- QProgressDialog

> Qt 2.0 introduces a QColorDialog for selecting colors and a QFontDialog for font-selection as well

### 2.4 Control Elements

Control elements are used within visible areas of the application and can be combined together to create a dialog or view. Beyond the control elements that the Qt library provides, KDE offers:

- KButton: active raise-lower button
- KButtonBox: manages buttons
- KColorButton: button displaying a color setting, calls `KColorDialog`
- KIconLoaderButton: button displaying a selected Icon, calls `KIconLoaderDialog`
- KDatePicker: Date selection widget
- KIntegerLine: line edit that only accepts integer values
- KLedLamp: LED lamp
- KLined: line edit
- KNewPanner: panner devider managing two widgets

  > Use `QSplitter` instead, this is already removed in KDE 2.

- KPopupMenu: popup menu with title
- KRestrictedLine: line edit that only accepts certain input
- KSelector: value selector
- KSeparator: standard separator
- KSlider: slider widget
- KTabCtl: tabulator widget

### 2.5 General Purpose Classes

#### Files and Directories

Qt already offers a set of classes to work with files and directories. Those classes are:

- `QDir`
- `QFileInfo`
- `QFile`
- `QFileDialog`

A comparable and extended technology has been introduced by the KDE libraries and have a similar usage like the corresponding classes of Qt. Those are:

- `KDir`
- `KFileInfo`
- `KFileDialog`
- `KFilePreviewDialog`

For loading and saving files, use the class `QFile` which operates with streams. If you want network transparent file access, consider using `KFile`.

#### Data Objects

The Qt library supports data objects by classes that offer handling of lists, arrays, streams, strings and the like. See the Qt documentation for mor information.

#### Graphics

Qt supports a set of graphics formats that can be used for drawings or image programs. The graphics device for painting is `QPainter`.

#### Processes

As applications can have different types of application communication with other programs available on the system such as standard Unix actions, developers can make use of the class `KProcess` to call another application. As the application is running independently from the one that invoked it, you can only receive the current status of the application invoked by `isRunning()`. Also, the invocation can be done with various initialization values. Finally, the process can inform the application whether it has been terminated or ended. See `KProcess` for details.

Next Previous Table of Contents