Podręcznik KSplash

Zanim program użytkownika rozpocznie pracę obciążającą procesor lub przed rozpoczęciem jej ładowania itp. należy wywołać KSplash w sposób następujący:

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

W przykładzie przyjęto założenie, iż uruchomione zostało tylko jedno wystąpienie programu KSplash. Inne przypadki są bardziej złożone, a ich opis dostępny jest w dokumentacji mechanizmu DCOP.

Zanim wyświetlone zostaną jakiekolwiek komunikaty, należy określić ilość wyświetlanych etapów (kroków) uruchamiania. Na przykład procedura uruchamiania środowiska KDE zawiera 7 kroków.

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

Zawsze gdy należy wyświetlić wiadomość (z ikoną lub bez) należy wywołać funkcję

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

Każde wywołanie funkcji programStarted, zwiększa licznik kroków uruchamiania. Jeżeli program skończy się uruchamiać to poniższy kod zamyka ekran powitalny:

if (!(c->send(KSplashName, "KSplashIface", "startupComplete()", data))
    {
      // obsługa błędów.
    }

To wszystko !. Nic już więcej nie trzeba robić, aby skorzystać z możliwości, które oferuje program KSplash.

Ponieważ wykorzystany zostanie standardowy szablon aplikacji KDE, nie będzie konieczne tworzenie kodu uzależnionego od platformy sprzętowej, na której program będzie uruchamiany. Aby skorzystać z szablonu należy zainstalować pakiet kdesdk. Utworzenie szkieletu programu sprowadza się do uruchomienie polecenia kapptemplate, które utworzy główny katalog programu "2k" wraz z pewnymi typowymi plikami jak np. AUTHORS, itp. Najważniejsza część programu znajdzie się w podkatalogu 2k. Należy przejść do niego oraz wykasować wszystkie znajdujące się tam pliki. W tym momencie szkielet aplikacji jest już gotowy.

Następnym krokiem jest utworzenie pliku .desktop, którego celem jest informowanie programu KSplash o dostępności tworzonej wtyczki. Należy stosować konsekwencję nazywania plików opisaną w poprzedniej części i utworzyć plik o nazwie ksplash2k.desktop w odpowiednim katalogu. Powinien mieć on następującą zawartość:

[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

Parametry Encoding, Type, Comment oraz ServiceTypes są takie same jak we wszystkich innych wtyczkach. Nazwa wtyczki i nazwa biblioteki musi być zgodna z omawianą wcześniej konwencją nazewniczą. Parametr X-KSplash-Default zawiera wartość true lub false (prawda lub fałsz) określając czy wtyczka będzie widoczna w oknie modułu konfiguracji wtyczek. Poza bardzo wyjątkowymi sytuacjami, parametr ten powinien mieć wartość true.

Po zakończeniu prac przygotowawczych, należy przejść do najciekawszej części - stworzenia klasy z programem określającym wymagane przez użytkownika zachowanie. Mimo tego, iż użytkownik może nakazać programowi wykonanie dowolnych czynności, to powinien pamiętać o kilku ograniczeniach.

Ostatnie wymaganie może wydawać się skomplikowane, jednak jak okaże się to poniżej, poprzez dodanie jednego wiersza to kodu programu, można go praktycznie zignorować.

Poniżej przedstawiono zawartość pliku nagłówkowego theme2k.h uwzględniającego powyższe wymagania:

#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

Analizując zawartość powyższego kodu programu zauważyć można następujące elementy. Klasa Theme2k została nazwana zgodnie z omawianą wcześniej konwencją nazewniczą, jest potomna względem klasy ThemeEngine. Zawiera ona metodę Theme2k::names() oraz konstruktor obsługujący wymagane parametry wtyczki: Theme2k( QWidget *, const char *, const QStringList& ); dodatkowo zdefiniowana została metoda Theme2k::slotSetText().Na razie nie należy zwracać uwagi na klasę RotWidget, która udostępnia obsługę miłych dla oka elementów interfejsu użytkownika. Omawiana w przykładzie wtyczka jest bardzo prosta, nie wyświetla ona żadnych ikon czy też paska postępu. Jeżeli użytkownik chciałby wyświetlać ikony, to powinien zdefiniować funkcję slotSetPixmap. Istnieją również funkcje określające rozmiar - ilość kroków - paska postępu (slotUpdateSteps) oraz zwiększające pozycję na pasku (slotUpdateProgress) o jeden krok.

Omówione zostały tylko najważniejsze części implementacji. Pełny kod programu dostępny jest w załączniku. Pierwszą częścią jest zadeklarowanie wymaganych bibliotek:

K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> );

Makro K_EXPORT_COMPONENT_FACTORY jest zdefiniowane w pliku kgenericfactory.h. Kontynuując, ponieważ jest to bardzo prosta wtyczka, to konstruktor klasy jest bardzo prosty.

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

Metoda readSettings() pokazuje właściwy sposób odczytywania ustawień tematu. (Jest to niezbędne gdy chcemy aby inni użytkownicy korzystali z tworzonej wtyczki przy tworzeniu własnych tematów)

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

Ponieważ należy dbać o użytkownika, ważne jest aby dopasować rozsądne wartości domyślne dla parametrów nie zdefiniowanych w pliku tematu. Należy pamiętać, aby zawsze ustawić grupę na "KSplash Theme: nazwa_tematu" aby zachować zgodność z przyszłymi możliwymi specyfikacjami tematów. Metoda initUI() nie jest zbyt interesująca, ponieważ jedynie tworzy elementy kontrolne interfejsu użytkownika. Więcej na ten temat w załączniku.

Ponieważ do kompilacji wtyczki wykorzystywane jest środowisko programistyczne KDE to niezbędne jest utworzenie pliku Makefile.am. Powinien on wyglądać tak:

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

Więcej informacji dotyczących tworzenia plików Makefile.am dla programów środowiska KDE znajduje się na stronach deweloperów KDE. Jedyną rzeczą o której należy pamiętać jest utworzenie domyślnego tematu bazującego na utworzonej wtyczce wraz z odpowiednim obrazkiem podglądu. W dobrym tonie jest również przygotowanie przykładowego pliku Theme.rc zawierającego komentarze ilustrujące działanie różnorodnych opcji konfiguracyjnych.