configuration dialogs

howto create configuration dialogs

Although superkaramba provides theme makers with a way to provide configuration options to users through the configuration dialog, for some themes, the configuration menu can be quite limiting. With a complex theme like liquid weather ++, a configuration dialog using a comprehensive gui toolkit becomes essential. Imagine trying to do this through a simple menu:

So what's the answer? Simple pyqt. Qt is the toolkit that underlies the kde desktop. It is a comprehensive gui toolkit that allows rapid application development and has great development tools to assist you. Furthermore, there are comprehensive and well maintained python bindings for qt, which means you can write your config dialog using the same language you use for your theme.

what this howto is and isn't

I am not going to write a comprehensive howto on pyqt. There are whole books written on the topic, and a whole bunch of tutorials available that should help you with that. This howto is to help you get a configuration dialog going for superkaramba, and should help you overcome some of the pitfalls I ran into, and ways to work around them. Often times, I will refer to useful articles on the topic, which are resources I found useful. Hopefully this tutorial together with the resources linked to will speed up your development of a config dialog for your theme. So on with the show...

it's all in the layout

Qt comes with a great tool for laying out your dialog and widgets called designer (just type "designer" into a terminal window, or the alt+f2 run dialog). The great thing about designer is that it helps you with layout. Qt has a great dynamic layout tool that organises widgets so that they are laid out nicely, and behave nicely when the dialog window is resized. If you want to have a professional looking dialog, which behaves nicely for your users, you should use the built in layouts. There is a really good tutorial on how to use the layout management in qt using the designer tool.

storing the configuration

Once you've run your configuration dialog, you'll want to store the configuration settings input by the user somewhere. Using superkaramba's tools can be problematic for a couple of reasons:

• superkaramba doesn't update its inbuilt configuration file until it closes or is reloaded, so if you want to access the updated configuration information while your theme is running, you have to store it elsewhere
• to write to the inbuilt configuration file, you have to import the karamba python module.

To get around these issues, I create a separate config file that stores all the configuration information that gets created by the configuration dialog. I store this in the ~/.superkaramba directory. It is sensible to use the ConfigParser python module. This provides useful tools for creating and reading configuration files.

When using the ConfigParser module within pyqt, you will have to remember that the .set() method expects a string. Often times the configuration information generated by qt widgets are integers - for example wither a checkbox is checked or not. To confuse the situation even further, when dealing with a pyqt widget states/objects, you need to specify the data type, otherwise pyqt gets grumpy. So to save a widget's state to the config file, you will need to use something like:

Obviously, you'll need to write all the config information to the config file when the config dialog is closed using an "OK" button, or when the "Apply" button is pressed (if you have one). You'll also need to read from the config file in the initWidget() callback and (if appropriate) in the widgetUpdated() callback. I would also suggest setting out all the configuration variables stored in the config file in the main part of your .py file before any other functions are set (so that they are in the global namespace), so that if they are not available in the config file, or this is the first time that the user has run the theme, all the necessary variables are set.

getting things going

There is a fishhook with getting the config dialog to actually run from a superkaramba theme. To start a pyqt application, you usually write something like this:

However, because there can only be one QApplication per application, and superkaramba itself is already using this, you can't launch the dialog from within your superkaramba theme. You need to call a separate python script containing the above code to do it. You can set the widget states for your config dialog in this script as well. Your code should end up looking something like this:

applying config changes interactively

The superkaramba developers in a recent update added a call to allow you to change the update interval of your theme from within the theme itself. This feature allows users to apply changes made in the config dialog interactively while the config dialog is still running. To do this, I use the karamba.executeInteractive() method to launch the config dialog. This allows you to execute a command which is run in a different thread to the theme itself, which means that the theme doesn't hang while waiting for the config dialog to be closed. At the same time, I increase the update interval of the theme to 1 second. I then make sure that the only command that runs in the widgetUpdated() callback while the config dialog is running is a command to check whether the config file has been updated. If it has, then the config file is read and all config variables are updated and the widget is reset (I have all the code necessary to reset the theme in a separate function, so that it is easy call whenever it's needed) using the new config information. On closing the config dialog, I change the theme update interval back to the usual interval under the commandOutput() callback, which runs when a karamba.executeInteractive()command is finished.

You can discuss this howto on the forums.

©2005 No Rights Reserved
Valid XHTML & CSS
email the webmaster
Content managed by the Etomite Content Management System.