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

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.

// 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);
// A small demonstration of the setFailedToLaunch function
bool Armageddon = false;
if (Armageddon) {
setFailedToLaunch(true,"No world to say hello");
}

// 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());

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

failedToLaunch()

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. If your plasmoid becomes more complex and depends on multiple factors this is the nicest way to cleanup.

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.