Plama Wallpaper Tutorial 2 - Configuration

Introduction

In the previous tutorial we made a simple wallpaper where we had some blue text saying 'Hello World'. In this tutorial we will add some configuration options to our wallpaper so that the user can change the colors, text and font of the wallpaper.

Adding Configuration Options

There are 4 steps to adding configuration options to our wallpaper:

Decide what should be configurable.

Add code to load and save configurations.

Design the interface of the configuration dialog.

Add code to show the configuration interface.

Step 1: Decide what should be configurable

As we said above we want the user to be able to change:

The text and background color

The font of the text

The text itself

So we will need to add variables to our Tutorial class to keep track of these. So change tutorial.h to look like the following:

Tutorial::init(), gets called whenever the wallpaper needs to reload it's configurations. In there we use config.readEntry() to read each entry from our configuration file. The first argument of config.readEntry() is the name of the configuration entry. The second argument is the initial value for when we do not have that entry. config.readEntry() will try to read the value for the entry in our config file, if it can't it will use the initial value, and return it.

After we finish loading our config options, we repaint the screen by emitting the update() signal on our entire wallpaper.

In Tutorial::save() we write our variables back into the config file.

Note that we did not have to specify a location or name for our config file. Plasma will automatically handle that for us. All we need to worry about is reading and writing the entries we are interested in. If you are curious you can see what these configuration files look like at $HOME/.kde4/share/config/plasma-desktop-appletsrc.

Step 3: Design the interface of the configuration dialog

We will now design the interface that will be presented to the user when they try to configure our wallpaper. We can do this using Qt Designer. I will not go into the details of how to make interfaces in this tutorial. For help you can refer to the Qt Designer Manual.

When creating a new form in Designer, choose the 'Widget' option. Change the name of the form/QWidget to 'Config'. Now we can make labels and widgets for each of our configuration options. Make sure to give meaningful names to the widgets, for example textString for the line edit.

Also we will need to lay it out nicely. The end result might look something like this:

Save the interface in our wallpaper directory as 'config.ui'.

We also need to add our config file to our CMakeLists.txt. Add the following line to CMakeLists.txt:

In createConfigurationInterface() we put our configuration interface on a new QWidget. Then we set each of the widgets in the interface to their appropriate values. Then we connect each widget's change signal to our settingsModified() slot. This will cause settingsModified() to be called whenever any widget's value is changed in our interface. Next we connect our settingsChanged(bool) signal to our parents settingsChanged(bool) so that the dialog containing our interface can react to the change (by enabling it's 'Apply' button for example). Finally we return the widget so that it can be displayed in the dialog.

In settingsModified() we get the values from our widgets and put them in our variables. We then call settingsChanged(bool) so that the parent dialog can react. Then we repaint our entire wallpaper.