2.3. KDE Application Structure

2.3.1. KApplication

KApplication receives messages from X, the underlying windowing system, and distributes them to the widgets in your application. It gives access to fonts, desktop style options, and processes some KDE-standard command line options. It also provides access to the session-management features of KWin, although you generally do not need to use these because KTMainWindow offers a higher-level session management API.

2.3.2. KTMainWindow

Listings 2.3–2.5 present a simple KDE application: KSimpleApp.

   1 
   2  1: #include <ktmainwindow.h>
   3  2:
   4  3: class QLabel;
   5  4:
   6  5: /**
   7  6:  * This is a simple KDE application.
   8  7:  *
   9  8:  * @author David Sweet <dsweet@kde.org>
  10  9:  **/
  11 10: class KSimpleApp : public KTMainWindow
  12 11: {
  13 12:  Q_OBJECT
  14 13:
  15 14:  public:
  16 15:   /**
  17 16:    * Create the widget.
  18 17:    **/
  19 18:   KSimpleApp (const char *name=0);
  20 19:
  21 20:   public slots:
  22 21:     /**
  23 22:      * Reposition the text in the context area.  The user will
  24 23:      *  cycle through:  left, center, and right.
  25 24:      **/
  26 25:     void slotRepositionText();
  27 26:
  28 27:  private:
  29 28:   QLabel *text;
  30 29:   int alignment [3], indexalignment;
  31 30: };

The file ksimpleapp.h contains the class declaration for the class KSimpleApp. This class is the equivalent of KMyMainWindow in Figure 2.3 and thus is derived from KTMainWindow.

The KSimpleApp widget shows how to use KTMainWindow to create a document-centric application. A document-centric application contains a menubar, a toolbar, a statusbar, and a content area. These elements can be seen in Figure 2.4, which shows a screen shot of KWrite, a text-editing utility included with KDE. KWrite is an example of a document-centric application.

The content area in this case contains the document being edited. In general, the content area contains a view of the document being worked on, but the concept of "document" is extended to include images, Web pages, scientific plots, file-manager views, or whatever data the application deals with.

The menubar, toolbar, and statusbar widgets are created, positioned, and deleted by KTMainWindow. The menubar contains the familiar File, Edit, and other pull-down menu headings. The toolbar shows icon buttons that provide quick access to frequently used menu entries. The statusbar displays short messages and state indicators that let the user know what tasks the application is performing and that give extended information about UI objects or document elements.

KTMainWindow also implements basic session management. The session manager, as implemented by KWin saves the state of the desktop when the user logs out, and it re-creates it at the next login. This means that each application that was running at logout should be restarted in a window that has the same position and size and that contains the document that was being edited. KTMainWindow takes care of positioning and sizing your application's window when kwm restores it. You will see in Chapter 7, "Further KDE Compliance," how to save additional information such as the contents of the document that was being edited when the user logged out.

2.3.3. A Typical main() Function

Listing 2.4 contains a main() function that is typical for a KDE application. It is short because the real work is done in the class you derive from KTMainWindow (KSimpleApp in this case). It creates an instance of KApplication, an instance of KSimpleApp, and it passes control to the instance KApplication.

   1 
   2  1: #include <kapp.h>
   3  2:
   4  3: #include "ksimpleapp.h"
   5  4:
   6  5: int
   7  6: main (int argc, char *argv[])
   8  7: {
   9  8:   KApplication kapplication (argc, argv, "ksimpleapp");
  10  9:
  11 10:   if (kapplication.isRestored())
  12 11:       RESTORE(KSimpleApp)
  13 12:   else
  14 13:   {
  15 14:     KSimpleApp *ksimpleapp = new KSimpleApp;
  16 15:     ksimpleapp->show();
  17 16:   }
  18 17:
  19 18:   return kapplication.exec();
  20 19: }

The KApplication constructor needs argc and argv so that it can process command-line options. Table 2.1 is a list of options that are processed by all KDE applications and removed from argc/argv after the constructor is called:

You may process the remaining command-line options however you want.

The last option to the KApplication constructor is the name of the application. This name serves as the default caption as well as the name of the icon and of the miniicon. In this case, as is generally the case, no icon or miniicon name was specified in the command line. This causes KApplication to look for the default icon file for this application, ksimpleapp.png, (.png is used to denote files Portable Network Graphics (PNG) format) in the standard icon and miniicon directories. Of course, in this example you have not created an icon file for the KSimpleApp, so the file will not be found and a generic icon will be used instead. (The standard locations of icons and other resources are discussed in Chapter 16.)

If your application has been started by the session manager, KApplication::isRestored(), as used on line 9 of Listing 2.4, will return true. In this case, use the RESTORE macro, defined in ktmainwindow.h, to create KSimpleApp. Creating KSimpleApp in this way will place the window, the menubar and the toolbars where the user left them at logout. (Note that the menubar and toolbars can be positioned by the user. Try right-clicking the textured vertical bar to the left of the menubar. You are offered the following options for positioning the menubar: Left, Top, Right, Bottom, Float, and Flat.)

If your application was started normally—that is, by the user and not by the session manager— you create a new instance of KSimpleApp and make it visible with

   1 
   2 KSimpleApp *ksimpleapp = new KSimpleApp;
   3 ksimpleapp->show();
   4 

The show() method does not actually show the window. The window will be shown after you enter the event loop with

   1 
   2 kapplication->exec();
   3 

In this method, all the events received from X, such as window move, resize, paint events, mouse-move events, button-press events, and keypress events will be dispatched to the appropriate KDE/Qt widget classes. This loop exits when the last window is closed. At this time, your program should not expect to have a user interface and should terminate.