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 PlasmaTutorial1::paintInterface(QPainter *p,

           const QStyleOptionGraphicsItem *option, const QRect &contentsRect)
    

    {

       p->setRenderHint(QPainter::SmoothPixmapTransform);
       p->setRenderHint(QPainter::Antialiasing);
    
       // Now we draw the applet, starting with our svg
       m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
       m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());
    
       // We place the icon and text
       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-tutorial1.moc"

    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

    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


    Plasma/Svg

    As you can see in the example code we are using the Plasma::Svg object, there are some important things to note here.

    First we're using a relative path widgets/background which causes Plasma::Svg to use Plasma::Theme to locate the SVG data. While 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 Plasma Theme page.

    In either mode, 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.

    setBackgroundHints(DefaultBackground)

    Since drawing a background is a common function there is fast and easier way of doing it. By adding setBackgroundHints(DefaultBackground) 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.

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