Development/Tutorials/Plasma4/GettingStarted (fr)

Traduction en cours...

Introduction

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

• Une image SVG
• Une icone
• Un sympathique petit texte.

Le Code

Le fichier .desktop

Tout plasmoide 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 sont 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'entête

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

plasma-tutoriel1.h // Ici, nous nous protégeons contre les inclusions multiples

1. ifndef Tutoriel1_HEADER
2. define Tutoriel1_HEADER

// Nous avons besoin des entêtes d'Applet Plasma

1. include <KIcon>

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

class QSizeF;

// Définition de notre 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 votre applet et le fichier .desktop K_EXPORT_PLASMA_APPLET(tutoriel1, PlasmaTutoriel1)

1. endif

QRectF boundingRect()

La fonction boundingRect() indique à Plasma la taille effective du plasmoide. 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 plasmoide 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 plasmoide à l'écran. C'est ici que vous définissez l'apparence de votre plasmoide. Vous ne devriez dessiner que dans les limites définies par contentsRect et éviter d'utiliser geometry(). Lorsqu'un plasmoide 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, "Aucun Monde pour dire Bonjour");
   }

}

void PlasmaTutoriel1::paintInterface(QPainter *p,

       const QStyleOptionGraphicsItem *option, const QRect &contentsRect)

{

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

   // Maintenant, nous allons dessiner l'applet, en commençant par notre SVG
   m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
   m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());

   // Nous plaçons 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 votre applet semble ne pas se charge, cela peut re dû à une différence entre cette déclaration et votre 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 vous pouvez le voir dans cet exemple, nous utilisons un objet Plasma::Svg. Quelques points importants sont à noter ici.

Tout d'abord, nous utilisons 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 personaliser l'apparence de Plasma. Chacun des plasmoides 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. Si vous l'ouvrez, vous constaterz qu'il est constituté 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 5 fichiers séparés et de devoir 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 votre plasmoide, 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 notre exemple, notre dialogue avec Plasma se cantonne à lui parler de l'arrière plan et du fichier de configuration. Mais vous pouvez également fixer la taille initiale du plasmoide. Une fois cela fait, Plasma s'occupera de tout changement de taille et vous n'aurez plus à vous en soucier. Dans la méthode init() , il faut initialiser tout ce qui doit l'être, comme, par exemple, lire et appliquer des données de configuration.

hasFailedToLaunch()

Si, pour une raison quelconque, l'applet ne parvient pas à démarrer (la library n'a pas pu être chargée, un pilot 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 votre applet ne parvient pas à démarrer, cette fonction vous 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 votre plasmoide 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 vous souhaitez vous connecter aux DataEngines de Plasma, vous pouvez implémenter la méthode dataUpdated dans votre plasmoide. Lorsqu'un DataEngine est directement connecté à la sous-classe de votre Applet, dataUpdated sera appelée à chaque fois que le DataEngine vous enverra des données mises à jour.

Determine the applet size and geometry: geometry() and contentsRect()

Si votre applet a besoin de connaître quelles sont sa taille et sa géométrie, utilisez contentsRect() et contentsRect().size(). Evitez 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. Evitez également d'utiliser des coordonnées absolues pour positionner les éléments de l'applet, comme par exemple QPoint(0, 0) pour se référer au coin en haut à gauche de votre applet. A la place, il est préférable d'utiliser contentsRect().topLeft().

Building it all, the CMakeLists.txt

Finally, to put everything together you need to build everything. To tell cmake what needs to go where there is the CMakeLists.txt file.

For more details on CMake please read Development/Tutorials/CMake

1. Project Needs a name ofcourse

project(plasma-tutorial1)

1. Find the required Libaries

find_package(KDE4 REQUIRED) include(KDE4Defaults)

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

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

1. We add our source code here

set(tutorial1_SRCS plasma-tutorial1.cpp)

1. Now make sure all files get to the right place

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