Development/Tutorials/SuperKaramba

SuperKaramba

Intro

SuperKaramba is a tool that allows one to easily create functionality enhancement modules on a KDE desktop. Such modules are interactive programs written in Python, Ruby or KDE JavaScript that are usually embedded directly into the background and do not disturb the normal view of the desktop.

Links

Homepage The homepage of SuperKaramba.
Project Page The projectpage on techbase.
API Reference of the scripting application programmer interface.
Examples Some examples SuperKaramba ships with.

Basic Tutorial for Theme Creators

Themes in SuperKaramba consist of two parts. A theme file that defines the shape and size of the theme, and possibly many other things and a script file that adds interactivity to the theme. Basically, whenever an event happens, such as the user clicking the mouse on your theme, a function is called in your script file to let you react to the event.

Creating the Theme File

The theme files, those files with the fileextension *.theme, are text files that contain layout information and information about the values that will be shown.

Commands, Meters and Sensors

A list of General Commands that you can put in your theme file. This includes tags that define the widget shape, set default fonts, and create click-areas that launch programs.
A list of Meters that you can put in your theme file. This includes meters display the values of sensors. Meters can auto-update.
A list of Sensors that you can put in your theme file. Sensors allow you to display system properties automatically. There are sensors to display the status of everything from memory use to the results of shell scripts

Samples

The simplest form of Karamba is to load a file containing the word karamba. This will give you a empty transparent window with the size 300x300. A better idea is to enter something like this in a file:

karamba x=30 y=30 w=400 h=200 interval=2000

This will bring up a window at 30,30 with the size 400x200, and the window will refresh every 2000 milliseconds = 2 seconds.

The graphics elements of Karamba are called meters. The meters can be connected to sensors. A sensor can get, e.g., the current CPU load, the uptime, the date, and a lot of other things. It is also possible to display the output of an external program in a meter.

Creating a meter is not that hard. A text label can be created by putting this line in the file:

text x=10 y=10 value="This is a test"

To add some more spice we connect a sensor to a meter:

text x=15 y=25 sensor=uptime

A graph that logs the CPU load can be made like this:

graph x=10 y=40 w=200 h=60 sensor=cpu

Adding an image (the path is either relative to the configuration file or an absolute path):

image x=10 y=270 path="picture.png"

An introduction to the format parameter:

text x=10 y=330 sensor=memory format="You have %tm MB memory"

Please note that only one meter per line in the configuration file is allowed. No spaces are allowed around the '=' characters.

Notes

In Karamba all the graphic elements inside one configuration file have the same refresh rate. So it could be wise to split up a configuration into smaller parts, if different parts need different refresh times. An area showing a log file, for example, probably does not need the same refresh rate as an area showing the CPU load. The refresh rate of the sensors can be set individually. Also Karamba does not work with backgrounds without a picture, i.e., solid color, gradient, or pattern. One can get around this bug by creating a transparent PNG image (the size can be 1x1 pixel) and selecting this as the background picture.

Creating the Script File

The script file adds interactivity to the theme and can be written using the Python, Ruby or the KDE JavaScript language.

Super-Quick Start

Make a theme file like described at the "Creating the Theme File" chapter above.
Download template.py or the template.rb script file, depending on what scripting language you like to use, and rename this file to match your theme file.
Fill in all the callbacks in the script file that you want to handle. The template files just contain all callbacks, but you can safly remove those you don't need or just leave them in.
Use the API Reference to know what commands to use to fill in the callbacks.
Finally save your script file and open your theme file in SuperKaramba to test it!

Regular Guide for "Mere Mortals"

Now lets add interactivity to your theme file. If you have not written a theme file yet, you need to do that first like described at the "Creating the Theme File" chapter above. It will define the size, location on screen, and other basic elements of your theme.

Event-based Programming

Now that you have a basic theme file, load it with SuperKaramba. If there is nothing defined in the theme file other than size and location, you will have made an empty, transparent square that might be hard to find on the desktop. Let's assume you have made a basic theme that just shows a few images in small area. To make your theme do anything interesting, it needs to be able to react to events.

