View source for Development/Tutorials/SuperKaramba

==SuperKaramba==

===Intro===

[http://netdragon.sourceforge.net SuperKaramba] is a tool that allows one to easily create functionality enhancement modules on a [http://www.kde.org KDE desktop]. Such modules are interactive programs written in [http://www.python.org Python] or [http://www.ruby-lang.org/ Ruby] that are usually embedded directly into the background and do not disturb the normal view of the desktop.

===Links===

* [http://netdragon.sourceforge.net Homepage]
* [[Projects/SuperKaramba|Project Page]]
* [[Projects/SuperKaramba/API|API]]
* [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/ Examples]

==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.

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:
<pre>
karamba x=30 y=30 w=400 h=200 interval=2000
</pre>
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:
<pre>
text x=10 y=10 value="This is a test"
</pre>
To add some more spice we connect a sensor to a meter:
<pre>
text x=15 y=25 sensor=uptime
</pre>
A graph that logs the CPU load can be made like this:
<pre>
graph x=10 y=40 w=200 h=60 sensor=cpu 
</pre>
Adding an image (the path is either relative to the configuration file or an absolute path):
<pre>
image x=10 y=270 path="picture.png"
</pre>
An introduction to the format parameter:
<pre>
text x=10 y=330 sensor=memory format="You have %tm MB memory"
</pre>

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.

See also...
# A list of [http://netdragon.sourceforge.net/sgeneral.html 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 [http://netdragon.sourceforge.net/smeters.html Meters] that you can put in your theme file. This includes meters display the values of sensors. Meters can auto-update.
# A list of [http://netdragon.sourceforge.net/ssensors.html 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

===Creating the Script File===

The script file adds interactivity to the theme and can be written using the [http://www.python.org Python] or the [http://www.ruby-lang.org/ Ruby] language.

====Super-Quick Start====
# Make a theme file like described at the "Creating the Theme File" chapter above.
# Download [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/template.py template.py] or the [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/template.rb 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 [[Projects/SuperKaramba/API|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 [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/template.py template.py] or the [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/template.rb 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:

<pre>
#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
</pre>

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:
* [[Projects/SuperKaramba/API|The SuperKaramba API (or Function List)]]

Here is how the callback might look after you add some code to it:
<pre>
def widgetMouseMoved(widget, x, y, button):
    myText = karamba.getThemeText(widget, "mouseText")
    karamba.changeText(widget, myText, "mouse at %s:%s" % (x,y))
</pre>

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 [[Projects/SuperKaramba/API|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:
<pre>
superkaramba ./coolbar.theme
</pre>

Have fun making themes!

==Script Samples==

===A clock with Ruby and Python===

Let's take a look at one of them, the 
[http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/rubyclock/clock.rb?view=markup clock.rb]
theme written in Ruby. The theme just displays the current time in a RichText widget.

<pre>
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
</pre>

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 [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/rubyclock/clock.theme?view=markup 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 [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/text/text.py?view=markup 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 [http://websvn.kde.org/trunk/KDE/kdeutils/superkaramba/examples/rubyclock/clock.rb?view=markup clock.rb] above, that is to display the current time within a text widget.

<pre>
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)
</pre>

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.

See also...
* [http://www.kde-look.org/index.php?xcontentmode=38 Themes]
* [http://www.biodesign.com.ar/blog/?cat=2 More Themes]

===Forms and Modules===

Modules are libraries loaded on demand provided by Kross. One of them is the [http://websvn.kde.org/trunk/KDE/kdelibs/kross/modules/form.h?view=markup 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.

<pre>
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")
</pre>

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

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

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

<pre>
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
</pre>

===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 [[Development/Tutorials/KSpread_Scripting|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.

<pre>
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)
</pre>

See also...
* [[Development/Tutorials/KWord_Scripting|KWord Scripting]]
* [[Development/Tutorials/KSpread_Scripting|KSpread Scripting]]
* [[Development/Tutorials/Krita_Scripting|Krita Scripting]]

===TkInter with Python===

While you are able to use [http://www.riverbankcomputing.co.uk/pyqt/ 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.

<pre>
import karamba

def widgetClicked(widget, x, y, button):
    from Tkinter import *
    root = Tk()
    w = Label(root, text="Hello, world!")
    w.pack()
    root.mainloop()
</pre>

See also...
* [http://docs.python.org/lib/module-Tkinter.html Tkinter, Python interface to Tcl/Tk]
* [http://wiki.python.org/moin/TkInter Python Tkinter]
* [http://www.pythonware.com/library/tkinter/introduction/ An Introduction to Tkinter]

===QtRuby/Korundum with Ruby===

The following sample script written in Ruby demonstrates that you are able to use [http://rubyforge.org/projects/korundum/ QtRuby/Korundum] within your Ruby scripts.

<pre>
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
</pre>

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...
* [[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
* [[Development/Languages/Ruby|Ruby Development Languages]]