Development/Tutorials/Plasma4/WallpaperHelloWorld: Difference between revisions

From KDE TechBase
(Added screenshot at the beginning)
 
(13 intermediate revisions by 5 users not shown)
Line 9: Line 9:
This tutorial will show you how to make a basic plasma wallpaper that draws a message to the screen.
This tutorial will show you how to make a basic plasma wallpaper that draws a message to the screen.


To compile the wallpaper you will need to have the kdebase workspace development files installed on your system. On debian based systems you can type:
To compile the wallpaper you will need to have the kdebase workspace development files installed on your system.


<code bash>
On ubuntu/debian systems you can type in the terminal:
<syntaxhighlight lang="bash">
sudo apt-get install kdebase-workspace-dev
sudo apt-get install kdebase-workspace-dev
</code>
</syntaxhighlight>
openSUSE:
<syntaxhighlight lang="bash">
sudo zypper install kdebase4-workspace-devel
</syntaxhighlight>


This tutorial assumes that you are using KDE 4.3. Some parts of this tutorial may not work with older versions.
This tutorial assumes that you are using KDE 4.3 or newer. Some parts of this tutorial may not work with older versions.


== Setting Up ==
== Setting Up ==
Before we get coding we need to set up some files for our wallpaper. Create a directory called plasma-wallpaper-tutorial-1. Inside it create a file called plasma-wallpaper-tutorial1.desktop. A .desktop file contains information about the wallpaper such as it's name, author, etc. Copy the following into the file:
Before we get coding we need to set up some files for our wallpaper. Create a directory called plasma-wallpaper-tutorial. Inside it create a file called plasma-wallpaper-tutorial.desktop. A .desktop file contains information about the wallpaper such as its name, author, etc. Copy the following into the file:


<code ini>
<syntaxhighlight lang="ini">
[Desktop Entry]
[Desktop Entry]
Name=Tutorial 1
Name=Tutorial
Type=Service
Type=Service
Icon=image-jpeg
Icon=image-jpeg
ServiceTypes=Plasma/Wallpaper
ServiceTypes=Plasma/Wallpaper


X-KDE-Library=plasma_wallpaper_tutorial1
X-KDE-Library=plasma_wallpaper_tutorial
X-KDE-PluginInfo-Author=My Name
X-KDE-PluginInfo-Author=My Name
X-KDE-PluginInfo-Name=tutorial1
X-KDE-PluginInfo-Name=tutorial
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Website=http://plasma.kde.org/
Line 36: Line 41:
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true  
X-KDE-PluginInfo-EnabledByDefault=true  
</code>
</syntaxhighlight>


Next we will make a CMakeLists.txt file that contains information about how to compile this project. Copy the following into your CMakeLists.txt file:
Next we will make a CMakeLists.txt file that contains information about how to compile this project. Copy the following into your CMakeLists.txt file:


<code cmake>
<syntaxhighlight lang="cmake">
project(plasma-wallpaper-tutorial1)
project(plasma-wallpaper-tutorial)


find_package(KDE4 REQUIRED)
find_package(KDE4 REQUIRED)
Line 50: Line 55:
include_directories(${CMAKE_SOURCE_DIR} ${CMAKE_BINARY_DIR} ${KDE4_INCLUDES})
include_directories(${CMAKE_SOURCE_DIR} ${CMAKE_BINARY_DIR} ${KDE4_INCLUDES})


set(tutorial1_SRCS
set(tutorial_SRCS
     tutorial1.cpp
     tutorial.cpp
)
)


kde4_add_plugin(plasma_wallpaper_tutorial1 ${tutorial1_SRCS})
kde4_add_plugin(plasma_wallpaper_tutorial ${tutorial_SRCS})
target_link_libraries(plasma_wallpaper_tutorial1 ${KDE4_PLASMA_LIBS})
target_link_libraries(plasma_wallpaper_tutorial ${KDE4_PLASMA_LIBS})


install(TARGETS plasma_wallpaper_tutorial1 DESTINATION ${PLUGIN_INSTALL_DIR})
install(TARGETS plasma_wallpaper_tutorial DESTINATION ${PLUGIN_INSTALL_DIR})
install(FILES plasma-wallpaper-tutorial1.desktop DESTINATION ${SERVICES_INSTALL_DIR})
install(FILES plasma-wallpaper-tutorial.desktop DESTINATION ${SERVICES_INSTALL_DIR})
</code>
</syntaxhighlight>


