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.

The init() method

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 init() method you initialize everything that needs to be initialize such as reading config data for example.

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.

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.

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.

Determine the applet size and geometry: geometry() and 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. 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

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