11.3. Panel Applets

Panel applets are small applications with minimal user interfaces that run in the KDE panel, Kicker. They generally indicate the status of some part of the system, such as CPU load, network activity, the system time, or provide easy access to functions that are not directly related to the work being performed by the user, such as a desktop pager, a CD player controller, or an instant-messaging client. For creating your own panel applet, the KDE libraries provide the class KPanelApplet. It is derived from QWidget (and DCOPObject) and takes the place of KTMainWindow in the design of your application. Listing 11.7 shows our usual main() function modified to create an applet.

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

This applet, the subclass of KPanelApplet, is called KWeather. KWeather is a mock-up of an applet that displays the outside weather, say, to a graduate student trapped in a windowless office. A complete implementation of KWeather might query a weather service via HTTP (using KIONetAccess) to determine the actual weather. In this implementation the weather is always rainy and 48°F so that the graduate student won't feel that he is missing out on a nice day.

Listing 11.8 shows how the KWeather class is implemented.

   1 
   2  1: #include <stdio.h>
   3  2:
   4  3: #include <qlabel.h>
   5  4:
   6  5: #include <kiconloader.h>
   7  6: #include <kpopupmenu.h>
   8  7:
   9  8: #include "kweather.h"
  10  9:
  11 10: KWeather::KWeather (QWidget* parent, const char* name)
  12 11:     : KPanelApplet (parent, name)
  13 12: {
  14 13:   setPalette(QPalette(Qt::gray));
  15 14:   QLabel *qlabel = new QLabel ("Rainy\n  48F", this);
  16 15:   qlabel->setAlignment (Qt::AlignVCenter);
  17 16:   setMinimumSize (qlabel->sizeHint());
  18 17:
  19 18:   setActions (Preferences);
  20 19:
  21 20:   dock("kweather");
  22 21: }
  23 22:
  24 23: void
  25 24: KWeather::preferences()
  26 25: {
  27 26:   printf ("Here we let the user configure the panel applet.\n");
  28 27: }
  29 

In the constructor, you create your content area, a QLabel. Be sure when you design your content area that it will fit comfortably in the small area given to it by Kicker, the KDE panel. The content area here consists of two lines of text on a colored background. It fits nicely. Generally, a well-designed icon can convey more information in the small space—or at least convey it in a more appealing way.

The call on line 16 to setMinimumSize() keeps Kicker from shrinking the widget so that the text is too small to read. Kicker is trying to minimize usage of the valuable panel space, so be sure to set a minimum size for your widget.

KPanelApplet provides a context menu (a pop-up menu that appears when the user clicks the applet with the right mouse button, also known as an "RMB menu"). This menu provides the minimum of choices to the user: Move and Remove, which allow the user to, respectively, move the applet along the panel or remove from the panel, thus exiting the applet.You may add other menu entries—About, Help, and Preferences—using the method setActions(), as on line 18. The enum constants About, Help and Preferences may be combined with the bitwis-or operator (i.e., &) and passed to setActions() to add any combination of these menu entries. To respond to the user's selection of one of these menu entries, you should reimplement the corresponding virtual method: about(), help(), or preferences(). The latter is reimplemented, as an example, on lines 23-27.

The final bit of code needed for KWeather is given in Listing 11.9.

   1 
   2  1: #ifndef __KWEATHER_H__
   3  2: #define __KWEATHER_H__
   4  3:
   5  4: #include <kapplet.h>
   6  5:
   7  6: class KWeather : public KApplet
   8  7: {
   9  8:
  10  9: public:
  11 10:   KWeather (QWidget * parent=0, const char *name=0);
  12 11:
  13 12:  protected:
  14 13:   void mousePressEvent (QMouseEvent *);
  15 14:
  16 15: };
  17 16:
  18 17: #endif
  19