The CMakeLists.txt file tells us what packages are required to compile this project, what source files we have, what libraries we need to link to and what files to install.
The CMakeLists.txt file tells us what packages are required to compile this project, what source files we have, what libraries we need to link to and what files to install.
Line 66: Line 71:


== Code ==
== Code ==
First make a file called tutorial1.h. Copy the following into the file:
First make a file called tutorial.h. Copy the following into the file:


<code cpp>
<syntaxhighlight lang="cpp">
#ifndef PLASMA_WALLPAPER_TUTORIAL1
#ifndef PLASMA_WALLPAPER_TUTORIAL
#define PLASMA_WALLPAPER_TUTORIAL1
#define PLASMA_WALLPAPER_TUTORIAL


#include <Plasma/Wallpaper>
#include <Plasma/Wallpaper>


class Tutorial1 : public Plasma::Wallpaper
class Tutorial : public Plasma::Wallpaper
{
{
     Q_OBJECT
     Q_OBJECT
     public:
     public:
         Tutorial1(QObject* parent, const QVariantList& args);
         Tutorial(QObject* parent, const QVariantList& args);


         void paint(QPainter* painter, const QRectF& exposedRect);
         void paint(QPainter* painter, const QRectF& exposedRect);
};
};


K_EXPORT_PLASMA_WALLPAPER(tutorial1, Tutorial1)
K_EXPORT_PLASMA_WALLPAPER(tutorial, Tutorial)


#endif
#endif
</code>
</syntaxhighlight>


Every plasma wallpaper has to inherit from Plasma::Wallpaper. We have to add a Q_OBJECT since it inherits a QObject. The constructor will be used to intialize our wallpaper. The paint function is where we will draw our wallpaper. Finally the K_EXPORT_PLASMA_WALLPAPER macro tells us that the class Tutorial1 will make a wallpaper plugin called tutorial1.
Every plasma wallpaper has to inherit from Plasma::Wallpaper. We have to add a Q_OBJECT since it inherits a QObject. The constructor will be used to intialize our wallpaper. The paint function is where we will draw our wallpaper. Finally the K_EXPORT_PLASMA_WALLPAPER macro tells us that the class 'Tutorial' will make a wallpaper plugin called 'tutorial'.


Now make another file called tutorial1.cpp. Put the following code inside it:
Now make another file called tutorial.cpp. Put the following code inside it:


<code cpp>
<syntaxhighlight lang="cpp">
#include <QPainter>
#include <QPainter>


#include "tutorial1.h"
#include "tutorial.h"


Tutorial1::Tutorial1(QObject *parent, const QVariantList &args)
Tutorial::Tutorial(QObject *parent, const QVariantList &args)
         : Plasma::Wallpaper(parent, args)
         : Plasma::Wallpaper(parent, args)
{
{
}
}


void Tutorial1::paint(QPainter *painter, const QRectF& exposedRect)
void Tutorial::paint(QPainter *painter, const QRectF& exposedRect)
{
{
    painter->setPen(Qt::white);
     painter->setBrush(Qt::white);
     painter->setBrush(Qt::white);
     painter->drawRect(boundingRect());
     painter->drawRect(boundingRect());
Line 112: Line 118:
}
}


#include "tutorial1.moc"
#include "tutorial.moc"
</code>
</syntaxhighlight>


We leave the constructor blank for now and just pass the arguments to the Plasma::Walllpaper.
We leave the constructor blank for now and just pass the arguments to the Plasma::Wallpaper.


The paint function is where we draw our wallpaper. It has two arguments: the first is a QPainter which to draw with, and the second is a QRectF telling us which part of the wallpaper needs to be repainted. For now we will ignore exposedRect.
The paint function is where we draw our wallpaper. It has two arguments: the first is a QPainter which to draw with, and the second is a QRectF telling us which part of the wallpaper needs to be repainted. For now we will ignore exposedRect.
Line 123: Line 129:
Next we draw some big, blue text in the middle of the screen.
Next we draw some big, blue text in the middle of the screen.


