Difference between revisions of "Development/Tutorials/Plasma4/GettingStarted (fr)"

Jump to: navigation, search
(Introduction)
m (Text replace - "</code>" to "</syntaxhighlight>")
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
'''Traduction en cours...'''
 
 
 
==Introduction==
 
==Introduction==
 
Pour compiler ce tutoriel il est nécessaire de disposer de KDE 4.2 (trunk).
 
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:
+
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 image SVG ;
* Une icone
+
* une icône  ;
* Un sympathique petit texte.
+
* un sympathique petit texte.
  
 
[[image:creatingyourfirstplasmoid1.png|frame|center]]
 
[[image:creatingyourfirstplasmoid1.png|frame|center]]
  
== Le Code ==
+
== Le code ==
 
=== Le fichier .desktop ===
 
=== Le fichier .desktop ===
Tout plasmoide doit fournir un fichier .desktop qui indique à Plasma comment le démarrer et comment il s'appelle.
+
Tout plasmoïde doit fournir un fichier .desktop qui indique à Plasma comment le démarrer et comment il s'appelle.
  
 
'''plasma-applet-tutoriel1.desktop'''
 
'''plasma-applet-tutoriel1.desktop'''
<code ini>
+
<syntaxhighlight lang="ini">
 
[Desktop Entry]
 
[Desktop Entry]
 
Name=Tutoriel 1
 
Name=Tutoriel 1
Line 33: Line 31:
 
X-KDE-PluginInfo-License=GPL
 
X-KDE-PluginInfo-License=GPL
 
X-KDE-PluginInfo-EnabledByDefault=true
 
X-KDE-PluginInfo-EnabledByDefault=true
</code>
+
</syntaxhighlight>
  
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 [[Projects/Plasma/PIG | PIG]] (en anglais).
+
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 [[Projects/Plasma/PIG | PIG]] (en anglais).
  
=== Le fichier d'entête ===
+
=== Le fichier d'en-tête ===
Voici le fichier d'entête de l'example. Des commentaires ont été ajoutés dans le code pour plus de clarté.
+
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'''
 
'''plasma-tutoriel1.h'''
<code cppqt>
+
<syntaxhighlight lang="cpp-qt">
// Ici, nous nous protégeons contre les inclusions multiples
+
// Ici, on se protège contre les inclusions multiples
 
#ifndef Tutoriel1_HEADER
 
#ifndef Tutoriel1_HEADER
 
#define Tutoriel1_HEADER
 
#define Tutoriel1_HEADER
// Nous avons besoin des entêtes d'Applet Plasma
+
// On a besoin des en-têtes d'applet Plasma
 
#include <KIcon>
 
#include <KIcon>
 
   
 
   
Line 53: Line 51:
 
class QSizeF;
 
class QSizeF;
 
   
 
   
// Définition de notre Applet Plasma
+
// Définition de l'applet Plasma
 
class PlasmaTutoriel1 : public Plasma::Applet
 
class PlasmaTutoriel1 : public Plasma::Applet
 
{
 
{
 
     Q_OBJECT
 
     Q_OBJECT
 
     public:
 
     public:
         // Constructeur et Destructeur simples
+
         // Constructeur et destructeur simples
 
         PlasmaTutorial1(QObject *parent, const QVariantList &args);
 
         PlasmaTutorial1(QObject *parent, const QVariantList &args);
 
         ~PlasmaTutorial1();
 
         ~PlasmaTutorial1();
 
   
 
   
         // La méthode paintInterface dessine l'applet à l'écran.
+
         // La méthode paintInterface dessine l'applet à l'écran
 
         void paintInterface(QPainter *painter,
 
         void paintInterface(QPainter *painter,
 
                 const QStyleOptionGraphicsItem *option,
 
                 const QStyleOptionGraphicsItem *option,
Line 73: Line 71:
 
};
 
};
  
// Cette commande fait le lien entre votre applet et le fichier .desktop
+
// Cette commande fait le lien entre l'applet et le fichier .desktop
 
K_EXPORT_PLASMA_APPLET(tutoriel1, PlasmaTutoriel1)
 
K_EXPORT_PLASMA_APPLET(tutoriel1, PlasmaTutoriel1)
 
   
 
   
 
#endif
 
#endif
</code>
+
</syntaxhighlight>
  
 
==== QRectF boundingRect() ====
 
==== QRectF boundingRect() ====
La fonction <tt>boundingRect()</tt> indique à Plasma la taille effective du plasmoide. Elles est importante car nous avons besoin de savoir quelle surface est occupée à l'écran.  
+
La fonction <tt>boundingRect()</tt> 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|
 
{{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().
+
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) ====
 
==== 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.
+
'''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 ===
 
