The KSplash Handbook

Before your application starts its computation intensive work, or before it starts loading plugins, etc., invoke KSplash as follows:

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

We will assume that there is only one instance of KSplash running. Other cases are slightly more complex. Please see the DCOP documentation for further details.

Before you show any messages, you need to set up the number of steps you will show. For example, the KDE startup procedure uses 7 steps.

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

Whenever you want to display a message with or without an icon, use

arg << QString("iconName") << QString("programName") << QString("Some description");
    if (!(c->send(KSplashName, "KSplashIface", "programStarted(QString,QString,QString)", data))
    {
      // Some error processing here.
    }

Each time you call programStarted, the steps completed is incremented. When your program has finished its startup, do the following to make the splash screen go away:

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

That's it! You don't need anything more to take advantage of all that KSplash has to offer you.

We will use the KDE application framework which will take care of building the plugin and will provide us with platform independence without any work on our part. To do that, make sure you have the kdesdk package installed. Run the command kapptemplate to produce an application named "2k". It will create a toplevel folder which contains generic files such as AUTHORS, etc.. We are most interested in the subfolder called 2k. Go into that subfolder and delete all the files there. Now we have the skeleton we require.

The next step is to create a .desktop file which, when installed, will tell KSplash that our plugin is available. Consistent with the naming conventions laid out in the preceding section, create a file called ksplash2k.desktop in that folder. It should contain the following lines:

[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

The Encoding, Type, Comment and ServiceTypes are the same for all plugins. The plugin name and the library name follow the conventions noted earlier. The entry X-KSplash-Default takes a boolean value which determines whether it is shown in the control panel configuration module by default. Except for some very rare cases, it should be true.

Now that we have the preliminary work done, let us get into the actual fun part - creating a class that will provide the behaviour we want. While we are free to make this class do almost anything we want it to do, there are a few restrictions.

The last requirement may seem complicated, but, as we will see later, by adding a single line to your source files, you can usually ignore it.

Given the constaints, we will now see what the header file theme2k.h looks like this:

#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

Let us analyse the listing above. The Theme2k class satisfies the naming conventions, and is inherited from ThemeEngine. It provides a Theme2k::names(), and has a constructor that takes the required parameters: Theme2k( QWidget *, const char *, const QStringList& ); and also provides a simple Theme2k::slotSetText() method. For the moment, do not worry about the RotWidget class. It is a small widget that provides some eye candy for the user. Our plugin is very simple and does not display any icons or show a progressbar. If you would like to display icons, override the slotSetPixmap function. Similar functions exist for setting the progressbar range (slotUpdateSteps) and incrementing(slotUpdateProgress) the current step.

We will examine only the relevant parts of the implementation. For a listing of the whole implementation, please see the appendix. The first thing we will do is to get the library requirement out of the way:

K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> );

The macro K_EXPORT_COMPONENT_FACTORY is declared in kgenericfactory.h. Onwards to the constructor! Since this is a very simple plugin, the constructor is pretty straightforward.

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

The method readSettings() illustrates the proper way to obtain your theme settings. (You do want people to use your plugins in their themes, don't you?)

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 );
}

Since we like our users, we provide sensible defaults for parameters that are not present in the theme file. Note that we should always set our group to "KSplash Theme: themename" to remain compatible with future theme specifications. The initUI() method is not very interesting, as it merely builds up the widgets. Please see the appendix for details.

Since we decided to use the KDE framework for compiling the plugin, we need to create a Makefile.am. It should look like this:

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

For more information on writing Makefile.am files for KDE, please see the KDE developers' website. The only thing of note is that we provide a default theme based on this plugin, and provide a preview image for it. As a matter of courtesy to your users, you should provide an example Theme.rc file illustrating the use of the various options.