Finally at the end of the file we include the tutorial1.moc file that gets generated from our tutorial1.h.
Finally at the end of the file we include the tutorial.moc file that gets generated from our tutorial.h.


== Compiling ==
== Compiling ==
We will compile our wallpaper inside a directory called build. Type the following inside the terminal:
We will compile our wallpaper inside a directory called build. Type the following inside the terminal:


<code bash>
<syntaxhighlight lang="bash">
mkdir -p build
mkdir -p build
cd build
cd build
Line 134: Line 140:
make
make
sudo make install
sudo make install
</code>
</syntaxhighlight>


The cmake command will generate Makefiles by using the information in our CMakeLists.txt file. We set the install directory to the output of `kde4-config --prefix` which is usually something like /usr.
The cmake command will generate Makefiles by using the information in our CMakeLists.txt file. We set the install directory to the output of `kde4-config --prefix` which is usually something like /usr.
Line 143: Line 149:
To see our wallpaper we can use a tool called plasmawallpaperviwer. To run our wallpaper type the following inside the terminal:
To see our wallpaper we can use a tool called plasmawallpaperviwer. To run our wallpaper type the following inside the terminal:


<code bash>
<syntaxhighlight lang="bash">
plasmawallpaperviewer -p tutorial1
plasmawallpaperviewer -p tutorial
</code>
</syntaxhighlight>


Alternatively you can run the wallpaper inside your actual desktop. You may need to restart plasma first by logging out or running the following command:
Alternatively you can run the wallpaper inside your actual desktop. You may need to restart plasma first by logging out or running the following command:


<code bash>
<syntaxhighlight lang="bash">
kquitapp plasma-desktop && plasma-desktop
kquitapp plasma-desktop; sleep 1; plasma-desktop
</code>
</syntaxhighlight>


Now right click on your desktop, go to Desktop Settings>Category and select Tutorial 1.
Now right click on your desktop, go to Desktop Settings>Wallpaper>Type and select 'Tutorial'.


Congratulations! You have just made your very first plamsa wallpaper!
Congratulations! You have just made your very first plamsa wallpaper!
Line 159: Line 165:
You can try changing the code inside the paint function to whatever you want. The QPainter class has many functions that allow you to draw draw images, text and shapes.
You can try changing the code inside the paint function to whatever you want. The QPainter class has many functions that allow you to draw draw images, text and shapes.


In the next tutorial we will add some configuration options to our wallpaper.
In the [[Development/Tutorials/Plasma/WallpaperConfiguration|next tutorial]] we will add some configuration options to our wallpaper.

Latest revision as of 23:27, 11 September 2014

Plama Wallpaper Tutorial 1 - Hello World

Introduction

The plasma desktop allows different kinds of plugins to be used as wallpapers. Unlike normal wallpapers, these wallpapers can be configurable and also be animated.

This tutorial will show you how to make a basic plasma wallpaper that draws a message to the screen.

To compile the wallpaper you will need to have the kdebase workspace development files installed on your system.

On ubuntu/debian systems you can type in the terminal:

sudo apt-get install kdebase-workspace-dev

openSUSE:

sudo zypper install kdebase4-workspace-devel

This tutorial assumes that you are using KDE 4.3 or newer. Some parts of this tutorial may not work with older versions.

Setting Up

Before we get coding we need to set up some files for our wallpaper. Create a directory called plasma-wallpaper-tutorial. Inside it create a file called plasma-wallpaper-tutorial.desktop. A .desktop file contains information about the wallpaper such as its name, author, etc. Copy the following into the file:

[Desktop Entry]
Name=Tutorial
Type=Service
Icon=image-jpeg
ServiceTypes=Plasma/Wallpaper

X-KDE-Library=plasma_wallpaper_tutorial
X-KDE-PluginInfo-Author=My Name
X-KDE-PluginInfo-Email=[email protected]
X-KDE-PluginInfo-Name=tutorial
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org/
X-KDE-PluginInfo-Depends=
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true

Next we will make a CMakeLists.txt file that contains information about how to compile this project. Copy the following into your CMakeLists.txt file:

project(plasma-wallpaper-tutorial)