=== Le véritable coeur du plasmoide ===
Line 93: Line 90:
  
 
'''plasma-tutoriel1.cpp'''
 
'''plasma-tutoriel1.cpp'''
<code cppqt>
+
<syntaxhighlight lang="cpp-qt">
 
#include "plasma-tutorial1.h"
 
#include "plasma-tutorial1.h"
 
#include <QPainter>
 
#include <QPainter>
Line 101: Line 98:
 
#include <plasma/svg.h>
 
#include <plasma/svg.h>
 
#include <plasma/theme.h>
 
#include <plasma/theme.h>
 
 
   
 
   
 
PlasmaTutoriel1::PlasmaTutorial1(QObject *parent, const QVariantList &args)
 
PlasmaTutoriel1::PlasmaTutorial1(QObject *parent, const QVariantList &args)
Line 109: Line 105:
 
{
 
{
 
     m_svg.setImagePath("widgets/background");
 
     m_svg.setImagePath("widgets/background");
     // Ceci nous amène l'arrière plan standard sur un plateau, gratuitement!
+
     // Ceci nous amène l'arrière-plan standard sur un plateau, gratuitement !
 
     setBackgroundHints(DefaultBackground);
 
     setBackgroundHints(DefaultBackground);
 
     resize(200, 200);
 
     resize(200, 200);
Line 129: Line 125:
 
     // Une petite démonstration de l'utilisation de la fonction '''setFailedToLaunch'''
 
     // Une petite démonstration de l'utilisation de la fonction '''setFailedToLaunch'''
 
     if (m_icon.isNull()) {
 
     if (m_icon.isNull()) {
         setFailedToLaunch(true, "Aucun Monde pour dire Bonjour");
+
         setFailedToLaunch(true, "Personne à qui dire bonjour");
 
     }
 
     }
 
}  
 
}  
 
   
 
   
 
   
 
   
void PlasmaTutorial1::paintInterface(QPainter *p,
+
void PlasmaTutoriel1::paintInterface(QPainter *p,
 
         const QStyleOptionGraphicsItem *option, const QRect &contentsRect)
 
         const QStyleOptionGraphicsItem *option, const QRect &contentsRect)
 
{
 
{
Line 140: Line 136:
 
     p->setRenderHint(QPainter::Antialiasing);
 
     p->setRenderHint(QPainter::Antialiasing);
 
   
 
   
     // Now we draw the applet, starting with our svg
+
     // Maintenant, on dessine l'applet, en commençant par le SVG
 
     m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
 
     m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
 
     m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());
 
     m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());
 
   
 
   
     // We place the icon and text
+
     // On place l'icône et le texte
 
     p->drawPixmap(7, 0, m_icon.pixmap((int)contentsRect.width(),(int)contentsRect.width()-14));
 
     p->drawPixmap(7, 0, m_icon.pixmap((int)contentsRect.width(),(int)contentsRect.width()-14));
 
     p->save();
 
     p->save();
