Development/Tutorials/Plasma4/GettingStarted (fr)

Introduction

Pour compiler ce tutoriel il est nécessaire de disposer de KDE 4.2 (trunk). Dans ce tutoriel, nous allons créer un plasmoïde simple. Afin de rester simple, nous nous contenterons d'un plasmoïde statique qui contiendra les éléments suivants :

• une image SVG ;
• une icône  ;
• un sympathique petit texte.

Le code

Le fichier .desktop

Tout plasmoïde doit fournir un fichier .desktop qui indique à Plasma comment le démarrer et comment il s'appelle.

plasma-applet-tutoriel1.desktop [Desktop Entry] Name=Tutoriel 1 Comment=Tutoriel Plasma 1 Type=Service ServiceTypes=Plasma/Applet

X-KDE-Library=plasma_applet_tutoriel1 X-KDE-PluginInfo-Author=Bas Grolleman [email protected] X-KDE-PluginInfo-Name=tutoriel1 X-KDE-PluginInfo-Version=0.1 X-KDE-PluginInfo-Website=http://plasma.kde.org/ X-KDE-PluginInfo-Category=Examples X-KDE-PluginInfo-Depends= X-KDE-PluginInfo-License=GPL X-KDE-PluginInfo-EnabledByDefault=true

Les variables les plus importantes sont X-KDE-Library et X-KDE-PluginInfo-Name. Elles constituent le lien entre votre classe et Plasma. Sans elles, rien ne démarrera. Pour la variable X-KDE-PluginInfo-Category, consultez PIG (en anglais).

Le fichier d'en-tête

Voici le fichier d'en-tête de l'exemple. Des commentaires ont été ajoutés dans le code pour plus de clarté.

plasma-tutoriel1.h // Ici, on se protège contre les inclusions multiples

1. ifndef Tutoriel1_HEADER
2. define Tutoriel1_HEADER

// On a besoin des en-têtes d'applet Plasma

1. include <KIcon>

1. include <Plasma/Applet>
2. include <Plasma/Svg>

class QSizeF;

// Définition de l'applet Plasma class PlasmaTutoriel1 : public Plasma::Applet {

   Q_OBJECT
   public:
       // Constructeur et destructeur simples
       PlasmaTutorial1(QObject *parent, const QVariantList &args);
       ~PlasmaTutorial1();

       // La méthode paintInterface dessine l'applet à l'écran
       void paintInterface(QPainter *painter,
               const QStyleOptionGraphicsItem *option,
               const QRect& contentsRect);

void init();

   private:
       Plasma::Svg m_svg;
       KIcon m_icon;

};

// Cette commande fait le lien entre l'applet et le fichier .desktop K_EXPORT_PLASMA_APPLET(tutoriel1, PlasmaTutoriel1)

1. endif

QRectF boundingRect()

La fonction boundingRect() indique à Plasma la taille effective du plasmoïde. Elles est importante car nous avons besoin de savoir quelle surface est occupée à l'écran.

Tip

Si vous rencontrez des problèmes avec votre plasmoïde qui laisse des pixels derrière lui lorsqu'il est déplacé, ceci est habituellement dû à une implémentation incorrecte de boundingRect().

void paintInterface(QRectF contentsRect)

contentsRect peut être considérée comme la fonction principale puisqu'elle dessine le plasmoïde à l'écran. C'est ici que vous définissez l'apparence de votre plasmoïde. Vous ne devriez dessiner que dans les limites définies par contentsRect et éviter d'utiliser geometry(). Lorsqu'un plasmoïde n'a pas d'arrière plan standard, par exemple s'il a été désactivé par un appel à setBackgroundHints() ou s'il se trouve dans le panel, geometry() et boundingRect() se comportent de la même manière. Cependant, lorsque l'arrière-plan standard est activé (ce qui est habituellement le cas), l'applet sera dotée d'une bordure dans laquelle elle ne doit pas dessiner.

Le véritable coeur du plasmoide

Voici le corps de la fonction, là aussi largement commentée.

plasma-tutoriel1.cpp

1. include "plasma-tutorial1.h"
2. include <QPainter>
3. include <QFontMetrics>
4. include <QSizeF>

1. include <plasma/svg.h>
2. include <plasma/theme.h>

PlasmaTutoriel1::PlasmaTutorial1(QObject *parent, const QVariantList &args)

   : Plasma::Applet(parent, args),
   m_svg(this),
   m_icon("document")

