Chapter 11. Alternative Application Types

by David Sweet

In this chapter

Not every application fits neatly into the document-centric model described in Chapter 2, "A Simple KDE Application", and Chapter 5, "KDE User Interface Compliance." For example, short-lived, single-task applications (such as KPPP or KFind) use a dialog box for their main window. For some applications it only makes sense for one instance of an application to be running (for example, Kicker, KPPP). Still other applications, called applets, run in a small space on the panel and usually serve as status indicators or perform limited functions.

11.1. Dialog-Based Applications

Short-lived, single-task applications can be implemented in dialog boxes. Think of KFind, for example. This application searches for files on your local hard disk and then, typically, the user exits the application. A find operation is commonly included in a dialog box in document- centric applications, and so the appearance of a system-level find operation in a dialog box is not unfamiliar to the user.

Other utilities also use dialog boxes: KFontManager and KPPP. The motivation for writing KFontManager into a dialog is the same as that for KFind: It performs a common application function (usually implemented in a dialog box), but at the system level. KPPP is appropriately placed in a dialog box because the user interaction (in normal use) is limited. The user chooses only which connection to try and, when connected, wants to get back to work.

11.1.1. Creating the Dialog-Based Application

Creating a dialog-based application is different from creating a document-centric application, but not more difficult. No standard "KdialogApplication" base class exists from which all such applications are derived (as KTMainWindow analogously provides a common base for all document-centric applications), but there are generally fewer UI elements to worry about, and thus, such a base class is not necessary. In fact, in Listings 11.1 and 11.2, you see how to derive from KDialogBase a base class dialog box and this serves you well.

Listings 11.1–11.3 show how to construct a dialog-based application.

Example 11.1. kdialogapp.h: Class Declaration for KDialogApp, a Dialog-Based Application

   2  1: #ifndef __KDIALOG_H__
   3  2: #define __KDIALOG_H__
   4  3:
   5  4: #include <kdialogbase.h>
   6  5:
   7  6: class KDialogApp : public KDialogBase
   8  7: {
   9  8:  public:
  10  9:   KDialogApp (QWidget *parent = 0, const char *name = 0);
  11 10:
  12 11:  protected slots:
  13 12:     /**
  14 13:      * The Start button was pressed.
  15 14:      **/
  16 15:   void slotUser2(void);
  17 16:     /**
  18 17:      * The Quit button was pressed.
  19 18:      **/
  20 19:   void slotUser1(void);
  21 20:
  22 21: };
  23 22:
  24 23: #endif

It is necessary for the main application widget to be (ultimately) derived from QDialog because QDialog provides its own event loop for processing window system events. KDialogApp is derived from KDialogBase for simplicity, but KDialog or QDialog would work as well. KDialogBase offers virtual methods that can be overloaded (here, slotUser1(), line 19 and slotUser2(), line 15) to provide responses to button clicks.

Example 11.2. kdialogapp.cpp: Class Definition for KDialogApp

   2  1: #include <qlabel.h>
   3  2:
   4  3: #include <kapp.h>
   5  4: #include <kmessagebox.h>
   6  5:
   7  6: #include "kdialogapp.h"
   8  7:
   9  8: KDialogApp::KDialogApp (QWidget *parent, const char *name) :
  10  9:   KDialogBase (parent, name, true, "kdialogapp", User1 | User2,
  11 10:            User2, true, "&Quit", "&Start")
  12 11: {
  13 12:   QLabel *qlabel = new QLabel ("Content area.", this);
  14 13:   setMainWidget (qlabel);
  15 14: }
  16 15:
  17 16: void
  18 17: KDialogApp::slotUser2(void)
  19 18: {
  20 19:   KMessageBox::sorry (this, "No functions implemented!");
  21 20: }
  22 21:
  23 22: void
  24 23: KDialogApp::slotUser1(void)
  25 24: {
  26 25:   close();
  27 26: }

KDialogBase, as it is used here, creates a dialog box that displays a custom widget with two control buttons below it. The arguments—beyond the first two—passed to the KDialogBase constructor (line 9) configure the dialog (see Chapter 8, "Using Dialog Boxes", for more information about KDialogBase). Arguments three through nine do the following:

  • true—Create a modal dialog. Passing true lets you make use of QDialog's (from which KDialogBase is derived) local event loop.

  • User1 [verbar] User2—Create two user-defined buttons. The virtual methods slotUser1() and slotUser2() will be called when the buttons are clicked. The buttons are displayed right to left (see Figure 11.1).

  • User2—Make the button User2 the default button. If the user presses Enter, the default button is clicked.

  • true—Draw a horizontal line between the content area and the control buttons.

  • Quit—The text for button User1.

  • Start—The text for button User2.

Figure 11.1. Screenshot of KDialogApp.

You place a label in the content area in lines 12 and 13. Note that the setMainWidget() method is a member of KDialogBase. You should place your dialog application's main widget in here.

Example 11.3. main.cpp: The main() Function Needed to Start KDialogApp

   2  1: #include <kapp.h>
   3  2:
   4  3: #include "kdialogapp.h"
   5  4:
   6  5: void main (int argc, char *argv[])
   7  6: {
   8  7:   KApplication *kapplication = new KApplication (argc, argv, "kdialogapp");
   9  8:
  10  9:   KDialogApp * kdialogapp = new KDialogApp;
  11 10:   kdialogapp->exec();
  12 11: }

You need to create a KApplication object to provide initialization of the Qt toolkit, but you do not need to make any calls to KApplication methods. The event loop provided by QDialog is started with

   2 kdialogapp->exec();

The program exits after this call completes. kdialogapp->exec() exits when the dialog is finished, which happens when the user closes the window, presses the Quit button, or presses Esc.