Development/Tutorials/Plasma4/GettingStarted

    From KDE TechBase
    Revision as of 04:05, 18 July 2007 by Bgrolleman (talk | contribs) (→‎Building it all, the CMakeLists.txt: - KDE4 automoc not needed anymore)
    The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
    Creating your first Plasmoid
    Tutorial Series   Plasma Tutorial
    Previous   C++, Qt, KDE4 development environment
    What's Next  
    Further Reading   CMake

    Abstract

    We're going to start creating a simple plasmoid in this tutorial, to keep things simple we will only create a static plasmoid, it will contain the following items.

    • SVG Background
    • Icon
    • Some nice text

    I seem to be unable to upload images to the wiki, example image

    The Code

    The .desktop file

    Every Plasmoid needs a .desktop file to tell plasma how they should be started, and what name they carry.

    plasma-applet-tutorial1.desktop [Desktop Entry] Encoding=UTF-8 Name=Tutorial 1 Comment=Plasma Tutorial 1 Type=Service ServiceTypes=Plasma/Applet

    X-KDE-Library=plasma_applet_tutorial1 X-KDE-PluginInfo-Author=Bas Grolleman [email protected] X-KDE-PluginInfo-Name=plasma_applet_tutorial1 X-KDE-PluginInfo-Version=0.1 X-KDE-PluginInfo-Website=http://plasma.kde.org/ X-KDE-PluginInfo-Category= X-KDE-PluginInfo-Depends= X-KDE-PluginInfo-License=GPL X-KDE-PluginInfo-EnabledByDefault=true

    The most important bits are the X-KDE-Library and X-KDE-PluginInfo-Name, they are the paste between your class and plasma, without it, nothing will start.

    The header file

    This is the example header file, I will add lot's of comment's in the code to explain everything.

    plasma-tutorial1.h // Here we avoid loading the header multiple times

    1. ifndef Tutorial1_HEADER
    2. define Tutorial1_HEADER

    // We need the Plasma Applet headers

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

    // Define our plasma Applet class PlasmaTutorial1 : public Plasma::Applet {

       Q_OBJECT
       public:
           // Basic Create/Destroy
           PlasmaTutorial1(QObject *parent, const QStringList &args);
           ~PlasmaTutorial1();
    
           // This function returns the size of your applet
           QRectF boundingRect() const;
           // The paintInterface procedure paints the applet to screen
           void paintInterface(QPainter *painter,
                   const QStyleOptionGraphicsItem *option,
                   QWidget *widget =0);
       private:
           Plasma::Svg m_tutorial_theme;
           KIcon m_tutorial_icon;
    

    };

    // This is the command that links your applet to the .desktop file K_EXPORT_PLASMA_APPLET(tutorial1, PlasmaTutorial1)

    1. endif

    QRectF boundingRect()

    The boundingRect() function tells plasma the actual size of the plasmoid, this is important because we need to know how much space is taken on screen.

    Tip
    If you have issues with your plasmoid leaving pixels behind when dragging this is almost always a result of a incorrect boundingRect()


    void paintInterface(...)

    You could call this the main function, since this paints the plasmoid on screen, here you define how you want your plasmoid to look.

    K_EXPORT_PLASMA_APPLET ( <name>, <class> )

    This is a small but very important part, this links your classname to the applet name in the .desktop file, if your applet doesn't seem to be loaded than chances are there is a difference between this 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


    The actual work file

    Here is the body of the function, again with a lot of comments in between.

    plasma-tutorial1.cpp

    1. include "plasma-tutorial1.h"
    2. include <QPainter>
    3. include <QFontMetrics>

    PlasmaTutorial1::PlasmaTutorial1(QObject *parent,

           const QStringList &args)
       : Plasma::Applet(parent, args),
       // This creates the "non-pointer" objects
       m_tutorial_theme("widgets/background",this),
       m_tutorial_icon("document")
    

    {

       // First we create the objects to hold the icon and
       // background image
       // TIP: Read the section about setDrawStandardBackground(true)
       // m_tutorial_theme = new Plasma::Svg("widgets/background",this);
       // m_tutorial_icon = new KIcon("document");
       // Tell the Plasma/Svg object to use the whole image, instead
       // of parts of it.
       m_tutorial_theme.setContentType(Plasma::Svg::SingleImage);
    

    }

    PlasmaTutorial1::~PlasmaTutorial1() { }

    QRectF PlasmaTutorial1::boundingRect() const {

       // In this tutorial we use a fixed size
       return QRectF(0,0,128,128);
    

    }

    void PlasmaTutorial1::paintInterface(QPainter *p,

           const QStyleOptionGraphicsItem *option, QWidget *widget)
    

    {

       // Now we draw the applet, starting with the background
       m_tutorial_theme.resize(
               (int)boundingRect().width(),(int)boundingRect().height());
       m_tutorial_theme.paint(p,
               (int)boundingRect().left(),(int)boundingRect().top());
    
       // The we place the icon and text
       p->drawPixmap(20, 0,
               m_tutorial_icon.pixmap((int)boundingRect().width()-40));
       p->save();
       p->setPen(Qt::white);
       p->drawText(boundingRect(),Qt::AlignBottom+Qt::AlignHCenter,
               "Hello Plasmoid!");
       p->restore();
    

    }

    1. include "plasma-tutorial1.moc"

    Plasma/Svg

    As you can see in the example code where using the Plasma::Svg object, there are some important things to note here. First we're using a relative path widgets/background, trying to do this as often as possible as it will make plasma skinable and make the plasmoids look like a combined whole instead of a group of separate unrelated applications.

    Second is something we didn't use here, Plasma/Svg can draw a subset of an svg file, this is usefull since we only require a single .svg file to hold all images. For a good example I would suggest opening the clock .svg, you will see that it has a background, 3 handles (hour, minute and seconds) and a foreground (the glass). Now because of the ability to put this all in one file the .svg file shows a clock, and this is much nicer than 5 separate files that you have to imagine on top of eachother.

    setDrawStandardBackground(bool)

    In this tutorial I show you how to draw your own SVG background, but since this is a common function there is a much faster and easier way of doing it. By adding setDrawStandardBackground(true) to the creation function the default plasma background image get's placed behind your plasmoid. We will use this function instead of doing it by hand in the following tutorials

    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

      plasma ${KDE4_KIO_LIBS}
      )
    

    set_target_properties(plasma_applet_tutorial1

      PROPERTIES VERSION 1.0.0 SOVERSION 1
      )
    

    install(

      TARGETS plasma_applet_tutorial1
      DESTINATION ${PLUGIN_INSTALL_DIR}
      )
    

    install(

      FILES plasma-applet-tutorial1.desktop
      DESTINATION ${SERVICES_INSTALL_DIR}
      )