Manuale di KSplash

Prima che l'applicazione inizi intensivi cicli di calcolo, o prima di caricare i plugin, ecc., invoca KSplash nel seguente modo:

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, "Impossibile invocare KSplash");
  // Qui gestisci gli errori.
}

Qui assumiamo che esiste una sola istanza di KSplash in esecuzione. Altri casi sono leggermente più complessi. Per favore vedi la documentazione DCOP per maggiori dettagli.

Prima di visualizzare qualsiasi messaggio, devi impostare il numero di passi che vuoi visualizzare. Per esempio la procedura di partenza di KDE impiega 7 passi.

QByteArray data;
    QDataStream arg(data,IO_WriteOnly);
    arg << someNumber;
    if (!(c->send(KSplashName, "KSplashIface", "setStartupItemCount(int)", data))
      // Processamento degli errori qui.

Quando vuoi mostrare un messaggio con o senza un'icona, usa

arg << QString("iconName") << QString("programName") << QString("Some description");
    if (!(c->send(KSplashName, "KSplashIface", "programStarted(QString,QString,QString)", data))
    {
      // Processamento degli errori qui .
    }

Ogni volta che chiami la funzione programStarted, il passo compiuto viene incrementato. Quando il programma ha finito la fase di startup, fai la seguente cosa per mandar via lo splash screen:

if (!(c->send(KSplashName, "KSplashIface", "startupComplete()", data))
    {
      // Qui gestisci gli errori.
    }

Ecco fatto! Non hai bisogno di nient'altro per sfruttare tutto quello che KSplash ti offre.

Useremo l'infrastruttura delle applicazioni di KDE, che si prenderà cura della compilazione del plugin e ci garantirà l'indipendenza dalla piattaforma senza nessun lavoro da parte nostra. Per fare ciò assicurati di avere il pacchetto kdesdk installato. Esegui il comando kapptemplate per produrre un applicazione chiamata "2k". Verrà creata una cartella che contiene file generici come AUTHORS, ecc.. Quello che ci interessa è una sottocartella chiamata 2k. Vai in questa cartella e cancella tutti i file presenti. Ora abbiamo lo scheletro di applicazione che ci serve.

Il prossimo passo consiste nel creare un file .desktop che, una volta installato, dirà a KSplash che il nostro plugin è disponibile. Coerentemente con la nomenclatura portata avanti nella sezione precedente, crea un file chiamato ksplash2k.desktop nella sottocartella suddetta. Deve contenere le seguenti linee.

[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

Le linee Encoding, Type, Comment e ServiceTypes sono le stesse per tutti i plugin. Il nome del plugin e della libreria seguono la stessa nomenclatura già usata. La linea X-KSplash-Default accetta un valore booleano che determina se il plugin deve essere visualizzato nel modulo di configurazione nel centro di controllo. Ad eccezione di pochi casi, questa linea deve essere true.

Adesso che abbiamo svolto le faccende preliminari, andiamo con la parte più divertente, creando una classe che fornirà il comportamento che vogliamo. Siete liberi di fare quasi tutto quello che volete con questa classe, segendo delle semplici restrizioni.

L'ultima richiesta può sembrare complicata ma, come vedremo dopo, aggiungendo una singola linea al tuo file sorgente, puoi ignorarla.

Dati i vincoli, possiamo ora vedere il file header theme2k.h che sarà:

#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

Analizziamo il listato precedente. La classe Theme2k soddisfa la convenzione di nomi voluta, ed è ereditata dalla classe ThemeEngine. Fornisce un metodo Theme2k::names(), ed ha un costruttore che prende i parametri richiesti: Theme2k( QWidget *, const char *, const QStringList& ); e fornisce un semplice metodo Theme2k::slotSetText(). Per il momento non dobbiamo preoccuparci della classe RotWidget. Si tratta di un piccolo widget che fornisce alcuni effetti grafici. Il nostro plugin è molto semplice e non mostra icone o barre di progresso. Se vuoi mostrare delle icone devi overloadare la funzione slotSetPixmap . Funzioni simili esistono per impostare l'intervallo della barra di progresso (slotUpdateSteps) e incrementare il passo corrente (slotUpdateProgress).

Esamineremo solo le parti rilevanti dell'implementazione. Per il listato completo vedi in appendice. La prima cosa che faremo è ottenere i requisiti delle librerie:

K_EXPORT_COMPONENT_FACTORY( libksplash2k, KGenericFactory<Theme2k> );

La macro K_EXPORT_COMPONENT_FACTORY è dichiarata in kgenericfactory.h. E ora il costruttore! Dato che questo plugin è super semplice, il costruttore è alquanto semplice.

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

Il metodo readSettings() illustra il modo giusto per ottenere le impostazioni del tema (Di sicuro vuoi che altre persone utilizzino il tuo plugin nel loro tema, giusto?)

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

Siccome noi amiamo i nostri utenti, forniremo dei parametri di default che non sono presenti nel file del tema. Nota che dovresti sempre impostare il gruppo come "KSplash Theme: nome del tema" per rimanere compatibili con le future spacifiche per i temi. Il metodo initUI() non è interessante, in quanto crea semplicemente il widget. Per favore vedi in appendice per i dettagli.

Dato che abbiamo deciso di utilizzare l'infrastruttura delle applicazioni di KDE per compilare il plugin, dobbiamo creare un Makefile.am. Dovrebbe apparire come segue:

INCLUDES = $(all_includes)

kde_module_LTLIBRARIES = libksplash2k.la

libksplash2k_la_SOURCES = theme2k.cpp rotwidget.cpp
libksplash2k_la_LDFLAGS = $(all_libraries) $(KDE_RPATH)
libksplash2k_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

Per maggiori informazioni su come scrivere un file Makefile.am per KDE, per favore vedi il sito degli sviluppatori di KDE. La cosa da notare è che noi forniamo un tema predefinito basato su questo plugin, nonché un'anteprima di esso. Per una questione di cortesia ai tuoi utenti, dovresti fornire un file di esempio Theme.rc che illustra le varie opzioni.