Das Handbuch zu KSplash

Bevor Ihr Programm seine eigentliche Arbeit beginnt oder bevor z. B. Module und Erweiterungen geladen werden, starten Sie KSplash:

DCOPClient *c = kapp->dcopClient();
QString error;
QCString KSplashName;
int pid = 0;
QStringList args;
args << "--theme=MeinDesign" << "--managed";
if (kapp->startServiceByDesktopName("ksplash", args, &error,
&KSplashName, &pid))
{
  KMessageBox::sorry(0, error, "Unable to invoke KSplash");
  // Some error processing here.
}

Wir gehen in diesem Fall davon aus, dass nur eine Instanz von KSplash gleichzeitig läuft. Andere Fälle sind etwas komplizierter. Lesen Sie dazu bitte die DCOP-Dokumentation.

Bevor Sie irgendwelche Meldungen anzeigen können, müssen Sie die Anzahl der anzuzeigenden Schritte festlegen. Der KDE-Start z. B. benutzt sieben Schritte.

QByteArray data;
    QDataStream arg(data,IO_WriteOnly);
    arg << eineZahl;
    if (!(c->send(KSplashName, "KSplashIface", "setStartupItemCount(int)",
data))
      // Some error processing here.

Immer wenn Sie eine Meldung mit oder ohne Symbol anzeigen möchten, verwenden Sie

arg << QString("symbolName") << QString("programmName") <<
QString("Eine Beschreibung");
    if (!(c->send(KSplashName, "KSplashIface",
"programStarted(QString,QString,QString)", data))
    {
      // Some error processing here.
    }

Jedesmal wenn Sie programStarted aufrufen, wird ein Schritt als abgeschlossen markiert und inkrementiert. Wenn Ihr Programm mit dem Start fertig ist, können Sie den Startbildschirm auf diese Weise wieder ausblenden:

if (!(c->send(KSplashName, "KSplashIface", "startupComplete()", data))
    {
      // Some error processing here.
    }

Das ist alles! Mehr ist nicht nötig, um von KSplashs Möglichkeiten zu profitieren :)

Wir benutzen das KDE application framework, welches sich um den Bau des Moduls und um Plattformunabhängigkeit kümmert, ohne das wir selber etwas dazu tun müssen. Dafür müssen Sie das Paket kdesdk installiert haben. Führen Sie den Befehl kapptemplate aus und erzeugen Sie ein Programm mit dem Namen "2k". Für Sie wird ein Basisordner erzeugt, der allgemeine Dateien wie z. B. AUTHORS etc. enthält. Unser Interesse gilt nun aber erstmal nur dem Unterordner 2k. Wechseln Sie in diesen Ordner und löschen Sie dort alle Dateien. Nun haben wir das benötigte Grundgerüst.

Als nächsten Schritt erzeugen wir eine .desktop-Datei. Wenn diese installiert wird, weiß KSplash, dass Ihr Darstellungsmodul verfügbar ist. Nach den beschriebenen Namenskonventionen aus dem vorigen Kapitel erzeugen Sie nun eine Datei mit dem Namen ksplash2k.desktop. Sie sollte folgenden Inhalt haben:

[Desktop Entry]
Encoding=UTF-8
Type=Service
Comment=KSplash Plugin
Name=KSplash2k
ServiceTypes=KSplash/Plugin
X-KDE-Library=ksplash2k
X-KSplash-Default=true
X-KSplash-PluginName=2k
X-KSplash-ObjectName=Theme2k

Die Einträge Encoding, Type, Comment und ServiceTypes sind für alle Darstellungsmodule gleich. Der Modul- und Bibliotheksname folgen den vorher genannten Namenskonventionen. Der Eintrag X-KSplash-Default kann einen Wahrheitswert enthalten und legt fest, ob das Modul im Kontrollzentrum angezeigt wird. Normalerweise ist der Wert hier true; es gibt nur ganz wenige Ausnahmen.

Nun haben wir die Vorbereitungen abgeschlossen und können mit dem schönen Teil beginnen - dem Erzeugen einer Klasse die das gewünschte Verhalten festlegt. Die Klasse kann im Grunde alles tun, was wir möchten, mit ein paar wenigen Einschränkungen:

Die letzte Anforderung scheint kompliziert zu sein, aber Sie werden später feststellen, dass dies durch nur eine einzige Zeile im Quelltext erledigt werden kann.

Nachdem wir nun diese Bedingungen kennen, lassen Sie uns schauen, wie die Headerdatei theme2k.h aussieht:

#ifndef __THEME2K_H__
#define __THEME2K_H__

#include <qlabel.h>
#include <qwidget.h>

#include <kdialogbase.h>
#include <kpixmap.h>
#include <ksplash/themeengine.h>

class RotWidget;

class Cfg2k: public ThemeEngineConfig
{
  Q_OBJECT
public:
  Cfg2k( KConfig * );
};

class ObjKsTheme;
class Theme2k: public ThemeEngine
{
  Q_OBJECT
public:
  Theme2k( QWidget *, const char *, const QStringList& );

  inline const QString name()
  {
    return( QString("KSplash2k") );
  }
  inline const KDialogBase *config( KConfig *kc )
  {
    return new Cfg2k( kc );
  }
  static QStringList names()
  {
    QStringList Names;
    Names << "KSplash2k";
    Names << "ks2k";
    Names << "2k";
    Names << "2000";
    return( Names );
  };

public slots:
  inline void slotSetText( const QString& s )
  {
    if( mText && mText->text() != s ) mText->setText( s );
  };

private:
  void initUi();
  void readSettings();

  QLabel *mText;
  RotWidget *mRotator;
  QColor mTBgColor, mTFgColor, mRotColor1, mRotColor2, mStatusColor;
  int mRotSpeed;
  QString mWndTitle, mLogoFile;
};

#endif

Nun gut, gehen wir die obige Auflistung durch: Die Klasse Theme2k ist von ThemeEngine abgeleitet und erfüllt die Namenskonvention. Sie enthält die Funktion Theme2k::names() und hat einen Konstruktor mit den benötigten Parametern: Theme2k( QWidget *, const char *, const QStringList& ); und enthält eine einfache Methode Theme2k::slotSetText(). Kümmern Sie sich erstmal nicht um die Klasse RotWidget; sie erzeugt nur ein hübsches Bildschirmelement. Unser Modul ist sehr einfach gehalten und zeigt keine Symbole oder eine Fortschrittsanzeige an. Wenn Sie das möchten, überschreiben Sie die Funktion slotSetPixmap. Ähnliche Funktionen gibt es auch für die Schritte der Fortschrittsanzeige (slotUpdateSteps) und zum Inkrementieren (slotUpdateProgress) des aktuellen Schrittes.

Wir schauen uns nun die wichtigsten Teile der Implementation an. Eine Auflistung des gesamten Codes finden Sie im Anhang. Als erstes schauen wir uns die Voraussetzungen für die Bibliothek an:

K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> );

Das Makro K_EXPORT_COMPONENT_FACTORY ist in kgenericfactory.h deklariert. Gut, nun weiter zum Konstruktor! Weil es sich hier um ein sehr einfaches Modul handelt, ist der Konstruktor ebenso einfach.

Theme2k::Theme2k( QWidget *parent, const char *name, const QStringList &args
 )
    :ThemeEngine( parent, name, args )
{
  readSettings();
  initUi();
}

Die Methode readSettings() zeigt, wie Sie die Design-Einstellungen einlesen. (Sie wollen ja schließlich, dass Ihr Modul auch von Designs verwendet wird, richtig?)

void Theme2k::readSettings()
{
  if( !mTheme )
    return;

  KConfig *cfg = mTheme->themeConfig();
  if( !cfg )
    return;

  cfg->setGroup( QString("KSplash Theme: %1").arg(mTheme->theme()) );

  QColor DefaultTBgColor( Qt::darkBlue );
  QColor DefaultTFgColor( Qt::white );

  mTBgColor = cfg->readColorEntry( "Title Background Color",
&DefaultTBgColor );
  mTFgColor = cfg->readColorEntry( "Title Foreground Color",
&DefaultTFgColor );
  mStatusColor = cfg->readColorEntry("Status Text Color", &mTBgColor );

  QColor DefaultRot1( Qt::darkBlue );
  QColor DefaultRot2( Qt::cyan );
  mRotColor1 = cfg->readColorEntry( "Rotator Color 1", &DefaultRot1 );
  mRotColor2 = cfg->readColorEntry( "Rotator Color 2", &DefaultRot2 );

  mRotSpeed = cfg->readNumEntry( "Rotator Speed", 30 );
  mWndTitle = cfg->readEntry( "Window Title", i18n("Please wait...") );
  mLogoFile = cfg->readEntry( "Logo File", QString::null );
}

Weil wir unseren Benutzern wohlgesonnen sind, legen wir sinnvolle Voreinstellungen fest. Wir stellen unsere Gruppe immer auf "KSplash Theme: designname" ein, um mit zukünftigen Design-Spezifikationen kompatibel zu sein. Die Methode initUI() ist nicht sonderlich interessant, denn Sie erzeugt nur die Bildschirmelemente. Details finden Sie im Anhang.

Weil wir uns für das KDE application framework entschieden haben, müssen wir die Datei Makefile.am erstellen. Sie sollte so aussehen:

INCLUDES = $(all_includes)

kde_module_LTLIBRARIES = ksplash2k.la

ksplash2k_la_SOURCES = theme2k.cpp rotwidget.cpp
ksplash2k_la_LDFLAGS = $(all_libraries) $(KDE_RPATH)
ksplash2k_la_LIBADD = $(LIB_KDEUI) -lksplashthemes

METASOURCES = AUTO

noinst_HEADERS        = theme2k.h rotwidget.h

servicesdir = $(kde_servicesdir)
services_DATA = ksplash2k.desktop

themedir = $(kde_datadir)/ksplash/Themes/2k
theme_DATA = Theme.rc Preview.png

Informationen, wie man Makefile.am-Dateien für KDE schreibt, finden Sie auf der KDE Webseite. Das einzig zu beachtende hier ist, dass wir ein Standard-Design bereitstellen, das unser Modul benutzt, sowie ein Vorschaubild dafür. Um den Benutzern einen Gefallen zu tun, sollten Sie eine Beispieldatei Theme.rc bereitstellen, die die verschiedenen Optionen aufzeigt.