Contents 1 SuperKaramba API 1.1 Bar 1.1.1 createBar 1.1.2 deleteBar 1.1.3 getBarImage 1.1.4 getBarMinMax 1.1.5 getBarPos 1.1.6 getBarSensor 1.1.7 getBarSize 1.1.8 getBarValue 1.1.9 getBarVertical 1.1.10 getThemeBar 1.1.11 hideBar 1.1.12 moveBar 1.1.13 resizeBar 1.1.14 setBarImage 1.1.15 setBarMinMax 1.1.16 setBarSensor 1.1.17 setBarValue 1.1.18 setBarVertical 1.1.19 showBar 1.2 Config 1.2.1 addMenuConfigOption 1.2.2 readConfigEntry 1.2.3 readMenuConfigOption 1.2.4 setMenuConfigOption 1.2.5 writeConfigEntry 1.3 Graph 1.3.1 createGraph 1.3.2 deleteGraph 1.3.3 getGraphColor 1.3.4 getGraphMinMax 1.3.5 getGraphPos 1.3.6 getGraphSensor 1.3.7 getGraphSize 1.3.8 getGraphValue 1.3.9 getThemeGraph 1.3.10 hideGraph 1.3.11 moveGraph 1.3.12 resizeGraph 1.3.13 setGraphColor 1.3.14 setGraphMinMax 1.3.15 setGraphSensor 1.3.16 setGraphValue 1.3.17 showGraph 1.4 Image 1.4.1 addImageTooltip 1.4.2 changeImageChannelIntensity 1.4.3 changeImageIntensity 1.4.4 changeImageToGray 1.4.5 changeImageAlpha 1.4.6 createBackgroundImage 1.4.7 createImage 1.4.8 createEmptyImage 1.4.9 createTaskIcon 1.4.10 deleteImage 1.4.11 getImageHeight 1.4.12 getImagePath 1.4.13 getImagePos 1.4.14 getImageSensor 1.4.15 getImageSize 1.4.16 getImageWidth 1.4.17 getThemeImage 1.4.18 hideImage 1.4.19 moveImage 1.4.20 removeImageEffects 1.4.21 removeImageTransformations 1.4.22 resizeImage 1.4.23 resizeImageSmooth 1.4.24 rotateImage 1.4.25 setImagePath 1.4.26 setImageSensor 1.4.27 showImage 1.4.28 setPixel 1.4.29 changeImageAnimation 1.4.30 getImageAnimation 1.4.31 setImageElement 1.4.32 setImageElementAll 1.4.33 getImageElement 1.5 Input Box 1.5.1 changeInputBox 1.5.2 changeInputBoxBackgroundColor 1.5.3 changeInputBoxFont 1.5.4 changeInputBoxFontColor 1.5.5 changeInputBoxFontSize 1.5.6 changeInputBoxFrameColor 1.5.7 changeInputBoxSelectedTextColor 1.5.8 changeInputBoxSelectionColor 1.5.9 clearInputFocus 1.5.10 createInputBox 1.5.11 deleteInputBox 1.5.12 getInputBoxBackgroundColor 1.5.13 getInputBoxFont 1.5.14 getInputBoxFontColor 1.5.15 getInputBoxFontSize 1.5.16 getInputBoxFrameColor 1.5.17 getInputBoxPos 1.5.18 getInputBoxSelectedTextColor 1.5.19 getInputBoxSelectionColor 1.5.20 getInputBoxSize 1.5.21 getInputBoxValue 1.5.22 getInputFocus 1.5.23 getThemeInputBox 1.5.24 hideInputBox 1.5.25 moveInputBox 1.5.26 resizeInputBox 1.5.27 setInputFocus 1.5.28 showInputBox 1.5.29 getInputBoxTextWidth 1.5.30 changeInputBoxSelection 1.5.31 getInputBoxSelection 1.5.32 clearInputBoxSelection 1.6 Menu 1.6.1 addMenuItem 1.6.2 addMenuSeparator 1.6.3 createMenu 1.6.4 deleteMenu 1.6.5 popupMenu 1.6.6 removeMenuItem 1.7 Misc 1.7.1 acceptDrops 1.7.2 attachClickArea 1.7.3 callTheme 1.7.4 changeInterval 1.7.5 createClickArea 1.7.6 createServiceClickArea 1.7.7 execute 1.7.8 executeInteractive 1.7.9 getIconByName 1.7.10 getIncomingData 1.7.11 getIp 1.7.12 getNumberOfDesktop 1.7.13 getPrettyThemeName 1.7.14 getServiceGroups 1.7.15 getThemePath 1.7.16 getUpdateTime 1.7.17 hide 1.7.18 language 1.7.19 managementPopup 1.7.20 openNamedTheme 1.7.21 openTheme 1.7.22 readThemeFile 1.7.23 reloadTheme 1.7.24 removeClickArea 1.7.25 run 1.7.26 setIncomingData 1.7.27 setUpdateTime 1.7.28 show 1.7.29 toggleShowDesktop 1.7.30 translateAll 1.7.31 userLanguage 1.7.32 userLanguages 1.7.33 wantRightButton 1.7.34 version 1.7.35 desktopSize 1.8 Rich Text 1.8.1 changeRichText 1.8.2 changeRichTextFont 1.8.3 changeRichTextSize 1.8.4 createRichText 1.8.5 deleteRichText 1.8.6 getRichTextFont 1.8.7 getRichTextFontSize 1.8.8 getRichTextPos 1.8.9 getRichTextSensor 1.8.10 getRichTextSize 1.8.11 getRichTextValue 1.8.12 getThemeRichText 1.8.13 hideRichText 1.8.14 moveRichText 1.8.15 resizeRichText 1.8.16 setRichTextSensor 1.8.17 setRichTextWidth 1.8.18 showRichText 1.9 Task 1.9.1 getStartupInfo 1.9.2 getStartupList 1.9.3 getTaskInfo 1.9.4 getTaskList 1.9.5 getTaskNames 1.9.6 performTaskAction 1.10 Text 1.10.1 changeText 1.10.2 changeTextColor 1.10.3 changeTextFont 1.10.4 changeTextShadow 1.10.5 changeTextSize 1.10.6 createText 1.10.7 deleteText 1.10.8 getTextAlign 1.10.9 getTextColor 1.10.10 getTextFont 1.10.11 getTextFontSize 1.10.12 getTextPos 1.10.13 getTextSensor 1.10.14 getTextShadow 1.10.15 getTextSize 1.10.16 getTextValue 1.10.17 getThemeText 1.10.18 hideText 1.10.19 moveText 1.10.20 resizeText 1.10.21 setTextAlign 1.10.22 setTextSensor 1.10.23 showText 1.10.24 getTextTextWidth 1.11 Widget 1.11.1 createWidgetMask 1.11.2 getWidgetPosition 1.11.3 moveWidget 1.11.4 redrawWidget 1.11.5 redrawWidgetBackground 1.11.6 resizeWidget 1.11.7 toggleWidgetRedraw 1.12 Sensor 1.12.1 getPlasmaSensor 1.13 CanvasWidget 1.13.1 createCanvasWidget 1.13.2 moveCanvasWidget 2 Wiki Markup Generation

