Projects/SuperKaramba/FAQ

From KDE TechBase

Installation

How to install SuperKaramba

SuperKaramba is part of most Linux distributions as it is released with KDE 3.4 and later. On most distributions it can be found in a package named kdeutils (kdeutils3-extra on openSUSE not kde4-superkaramba!) or a special package named superkaramba (on K/Ubuntu).

If your distribution doesn't come with superkaramba or you want to install it manually you can find the source package here.

To compile the SuperKaramba package manually you will need the KDE development packages and the Python development packages. Both are shipped with your distribution. Beside that you will also need a working tool chain to be able to compile the sources. These will also come with your distribution.

Usage

How can themes be started automatically on start up?

To start themes automatically with the KDE start, you just need to keep SuperKaramba running with the desired themes when you log out of KDE. However this requires that KDE be configured to restore the previous session or a manually configured session. If KDE is configured to "Start with an empty session" upon login, use the Autostart directory method.

On some systems (e.g. openSUSE) or when KDE always starts with an empty session, this will not work. In this case you need to create a link to SuperKaramba in the Autostart directory of KDE (~/.kde/Autostart/).

For example, to autostart the fictitious "my.theme" create a file which is execute able called mytheme.desktop in ~/.kde/Autostart containing the following:

  [Desktop Entry]
  Comment=link to autostart My theme
  Exec=superkaramba ~/my.theme
  Name=My Cool Theme
  StartupNotify=false
  Type=Application

If you are running Compiz and find that this causes the superkaramba app to launch but not show the themes. After checking, of course, that the references to the theme are correct e.g. if you find superkaramba telling you that the theme is running but you can't see anything on the desktop, you may try removing the mytheme.desktop file from ~/.kde/Autostart and replacing it with a shell script called mytheme.sh containing the following:

  1. !/bin/bash

sleep 60 sh superkaramba <path_to_mytheme>/mytheme.theme

If your mytheme.theme is in your home directory this would be:

  1. !/bin/bash

sleep 60 sh superkaramba ~/mytheme.theme

Next make superkaramba.sh executable as follows:

  1. chmod +x ~/.kde/Autostart/superkaramba.sh

What this will do is allow compiz to get up and running before KDE tries to invoke the superkaramba launch.

How to run SuperKaramba themes inside Plasma

If you want to use SuperKaramba themes in Plasma you have to first run the theme at least once in SuperKaramba. After that the theme will appear in the Plasma Widget Browser like normal widgets do.

Problems

Themes can't be reinstalled with SuperKaramba

Delete the file ~/.kde/share/config/superkarambarc

Black Frame around Themes

You are probably trying to run SuperKaramba with a window manager (Fluxbox, GNOME) that isn't supported by SuperKaramba. Unfortunately SuperKaramba is currently limited to KDE due to the high integration into the KDE framework.

This also can happen on KDE when using a desktop background that is a plain color or a tiled image.

If you use openSUSE you probably installed the package kde4-superkaramba. Remove that package and install the kdeutils3-extra package. See How to install SuperKaramba

Themes don't refresh sensor values

You are probably trying to run SuperKaramba with a Window Manager (Fluxbox, GNOME) that isn't supported by SuperKaramba. Unfortunately SuperKaramba is currently limited to KDE due to the high integration into the KDE framework.

SuperKaramba gets minimized with the Show Desktop toggle

You are probably trying to run SuperKaramba with Compiz or Beryl. Unfortunately this is currently not fully supported with SuperKaramba. In Compiz-Fusion, the Fade to Desktop module is known to work better than the Show Desktop module.

SuperKaramba not below all other windows or on all desktops

Make sure that you are running KDE and not another window manager. If you are running Compiz-Fusion, while it is not supported, you can enable Compiz-Fusion's Window Rules module and enter a Window Match rule for the Below and Sticky entries as needed based on the name or class values (given in "Writing Compiz Window Match rules" below). As a last resort, try restarting X.

Or CompizConfig Settings Manager -> Utility -> Workarounds -> Check 'Make "on all desktops" windows "sticky"' and make sure '"On all desktops" sticky match' has a value of "all". YMMV ofanged1 ;)

Writing Compiz Window Match rules

Running SuperKaramba with Compiz, Beryl or the merged Compiz-Fusion project is not fully supported. However, it can be useful to use Window Match rules within Compiz to achieve the desired behavior. The following window matching rules are based off of xprop results for SuperKaramba. The most preferable rule to use for SuperKaramba specific behavior is either the name or the class rule. While the other rules will match SuperKaramba, it is easier for non-SuperKaramba windows to match as well.

(Note that Window Match rules are usually case-sensitive and cannot have spaces around the equals sign.)

  class=Superkaramba
  name=superkaramba
  type=dock
  title=superkaramba

Development

Where are themes config stored?

Themes configs are stored in ~/.superkaramba/

How to set sensors arguments from Python ?

Sensors arguments are set in the 'sensor' argument of function like setImageSensor(), setTextSensor(), etc...

Example:

txt = karamba.createText(widget, 0, 0, 200, 20, "")
karamba.setTextSensor(widget, txt, 'SENSOR=DISK MOUNTPOINT="/" FORMAT="Free space: %f MB"')
karamba.redrawWidget(widget)

Other Things

If your question wasn't answered, you need some additional help or you want to contribute to SuperKaramba. Feel free to join us at #superkaramba on irc.freenode.net.