Basic Instructions for writing the .py file for your theme.

Super-Quick Start:

• Make a .theme file
• Download template.py and rename it to match your .theme file.
• Fill in all the callbacks in template.py that you want to handle.
• Use the API to know what commands to use to fill in the callbacks.
• Save your .py 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 haven't written a .theme file yet, you need to do that first. 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 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 python template that all themes use. Download this file to where your .theme file is. Now, rename template.py to mytheme.py where mytheme is the name of your theme. For example, if you wrote coolbar.theme, rename template.py to coolbar.py and put it in the same directory as coolbar.theme.

Now, lets open up your coolbar.py file (your file name will be different obviously). Look for the event callback that reacts to mouse movement:

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 .py file

SuperKaramba has a python 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 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:

This code simply changes the text called "mouseText" (which we defiend in our .theme file) to tell use 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 file basically contain everything you could ever need to know to write your theme.

Testing!

To test your new python code, just open your .theme file in SuperKaramba.

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

You DO NOT need to compile your python code. SuperKaramba contains a built-in python interpreter and it will do that automatically and tell you about any errors. In fact, you can't run your .py file directly in regular python because it doesn't know anything about the karamba.* functions. Those functions only exist inside of SuperKaramba's python interpreter.

Have fun making themes!

Quick Links