The latest API definition is always here.
All of the functions here are defined in the module karamba. To use them:
import karamba
This function will move the systray that you have already create with createSystray(). Specify the new location of the systray's upper-left corner with x and y, and the new width and height with w and h.
This function shows a systray that you have previously created with createSystray() and hidden with hideSystray().
This function hides a systray that you have previously created with createSystray().
This function creates a System Tray with it's top-left corner at x, y and with a width and height of w, h. The systray is the area where little icons from different programs appear, usually to allow you to control programs that are running in the background.
NOTE: You must disable any other systrays (remove the systray from the KDE Kicker Bar) before using a SuperKaramba theme with a systray because you can only have one systray at a time.
NOTE 2: Thus, it follows that you should only call createSystray once, because creating more than one systray is a horrible idea that will cause problems with KDE.
Calling this enables your widget to receive Drop events. In other words, the user will be able to drag icons from her desktop and drop them on your widget. The "itemDropped" callback is called as a result with the data about the icon that was dropped on your widget. This allows, for example, icon bars where items are added to the icon bar by Drag and Drop.
Shows text that has been hidden with hideRichText()
Hides rich text that is visible. You need to call redrawWidget() afterwords to actually hide the text on screen.
Given a reference to a rich text object, this will return a tuple containing the height and width of a rich text object.
Given a reference to a rich text object, this function changes it's width to the specified value in pixels.
The height adjusts automatically as the contents are changed with changeRichText.
This removes a richt text object from memory. Please do not call functions on "text" after calling deleteRichText, as it does not exist anymore and that could cause crashes in some cases.
This moves a rich text object to a new x, y relative to your widget. In other words, (0,0) is the top corner of your widget, not the screen.
This will change the contents of a rich text widget. richText is the reference to the text object to change that you saved from the createRichText() call. text is a string containing the new value for the rich text object.
The differance between Rich Text and a regular text field is that rich text fields can display HTML code embedded in your text.
In a <a href="command"> ... </a> tag command is executed if the link is click with the left mouse button.
Except if command starts with an '#' (ie: href="#value" ) the callback meterClicked is called with value (without the #) as the meter argument.
Also inline images work. Unfortunatly currently only when using absolute paths.
This creates creates a rich text string. underlineLinks is a boolean that determines if html links will be automatically underlined so that the user knows that the links can be clicked on. You need to save the return value of this function to call other functions on your rich text field, such as changeRichText().
The differance between Rich Text and a regular text field is that rich text fields can display HTML code embedded in your text.
In a <a href="command"> ... </a> tag command is executed if the link is click with the left mouse button.
Except if command starts with an '#' (ie: href="#value" ) the callback meterClicked is called with value (without the #) as the meter argument.
Also inline images work. Unfortunatly currently only when using absolute paths.
This command simply executes a program or command on the system. This is just for convience (IE you could accomplish this directly through python, but sometimes threading problems crop up that way). The only option is a string containing the command to execute.
This command executes a program or command on the system. But it allows you to get any text that the program outputs. Futhermore, it won't freeze up your widget while the command executes.
To use it, call executeInteractive with the reference to your widget and a list of command options. The array is simply a list that contains the command as the first entry, and each option as a seperate list entry. Output from the command is returned via the commandOutput callback.
The command returns the process number of the command. This is useful if you want to run more than one program at a time. The number will allow you to figure out which program is outputting in the commandOutput callback.
Example: Run the command "ls -la *.zip"
myCommand = ["ls", "-la", "*.zip"] karamba.executeInteractive(widget, myCommand)
It is possible to attach a clickarea to a meter (image or text field), which is moved and resized correctly if the meter is moved or resized.
There is also a callback meterClicked(widget, meter, button) which is called whenever a meter is clicked (if something is attached to it).
Given an Image or a TextLabel, this call makes it clickable. When a mouse click is detected, the callback meterClicked is called.
lB, mB, and rB are strings that specify what command is executed when this meter is clicked with the left mouse button, middle mouse button, and right mouse button respectively. If given, the appropriate command is executed when the mouse click is received.
The keyword arguments are all optional. If command is an empty string nothing is executed.
For now the command given to RightButton has obviosly no effect (because that brings up the SuperKaramba menu).
This creates an empty popup menu and returns a pointer to the menu.
This deletes the referenced menu if that menu exists. It returns 1 if menu existed and was deleted, returns 0 otherwise.
This adds an entry to the given menu with label text and with given icon. icon can be just an application name in which case the user's current icon set is used, or can be a path to a 16x16 png file.
The function returns the id of the menu item, which identifies that popup menu item uniquely among popupmenu items application-wide or returns 0 if the given menu doesn't exist.
This removes the item with given id from given menu if that menu exists.
The function returns 1 if the menu item existed and was removed or returns zero otherwise.
This pops up the given menu at the given co-ordinates. The co-ordinates are relative to the widget, not the screen. You can use negative co-ordinates to make a menu appear to the right of or above your theme.
This function returns 1 if the menu existed and was popped up, returns 0 otherwise
You can reference text in your python code that was created in the .theme file. Basically, you just add a NAME= value to the TEXT line in the .theme file. Then if you want to use that object, instead of calling createText, you can call this function.
The name you pass to the function is the same one that you gave it for the NAME= parameter in the .theme file.
You can reference an image in your python code that was created in the .theme file. Basically, you just add a NAME= value to the IMAGE line in the .theme file. Then if you want to use that object, instead of calling createImage, you can call this function.
The name you pass to the function is the same one that you gave it for the NAME= parameter in the .theme file.
SuperKaramba supports a simplistic configuration pop-up menu. This menu appears when you right-click on a widget and choose Configure Theme. Basically, it allows you to have check-able entrys in the menu to allow the user to enable or disable features in your theme.
Before you use any configuration menu stuff, you NEED to add a new callback to your script:
def menuOptionChanged(widget, key, value):
This will get called whenever a config menu option is changed. Now you can add items to the config menu:
addMenuConfigOption(widget, String key, String name)
Key is the name of a key value where the value will be saved automatically into the widget's config file. Name is the actual text that will show up in the config menu.
For example, I could allow the user to enable or disable a clock showing up in my theme:
karamba.addMenuConfigOption(widget, "showclock", "Display a clock")
This sets whether or not the given option is checked in the theme's Configure Theme menu. Value should be 0 if key should not be checked and 1 if key should be checked.
See addMenuConfigOption for a more detailed explanation.
This returns whether or not the given option is checked in the theme's Configure Theme menu. 0 is returned if it is not checked and 1 is returned if it is.
See addMenuConfigOption for a more detailed explanation.
SuperKaramba automatically supports configuration files for each theme. These files will be saved in /your/home/dir/.superkaramba/ and will be named themenamerc where themename is the name of the theme.
This function writes an entry into the config file with the given key and value.
For example, to save my favorite color, I would do karamba.writeConfigEntry(widget, "FavColor", "Red")
This shows/hides the current desktop just like the Show Desktop button on kicker. Basically, it minimizes all the windows on the current desktop. Call it once to show the desktop and again to hide it.
This peforms the given action on a task object. widget is a reference to the current widget. task is a reference to a task object you got from getTaskList(). Action is a number from 1 to 10. See the list below.
Possible actions:
This returns a Python List containing the String names of all open windows on the system. This is for convience if you want to list open windows or see if a window by a certain name exists. Anything else requires the reference to the window you would obtain from getTaskList()
This returns a Python List object with references to all the current windows open on this system. You can then call performTaskAction() or getTaskInfo() on any of the entries in the list.
This returns all of the info about a certain task in the form of a Python List. widget is a reference to the current widget. task is a reference to the window you want info about which you obtain by calling getTaskList().
Here is the format of the returned list by index value:
This returns a Python List object with references to all the current windows that are in the process of loading on this system. You can then call getStartupInfo() on any of the entries in the list.
This returns all of the info about a certain starting task in the form of a Python List. widget is a reference to the current widget. task is a reference to the window you want info about which you obtain by calling getStartupList().
Here is the format of the returned list by index value:
Returns a Python Tuple containing the x and y position of you widget. widget is a reference to the current widget.
Returns a string containing the directory where your theme was loaded from.
This function doesn't work currently due to a bug in KDE. Please use MASK= in your .theme file for the time being.
This creates a clickable area at x,y with width and height w,h. When this area is clicked, cmd_to_run will be executed. The mouse will change to the clickable icon when over this area.
If you have called image effect commands on your image (ex: changeImageIntensity), you can call this to restore your image to it's original form.
Changes the "intensity" of the image, which is similar to it's brightness. ratio is a floating point number from -1.0 to 1.0 that determines how much to brighten or darken the image. Millisec specifies how long in milliseconds before the image is restored to it's original form. This is useful for "mouse over" type animations. Using 0 for millisec disables this feature and leaves the image permanently affected.
There is no infomation for this function yet.
Turns the given image into a grayscale image. Millisec specifies how long in milliseconds before the image is restored to it's original form. This is useful for "mouse over" type animations. Using 0 for millisec disables this feature and leaves the image permanently affected.
If you have rotated or resized your image, you can call this to restore your image to it's original form.
This rotates your image to by the specified amount of degrees. The imageToRotate parameter is a reference to an image that you saved as the return value from createImage()
This returns the height of an image. This is useful if you have rotated an image and its size changed, so you do not know how big it is anymore. The return value is a long.
This returns the width of an image. This is useful if you have rotated an image and its size changed, so you do not know how big it is anymore. The return value is a long.
DEPRECATED: resizeImage now allows the user to pick whether to use fast or smooth resizing from the SuperKaramba menu - This resizes your image to width, height. The imageToResize parameter is a reference to an image that you saved as the return value from createImage()
This resizes your image to width, height. The imageToResize parameter is a reference to an image that you saved as the return value from createImage()
This shows a previously hidden image. It does not actually refresh the image on screen. That is what redrawWidget() does.
This hides an image. In other words, during subsequent calls to widgetUpdate(), this image will not be drawn.
This moves an image to a new x, y relative to your widget. In other words, (0,0) is the top corner of your widget, not the screen. The imageToMove parameter is a reference to the image to move that you saved as the return value from createImage()
This creats a tooltip for image with tooltip_text.
NOTE
This removes image from memory. Please do not call functions on "image" after calling deleteImage, as it does not exist anymore and that could cause crashes in some cases.
There is no infomation for this function yet.
This creates an image on your widget at x, y. The filename should be given as the path parameter. In theory the image could be local or could be a url. It works just like adding an image in your theme file. You will need to save the return value to be able to call other functions on your image, such as moveImage()
Shows text that has been hidden with hideText()
Hides text that is visible. You need to call redrawWidget() afterwords to actually hide the text on screen.
This moves a text object to a new x, y relative to your widget. In other words, (0,0) is the top corner of your widget, not the screen.
This will change the shadow size of a text widget (only ones you created through python currently). textToChange is the reference to the text object to change that you saved from the createText() call. size is the offset of the shadow in pixels. 1 or 2 is a good value in most cases.
This will change the font size of a text widget (only ones you created through python currently). textToChange is the reference to the text object to change that you saved from the createText() call. size is the new font point size.
This will change the color of a text widget (only ones you created through python currently). textToChange is the reference to the text object to change that you saved from the createText() call. r, g, b are ints from 0 to 255 that represent red, green, and blue.
This will change the font of a text widget (only ones you created through python currently). textToChange is the reference to the text object to change that you saved from the createText() call. newFont is a string the the name of the font to use.
This will change the contents of a text widget. textToChange is the reference to the text object to change that you saved from the createText() call.
This removes a text object from memory. Please do not call functions on "text" after calling deleteText, as it does not exist anymore and that could cause crashes in some cases.
This creates creates a text string at x, y with the specified width and height. You need to save the return value of this function to call other functions on your text field, such as changeText()
There is no infomation for this function yet.
This is THE most important function. After you do a bunch of other calls (moving images, adding images or text, etc), you call this to update the widget display area. You will not see your changes until you call this.
Resizes your karamba widget to width=w, height=h
Moves your karamba widget to a new screen location