O Manual do KSplash

Antes de seu aplicativo iniciar um trabalho intensivo de computação, ou antes de ele iniciar o carregamento de plugins, etc, invoque o KSplash como se segue:

DCOPClient *c = kapp->dcopClient();
QString erro;
QCString NomeKSplash;
int pid = 0;
QStringList args;
args << "--theme=MeuTemaLegal" << "--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 assumiremos que existe somente uma instância do KSplash em execução. Outros casos são ligeiramente mais complexos. Por favor veja a documentação do DCOP para mais detalhes.

Antes de mostrar qualquer mensagem, você precisa configurar o número de passos que serão mostrados. Por exemplo, a inicialização do KDE se processa em 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 você deseja exibir uma mensagem com ou sem um ícone, 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.
    }

Cada vez que você chama programStarted, os passos completados são incrementados. Quando seu programa tiver terminado sua inicialização, faça o seguinte para fazer com que a tela de abertura vá embora:

if (!(c->send(KSplashName, "KSplashIface", "startupComplete()", data))
    {
      // Algum processamento de erro aqui.
    }

É isto! Você não precisa fazer nada mais para aproveitar todas as vantagens que o KSplash tem para oferecer.

Nós usaremos o ambiente de trabalho de aplicativos do KDE que tomará conta da construção do plugin e fornecerá uma plataforma independente sem nenhum trabalho de nossa parte. Para fazer isto, certifique-se de que possui o pacote kdesdk instalado. Execute o comando kapptemplate para produzir um aplicativo nomeado "2k". Isto criará uma pasta de nível superior que contém arquivos genéricos como AUTHORS, etc. Nós estamos mais interessados na subpasta chamada 2k. Vá para esta subpasta e exclua todos os arquivos nela. Agora nós temos o esqueleto que precisamos.

O próximo passo é criar um arquivo .desktop que, quando instalado, dirá ao KSplash que seu plugin está disponível. Consistente com a convenções de nomes estabelecida na seção anterior, crie um arquivo chamado ksplash2k.desktop nesta pasta. Ele deve conter as seguintes linhas:

[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

O Encoding, Type, Comment e ServiceTypes são o mesmo para todos os plugins. O nome do plugin e o nome da biblioteca segue as convenções estabelecidas anteriormente. A entrada X-KSplash-Default recebe um valor booleano que determina se ele é mostrado no módulo de configuração do painel de controle por padrão. Exceto para casos muito raros, isto deve ser true(verdadeiro).

Agor que nós terminamos o trabalho preliminar, vamos para a parte mais divertida - criar uma classe que fornecerá o comportamento que nós desejamos. Apesar de sermos livre para fazer esta classe fazer quase qualquer coisa que nós quisermos, existem algumas poucas restrições.

O último requisito pode ser mais complicado, mas, como veremos mais tarde, adicionando uma linha simples ao seus arquivos fonte, você pode normalmente ignorá-lo.

Fornecida as constantes, nós agora iremos ver que o arquivo de cabeçalho theme2k.h se parecerá com este:

#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

Vamos analisar a lista acima. A classe Theme2k satisfaz a convenção de nomes, e é filha de ThemeEngine. Ela fornece um Theme2k::names(), e possui um construtor que recebe os seguintes parâmetros: Theme2k( QWidget *, const char *, const QStringList& ); e também fornece um método Theme2k::slotSetText() simples. Por enquanto, não se preocupe com a classe RotWidget. Ela é um pequeno widget que fornece algum colírio para os olhos do usuário. Nosso plugin é muito simples e não exibe nenhum ícone ou mostra uma barra de progresso. Se você gostaria de exibir ícones, sobrescreva a função slotSetPixmap. Funções semelhantes existem para configurar o intervalo da barra de progresso (slotUpdateSteps) e incrementar (slotUpdateProgress) o passo atual.

Nós examinaremos somente as partes relevantes da implementação. Para uma listagem de toda implementação, por favor veja o apêndice. A primeira coisa que nós faremos é obter o requisito da biblioteca desta maneira:

K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> );

O macro K_EXPORT_COMPONENT_FACTORY é declarado em kgenericfactory.h. Vamos para o construtor! Uma vez que é um plugin muito simples, o construtor é consideravelmente simples.

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

O método readSettings() ilustra a maneira correta de obter as configurações do seu tema. (Você deseja que as pessoas usem seus plugins em seus temas, não é?)

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

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

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

  QColor TCorFundoPadrao( Qt::darkBlue );
  QColor TCorTextoPadrao( 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 Rot1Padrao( Qt::darkBlue );
  QColor Rot2Padrao( Qt::cyan );
  mRotCor1 = cfg->readColorEntry( "Cor 1 da Rotação", &Rot1Padrao );
  mRotCor2 = cfg->readColorEntry( "Cor 2 da Rotação", &Rot2Padrao );

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

Uma vez que nós gostamos de nossos usuários, nós fornecemos padrões adequados para os parâmetros que não estão presentes no arquivo de tema. Observe que nós devemos sempre configurar nosso grupo para "KSplash Theme: nome_tema" para manter compatibilidade com especificações de tema futuras. O método initUI() não é muito interessante, uma vez que ele simplesmente constrói os widgets. Por favor veja o apêndice para detalhes.

Uma vez que decidimos usar o ambiente de trabalho do KDE para compilação do plugin, nós precisamos criar um Makefile.am. Ele deve se parecer com isto:

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 arquivos Makefile.am para o KDE, por favor veja a página Web dos programadores do KDE. A única coisa a notar é que nós oferecemos um tema padrão baseado neste plugin e oferecemos uma imagem de previsão para o mesmo. Como cortesia para os seus usuários, você deverá oferecer um Theme.rc de exemplo e que ilustre a utilização das várias opções.