Manuel de KSplash

Avant que votre application en commence son travail de calcul intensif, ou avant qu'elle ne commence à charger des modules externes, etc., invoquez KSplash comme suit :

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.
}

Nous supposons qu'il n'y a qu'une instance de KSplash en fonctionnement. Les autres cas sont un peu plus complexes. Veuillez voir la documentation de DCOP pour des détails plus approfondis.

Avant que vous n'affichiez des messages, vous avez besoin de régler le nombre d'étapes que vous afficherez. Par exemple, la procédure de démarrage de KDE utilise 7 étapes.

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

Si vous voulez afficher un message avec ou sans icône, utilisez

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

À chaque fois que vous appelez programStarted, les étapes terminées sont incrémentées. Quand votre programme a fini de démarrer, faites les choses suivantes pour éliminer l'écran de démarrage :

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

C'est tout ! Vous n'avez pas besoin d'autre chose pour prendre avantage de tout ce que KSplash vous offre.

Nous utiliserons le cadre d'application de KDE qui prendra soin de construire l'additif et nous fournira une indépendance de la plate-forme sans travail de notre part. Pour faire cela, assurez-vous d'avoir installé le paquet kdesdk. Lancez la commande kapptemplate pour produire une application nommée « 2k ». Il créera un dossier de plus haut niveau qui contient des fichiers génériques comme AUTHORS, etc. Nous sommes surtout intéressés par le sous-dossier nommé 2k. Allez dedans et supprimez tous les fichiers qui s'y trouvent. Maintenant, nous avons le squelette nécessaire.

L'étape suivante est de créer un fichier .desktop, qui, lorsqu'installé, dira à KSplash que notre additif est disponible. Comme dit dans les conventions de nommage expliquées dans la section précédente, créez un fichier nommé ksplash2k.desktop dans ce dossier. Il devrait contenir les lignes suivantes :

[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

Les Encoding, Type, Comment et ServiceTypes sont les mêmes pour tous les modules externes. Le nom de l'additif et le nom de la bibliothèque suivent les conventions notées plus tôt. L'entrée X-KSplash-Default prend une valeur booléenne qui détermine si elle est affichée dans le module du centre de configuration par défaut. Sauf pour certains rares cas, ça devrait être true.

Maintenant que nous avons fait le travail préliminaire, entrons dans la partie vraiment amusante - la création d'une classe qui fournira le comportement que nous voulons. Bien que nous soyons libres de faire que cette classe fasse presque tout ce que nous voulons, il y a quelques restrictions.

La dernière chose nécessaire peut sembler compliquée, mais, comme nous le verrons plus tard, en ajoutant une simple ligne à vos fichiers source, vous pouvez habituellement ignorer cela.

Étant données les contraintes, nous verrons maintenant à quoi le fichier d'en-tête theme2k.h ressemble :

#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

Analysons le listing ci-dessus. La classe Theme2k satisfait les conventions de nommage, et est héritée de ThemeEngine. Elle fournit un Theme2k::names(), et a un constructeur qui prend les paramètres requis : Theme2k( QWidget *, const char *, const QStringList& );, et fournit aussi une méthode Theme2k::slotSetText() simple. Pour le moment, ne vous inquiétez pas à propos de la classe RotWidget. C'est un petit widget qui fournit des choses agréables à l'œil pour l'utilisateur. Notre additif est très simple et n'affiche pas d'icône ou de barre de progression. Si vous voulez afficher des icônes, écrasez la fonction slotSetPixmap. Des fonctions similaires existent pour la plage de la barre de progression (slotUpdateSteps) et l'incrémentation (slotUpdateProgress) le pas courant.

Nous n'examinerons que les parties significatives de l'implémentation. Pour un listing de l'implémentation complète, veuillez voir l'appendice. La première chose que nous ferons est de ne plus avoir besoin des prérequis :

K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> );

La macro K_EXPORT_COMPONENT_FACTORY est déclarée dans kgenericfactory.h. En avant vers le constructeur ! Comme c'est un additif très simple, le constructeur est minimaliste.

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

La méthode readSettings() illustre la bonne manière d'obtenir vos réglages de thème. (Vous voulez pas que les gens utilisent vos additifs dans leurs thèmes, n'est-ce pas ?)

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

Comme nous aimons nos utilisateurs, nous fournissons des paramètres par défaut qui ne sont pas présents dans le fichier de thème. Notez que nous devrions toujours positionner notre groupe sur « KSplash Theme: themename » pour rester compatible avec les futures spécifications de thèmes. La méthode initUI() n'est pas très intéressante, car elle fabrique essentiellement les widgets. Veuillez voir l'appendice pour les détails.

Comme nous avons décidé d'utiliser le cadre de KDE pour compiler l'additif, nous devons créer un Makefile.am. Il devrait ressembler à ça :

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

Pour plus d'informations sur l'écriture des fichiers Makefile.am pour KDE, veuillez voir Le site web des développeurs de KDE. La seule chose à noter est que nous fournissons un thème par défaut basé sur cet additif, et en fournissons une image d'aperçu. Par courtoisie pour vos utilisateurs, vous devriez fournir un fichier d'exemple de Theme.rc, illustrant l'utilisation des diverses options.