Jump to content

Development/Tutorials/Plasma4/GettingStarted (fr)

From KDE TechBase

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)

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

Retrieved from "https://techbase.kde.org/index.php?title=Development/Tutorials/Plasma4/GettingStarted_(fr)&oldid=51634"