{

   m_svg.setImagePath("widgets/background");
   // Ceci nous amène l'arrière-plan standard sur un plateau, gratuitement !
   setBackgroundHints(DefaultBackground);
   resize(200, 200);

}

PlasmaTutoriel1::~PlasmaTutoriel1() {

   if (hasFailedToLaunch()) {
       // Faire du nettoyage ici
   } else {
       // Sauvegarde des paramètres
   }

}

void PlasmaTutoriel1::init() {

   // Une petite démonstration de l'utilisation de la fonction setFailedToLaunch
   if (m_icon.isNull()) {
       setFailedToLaunch(true, "Personne à qui dire bonjour");
   }

}

void PlasmaTutoriel1::paintInterface(QPainter *p,

       const QStyleOptionGraphicsItem *option, const QRect &contentsRect)

{

   p->setRenderHint(QPainter::SmoothPixmapTransform);
   p->setRenderHint(QPainter::Antialiasing);

   // Maintenant, on dessine l'applet, en commençant par le SVG
   m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
   m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());

   // On place l'icône et le texte
   p->drawPixmap(7, 0, m_icon.pixmap((int)contentsRect.width(),(int)contentsRect.width()-14));
   p->save();
   p->setPen(Qt::white);
   p->drawText(contentsRect,
               Qt::AlignBottom | Qt::AlignHCenter,
               "Hello Plasmoid!");
   p->restore();

}

1. include "plasma-tutoriel1.moc"

K_EXPORT_PLASMA_APPLET ( <name>, <class> )

Cette simple ligne est très importante, car elle établit le lien entre le nom de notre classe et le nom de l'applet dans le fichier .desktop. Si l'applet semble ne pas se charge, cela peut être dû à une différence entre cette déclaration et le fichier .desktop.

Tip

K_EXPORT_PLASMA_APPLET ajoute "plasma_applet_" devant le nom. Pensez-y lorsque vous remplissez votre fichier .desktop afin d'éviter une différence dans le nom.

Plasma/Svg

Comme on peut le voir dans cet exemple, on utilise un objet Plasma::Svg. Quelques points importants sont à noter ici.

Tout d'abord, on utilise un chemin relatif, widgets/background, ce qui amène Plasma::Svg à utiliser Plasma::Theme pour localiser les données SVG. Bien que Plasma::Svg puisse charger n'importe quel fichier à partir d'un chemin absolu, utilisez des chemins relatifs au thème aussi souvent que possible car cela permet de personnaliser l'apparence de Plasma. Chacun des plasmoïdes apparaît alors comme un ensemble homogène plutôt que comme un ensemble d'applications séparées et sans liens entre elles. Vous pouvez obtenir une liste des composants graphiques disponibles sur la page de thème Plasma (en anglais)

Dans les deux cas, Plasma::Svg peut être utilisée pour ne dessiner qu'un sous ensemble du fichier SVG en lui passant l'identifiant d'un élément apparaissant dans le document SVG. Le fichier clock.svg en est un bon exemple. En l'ouvrant, on constate qu'il est constitué d'un arrière-plan, de trois aiguilles (heure, minute et secondes) et d'un avant-plan (le verre). Grâce à sa capacité à placer tous les éléments dans un même fichier, le document SVG affiche une horloge. Ceci est bien plus pratique pour les artistes que de créer cinq fichiers séparés et de les imaginer superposés les uns sur les autres et aussi bien plus performant, puisqu'un seul rendu SVG et une seule lecture de fichier sont nécessaires.

setBackgroundHints(DefaultBackground)

Comme le dessin de l'arrière plan est une fonction courante, il existe un moyen plus simple pour le faire. En ajoutant setBackgroundHints(DefaultBackground) dans le code, l'arrière-plan par défaut de Plasma sera dessiné derrière le plasmoïde, ce qui économise et du temps et du code, mais ce qui permet également d'offrir à l'utilisateur une présentation plus homogène.

La méthode init()

Dans le constructeur de l'exemple, le dialogue avec Plasma se cantonne à lui parler de l'arrière-plan et du fichier de configuration. Mais on peut également fixer la taille initiale du plasmoïde. Une fois cela fait, Plasma s'occupera de tout changement de taille et on n'aura plus à s'en soucier. Dans la méthode init() , il faut initialiser tout ce qui doit l'être, comme lire et appliquer des données de configuration.

hasFailedToLaunch()

Si, pour une raison quelconque, l'applet ne parvient pas à démarrer (la bibliothèque n'a pas pu être chargée, un pilote matériel nécessaire n'a pas été trouvé, etc.), cette méthode retourne true. L'utilisation de cette fonction donne une occasion à votre application de faire un peu de ménage avant de s'arrêter.

