O Manual do KSplash

Antes de a sua aplicação iniciar o seu trabalho intensivo, ou antes de começar a carregar os 'plugins', etc., invoke o KSplash como se mostra a seguir:

DCOPClient *c = kapp->dcopClient();
QString erro;
QCString NomeKSplash;
int pid = 0;
QStringList args;
args << "--theme=OMeuTemaFixe" << "--managed";
if (kapp->startServiceByDesktopName("ksplash", args, &erro, &NomeKSplash, &pid))
{
  KMessageBox::sorry(0, erro, "Não é possível invocar o KSplash");
  // Algum processamento de erros aqui.
}

Nós iremos assumir que só existe uma instância do KSplash a correr. Os outros casos são ligeiramente mais complexos. Por favor, veja a documentação do DCOP para mais detalhes.

Antes de você poder mostrar quaisquer mensagens, você precisa de configurar o número de passos que irá mostrar. Por exemplo, o procedimento de arranque do KDE utiliza 7 passos.

QByteArray dados;
    QDataStream arg(dados,IO_WriteOnly);
    arg << umNumero;
    if (!(c->send(NomeKSplash, "KSplashIface", "setStartupItemCount(int)", dados))
      // Algum processamento de erros aqui.

Sempre que quiser mostrar uma mensagem com um ícone ou sem nenhum, use

arg << QString("nomeIcone") << QString("nomePrograma") << QString("Uma descrição");
    if (!(c->send(NomeKSplash, "KSplashIface", "programStarted(QString,QString,QString)", dados))
    {
      // Algum processamento de erros aqui.
    }

De cada vez que você invocar o programStarted, os passos completos são incrementados. Quando o seu programa tiver terminado o seu arranque, faça o seguinte para fazer desaparecer o ecrã inicial:

if (!(c->send(NomeKSplash, "KSplashIface", "startupComplete()", dados))
    {
      // Algum processamento de erros aqui.
    }

Já está! Você não precisa de mais nada para tirar partido de tudo o que o KSplash tem para lhe oferecer.

Nós iremos usar a plataforma de aplicações do KDE, a qual tomará conta de construir o 'plugin' e que nos irá garantir alguma independência da plataforma, sem nenhum trabalho da nossa parte. Para o fazer, certifique-se que tem o pacote kdesdk instalado. Corra o comando kapptemplate para produzir uma aplicação chamada "2k". Ela irá criar uma pasta de topo que contém alguns ficheiros genéricos como o AUTHORS, etc.. Nós estamos mais interessados na subpasta chamada 2k. Vá para essa subpasta e remova todos os ficheiros que lá estejam. A partir de agora, temos o esqueleto que pretendemos.

O próximo passo é a criação de um ficheiro .desktop que, ao ser instalado, irá indicar ao KSplash que o nosso 'plugin' está disponível. Estando consistente com as convenções de nomes indicadas na secção anterior, crie um ficheiro chamado ksplash2k.desktop nessa pasta. Deverá conter as seguintes linhas:

[Desktop Entry]
Encoding=UTF-8
Type=Service
Comment=Plugin do KSplash
Name=KSplash2k
ServiceTypes=KSplash/Plugin
X-KDE-Library=libksplash2k
X-KSplash-Default=true
X-KSplash-PluginName=2k
X-KSplash-ObjectName=Tema2k

Os campos Encoding, Type, Comment e ServiceTypes são os mesmos para todos os 'plugins'. O nome do 'plugin' e da biblioteca seguem as convenções indicadas acima. O campo X-KSplash-Default usa um valor booleano que indica se deverá ser mostrado no módulo de configuração do painel de controlo por omissão. Excepto em casos muitos raros, deverá ser igual a true.

Agora que terminámos o trabalho preliminar, vamos para a parte divertida - criar uma classe que irá fornecer o comportamento que pretendemos. Embora tenhamos a liberdade de fazer com que esta classe faça praticamente tudo o que quisermos, existem algumas restrições.

O último requisito poderá parecer complicado mas, como veremos mais tarde, ao adicionar uma única linha aos seus ficheiros de código, você poderá normalmente ignorá-lo.

Dadas as restrições, nós veremos agora que o ficheiro de inclusão theme2k.h ficará como o seguinte:

#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 Nomes;
    Nomes << "KSplash2k";
    Nomes << "ks2k";
    Nomes << "2k";
    Nomes << "2000";
    return( Nomes );
  };

public slots:
  inline void slotSetText( const QString& s )
  {
    if( mTexto && mTexto->text() != s ) mTexto->setText( s );
  };

private:
  void initUi();
  void readSettings();

  QLabel *mTexto;
  RotWidget *mRotacao;
  QColor mTCorFundo, mTCorTexto, mRotCor1, mRot2, mCorEstado;
  int mRotVelocidade;
  QString mTitulo, mLogotipo;
};

#endif

Vamos então analisar a listagem em cima. A classe Theme2k satisfaz as convenções de nomes e herda da classe ThemeEngine. Ela contém um método Theme2k::names(), e tem um construtor que recebe os parâmetros obrigatórios: Theme2k( QWidget *, const char *, const QStringList& ); e também contém um método simples Theme2k::slotSetText(). De momento, não se preocupe com a classe RotWidget. É um pequeno item que oferece alguma beleza visual para o utilizador. O nosso 'plugin' é muito simples e não mostra nenhuns ícones nem nenhuma barra de progresso. Se você quiser mostrar os ícones, implemente de novo a função slotSetPixmap. Existem funções semelhantes para definir o intervalo da barra de progresso (slotUpdateSteps) e para incrementar (slotUpdateProgress) o passo actual.

Nós iremos examinar só as partes relevantes da implementação. Para uma listagem da implementação completa (e não traduzida), veja por favor o apêndice. A primeira coisa que será feita é descartar o requisito da biblioteca:

K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> );