Basically, an event is anything that can happen that SuperKaramba knows how to handle. Some examples are: the user moves or clicks the mouse, a new program is started on the desktop, a certain amount of time has passed, etc. So to make your theme do something, you add Python or Ruby scripting code to the event callback that corresponds to the event to which you want to react. This is not nearly as hard as it sounds.

First, you need the template.py or the template.rb template script file, depending on what scripting language you like to use. Download this file to where your theme file is. Now rename those just downloaded template file from template.py to mytheme.py or from template.rb to mytheme.rb where mytheme is the name of your theme. For example, if you wrote a coolbar.theme and like to use use Python, renamed the just downloaded template.py to coolbar.py and put it in the same directory as coolbar.theme.

Now, lets open up your coolbar.py (or coolbar.rb or whatever you named it to) scripting file. Look for the event callback that reacts to mouse movement. In the case you choosed Python as your prefered scripting language, it may look like this:

This gets called everytime our widget is clicked.
Notes
widget = reference to our widget
x = x position (relative to our widget)
y = y position (relative to our widget)
botton = button being held:
0 = No Mouse Button
1 = Left Mouse Button
2 = Middle Mouse Button
3 = Right Mouse Button, but this will never happen
because the right mouse button brings up the
Karamba menu.

def widgetMouseMoved(widget, x, y, button):

   #Warning: Don't do anything too intensive here since you don't
   #want to run complex piece of code everytime the mouse moves.
   pass

Notice how the template gives your instructions on what data each callback gives you. In this case, you can see that you will know the x and y co-ordinates of the mouse, the button being held down (if any), and a reference to your widget.

Delete the line that says pass and add in some code. This code will run whenever the mouse is moved over your widget. But you say, "What in the world am I supposed to write to make something happen?". Good question! Go on to the next section below!

How to "make stuff happen" from your script file