setFailedToLaunch(bool, QString)

Lorsque l'applet ne parvient pas à démarrer, cette fonction permet d'informer Plasma en fournissant optionnellement une raison. Plasma affichera alors une interface d'erreur standard pour informer l'utilisateur de la situation et, à partir de ce moment, les méthodes dessinant votre applet à l'écran ne seront plus appelées. Si le plasmoïde devient plus complexe et dépend de facteurs multiples pour démarrer, cette fonction est la meilleurs façon de faire le ménage en cas d'échec.

dataUpdated(const QString &source, const Plasma::DataEngine::Data &data)

Si on souhaite se connecter aux DataEngines de Plasma, on peut implémenter la méthode dataUpdated dans le plasmoïde. Lorsqu'un DataEngine est directement connecté à la sous-classe de l'applet, dataUpdated sera appelée à chaque fois que le DataEngine enverra des données mises à jour.

Déterminer la taille de l'applet et sa géométrie : geometry() et contentsRect()

Si l'applet a besoin de connaître quelles sont sa taille et sa géométrie, utilisez contentsRect() et contentsRect().size(). Évitez d'appeler geometry() et size() car ces deux fonctions ne prennent pas en compte la taille de la marge fixée par l'arrière plan par défaut des applets. Évitez également d'utiliser des coordonnées absolues pour positionner les éléments de l'applet, comme QPoint(0, 0) pour se référer au coin en haut à gauche de votre applet. À la place, il est préférable d'utiliser contentsRect().topLeft().

Construction de l'applet, le fichier CMakeLists.txt

Pour finir, pour assembler tous les éléments, il est nécessaire de compiler le tout. Pour indiquer à QMake ce qui doit aller à quel endroit, on utilise le ficher CMakeLists.txt.

Pour plus de détails concernant CMake, référez-vous à Development/Tutorials/CMake (anglais).

1. Le projet a besoin d'un nom, bien sûr

project(plasma-tutoriel1)

1. Trouve les bibliothèques requises

find_package(KDE4 REQUIRED) include(KDE4Defaults)

add_definitions (${QT_DEFINITIONS} ${KDE4_DEFINITIONS}) include_directories(

  ${CMAKE_SOURCE_DIR}
  ${CMAKE_BINARY_DIR}
  ${KDE4_INCLUDES}
  )

1. On insère les sources de notre code ici

set(tutorial1_SRCS plasma-tutorial1.cpp)

1. On s'assure que les fichiers vont au bon endroit

kde4_add_plugin(plasma_applet_tutorial1 ${tutorial1_SRCS}) target_link_libraries(plasma_applet_tutorial1

                     ${KDE4_PLASMA_LIBS} ${KDE4_KDEUI_LIBS})

install(TARGETS plasma_applet_tutorial1

       DESTINATION ${PLUGIN_INSTALL_DIR})

install(FILES plasma-applet-tutorial1.desktop

       DESTINATION ${SERVICES_INSTALL_DIR})

Tester l'applet

Si l'environnement de développement actuel diffère de l'environnement de test d'installation, on doit lancer CMake avec -DCMAKE_INSTALL_PREFIX=`kde-config --prefix`, puis lancer make. Si le test est réalisé avec succès, l'appelt peut être installée en lançant sudo make install ou

• cp ./lib/plasma_applet_tutorial1.so $KDEDIR/lib/kde4
• cp ./plasma-applet-tutorial1.desktop $KDEDIR/share/kde4/services/
• kbuildsycoca4

(ainsi, les applications KDE auront connaissance des nouveaux fichiers desktop). Pour tester l'applet, on peut utiliser le programme plasmoidviewer : plasmoidviewer applet_name On peut même visionner l'applet dans un petit bureau en utilisant la même application : plasmoidviewer -c desktop applet_name où applet_name est la valeur spécifiée dans .desktop pour la clé X-KDE-PluginInfo-Name.

Sinon, on peut redémarrer Plasma, ainsi l'applet sera affichée dans le navigateur des applets :

kbuildsycoca4
kquitapp plasma # in trunk (KDE4.3): kquitapp plasma-desktop
plasma          # in trunk (KDE4.3): plasma-desktop

Si cela ne fonctionne pas, il faut alors relancer la session KDE en se déloguant pour se reloguer. Ou tenter d'exporter KDEDIRS=/usr/local:'kde4-config --prefix' puis relancer kbuildsyscoca4.