[edit] SuperKaramba API

This document descriptes the API documentation of the current development version of SuperKaramba. It is mostly identical with the stable API. However you can find the stable API here.

[edit] Bar

[edit] createBar

This creates a bar at x, y with width and height w, h.

Synopsis:
reference createBar(widget, x, y, w, h, image)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• integer w -- width
• integer h -- height
• string image -- Path to image

Return Value:
Reference to new bar meter

[edit] deleteBar

This deletes the bar.

Synopsis:
boolean deleteBar(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
true if successful

[edit] getBarImage

Get the path to the bar image.

Synopsis:
string getBarImage(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
path to bar image

[edit] getBarMinMax

Returns possible min and max values of the bar.

Synopsis:
array getBarMinMax(widget, bar)

Arguments:

• reference to widget -- karamba
• reference bar -- bar

Return Value:
array with max & min values

[edit] getBarPos

Given a reference to a bar object, this will return an array containing the x and y coordinate of a bar object.

Synopsis:
array getBarPos(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
array with x and y coordinates

[edit] getBarSensor

Gets the current sensor string.

Synopsis:
string getBarSensor(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
sensor string

[edit] getBarSize

Given a reference to a bar object, this will return an array containing the height and width of the bar object.

Synopsis:
array getBarSize(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
array with width and height

[edit] getBarValue

Returns current bar value.

Synopsis:
integer getBarValue(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
value

[edit] getBarVertical

Check if bar is a vertical bar.

Synopsis:
boolean getBarVertical(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
true if vertical

[edit] getThemeBar

You can reference a bar in your python code that was created in the theme file. Basically, you just add a NAME= value to the BAR line in the .theme file. Then if you want to use that object, instead of calling createBar(), 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.

Synopsis:
reference getThemeBar(widget, name)

Arguments:

• reference to widget -- karamba
• string name -- name of the bar in the theme file

Return Value:
reference to bar

[edit] hideBar

This hides an bar. In other words, during subsequent calls to widgetUpdate(), this bar will not be drawn.

Synopsis:
boolean hideBar(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
true if successful

[edit] moveBar

This will move the bar to new x and y coordinates.

Synopsis:
boolean moveBar(widget, bar, x, y)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar
• integer x -- x coordinate
• integer y -- y coordinate

Return Value:
boolean (true if successful)

[edit] resizeBar

This will resize bar to new height and width.

Synopsis:
boolean resizeBar(widget, bar, w, h)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar
• integer w -- new width
• integer h -- new height

Return Value:
true if successful

[edit] setBarImage

Use the image in path for the background as the bar

Synopsis:
boolean setBarImage(widget, bar, image)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar
• string image -- path to the new image

Return Value:
true if successful

[edit] setBarMinMax

Returns current bar value.

Synopsis:
boolean setBarMinMax(widget, bar, min, max)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar
• integer min -- min value
• integer max -- max value

Return Value:
true if successful

[edit] setBarSensor

Sets the sensor string of the bar.

Synopsis:
boolean setBarSensor(widget, bar, sensor)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar
• string sensor -- new sensor string as in theme files

Return Value:
true if successful

[edit] setBarValue

Sets current bar value.

Synopsis:
reference setBarValue(widget, bar, value)

Arguments:

• long widget -- karamba
• long bar -- pointer to bar
• long value -- new value

Return Value:
reference to bar

[edit] setBarVertical

Set bar vertical

Synopsis:
boolean setBarVertical(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar
• boolean vertical -- true to draw the bar vertically

Return Value:
true if successful

[edit] showBar

This shows an bar. In other words, during subsequent calls to widgetUpdate(), this bar will be drawn.

Synopsis:
boolean showBar(widget, bar)

Arguments:

• reference to widget -- karamba
• reference to bar -- bar

Return Value:
true if successful

[edit] Config

[edit] addMenuConfigOption

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 entries 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")

Synopsis:
boolean addMenuConfigOption(widget, key, name)

Arguments:

• reference to widget -- karamba
• string key -- key for menu item
• string name -- name of the graph to get

Return Value:
true if successful

[edit] readConfigEntry

This function reads an entry from the config file with the given key.

Synopsis:
string readConfigEntry(widget, key, value)

Arguments:

• reference to widget -- karamba
• string key -- key for config item

Return Value:
config value for key

[edit] readMenuConfigOption

This returns whether or not the given option is checked in the theme's Configure Theme menu. See addMenuConfigOption() for a more detailed explanation.

Synopsis:
boolean readMenuConfigOption(widget, key)

Arguments:

• reference to widget -- karamba
• string key -- key for menu item

Return Value:
false is returned if it is not checked and true is returned if it is.

[edit] setMenuConfigOption

This sets whether or not the given option is checked in the theme's Configure Theme menu. Value should be false if key should not be checked and true if key should be checked. See addMenuConfigOption() for a more detailed explanation.

Synopsis:
boolean setMenuConfigOption(widget, key, value)

Arguments:

• referencce to widget -- karamba
• string key -- key for menu item
• boolean value -- true for checked

Return Value:
true if successful

[edit] writeConfigEntry

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

Synopsis:
boolean writeConfigEntry(widget, key, value)

Arguments:

• reference to widget -- karamba
• string key -- key for config item
• string value -- config value

Return Value:
true if successful

[edit] Graph

[edit] createGraph

This creates a graph at x, y with width and height.

Synopsis:
reference createGraph(widget, x, y, width, height, points)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• integer w -- width
• integer h -- height
• integer points -- Number of points in graph

Return Value:
reference to new graph meter

[edit] deleteGraph

This deletes graph.

Synopsis:
boolean deleteGraph(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
true if successful

[edit] getGraphColor

Gets the current graph color components.

Synopsis:
array getGraphColor(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
(red, green, blue, alpha)

[edit] getGraphMinMax

Returns current graph minimal and maximal values.

Synopsis:
array getGraphMinMax(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
max and min values

[edit] getGraphPos

Given a reference to a graph object, this will return an array containing the x and y coordinates of the graph object.

Synopsis:
array getGraphPos(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
x and y coordinates

[edit] getGraphSensor

Gets the current sensor string of the graph.

Synopsis:
string getGraphSensor(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
sensor string

[edit] getGraphSize

Given a reference to a graph object, this will return an array containing the height and width of a graph object.

Synopsis:
array getGraphSize(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
width and height of the graph

[edit] getGraphValue

Returns current graph value.

Synopsis:
integer getGraphValue(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
value

[edit] getThemeGraph

You can reference graph in your python code that was created in the theme file. Basically, you just add a NAME= value to the GRAPH line in the .theme file. Then if you want to use that object, instead of calling createGraph(), 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.

Synopsis:
reference getThemeGraph(widget, name)

Arguments:

• reference to widget -- karamba
• string name -- name of the graph in the theme file

Return Value:
reference to graph

[edit] hideGraph

This hides a graph. In other words, during subsequent calls to widgetUpdate(), this graph will not be drawn.

Synopsis:
boolean hideGraph(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
true if successful

[edit] moveGraph

This will move the graph to the new x and y coordinates.

Synopsis:
boolean moveGraph(widget, graph, x, y)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph
• integer x -- x coordinate
• integer y -- y coordinate

Return Value:
true if successful

[edit] resizeGraph

This will resize graph to new height and width.

Synopsis:
boolean resizeGraph(widget, graph, width, height)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph
• integer width -- new width
• integer height -- new height

Return Value:
true if successful

[edit] setGraphColor

Sets current graph color.

Synopsis:
boolean setGraphColor(widget, graph, red, green, blue, alpha=255)

Arguments:

• reference to widget -- karamba
• reference to graph -- pointer to graph
• integer red -- red component of color
• integer green -- green component of color
• integer blue -- blue component of color
• integer alpha -- alpha component of color (optional)

Return Value:
true if successful

[edit] setGraphMinMax

Sets the graphs min and max values.

Synopsis:
boolean setGraphMinMax(widget, graph, min, max)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph
• integer min -- min value
• integer max -- max value

Return Value:
true if successful

[edit] setGraphSensor

Sets current sensor string of the graph.

Synopsis:
boolean setGraphSensor(widget, graph, sensor)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph
• string sensor -- new sensor string as in theme files

Return Value:
true if successful

[edit] setGraphValue

Sets current graph value.

Synopsis:
reference setGraphValue(widget, graph, value)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph
• integer value -- new value

Return Value:
reference to graph

[edit] showGraph

This shows a graph. In other words, during subsequent calls to widgetUpdate(), this graph will be drawn.

Synopsis:
boolean showGraph(widget, graph)

Arguments:

• reference to widget -- karamba
• reference to graph -- graph

Return Value:
true if successful

[edit] Image

[edit] addImageTooltip

This creats a tooltip for image with text. Note:

• If you move the image, the tooltip does not move! It stays! Do not

create a tooltip if the image is off-screen because you will not be able to ever see it.

Synopsis:
boolean addImageTooltip(widget, image, text)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• string text -- tooltip text

Return Value:
true if successful

[edit] changeImageChannelIntensity

Changes the "intensity" of the image color channel, which is similar to it's brightness.

Synopsis:
boolean changeImageChannelIntensity(widget, image, ratio, channel, millisec)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• decimal ratio -- -1.0 to 1.0 (dark to bright)
• string channel -- color channel (red|green|blue)
• integer millisec -- milliseconds before the image is restored (optional)

Return Value:
true if successful

[edit] changeImageIntensity

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.

Synopsis:
boolean changeImageIntensity(widget, image, ratio, millisec)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• decimal ratio -- -1.0 to 1.0 (dark to bright)
• integer millisec -- milliseconds before the image is restored (optional)

Return Value:
true if successful

[edit] changeImageToGray

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.

Synopsis:
boolean changeImageToGray(widget, image, millisec)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• integer millisec -- milliseconds before the image is restored (optional)

Return Value:
true if successful

[edit] changeImageAlpha

This will change the image transparency to the given alpha value. The R,G, or B value of -1 indicates that pixels of all intensities in this channel will be assigned the given alpha. If a color (R,G, or B) intensity is specified in the range of 0-255, the alpha value is applied only to the pixels with that intensity. This allows to make, for example, only black (R=0,G=0,B=0) pixels transparent, while keeping all other pixel's alpha unchanged. The value of millisec instructs how long the transparency effect should stay. The value of 0 makes the alpha effect permanent.

Synopsis:
boolean changeImageAlpha(widget, image, alpha, red=-1, green=-1, blue=-1, millisec=0)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• integer alpha -- alpha value to use
• integer red -- specific intensity of red component (optional) (defaults to "all intensities")
• integer green -- specific intensity of green component (optional) (defaults to "all intensities")
• integer blue -- specific intensity of blue component (optional) (defaults to "all intensities")
• integer millisec -- milliseconds before the image is restored (optional)

Return Value:
true if successful

[edit] createBackgroundImage

This creates an background 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()

Synopsis:
reference createBackgroundImage(widget, x, y, w, h, image)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• string image -- path to the image for the background

Return Value:
reference to new image meter

[edit] createImage

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

Synopsis:
reference createImage(widget, x, y, image)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• string image -- image for the imagelabel

Return Value:
reference to new image meter

[edit] createEmptyImage

This creates an empty image on your widget at x, y. The empy image allows you to draw the contents with the setPixel() function without loading an image first.

Synopsis:
reference createEmptyImage(widget, x, y, w, h)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• integer w -- width of the image
• integer h -- height of the image

Return Value:
reference to new image meter

[edit] createTaskIcon

This creates a task image at x, y.

Synopsis:
reference createTaskIcon(widget, x, y, ctask)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• integer task -- task

Return Value:
reference to new image meter

[edit] deleteImage

This removes the image from the widhet. Please do not call functions on "image" after calling deleteImage, as it does not exist anymore and that could cause crashes in some cases.

Synopsis:
boolean deleteImage(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
true if successful

[edit] getImageHeight

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.

Synopsis:
integer getImageHeight(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
height of the image

[edit] getImagePath

Returns the current image path.

Synopsis:
string getImagePath(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
path

[edit] getImagePos

Given a reference to a image object, this will return a tuple containing the x and y coordinate of a image object.

Synopsis:
array getImagePos(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
x and y coordinates of the image

[edit] getImageSensor

Gets the current sensor string.

Synopsis:
string getImageSensor(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
sensor string

[edit] getImageSize

Given a reference to a image object, this will return an array containing the height and width of a image object.

Synopsis:
array getImageSize(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
height and width of the image

[edit] getImageWidth

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.

Synopsis:
integer getImageWidth(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
width of the image

[edit] getThemeImage

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.

Synopsis:
long getThemeImage(widget, name)

Arguments:

• reference to widget -- karamba
• string name -- name of the image in the theme files

Return Value:
reference to image

[edit] hideImage

This hides an image. In other words, during subsequent calls to widgetUpdate(), this image will not be drawn.

Synopsis:
boolean hideImage(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
true if successful

[edit] moveImage

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

Synopsis:
boolean moveImage(widget, image, x, y)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• integer x -- x coordinate
• integer y -- y coordinate

Return Value:
true if successful

[edit] removeImageEffects

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.

Synopsis:
boolean removeImageEffects(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
true if successful

[edit] removeImageTransformations

If you have rotated or resized your image, you can call this function to restore your image to its original form.

Synopsis:
boolean removeImageTransformations(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
true if successful

[edit] resizeImage

This resizes your image to width, height. The image parameter is a reference to an image that you saved as the return value from createImage()

Synopsis:
boolean resizeImage(widget, image, w, h)

Arguments:

• reference widget -- karamba
• reference image -- image
• integer w -- width
• integer h -- height

Return Value:
true if successful

[edit] resizeImageSmooth

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() In version 0.50 and later this function works exactly as resizeImage().

Synopsis:
boolean resizeImageSmooth(widget, image, w, h)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• integer w -- width
• integer h -- height

Return Value:
true if successful

[edit] rotateImage

This rotates your image to by the specified amount of degrees. The The image parameter is a reference to an image that you saved as the return value from createImage()

Synopsis:
long rotateImage(widget, image, deg)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• integer deg -- degrees to rotate

Return Value:
true if successful

[edit] setImagePath

This will change image of a image widget. Note, starting with SuperKaramba version 0.50 (KDE4.0) this function accepts SVG.

Synopsis:
reference setImagePath(widget, image, path)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• string path -- new path of the image

Return Value:
reference to the image

[edit] setImageSensor

Sets the current sensor string.

Synopsis:
long setImageSensor(widget, image, sensor)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• string sensor -- new sensor string as in theme files

Return Value:
true if successful

[edit] showImage

This shows a previously hidden image. It does not actually refresh the image on screen. That is what redrawWidget() does.

Synopsis:
boolean showImage(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
true if successful

[edit] setPixel

This sets the pixel in the image at the positon x, y to the color r, g, b with the alpha channel a. You can use this function to draw your own images with your theme script.

Synopsis:
boolean setPixel(widget, image, x, y, r, g, b, a=255)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• integer x -- x coordinate of the pixel
• integer y -- y coordinate of the pixel
• integer r -- red component of color
• integer g -- green component of color
• integer b -- blue component of color
• integer a -- alpha component of color (optional)

Return Value:
true if successful

[edit] changeImageAnimation

This function can be used to enable or disable animations in an SVG image. The animation is on by default.

Synopsis:
boolean changeImageAnimation(widget, image, enable)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• boolean enable -- enable or disable animations

Return Value:
true if successful

[edit] getImageAnimation

This function returns if the animation of an SVG image is currently activated.

Synopsis:
boolean getImageAnimation(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
true if animation is activated or false if it is deactivated or not an SVG image.

[edit] setImageElement

This function will only draw the named element of an SVG image.

Synopsis:
boolean setImageElement(widget, image, element)

Arguments:

• reference to widget -- karamba
• reference to image -- image
• string element -- ID of the element to draw

Return Value:
true if the element is available or false if it is not an SVG image.

[edit] setImageElementAll

This function reset a previous set element. A call to this function will result in a completly drawn SVG image.

Synopsis:
boolean setImageElementAll(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
true if successful

[edit] getImageElement

This function returns the ID of the currently drawn element of an SVG image.

Synopsis:
string getImageElement(widget, image)

Arguments:

• reference to widget -- karamba
• reference to image -- image

Return Value:
ID of the element or empty string if the image is not an SVG image or the complete SVG image is drawn.

[edit] Input Box

[edit] changeInputBox

This function will change the contents of a input box widget.

Synopsis:
reference changeInputBox(widget, inputBox, value)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box
• string value -- new text of the input box

Return Value:
reference to input box

[edit] changeInputBoxBackgroundColor

This will change the background color of a Input Box widget. InputBox is the reference to the text object to change r, g, b are ints from 0 to 255 that represent red, green, blue and the alpha channel.

Synopsis:
reference changeInputBoxBackgroundColor(widget, inputBox, r, g, b, a=255)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box
• integer red -- red component of color
• integer green -- green component of color
• integer blue -- blue component of color
• integer alpha -- alpha component of color (optional)

Return Value:
true if successful

[edit] changeInputBoxFont

This will change the font of a Input Box widget. InputBox is the reference to the Input Box object to change. Font is a string with the name of the font to use.

Synopsis:
boolean changeInputBoxFont(widget, inputBox, font)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- inputBox
• string font -- font name

Return Value:
true if successful

[edit] changeInputBoxFontColor

This will change the color of a text of a Input Box widget. InputBox is the reference to the text object to change r, g, b are ints from 0 to 255 that represent red, green, blue and the alpha channel.

Synopsis:
boolean changeInputBoxFontColor(widget, inputBox, r, g, b, a=255)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box
• integer red -- red component of color
• integer green -- green component of color
• integer blue -- blue component of color
• integer alpha -- alpha component of color (optional)

Return Value:
true if successful

[edit] changeInputBoxFontSize

This will change the font size of a Input Box widget. InputBox is the reference to the text object to change. Size is the new font point size.

Synopsis:
boolean changeInputBoxFontSize(widget, text, size)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box
• integer size -- new font size for text

Return Value:
true if successful

[edit] changeInputBoxFrameColor

This will change the frame color of a Input Box widget. InputBox is the reference to the text object to change r, g, b are ints from 0 to 255 that represent red, green, blue and the alpha channel.

Synopsis:
boolean changeInputBoxFrameColor(widget, inputBox, r, g, b, a=255)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box
• integer red -- red component of color
• integer green -- green component of color
• integer blue -- blue component of color
• integer alpha -- alpha component of color (optional)

Return Value:
true if successful

[edit] changeInputBoxSelectedTextColor

This will change the selected text color of a Input Box widget. InputBox is the reference to the text object to change r, g, b are ints from 0 to 255 that represent red, green, blue and the alpha channel.

Synopsis:
boolean changeInputBoxSelectedTextColor(widget, inputBox, r, g, b, a=255)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box
• integer red -- red component of color
• integer green -- green component of color
• integer blue -- blue component of color
• integer alpha -- alpha component of color (optional)

Return Value:
true if successful

[edit] changeInputBoxSelectionColor

This will change the color of the selection of a Input Box widget. InputBox is the reference to the text object to change r, g, b are ints from 0 to 255 that represent red, green, blue and teh alpha channel.

Synopsis:
boolean changeInputBoxSelectionColor(widget, inputBox, r, g, b, a=255)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box
• integer red -- red component of color
• integer green -- green component of color
• integer blue -- blue component of color
• integer alpha -- alpha component of color (optional)

Return Value:
true if successful

[edit] clearInputFocus

Releases the input focus from the Input Box.

Synopsis:
boolean clearInputFocus(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- pointer to Input Box

Return Value:
true if successful

[edit] createInputBox

This creates a new Input Box at x, y with width and height w, h. You need to save the return value of this function to call other functions on your Input Box field, such as changeInputBox(). The karamba widget is automatically set active, to allow user interactions.

Synopsis:
reference createInputBox(widget, x, y, w, h, text)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• integer w -- width
• integer h -- height
• string text -- text for the Input Box

Return Value:
reference to new Input Box

[edit] deleteInputBox

This removes the Input Box object from the widget. Please do not call functions of the Input Box after calling deleteInputBox, as it does not exist anymore and that could cause crashes in some cases. The karamba widget ist automatically set passive, when no more Input Boxes are on the karamba widget.

Synopsis:
boolean deleteInputBox(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference widget -- InputBox

Return Value:
true if successful

[edit] getInputBoxBackgroundColor

Gets the current background color of a Input Box

Synopsis:
array getInputBoxBackgroundColor(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
(red, green, blue, alpha)

[edit] getInputBoxFont

Gets the current Input Box font name

Synopsis:
string getInputBoxFont(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
font name

[edit] getInputBoxFontColor

Gets the current text color of a Input Box

Synopsis:
array getInputBoxFontColor(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
(red, green, blue, alpha)

[edit] getInputBoxFontSize

Gets the current text font size.

Synopsis:
integer getInputBoxFontSize(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
text font size

[edit] getInputBoxFrameColor

Gets the current frame color of a Input Box

Synopsis:
array getInputBoxFrameColor(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
(red, green, blue, alpha)

[edit] getInputBoxPos

Given a reference to a Input Box object, this will return an array containing the x and y coordinate of an Input Box.

Synopsis:
array getInputBoxPos(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
x and y coordinates of the inputBox

[edit] getInputBoxSelectedTextColor

Gets the current selected text color of a Input Box.

Synopsis:
array getInputBoxSelectedTextColor(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- pointer to Input Box

Return Value:
(red, green, blue, alpha)

[edit] getInputBoxSelectionColor

Gets the current selection color of a Input Box

Synopsis:
array getInputBoxSelectionColor(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
(red, green, blue, alpha)

[edit] getInputBoxSize

Given a reference to a Input Box object, this will return an array containing the height and width of a Input Box object.

Synopsis:
array getInputBoxSize(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
width and hight of the input box

[edit] getInputBoxValue

Returns current Input Box text.

Synopsis:
string getInputBoxValue(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
input box text

[edit] getInputFocus

Gets the Input Box that is currently focused.

Synopsis:
boolean getInputFocus(widget)

Arguments:

• reference to widget -- karamba

Return Value:
the input box or 0

[edit] getThemeInputBox

You can reference text in your python code that was created in the theme file. Basically, you just add a NAME= value to the INPUT line in the .theme file. Then if you want to use that object, instead of calling createInputBox(), 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.

Synopsis:
reference getThemeInputBox(widget, name)

Arguments:

• reference to widget -- karamba
• string name -- name of the Input Box in the theme file

Return Value:
reference to Input Box

[edit] hideInputBox

Hides a Input Box that is visible.

Synopsis:
boolean hideInputBox(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
true if successful

[edit] moveInputBox

This moves a Input Box 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.

Synopsis:
long moveInputBox(widget, inputBox, x, y)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box
• integer x -- x coordinate
• integer y -- y coordinate

Return Value:
true if successful

[edit] resizeInputBox

This will resize Input Box to the new height and width.

Synopsis:
boolean resizeInputBox(widget, inputBox, w, h)

Arguments:

• reference to widget -- karamba
• referenc to inputBox -- Input Box
• integer w -- new width
• integer h -- new height

Return Value:
true if successful

[edit] setInputFocus

Sets the input focus to the Input Box.

Synopsis:
boolean setInputFocus(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
true if successful

[edit] showInputBox

Shows Input Box that has been hidden with hideInputBox()

Synopsis:
boolean showInputBox(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
true if successful

[edit] getInputBoxTextWidth

Gets the width of the complete text of the Input Box.

Synopsis:
integer getInputBoxTextWidth(widget, input)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- Input Box

Return Value:
The text width or -1

[edit] changeInputBoxSelection

This will set the selection of the input box. The range can be set by the start cursor position and the length of the selection. Both arguments are counted in characters and not pixel.

Synopsis:
boolean changeInputBoxSelection(widget, inputBox, start, length)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- inputBox
• integer start -- start of the selection
• integer length -- length of the selection

Return Value:
true if successful

[edit] getInputBoxSelection

This will return the selection of the input box. If no selection was made in the input box (-1, 0) will be returned for the start and length of the selection.

Synopsis:
array getInputBoxSelection(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- inputBox

Return Value:
array with the selection start and length in characters

[edit] clearInputBoxSelection

This will clear the selection of the input box.

Synopsis:
boolean getInputBoxSelection(widget, inputBox)

Arguments:

• reference to widget -- karamba
• reference to inputBox -- inputBox

Return Value:
true if successful

[edit] Menu

[edit] addMenuItem

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 reference to 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.

Synopsis:
reference addMenuItem(widget, menu, text, icon)

Arguments:

• reference to widget -- karamba
• reference to menu -- menu
• string text -- text for menu item
• string icon -- icon name or path

Return Value:
reference to the menu item

[edit] addMenuSeparator

This adds an menu separator to the given menu.

Synopsis:
reference addMenuSeparator(widget, menu)

Arguments:

• reference to widget -- karamba
• reference to menu -- menu

Return Value:
reference to the separator

[edit] createMenu

This creates an empty popup menu and returns a reference to the menu.

Synopsis:
reference createMenu(widget)

Arguments:

• reference to widget -- karamba

Return Value:
reference to menu

[edit] deleteMenu

This deletes the referenced menu if that menu exists.

Synopsis:
boolean deleteMenu(widget, menu)

Arguments:

• reference to widget -- karamba
• reference to menu -- pointer to menu

Return Value:
true if menu existed and was deleted, returns false otherwise.

[edit] popupMenu

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.

Synopsis:
boolean popupMenu(widget, menu, x, y)

Arguments:

• reference to widget -- karamba
• reference to menu -- menu
• integer x -- x coordinate
• integer y -- y coordinate

Return Value:
true if the menu existed and was popped up, returns false otherwise.

[edit] removeMenuItem

This removes the menu if it exists.

Synopsis:
boolean removeMenuItem(widget, menu, id)

Arguments:

• reference to widget -- karamba
• reference to menu -- pointer to menu
• reference to menu item -- menu item

Return Value:
1 if the menu item existed and was removed or returns zero otherwise.

[edit] Misc

[edit] acceptDrops

Calling this enables your widget to receive Drop events. In other words, the user will be able to drag icons from his/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.

Synopsis:
boolean acceptDrops(widget)

Arguments:

• reference to widget -- karamba

Return Value:
true if successful

[edit] attachClickArea

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

Synopsis:
boolean attachClickArea(widget, meter, lB, mB, rB)

Arguments:

• reference to widget -- karamba
• reference to meter -- meter
• string lB -- command to left mouse button
• string mB -- command to middle mouse button
• string rB -- command to right mouse button

Return Value:
true if successful

[edit] callTheme

Calls a theme - identified by the pretty name - and passes it a string to it. This will work, despite superkaramba being multithreaded, because it uses the DBus interface to contact the other theme. If you need to pass complex arguments (dictionaries, lists etc.) then use the python "repr" and "eval" functions to marshall and unmarshall the data structure.

Synopsis:
boolean callTheme(widget, theme, info)

Arguments:

• reference to widget -- karamba
• string theme -- pretty theme name
• string info -- a string containing the info to be passed to the theme

Return Value:
true if successful

[edit] changeInterval

This function changes your widget's refresh rate (ms)

Synopsis:
boolean changeInterval(widget, interval)

Arguments:

• reference to widget -- karamba
• integer interval -- interval, in ms

Return Value:
true if successful

[edit] createClickArea

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 over this area.

Synopsis:
reference createClickArea(widget, x, y, w, h, cmdToRun)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• integer w -- width
• integer h -- height
• string cmdToRun -- command to be run

Return Value:
reference to the new click area

[edit] createServiceClickArea

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. For more information on the difference between createClickArea() and createServiceClickArea, see the KDE documentation about KService, and the difference between KRun::run() and KRun::runCommand.

Synopsis:
reference createServiceClickArea(widget, x, y, w, h, name_of_command, cmd_to_run, icon_to_display)

Arguments:

• reference to widget -- karamba
• integer x -- x coordinate
• integer y -- y coordinate
• integer w -- width
• integer h -- height
• string name_of_command -- name to be displayed
• string cmd_to_run -- command to be run()
• string icon_to_display -- name of icon to be displayed

Return Value:
reference to the new click area

[edit] execute

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.

Synopsis:
integer execute(command)

Arguments:

• string command -- command to execute

Return Value:
process id of the executed command

[edit] executeInteractive

This command executes a program or command on the system. Additionally 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 separate 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)

Synopsis:
integer executeInteractive(widget, command)

Arguments:

• reference to widget -- karamba
• list command -- command to execute()

Return Value:
process id of the executed command

[edit] getIconByName

Returns the absolute path to the icon. This function respects chosen icon set. In case the icon is not found, the path to "unknown.png" is returned.
Example: getIconByName('txt',32) would return something like "/usr/share/icons/crystalsvg/32x32/mimetypes/txt.png"

Synopsis:
string getIconByName(name, size)

Arguments:

• string name -- Name of the icon
• integer size -- Size of the icon (16, 22, 32, 48, 64, 128)

Return Value:
string with the absolute path to the icon

[edit] getIncomingData

Obtains the last data received by any other theme that set the "incoming data" of this theme. This isn't particularly sophisticated and could benefit from the data being placed in an FIFO queue instead.

Synopsis:
string getIncomingData(widget)

Arguments:

• reference to widget -- karamba

Return Value:
string containing the last information received from setIncomingData()

[edit] getIp

Gets the current IP address of the interface_name interface.

Synopsis:
string getIp(widget, interface_name)

Arguments:

• reference to widget -- karamba
• string interface_name -- name of the interface

Return Value:
ip address as string

[edit] getNumberOfDesktop

Returns number of desktops

Synopsis:
integer getNumberOfDesktop(widget)

Arguments:

• reference to widget -- karamba

Return Value:
number of desktops

[edit] getPrettyThemeName

When a theme is created (with openNamedTheme()), there is an option to give the theme an alternative name. This is useful if you open several widgets from the same theme: you need to give them unique names in order to contact them (for example, with callTheme() or with setIncomingData()

Synopsis:
string getPrettyName(theme)

Arguments:

• string theme -- path to n