SuperKaramba has a powerful API (Application Programmer's Interface). This is just a fancy way of saying SuperKaramba has a bunch of special commands you can run from your Python or your Ruby scripting code to make something happen in your theme. All of the commands are listed in one big list:

The SuperKaramba API (or Function List)

Here is how the callback might look after you add some code to it: def widgetMouseMoved(widget, x, y, button):

   myText = karamba.getThemeText(widget, "mouseText")
   karamba.changeText(widget, myText, "mouse at %s:%s" % (x,y))

This Python scripting code simply changes the text called "mouseText" (which we defiend in our theme file) to tell us the current position of the mouse.

How did I know what parameters karamba.changeText() and karamba.getThemeText() used? How did I even know those functions existed in the first place? Well, thats what the API tells you. The API and the template.py or template.rb script file basically contain everything you could ever need to know to write your own theme.

Testing!

To test your new Python or Ruby scripting code, just open your theme file in SuperKaramba.

You DO NOT open your .py or .rb file in SuperKaramba! Open the .theme file and if a matching .py or .rb file is found, it will be automatically loaded.

You DO NOT need to compile your scripting code. SuperKaramba will do that automatically and tell you about any errors. In fact, you can't run your .py or .rb file directly in regular python because it doesn't know anything about the karamba.* functions. Those functions only exist inside of SuperKaramba's Python and Ruby interpreters. But you are for sure able to just use SuperKaramba as your interpreter direct from within the commandline. Just start SuperKaramba with something like: superkaramba ./coolbar.theme

To ease the development, SuperKaramba will automatically reload your theme when you save your changes to the theme file or the script file. This allows you to see your modifications immediately without reloading the theme manually.

Have fun making themes!

FAQ

Scripting Interpreter Backends

SuperKaramba uses the Kross scripting framework to provide scripting with Python, Ruby and JavaScript as described at the Interpreter plugins section.

Defining Python Source Code Encodings

As described at the Python Enhancement Proposal Defining Python Source Code Encodings it is recommed to start a python script file with following both lines:

!/usr/bin/env superkaramba-bin
coding: utf-8

The first line is the shebang that causes Unix-like operating systems to execute the script file using the SuperKaramba interpreter. You are then able to start the karamba script with; chmod 755 myKaramba.py ./myKaramba.py The second line defines that the script file is encoded with utf-8 or whatever the script fiel is actualy encoded in. This seems to be needed at least with Python >=2.5.

Script Samples

A clock with Ruby, Python and JavaScript

Let's take a look at one of them, the clock.rb theme written in Ruby. The theme just displays the current time in a RichText widget.

require 'karamba'

def initWidget(widget)

   Karamba.resizeWidget(widget, 300, 120)
   @richtext = Karamba.createRichText(widget, Time.now.to_s)
   Karamba.moveRichText(widget, @richtext, 10, 10)
   Karamba.setRichTextWidth(widget, @richtext, 280)
   Karamba.redrawWidget(widget)

end
def widgetUpdated(widget)

   Karamba.changeRichText(widget, @richtext, Time.now.to_s)
   Karamba.redrawWidget(widget)

end

The initWidget method will be called once if the widget got initialized. Here we setup the RichText widget where we display the current time in. The widgetUpdated will be called each second once (the interval is defined in the clock.theme themefile) and just updates the text display in the RichText widget with the new time.

Let's take a look at another theme. The text.py theme written in Python just displays some text widgets. We take this as example to create our own script, that does the same as the clock.rb above, that is to display the current time within a text widget.

import karamba, time

text = None

def initWidget(widget):

   text = karamba.createText(widget, 0, 20, 200, 20, "Text meter")

def widgetUpdated(widget):

   t = time.strftime("%Y-%M-%d %H:%M.%S")
   karamba.changeText(widget, text, t)

In the initWidget method we create our text widget that is updated once per second (or per interval as defined in the matching theme file) at the widgetUpdated method to display the new current time.

The clock.js sample provides us with the same sample written using the JavaScript language.

There we have the currentTime() function that returns the current time as string. That function is used within the initWidget() and the widgetUpdated() functions to display the current time within a textwidget. var text = 0;

function currentTime() {

   var now = new Date();
   var hours = now.getHours();
   hours = hours < 10 ? '0' + hours : hours;
   var mins = now.getMinutes();
   mins = mins < 10 ? '0' + mins : mins;
   var secs = now.getSeconds();
   secs = secs < 10 ? '0' + secs : secs;
   return hours + ':' + mins + '.' + secs;

}
function initWidget(widget) {

   text = karamba.createText(widget,0,20,200,20,currentTime());

}
function widgetUpdated(widget) {

   karamba.changeText(widget,text,currentTime());
   karamba.redrawWidget(widget)

}

See also...

Forms and Modules

Modules are libraries loaded on demand provided by Kross. One of them is the forms module that implements some basic dialog and widget functionality. To display just a simple messagebox or load widgets from a UI-file those module can be used within all supported scripting languages.

The following sample Python script demonstrates how to display a messagebox.

import karamba, Kross

def widgetClicked(widget, x, y, button):

   forms = Kross.module("forms")
   if button == 1: #left
       forms.showMessageBox("Information","Caption","Message")
   elif button == 2: #middle
       forms.showMessageBox("Error","Caption","Message")

While the next sample Python script displays a dialog with an embedded "Open File" widget.

import karamba, Kross

def widgetClicked(widget, x, y, button):

   forms = Kross.module("forms")
   dialog = forms.createDialog("MyDialog")
   dialog.setButtons("Ok|Cancel")
   openpage = dialog.addPage("Open","Open File","fileopen")
   openwidget = forms.createFileWidget(
       openpage, "kfiledialog:///openfile")
   openwidget.setMode("Opening")
   openwidget.setFilter("*.txt|Text Files\n*|All Files")
   result = dialog.exec_loop()
   if result:
       print openwidget.selectedFile()

For sure you are also able to use those handy UI-files the QtDesigner produces like demonstrated on the sample below.

import karamba, os, Kross

def widgetClicked(widget, x, y, button):

   forms = Kross.module("forms")
   dialog = forms.createDialog("Sample")
   infospage = dialog.addPage("Title","Caption","iconname")
   # the ui-file is in the same directory our script is in
   uifile = os.path.join(karamba.getThemePath(),"my.ui")
   infoswidget = forms.createWidgetFromUIFile(infospage, uifile)
   if dialog.exec_loop():
       # here we print the content of the in the ui-file defined
       # lineedit-widget that has the name MyLineEdit
       print infoswidget["MyLineEdit"].text

Control KSpread

The following sample uses KSpread to read a OpenDocument spreadsheet file and to display it within a table.

For this we are loading the KSpread Scripting library and control it. Compared to dbus we don't need a running KSpread instance but just load and use the library direct (so, you still need to have KSpread installed).

While the sample is written in Python, the other supported backends like Ruby are able to access the whole same rich API.

import karamba, Kross

The OpenDocument spreadsheet file to read.

filename = "/home/kde4/kspreaddocument.ods"

This is called when your widget is initialized

def initWidget(widget):

   # Fetch the KSpread module.
   kspread = Kross.module("kspread")
   if not kspread:
       raise "KSpread is not installed"
   # Try to open the file.
   if not kspread.openUrl(filename):
       raise "Failed to open %s" % filename
   # Get the sheet we like to display.
   sheet = kspread.sheetByName( kspread.sheetNames()[0] )

text = "

\n"
    # Iterate now through all cells on the sheet.
    for row in range(1, sheet.lastRow() + 1):
        # Put the content of the row into the record-list.
        record = []
        for col in range(sheet.lastColumn() + 1, 1, -1):
            value = sheet.text(col, row)
            if value or len(record) > 0:
                record.insert(0,value)
        # If the record has at least one cell print it.
        if len(record) > 0:
            text += ""
            for r in record:
                text += "" % r
            text += "\n"
    text += "%s

\n"

   # Create the richtext widget to display the text.
   richtext = karamba.createRichText(widget, text)
   karamba.moveRichText(widget, richtext, 10, 10)
   karamba.setRichTextWidth(widget, richtext, 345)
   karamba.redrawWidget(widget)

See also...

TkInter with Python

While you are able to use PyQt4 which not only does look nicer but also provides the nice Qt-API pythonized, you are also able to use the default toolkit Python comes with, that is TkInter.

The following sample just displays a TkInter "hello world" dialog if you click on the widget.

import karamba

def widgetClicked(widget, x, y, button):

   from Tkinter import *
   root = Tk()
   w = Label(root, text="Hello, world!")
   w.pack()
   root.mainloop()

See also...

QtRuby/Korundum with Ruby

The following sample script written in Ruby demonstrates that you are able to use QtRuby/Korundum within your Ruby scripts.

require 'karamba' require 'Qt'

class Dialog < Qt::Dialog

   def initialize
       super()
       self.windowTitle = 'Hello World'
   end

end
def widgetClicked(widget, x, y, button)

   dialog = Dialog.new
   dialog.exec

end

The script does implement only the widgetClicked function that got called if the user clicks on the widget. What we do within that function is to create an instance of the Dialog class that implements a QDialog using QtRuby and then execute that modal dialog.

See also...

DBus with Python

The following sample script written in Python just prints a list with services available via dbus;

import karamba, dbus

def initWidget(widget):

   bus = dbus.SystemBus()
   dbus_object = bus.get_object(
       'org.freedesktop.DBus','/org/freedesktop/DBus')
   dbus_iface = dbus.Interface(
       dbus_object, 'org.freedesktop.DBus')
   services = dbus_iface.ListNames()
   text = "".join( ["%s
" % s for s in services] )
   karamba.resizeWidget(widget, 520, 520)
   richtext = karamba.createRichText(widget, text)
   karamba.moveRichText(widget, richtext, 10, 10)
   karamba.setRichTextWidth(widget, richtext, 500)
   karamba.redrawWidget(widget)

While the following Python script uses dbus to display a list with all the devices accessible with HAL.

import karamba, dbus

def initWidget(widget):

   bus = dbus.SystemBus()
   dbus_object = bus.get_object(
       'org.freedesktop.Hal','/org/freedesktop/Hal/Manager')
   dbus_iface = dbus.Interface(
       dbus_object, 'org.freedesktop.Hal.Manager')
   devices = dbus_iface.GetAllDevices()
   text = "".join( ["%s
" % d for d in devices] )
   karamba.resizeWidget(widget, 520, 520)
   richtext = karamba.createRichText(widget, text)
   karamba.moveRichText(widget, richtext, 10, 10)
   karamba.setRichTextWidth(widget, richtext, 500)
   karamba.redrawWidget(widget)

See also...