Line 154: Line 150:
 
}
 
}
 
   
 
   
#include "plasma-tutorial1.moc"
+
#include "plasma-tutoriel1.moc"
</code>
+
</syntaxhighlight>
  
 
==== K_EXPORT_PLASMA_APPLET ( <name>, <class> ) ====
 
==== K_EXPORT_PLASMA_APPLET ( <name>, <class> ) ====
This is a small but very important part that links your classname to the applet name in the .desktop file. If your applet doesn't seem to get loaded, there may be a difference between this declaration and your .desktop file
+
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|
 
{{tip|
The K_EXPORT_PLASMA_APPLET adds "plasma_applet_", please pay attention to this when setting up your .desktop file to avoid a name difference
+
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 ====
 
==== Plasma/Svg ====
As you can see in the example code we are using the {{class|Plasma::Svg}} object, there are some important things to note here.
+
Comme on peut le voir dans cet exemple, on utilise un objet {{class|Plasma::Svg}}. Quelques points importants sont à noter ici.
  
First we're using a relative path '''widgets/background''' which causes {{class|Plasma::Svg}} to use {{class|Plasma::Theme}} to locate the SVG data. While {{class|Plasma::Svg}} does support loading arbitrary files when passed an absolute path, use relative paths from the theme as often as possible as it makes Plasma skinable and the individual plasmoids look like a combined whole instead of a group of separate unrelated applications. You can see a list of available image components on the [[Projects/Plasma/Theme|Plasma Theme page]].
+
Tout d'abord, on utilise un chemin relatif, '''widgets/background''', ce qui amène {{class|Plasma::Svg}} à utiliser {{class|Plasma::Theme}} pour localiser les données SVG. Bien que {{class|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 [[Projects/Plasma/Theme|page de thème Plasma]] (en anglais)
  
In either mode, {{class|Plasma::Svg}} can be used to draw a subset of the SVG file by passing it an element id that appears in the SVG document. As a good example, if you open the clock.svg file that ships with the default theme, you will see that it has a background, 3 handles (hour, minute and seconds) and a foreground (the glass). Due to the ability to put all the elements in one file the SVG file shows a clock. This is much nicer for artists compared to editing 5 separate files that they have to imagine on top of each other, and much nicer for performance as only one SVG renderer and one file read from disk is necessary.
+
Dans les deux cas, {{class|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) ====
 
==== setBackgroundHints(DefaultBackground) ====
Since drawing a background is a common function there is fast and easier way of doing it. By adding <tt>setBackgroundHints(DefaultBackground)</tt> to the code, the default Plasma background gets drawn behind your plasmoid. This not only saves you time and code, but creates a more consistent presentation for the user.
+
Comme le dessin de l'arrière plan est une fonction courante, il existe un moyen plus simple pour le faire. En ajoutant <tt>setBackgroundHints(DefaultBackground)</tt> 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.
  
==== The init() method ====
+
==== La méthode init() ====
In the constructor you only tell plasma about the background and configuration file if any. You also set the start size in the constructor. After that, plasma will take care of any resizing and you never have to worry about size. In the <tt>init()</tt> method you initialize everything that needs to be initialize such as reading config data for example.
+
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 <tt>init()</tt> , il faut initialiser tout ce qui doit l'être, comme lire et appliquer des données de configuration.
  
 
==== hasFailedToLaunch() ====
 
==== hasFailedToLaunch() ====
If for some reason, the applet fails to get up on its feet (the library couldn't be loaded, necessary hardware support wasn't found, etc..) this method returns true. Using this function gives your application a chance to cleanup before quiting.  
+
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) ====
 
==== setFailedToLaunch(bool, QString) ====
When your application is unable to start, this function allows you to inform Plasma and give an optional reason why. Plasma will then draw a standardized error interface to inform the user of the situation and your applet will not be called upon to do any drawing on its own from that point forward. If your plasmoid becomes more complex and depends on multiple factors this is the nicest way to cleanup.
+
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) ====
 
==== dataUpdated(const QString &source, const Plasma::DataEngine::Data &data) ====
If you would like to connect to any of Plasma's DataEngines, you can implement the dataUpdated method in your Plasmoid. When a DataEngine is connected directly to your Applet subclass, dtaUpdated will be called when the DataEngine sends you updated 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.
  
==== Determine the applet size and geometry: geometry() and contentsRect() ====
+
==== Déterminer la taille de l'applet et sa géométrie : geometry() et contentsRect() ====
If you need to know, in your applet code, what the applet size and geometry is, call contentsRect() and contentsRect().size(). Avoid calling geometry() and size() because they don't take into account the margin's size set by the applets default background.
+
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().
Also avoid using absolute numbers to position items in the applet like QPoint(0, 0) to indicate the top-left point of your applet, instead use contentsRect().topLeft().
+
  
=== Building it all, the CMakeLists.txt ===
+
=== Construction de l'applet, le fichier 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.  
+
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.
  
For more details on CMake please read [[Development/Tutorials/CMake]]
+
Pour plus de détails concernant CMake, référez-vous à [[Development/Tutorials/CMake]] (anglais).
  
<code bash>
+
<syntaxhighlight lang="bash">
# Project Needs a name ofcourse
+
# Le projet a besoin d'un nom, bien sûr
project(plasma-tutorial1)
+
project(plasma-tutoriel1)
  
# Find the required Libaries
+
# Trouve les bibliothèques requises
 
find_package(KDE4 REQUIRED)
 
find_package(KDE4 REQUIRED)
 
include(KDE4Defaults)
 
include(KDE4Defaults)
Line 210: Line 205:
 
   )
 
   )
  
# We add our source code here
+
# On insère les sources de notre code ici
 
set(tutorial1_SRCS plasma-tutorial1.cpp)
 
set(tutorial1_SRCS plasma-tutorial1.cpp)
  
# Now make sure all files get to the right place
+
# On s'assure que les fichiers vont au bon endroit
 
kde4_add_plugin(plasma_applet_tutorial1 ${tutorial1_SRCS})
 
kde4_add_plugin(plasma_applet_tutorial1 ${tutorial1_SRCS})
 
target_link_libraries(plasma_applet_tutorial1  
 
target_link_libraries(plasma_applet_tutorial1  
Line 223: Line 218:
 
install(FILES plasma-applet-tutorial1.desktop
 
install(FILES plasma-applet-tutorial1.desktop
 
         DESTINATION ${SERVICES_INSTALL_DIR})
 
         DESTINATION ${SERVICES_INSTALL_DIR})
</code>
+
</syntaxhighlight>
 +
 
 +
== 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''' :
 +
<syntaxhighlight lang="bash">
 +
plasmoidviewer applet_name
 +
</syntaxhighlight>
 +
On peut même visionner l'applet dans un petit bureau en utilisant la même application :
 +
<syntaxhighlight lang="bash">
 +
plasmoidviewer -c desktop applet_name
 +
</syntaxhighlight>
 +
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.

Revision as of 20:53, 29 June 2011

Contents

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.
Creatingyourfirstplasmoid1.png

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
X-KDE-PluginInfo-Email=bgrolleman@emendo-it.nl
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
#ifndef Tutoriel1_HEADER
#define Tutoriel1_HEADER
// On a besoin des en-têtes d'applet Plasma
#include <KIcon>
 
#include <Plasma/Applet>
#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)
 
#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.

Ktip.png
 
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

#include "plasma-tutorial1.h"
#include <QPainter>
#include <QFontMetrics>
#include <QSizeF>
 
#include <plasma/svg.h>
#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();
}
 
#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.

Ktip.png
 
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).

# Le projet a besoin d'un nom, bien sûr
project(plasma-tutoriel1)
 
# 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}
   )
 
# On insère les sources de notre code ici
set(tutorial1_SRCS plasma-tutorial1.cpp)
 
# 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

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.


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal