KSplashi käsiraamat

Enne seda, kui sinu rakendus alustab arvutikurnamist või pluginate laadimist jne., kutsu KSplash nii välja:

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

Me eeldame, et korraga töötab ainult üks KSplashi protsess, muidu lähevad asjad natuke keerulisemaks. Täpsemalt loe selle kohta DCOPi dokumentatsioonist.

Enne kui näidata mingeid teateid, tuleb määrata, mitut sammu näidatakse. Näiteks KDE käivitusprotseduuril on 7 sammu.

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

Kui soovid näidata teadet ikooniga või ilma, kasuta

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

Iga kord, kui kutsuda välja programStarted, lisatakse uus samm. Kui rakendus on käivitumise lõpetanud, pane käivitulogo kaduma:

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

Ja ongi kõik! Selleks, et osa saada kõigest, mida KSplash sulle pakkuda suudab, ei ole vaja midagi rohkem teha.

Me kasutame KDE rakenduse raamistikku, mis hoolitseb plugina loomise eest ja pakub meile sõltumatust platvormist, ilma et me selleks ise erilisi pingutusi peaksime ette võtma. Selleks kontrolli, et paigaldatud oleks pakett kdesdk. Anna käsk kapptemplate rakenduse nimega "2k" tekitamiseks. See loob tipptaseme kataloogi, kus on mitmed üldised failid, näiteks AUTHORS jne. Meid huvitab kõige enam alamkataloog 2k. Mine sellesse alamkataloogi ja kustuta seal kõik failid. Nüüd on meil olemas vajalik "luustik".

Järgmine samm on luua .desktop-fail, mis paigaldamise korral teatab KSplashile, et meie plugin on saadaval. Vastavalt eelmises osas kirjeldatud nimekonventsioonidele loome siin kataloogis faili ksplash2k.desktop. See peaks sisaldama järgmisi ridu:

[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

Kodeering (Encoding), tüüp (Type), kommentaar (Comment) ja teenuse tüüp (ServiceTypes) on kõigile pluginatele ühesugused. Plugina ja teegi nimi järgivad eespool mainitud nimekonventsiooni. Kirje X-KSplash-Default kasutab tõeväärtust, mis määrab, kas seda näidatakse vaikimisi juhtimiskeskuse moodulis. Kui mõned harvad erandid kõrvale jätta, peaks see väärtus olema tõene (true).

Eeltöö on tehtud, asume nüüd tõeliselt vaimustava osa kallale - looma klassi, mis pakub just sellist käitumist, mida me soovime. Me võime selle klassiga ette võtta küll peaaegu kõike, mida soovime, kuid siiski on siin teatud piirangud.

Viimane nõue võib tunduda keerukana, kuid hiljem näeme, et üheainsa rea lisamisega lähtefailidesse võib seda enamasti ignoreerida.

Piiranguid arvestades vaatame nüüd, milline näeb välja päisefail theme2k.h:

#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

Analüüsime nüüd seda listingut. Klass Theme2k rahuldab nimekonventsiooni ja tema päritolu on ThemeEngine. Ta pakub Theme2k::names() ja tal on konstruktor, mis võtab soovitavad parameetrid Theme2k( QWidget *, const char *, const QStringList& ); ning pakub ka lihtsa meetodi Theme2k::slotSetText(). Hetkel ei ole mõtet pead vaevata klassiga RotWidget. See on väike element, mis pakub kasutajale veidi silmailu. Meie plugin on äärmiselt lihtne ega näita mingeid ikoone või edenemisriba. Kui soovid ikoone näidata, tühista funktsioon slotSetPixmap. Sarnased funktsioonid on olemas edenemisriba vahemikule (slotUpdateSteps) ja käesoleva sammu kasvamisele (slotUpdateProgress).

Uurime ainult meile kordaminevaid teostuse osi. Kogu teostuse listingut võib näha lisas. Kõigepealt tuleb välja saada teeginõue:

K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> );

Makro K_EXPORT_COMPONENT_FACTORY on deklareeritud failis kgenericfactory.h. Edasi konstruktori kallale. Kuna see on väga lihtne plugin, on ka konstruktor lihtne ja selge.

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

Meetod readSettings() illustreerib korrektset teemaseadistuste hankimise viisi. Sa ju soovid, et inimesed kasutaks sinu pluginaid oma teemades, või kuidas?

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

Kuna meile meeldivad meie kasutajad, pakume neile parameetritena mõistlikke vaikeväärtusi, mida teemafailis ei leidu. Pane tähele, et alati tuleb grupiks määrata "KSplash Theme: themename", et ühilduda tulevase teema spetsifikatsiooniga. Meetod initUI() meid praegu eriti ei huvita, sest see ainult loob elemente. Selle kohta vaata lähemalt lisast.

Kuna me otsustasime kasutada plugina kompileerimiseks KDE raamistikku, tuleb meil luua Makefile.am. See peaks välja nägema nii:

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

Rohkem infot Makefile.am kirjutamise kohta KDE tarbeks leiab KDE arendajate veebileheküljelt. Ainus asi, mida tasub märkida, on see, et me pakume sellele pluginale põhineva vaiketeema ning sellele ka eelvaatluse. Kasutajate huve silmas pidades tuleks pakkuda näidisfail Theme.rc, mis illustreerib erinevate valikut kasutamist.