find_package(KDE4 REQUIRED)
find_package(KDE4Workspace REQUIRED)
include(KDE4Defaults)

add_definitions(${KDE4_DEFINITIONS})
include_directories(${CMAKE_SOURCE_DIR} ${CMAKE_BINARY_DIR} ${KDE4_INCLUDES})

set(tutorial_SRCS
    tutorial.cpp
)

kde4_add_plugin(plasma_wallpaper_tutorial ${tutorial_SRCS})
target_link_libraries(plasma_wallpaper_tutorial ${KDE4_PLASMA_LIBS})

install(TARGETS plasma_wallpaper_tutorial DESTINATION ${PLUGIN_INSTALL_DIR})
install(FILES plasma-wallpaper-tutorial.desktop DESTINATION ${SERVICES_INSTALL_DIR})

The CMakeLists.txt file tells us what packages are required to compile this project, what source files we have, what libraries we need to link to and what files to install.

Now that we have finished setting up, we can start on the code!

Code

First make a file called tutorial.h. Copy the following into the file:

#ifndef PLASMA_WALLPAPER_TUTORIAL
#define PLASMA_WALLPAPER_TUTORIAL

#include <Plasma/Wallpaper>

class Tutorial : public Plasma::Wallpaper
{
    Q_OBJECT
    public:
        Tutorial(QObject* parent, const QVariantList& args);

        void paint(QPainter* painter, const QRectF& exposedRect);
};

K_EXPORT_PLASMA_WALLPAPER(tutorial, Tutorial)

#endif

Every plasma wallpaper has to inherit from Plasma::Wallpaper. We have to add a Q_OBJECT since it inherits a QObject. The constructor will be used to intialize our wallpaper. The paint function is where we will draw our wallpaper. Finally the K_EXPORT_PLASMA_WALLPAPER macro tells us that the class 'Tutorial' will make a wallpaper plugin called 'tutorial'.

Now make another file called tutorial.cpp. Put the following code inside it:

#include <QPainter>

#include "tutorial.h"

Tutorial::Tutorial(QObject *parent, const QVariantList &args)
        : Plasma::Wallpaper(parent, args)
{
}

void Tutorial::paint(QPainter *painter, const QRectF& exposedRect)
{
    painter->setPen(Qt::white);
    painter->setBrush(Qt::white);
    painter->drawRect(boundingRect());

    painter->setPen(Qt::blue);
    painter->setFont(QFont("Arial", 50));
    painter->drawText(boundingRect(), Qt::AlignCenter, "Hello World!");
}

#include "tutorial.moc"

We leave the constructor blank for now and just pass the arguments to the Plasma::Wallpaper.

The paint function is where we draw our wallpaper. It has two arguments: the first is a QPainter which to draw with, and the second is a QRectF telling us which part of the wallpaper needs to be repainted. For now we will ignore exposedRect.

In the paint function we first draw a white rectangle that covers the whole wallpaper. The boundingRect() function returns the geometry of the wallpaper as a QRectF.

Next we draw some big, blue text in the middle of the screen.

Finally at the end of the file we include the tutorial.moc file that gets generated from our tutorial.h.

Compiling

We will compile our wallpaper inside a directory called build. Type the following inside the terminal:

mkdir -p build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix`
make
sudo make install

The cmake command will generate Makefiles by using the information in our CMakeLists.txt file. We set the install directory to the output of `kde4-config --prefix` which is usually something like /usr.

If everything went well then we should be able to view it.

Running the Wallpaper

To see our wallpaper we can use a tool called plasmawallpaperviwer. To run our wallpaper type the following inside the terminal:

plasmawallpaperviewer -p tutorial

Alternatively you can run the wallpaper inside your actual desktop. You may need to restart plasma first by logging out or running the following command:

kquitapp plasma-desktop; sleep 1; plasma-desktop

Now right click on your desktop, go to Desktop Settings>Wallpaper>Type and select 'Tutorial'.

Congratulations! You have just made your very first plamsa wallpaper!

You can try changing the code inside the paint function to whatever you want. The QPainter class has many functions that allow you to draw draw images, text and shapes.

In the next tutorial we will add some configuration options to our wallpaper.