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 or Ruby that are usually embedded directly into the background and do not disturb the normal view of the desktop.

Links

• Homepage
• Project Page
• Basic Tutorial for Theme Creators
• API
• Examples

Examples

A clock sample with Ruby and Python

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.

more infos at...

• Themes
• More Themes

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

def widgetClicked(widget, x, y, button):
    import Kross
    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

def widgetClicked(widget, x, y, button):
    import Kross
    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

Connect with 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

# The OpenDocument spreadsheet file to read.
filename = "/home/kde4/kspreaddocument.ods"

#this is called when your widget is initialized
def initWidget(widget):
    # Import Kross and fetch the KSpread module.
    import Kross
    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 = "<table>\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 += "<tr>"
            for r in record:
                text += "<td>%s</td>" % r
            text += "</tr>\n"
    text += "</table>\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)

more infos at...

• KWord Scripting
• KSpread Scripting
• Krita Scripting

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()

more infos at...

• Tkinter, Python interface to Tcl/Tk
• Python Tkinter
• An Introduction to Tkinter

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.

more infos at...

• Qt4 Ruby Tutorial
• Ruby Development Languages

FAQ

Where are store themes config ?

• Themes config are store in ~/.superkaramba/