A macro K_EXPORT_COMPONENT_FACTORY é declarada no ficheiro kgenericfactory.h. Sigamos para o construtor! Dado que este é um 'plugin' muito simples, assim o é também o construtor.

Theme2k::Theme2k( QWidget *mae, const char *nome, const QStringList &argumentos  )
    :ThemeEngine( mae, nome, argumentos )
{
  readSettings();
  initUi();
}

O método readSettings() ilustra a forma correcta de obter a configuração do seu tema. (Você deseja que as pessoas usem os seus 'plugins' nos temas delas, não deseja?)

void Theme2k::readSettings()
{
  if( !mTheme )
    return;

  KConfig *cfg = mTheme->themeConfig();
  if( !cfg )
    return;

  cfg->setGroup( QString("KSplash Theme: %1").arg(mTheme->theme()) );

  QColor TCorFundoOmissao( Qt::darkBlue );
  QColor TCorTextoOmissao( Qt::white );

  mTCorFundo = cfg->readColorEntry( "Cor de Fundo do Título", &TCorFundoOmissao );
  mTCorTexto = cfg->readColorEntry( "Cor do Texto do Título", &TCorTextoOmissao );
  mCorEstado = cfg->readColorEntry("Cor do Texto do Estado", &mTCorFundo );

  QColor Rot1Omissao( Qt::darkBlue );
  QColor Rot2Omissao( Qt::cyan );
  mRotCor1 = cfg->readColorEntry( "Cor 1 da Rotação", &Rot1Omissao );
  mRotCor2 = cfg->readColorEntry( "Cor 2 da Rotação", &Rot2Omissao );

  mRotVelocidade = cfg->readNumEntry( "Velocidade da Rotação", 30 );
  mTitulo = cfg->readEntry( "Título da Janela", i18n("Espere por favor") );
  mLogotipo = cfg->readEntry( "Ficheiro do Logotipo", QString::null );
}

Dado que gostamos dos nossos utilizadores, nós oferecemos valores razoáveis para os parâmetros que não estejam presentes no ficheiro do tema. Repare que devemos ser definir o nosso grupo para "KSplash Theme: nomedotema" para continuarmos compatíveis com as especificações dos temas futuras. O método initUI() não é muito interessante, dado que apenas cria a interface gráfica. Veja por favor o apêndice para mais detalhes.

Dado que decidimos usar a plataforma do KDE para compilar o 'plugin', nós iremos precisar de criar um Makefile.am. Deverá ficar algo do género:

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

Para mais informações sobre como criar os ficheiros Makefile.am para o KDE, por favor veja o 'site' Web dos programadores do KDE. A única coisa a notar é que nós oferecemos um tema por omissão baseado neste 'plugin' e oferecemos uma imagem de antevisão para o mesmo. Por razões de cortesia para os seus utilizadores, você deverá oferecer um Theme.rc de exemplo e que ilustre a utilização das várias opções.