(performTaskAction)
 
Line 1: Line 1:
= 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 [http://netdragon.sourceforge.net/api.html here].
 
  
== Bar ==
 
 
=== createBar ===
 
This creates a bar at x, y with width and height w, h.
 
<br><br>'''Synopsis:'''<br>
 
reference createBar(widget, x, y, w, h, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
* integer w -- width
 
* integer h -- height
 
* string image -- Path to image
 
<br>'''Return Value:'''<br>
 
Reference to new bar meter
 
 
=== deleteBar ===
 
This deletes the bar.
 
<br><br>'''Synopsis:'''<br>
 
boolean deleteBar(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== getBarImage ===
 
Get the path to the bar image.
 
<br><br>'''Synopsis:'''<br>
 
string getBarImage(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
path to bar image
 
 
=== getBarMinMax ===
 
Returns possible min and max values of the bar.
 
<br><br>'''Synopsis:'''<br>
 
array getBarMinMax(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference bar -- bar
 
<br>'''Return Value:'''<br>
 
array with max & min values
 
 
=== getBarPos ===
 
Given a reference to a bar object, this will return a array
 
containing the x and y coordinate of a bar object.
 
<br><br>'''Synopsis:'''<br>
 
array getBarPos(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
array with x and y coordinates
 
 
=== getBarSensor ===
 
Gets the current sensor string.
 
<br><br>'''Synopsis:'''<br>
 
string getBarSensor(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
sensor string
 
 
=== getBarSize ===
 
Given a reference to a bar object, this will return a array
 
containing the height and width of the bar object.
 
<br><br>'''Synopsis:'''<br>
 
array getBarSize(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
array with width and height
 
 
=== getBarValue ===
 
Returns current bar value.
 
<br><br>'''Synopsis:'''<br>
 
integer getBarValue(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
value
 
 
=== getBarVertical ===
 
Check if bar is a vertical bar.
 
<br><br>'''Synopsis:'''<br>
 
boolean getBarVertical(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
true if vertical
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
reference getThemeBar(widget, name)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string name -- name of the bar in the theme file
 
<br>'''Return Value:'''<br>
 
reference to bar
 
 
=== hideBar ===
 
This hides an bar. In other words, during subsequent calls to
 
widgetUpdate(), this bar will not be drawn.
 
<br><br>'''Synopsis:'''<br>
 
boolean hideBar(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== moveBar ===
 
This will move the bar to new x and y coordinates.
 
<br><br>'''Synopsis:'''<br>
 
boolean moveBar(widget, bar, x, y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
<br>'''Return Value:'''<br>
 
boolean (true if successful)
 
 
=== resizeBar ===
 
This will resize bar to new height and width.
 
<br><br>'''Synopsis:'''<br>
 
boolean resizeBar(widget, bar, w, h)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
* integer w -- new width
 
* integer h -- new height
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setBarImage ===
 
Use the image in path for the background as the bar
 
<br><br>'''Synopsis:'''<br>
 
boolean setBarImage(widget, bar, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
* string image -- path to the new image
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setBarMinMax ===
 
Returns current bar value.
 
<br><br>'''Synopsis:'''<br>
 
boolean setBarMinMax(widget, bar, min, max)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
* integer min -- min value
 
* integer max -- max value
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setBarSensor ===
 
Sets the sensor string of the bar.
 
<br><br>'''Synopsis:'''<br>
 
boolean setBarSensor(widget, bar, sensor)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
* string sensor -- new sensor string as in theme files
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setBarValue ===
 
Sets current bar value.
 
<br><br>'''Synopsis:'''<br>
 
reference setBarValue(widget, bar, value)
 
<br><br>'''Arguments:'''<br>
 
* long widget -- karamba
 
* long bar -- pointer to bar
 
* long value -- new value
 
<br>'''Return Value:'''<br>
 
reference to bar
 
 
=== setBarVertical ===
 
Set bar vertical
 
<br><br>'''Synopsis:'''<br>
 
boolean setBarVertical(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
* boolean vertical -- true to draw the bar vertically
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== showBar ===
 
This shows an bar. In other words, during subsequent calls to
 
widgetUpdate(), this bar will be drawn.
 
<br><br>'''Synopsis:'''<br>
 
boolean showBar(widget, bar)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to bar -- bar
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
 
== Config ==
 
 
=== 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")
 
<br><br>'''Synopsis:'''<br>
 
boolean addMenuConfigOption(widget, key, name)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string key -- key for menu item
 
* string name -- name of the graph to get
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== readConfigEntry ===
 
This function reads an entry from the config file with the given key.
 
<br><br>'''Synopsis:'''<br>
 
string readConfigEntry(widget, key, value)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string key -- key for config item
 
<br>'''Return Value:'''<br>
 
config value for key
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean readMenuConfigOption(widget, key)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string key -- key for menu item
 
<br>'''Return Value:'''<br>
 
false is returned if it is not checked and true is returned if it is.
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean setMenuConfigOption(widget, key, value)
 
<br><br>'''Arguments:'''<br>
 
* referencce to widget -- karamba
 
* string key -- key for menu item
 
* boolean value -- true for checked
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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")
 
<br><br>'''Synopsis:'''<br>
 
boolean writeConfigEntry(widget, key, value)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string key -- key for config item
 
* string value -- config value
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
== Graph ==
 
 
=== createGraph ===
 
This creates a graph at x, y with width and height.
 
<br><br>'''Synopsis:'''<br>
 
reference createGraph(widget, x, y, width, height, points)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
reference to new graph meter
 
 
=== deleteGraph ===
 
This deletes graph.
 
<br><br>'''Synopsis:'''<br>
 
boolean deleteGraph(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== getGraphColor ===
 
Gets the current graph color components.
 
<br><br>'''Synopsis:'''<br>
 
array getGraphColor(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
(red, green, blue)
 
 
=== getGraphMinMax ===
 
Returns current graph minimal and maximal values.
 
<br><br>'''Synopsis:'''<br>
 
array getGraphMinMax(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
max and min values
 
 
=== getGraphPos ===
 
Given a reference to a graph object, this will return an array
 
containing the x and y coordinates of the graph object.
 
<br><br>'''Synopsis:'''<br>
 
array getGraphPos(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
x and y coordinates
 
 
=== getGraphSensor ===
 
Gets the current sensor string of the graph.
 
<br><br>'''Synopsis:'''<br>
 
string getGraphSensor(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
sensor string
 
 
=== getGraphSize ===
 
Given a reference to a graph object, this will return an array
 
containing the height and width of a graph object.
 
<br><br>'''Synopsis:'''<br>
 
array getGraphSize(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
width and height of the graph
 
 
=== getGraphValue ===
 
Returns current graph value.
 
<br><br>'''Synopsis:'''<br>
 
integer getGraphValue(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
value
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
reference getThemeGraph(widget, name)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string name -- name of the graph in the theme file
 
<br>'''Return Value:'''<br>
 
reference to graph
 
 
=== hideGraph ===
 
This hides a graph. In other words, during subsequent calls to
 
widgetUpdate(), this graph will not be drawn.
 
<br><br>'''Synopsis:'''<br>
 
boolean hideGraph(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== moveGraph ===
 
This will move the graph to the new x and y coordinates.
 
<br><br>'''Synopsis:'''<br>
 
boolean moveGraph(widget, graph, x, y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== resizeGraph ===
 
This will resize graph to new height and width.
 
<br><br>'''Synopsis:'''<br>
 
boolean resizeGraph(widget, graph, width, height)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
* integer  width -- new width
 
* integer height -- new height
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setGraphColor ===
 
Sets current graph color.
 
<br><br>'''Synopsis:'''<br>
 
boolean setGraphColor(widget, graph, red, green, blue)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setGraphMinMax ===
 
Sets the graphs min and max values.
 
<br><br>'''Synopsis:'''<br>
 
boolean setGraphMinMax(widget, graph, min, max)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
* integer min -- min value
 
* integer max -- max value
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setGraphSensor ===
 
Sets current sensor string of the graph.
 
<br><br>'''Synopsis:'''<br>
 
boolean setGraphSensor(widget, graph, sensor)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
* string sensor -- new sensor string as in theme files
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setGraphValue ===
 
Sets current graph value.
 
<br><br>'''Synopsis:'''<br>
 
reference setGraphValue(widget, graph, value)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
* integer value -- new value
 
<br>'''Return Value:'''<br>
 
reference to graph
 
 
=== showGraph ===
 
This shows a graph. In other words, during subsequent calls to
 
widgetUpdate(), this graph will be drawn.
 
<br><br>'''Synopsis:'''<br>
 
boolean showGraph(widget, graph)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to graph -- graph
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
== Image ==
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean addImageTooltip(widget, image, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
* string text -- tooltip text
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== changeImageChannelIntensity ===
 
Changes the "intensity" of the image color channel, which is similar to
 
it's brightness.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeImageChannelIntensity(widget, image, ratio, channel, millisec)
 
<br><br>'''Arguments:'''<br>
 
* 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)
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeImageIntensity(widget, image, ratio, millisec)
 
<br><br>'''Arguments:'''<br>
 
* 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)
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeImageToGray(widget, image, millisec)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
* integer millisec -- milliseconds before the image is restored (optional)
 
<br>'''Return Value:'''<br>
 
1 if successful
 
 
=== 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()
 
<br><br>'''Synopsis:'''<br>
 
reference createBackgroundImage(widget, x, y, w, h, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
* string image -- path to the image for the background
 
<br>'''Return Value:'''<br>
 
reference to new image meter
 
 
=== 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()
 
<br><br>'''Synopsis:'''<br>
 
reference createImage(widget, x, y, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
* string image -- image for the imagelabel
 
<br>'''Return Value:'''<br>
 
reference to new image meter
 
 
=== createTaskIcon ===
 
This creates a task image at x, y.
 
<br><br>'''Synopsis:'''<br>
 
reference createTaskIcon(widget, x, y, ctask)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
* integer task -- task
 
<br>'''Return Value:'''<br>
 
reference to new image meter
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean deleteImage(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
integer getImageHeight(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
height of the image
 
 
=== getImagePath ===
 
Returns the current image path.
 
<br><br>'''Synopsis:'''<br>
 
string getImagePath(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
path
 
 
=== getImagePos ===
 
Given a reference to a image object, this will return a tuple
 
containing the x and y coordinate of a image object.
 
<br><br>'''Synopsis:'''<br>
 
array getImagePos(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
x and y coordinates of the image
 
 
=== getImageSensor ===
 
Gets the current sensor string.
 
<br><br>'''Synopsis:'''<br>
 
string getImageSensor(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
sensor string
 
 
=== getImageSize ===
 
Given a reference to a image object, this will return an array
 
containing the height and width of a image object.
 
<br><br>'''Synopsis:'''<br>
 
array getImageSize(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
height and width of the image
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
integer getImageWidth(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
width of the image
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
long getThemeImage(widget, name)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string name -- name of the image in the theme files
 
<br>'''Return Value:'''<br>
 
reference to image
 
 
=== hideImage ===
 
This hides an image. In other words, during subsequent calls to
 
widgetUpdate(), this image will not be drawn.
 
<br><br>'''Synopsis:'''<br>
 
boolean hideImage(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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()
 
<br><br>'''Synopsis:'''<br>
 
boolean moveImage(widget, image, x, y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean removeImageEffects(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== removeImageTransformations ===
 
If you have rotated or resized your image, you can call this function to restore
 
your image to its original form.
 
<br><br>'''Synopsis:'''<br>
 
boolean removeImageTransformations(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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()
 
<br><br>'''Synopsis:'''<br>
 
boolean resizeImage(widget, image, w, h)
 
<br><br>'''Arguments:'''<br>
 
* reference widget -- karamba
 
* reference image -- image
 
* integer w -- width
 
* integer h -- height
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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().
 
<br><br>'''Synopsis:'''<br>
 
boolean resizeImageSmooth(widget, image, w, h)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
* integer w -- width
 
* integer h -- height
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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()
 
<br><br>'''Synopsis:'''<br>
 
long rotateImage(widget, image, deg)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
* integer deg -- degrees to rotate
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setImagePath ===
 
This will change image of a image widget.
 
<br><br>'''Synopsis:'''<br>
 
reference setImagePath(widget, image, path)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
* string path -- new path of the image
 
<br>'''Return Value:'''<br>
 
reference to the image
 
 
=== setImageSensor ===
 
Sets the current sensor string.
 
<br><br>'''Synopsis:'''<br>
 
long setImageSensor(widget, image, sensor)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
* string sensor -- new sensor string as in theme files
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== showImage ===
 
This shows a previously hidden image. It does not actually refresh the
 
image on screen. That is what redrawWidget() does.
 
<br><br>'''Synopsis:'''<br>
 
boolean showImage(widget, image)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to image -- image
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
 
== Input Box ==
 
 
=== changeInputBox ===
 
This function will change the contents of a input box widget.
 
<br><br>'''Synopsis:'''<br>
 
reference changeInputBox(widget, inputBox, value)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
* string value -- new text of the input box
 
<br>'''Return Value:'''<br>
 
reference to input box
 
 
=== 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, and blue.
 
<br><br>'''Synopsis:'''<br>
 
reference changeInputBoxBackgroundColor(widget, inputBox, r, g, b)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeInputBoxFont(widget, inputBox, font)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- inputBox
 
* string font -- font name
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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, and blue.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeInputBoxFontColor(widget, inputBox, r, g, b)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeInputBoxFontSize(widget, text, size)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
* integer size -- new font size for text
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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, and blue.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeInputBoxFrameColor(widget, inputBox, r, g, b)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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, and blue.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeInputBoxSelectedTextColor(widget, inputBox, r, g, b)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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, and blue.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeInputBoxSelectionColor(widget, inputBox, r, g, b)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== clearInputFocus ===
 
Releases the input focus from the Input Box.
 
<br><br>'''Synopsis:'''<br>
 
boolean clearInputFocus(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- pointer to Input Box
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
reference createInputBox(widget, x, y, w, h, text)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
reference to new Input Box
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean deleteInputBox(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference widget -- InputBox
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== getInputBoxBackgroundColor ===
 
Gets the current background color of a Input Box
 
<br><br>'''Synopsis:'''<br>
 
array getInputBoxBackgroundColor(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
(red, green, blue)
 
 
=== getInputBoxFont ===
 
Gets the current Input Box font name
 
<br><br>'''Synopsis:'''<br>
 
string getInputBoxFont(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
font name
 
 
=== getInputBoxFontColor ===
 
Gets the current text color of a Input Box
 
<br><br>'''Synopsis:'''<br>
 
array getInputBoxFontColor(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
(red, green, blue)
 
 
=== getInputBoxFontSize ===
 
Gets the current text font size.
 
<br><br>'''Synopsis:'''<br>
 
integer getInputBoxFontSize(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
text font size
 
 
=== getInputBoxFrameColor ===
 
Gets the current frame color of a Input Box
 
<br><br>'''Synopsis:'''<br>
 
array getInputBoxFrameColor(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
(red, green, blue)
 
 
=== getInputBoxPos ===
 
Given a reference to a Input Box object, this will return an array
 
containing the x and y coordinate of an Input Box.
 
<br><br>'''Synopsis:'''<br>
 
array getInputBoxPos(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
x and y coordinates of the inputBox
 
 
=== getInputBoxSelectedTextColor ===
 
Gets the current selected text color of a Input Box.
 
<br><br>'''Synopsis:'''<br>
 
array getInputBoxSelectedTextColor(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- pointer to Input Box
 
<br>'''Return Value:'''<br>
 
(red, green, blue)
 
 
=== getInputBoxSelectionColor ===
 
Gets the current selection color of a Input Box
 
<br><br>'''Synopsis:'''<br>
 
array getInputBoxSelectionColor(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
(red, green, blue)
 
 
=== getInputBoxSize ===
 
Given a reference to a Input Box object, this will return an array
 
containing the height and width of a Input Box object.
 
<br><br>'''Synopsis:'''<br>
 
array getInputBoxSize(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
width and hight of the input box
 
 
=== getInputBoxValue ===
 
Returns current Input Box text.
 
<br><br>'''Synopsis:'''<br>
 
string getInputBoxValue(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
input box text
 
 
=== getInputFocus ===
 
Gets the Input Box that is currently focused.
 
<br><br>'''Synopsis:'''<br>
 
boolean  getInputFocus(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
the input box or 0
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
reference getThemeInputBox(widget, name)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string name -- name of the Input Box in the theme file
 
<br>'''Return Value:'''<br>
 
reference to Input Box
 
 
=== hideInputBox ===
 
Hides a Input Box that is visible.
 
<br><br>'''Synopsis:'''<br>
 
boolean hideInputBox(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
long moveInputBox(widget, inputBox, x, y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== resizeInputBox ===
 
This will resize Input Box to the new height and width.
 
<br><br>'''Synopsis:'''<br>
 
boolean resizeInputBox(widget, inputBox, w, h)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* referenc to inputBox -- Input Box
 
* integer w -- new width
 
* integer h -- new height
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setInputFocus ===
 
Sets the input focus to the Input Box.
 
<br><br>'''Synopsis:'''<br>
 
boolean setInputFocus(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== showInputBox ===
 
Shows Input Box that has been hidden with hideInputBox()
 
<br><br>'''Synopsis:'''<br>
 
boolean showInputBox(widget, inputBox)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to inputBox -- Input Box
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
== Menu ==
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
reference addMenuItem(widget, menu, text, icon)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to menu -- menu
 
* string text -- text for menu item
 
* string icon -- icon name or path
 
<br>'''Return Value:'''<br>
 
reference to the menu item
 
 
=== addMenuSeparator ===
 
This adds an menu separator to the given menu.
 
<br><br>'''Synopsis:'''<br>
 
reference addMenuSeparator(widget, menu)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to menu -- menu
 
<br>'''Return Value:'''<br>
 
reference to the separator
 
 
=== createMenu ===
 
This creates an empty popup menu and returns a reference to the menu.
 
<br><br>'''Synopsis:'''<br>
 
reference createMenu(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
reference to menu
 
 
=== deleteMenu ===
 
This deletes the referenced menu if that menu exists.
 
<br><br>'''Synopsis:'''<br>
 
boolean deleteMenu(widget, menu)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to menu -- pointer to menu
 
<br>'''Return Value:'''<br>
 
true if menu existed and was deleted, returns false otherwise.
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean popupMenu(widget, menu, x, y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to menu -- menu
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
<br>'''Return Value:'''<br>
 
true if the menu existed and was popped up, returns false otherwise.
 
 
=== removeMenuItem ===
 
This removes the menu if it exists.
 
<br><br>'''Synopsis:'''<br>
 
boolean removeMenuItem(widget, menu, id)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to menu -- pointer to menu
 
* reference to menu item -- menu item
 
<br>'''Return Value:'''<br>
 
1 if the menu item existed and was removed or returns zero otherwise.
 
 
== Misc ==
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean acceptDrops(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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).
 
<br><br>'''Synopsis:'''<br>
 
boolean attachClickArea(widget, meter, lB, mB, rB)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
boolean callTheme(widget, theme, info)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string theme -- pretty theme name
 
* string info -- a string containing the info to be passed to the theme
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== changeInterval ===
 
This function changes your widget's refresh rate (ms)
 
<br><br>'''Synopsis:'''<br>
 
boolean changeInterval(widget, interval)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer interval -- interval, in ms
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
reference createClickArea(widget, x, y, w, h, cmdToRun)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
* integer w -- width
 
* integer h -- height
 
* string cmdToRun -- command to be run
 
<br>'''Return Value:'''<br>
 
reference to the new click area
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
reference createServiceClickArea(widget, x, y, w, h, name_of_command, cmd_to_run, icon_to_display)
 
<br><br>'''Arguments:'''<br>
 
* 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
 
<br>'''Return Value:'''<br>
 
reference to the new click area
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
integer execute(command)
 
<br><br>'''Arguments:'''<br>
 
* string command -- command to execute
 
<br>'''Return Value:'''<br>
 
process id of the executed command
 
 
=== 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)
 
<br><br>'''Synopsis:'''<br>
 
integer executeInteractive(widget, command)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* list command -- command to execute()
 
<br>'''Return Value:'''<br>
 
process id of the executed command
 
 
=== 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.
 
<br><br>'''Synopsis:'''<br>
 
string getIncomingData(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
string containing the last information received from setIncomingData()
 
 
=== getIp ===
 
Gets the current IP address of the interface_name interface.
 
<br><br>'''Synopsis:'''<br>
 
string getIp(widget, interface_name)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string interface_name -- name of the interface
 
<br>'''Return Value:'''<br>
 
ip address as string
 
 
=== getNumberOfDesktop ===
 
Returns number of desktops
 
<br><br>'''Synopsis:'''<br>
 
integer getNumberOfDesktop(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
number of desktops
 
 
=== 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()
 
<br><br>'''Synopsis:'''<br>
 
string getPrettyName(theme)
 
<br><br>'''Arguments:'''<br>
 
* string theme -- path to new theme
 
<br>'''Return Value:'''<br>
 
the pretty name of the theme
 
 
=== getServiceGroups ===
 
This function returns a list of services and service groups
 
that are in the user's KDE Menu.  It is not a recursive
 
function, so if there are submenus (service groups) in the
 
returned results, you must call getServiceGroups with the
 
path of the submenu in order to obtain the information in
 
that submenu.
 
The return result is complex: it's a list of tuples.
 
The tuple contains two elements - a 1 if the second element
 
is a service, and a 0 if it's a service group.
 
The second element is a dictionary, with keys (if they exist)
 
of caption, comment, icon, and relpath if it's a service group,
 
and keys (if they exist) of exec, menuid, name, path, icon,
 
library, comment, type and genericname.
 
To fully understand the return results of this function,
 
it is thoroughly recommended that you look up the
 
KDE documentation on KServiceGroup and KService.
 
<br><br>'''Synopsis:'''<br>
 
list getServiceGroups(widget, path)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string path -- path to the Service Group you wish to retrieve
 
<br>'''Return Value:'''<br>
 
List of Dictionaries of services and service groups
 
 
=== getThemePath ===
 
Returns a string containing the directory where your theme was loaded
 
from.
 
<br><br>'''Synopsis:'''<br>
 
string getThemePath(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
path to theme
 
 
=== getUpdateTime ===
 
Returns the last stored update time. Intended for use
 
so that the next refresh interval can work out how long ago
 
the mouse was last moved over the widget.
 
<br><br>'''Synopsis:'''<br>
 
decimal getUpdateTime(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
last stored update time (from setUpdateTime())
 
 
=== hide ===
 
Hides the widget.
 
<br><br>'''Synopsis:'''<br>
 
boolean hide(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== language ===
 
Returns a string containing the default language of a translation file.
 
<br><br>'''Synopsis:'''<br>
 
string language(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
default language or empty string if no translation files found.
 
 
=== managementPopup ===
 
The right click menu of SuperKaramba allows themes
 
to be loaded, closed, moved to other screens.
 
If you want this popup menu to appear, call
 
this function.
 
<br><br>'''Synopsis:'''<br>
 
boolean managementPopup(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== openNamedTheme ===
 
Opens a new theme, giving it a pretty (alternative and by your
 
own choice _unique_) name.
 
If you do not want the theme to be loaded when SuperKaramba is
 
first started up (but instead want it to only be opened by
 
this function call) then set is_sub_theme to 1.
 
Themes opened with openNamedTheme will be unique.  If a theme
 
with the same pretty name already exists, openNamedTheme will
 
have no effect.  If you want duplicate themes (and a bit of a
 
mess), use openTheme(), instead.
 
<br><br>'''Synopsis:'''<br>
 
reference openNamedTheme(theme, pretty_name, is_sub_theme)
 
<br><br>'''Arguments:'''<br>
 
* string theme -- path to new theme
 
* string pretty_name -- the name to be associated with the new widget
 
* boolean is_sub_theme -- sets persistence (save state) of the theme
 
<br>'''Return Value:'''<br>
 
reference to the new widget
 
 
=== openTheme ===
 
Opens a new theme.
 
<br><br>'''Synopsis:'''<br>
 
reference openTheme(theme)
 
<br><br>'''Arguments:'''<br>
 
* string theme -- path to theme that will be opened
 
<br>'''Return Value:'''<br>
 
reference to the new widget
 
 
=== readThemeFile ===
 
Returns a string with the contents of the theme file
 
<br><br>'''Synopsis:'''<br>
 
string readThemeFile(widget, file)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string file -- name of the file to read
 
<br>'''Return Value:'''<br>
 
file contents
 
 
=== reloadTheme ===
 
Reloads the current theme.
 
<br><br>'''Synopsis:'''<br>
 
boolean reloadTheme(theme)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== removeClickArea ===
 
This function deletes a clickable area.
 
<br><br>'''Synopsis:'''<br>
 
boolean removeClickArea(widget, clickarea)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to clickarea -- click area
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== run ===
 
This command simply executes a program or command on the system.
 
The difference between run and execute() is that run takes arguments,
 
and the name of the icon to be displayed.
 
<br><br>'''Synopsis:'''<br>
 
boolean run(name, command, icon, list_of_args)
 
<br><br>'''Arguments:'''<br>
 
* string name -- name to be displayed
 
* string command -- command to execute()
 
* string icon -- name of icon to be displayed
 
* string list_of_args -- arguments to be passed to the command
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setIncomingData ===
 
Contacts a theme - identified by the pretty name - and stores a string
 
to be associated with the remote theme. The difference between
 
setIncomingData and callTheme() is that the theme is not notified
 
by setIncomingData that the data has arrived. Previous information,
 
if any, is overwritten. Use getIncomingData() to retrieve the last
 
stored information.
 
setIncomingData is not very sophisticated, and could benefit from
 
having info passed to it put into a queue, instead of being overwritten.
 
<br><br>'''Synopsis:'''<br>
 
boolean setIncomingData(widget, theme, info)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string theme -- path to theme to have information passed to it.
 
* string info -- a string containing the info to be passed to the theme
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setUpdateTime ===
 
Sets the update time. Intended for use
 
so that the next refresh interval can work out how long ago
 
the mouse was last moved over the widget.
 
<br><br>'''Synopsis:'''<br>
 
boolean getUpdateTime(widget, updated_time)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer updated_time -- the update time to be associated with the widget
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== show ===
 
Shows the widget.
 
<br><br>'''Synopsis:'''<br>
 
boolean show(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== toggleShowDesktop ===
 
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.
 
<br><br>'''Synopsis:'''<br>
 
boolean toggleShowDesktop(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== translateAll ===
 
Moves all widgets within a theme in a particular direction relative from
 
the previous spot without moving the parent theme widget.
 
<br><br>'''Synopsis:'''<br>
 
boolean translateAll(widget, relative_x, relative_y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer translate_x -- move horizontally
 
* integer translate_y -- move vertically
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== userLanguage ===
 
Returns a string containing the global KDE user language.
 
<br><br>'''Synopsis:'''<br>
 
string userLanguage(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
user language or empty string
 
 
=== userLanguages ===
 
Returns an array containing the language name abbreviations for the
 
preferred interface languages user chose for KDE session in Region &
 
Language settings.
 
Having the whole array of preferred languages available is important for
 
cases when you cannot provide interface translation for the 1st preferred
 
language, but can for consecutive languages.
 
(Implemented in version 0.42.)
 
<br><br>'''Synopsis:'''<br>
 
array userLanguages(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
list (array) with user languages in the order of preference.
 
 
=== wantRightButton ===
 
The right click menu of SuperKaramba allows themes
 
to be loaded, closed, moved to other screens.
 
Not all themes will want the right click menu.
 
Call karamba.wantRightButton(widget, 1)
 
if you want to receive MouseUpdate button notifications.
 
<br><br>'''Synopsis:'''<br>
 
boolean wantRightButton(widget, want_receive_right_button)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* boolean want_receive_right_button -- whether the widget will receive right clicks
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
== Rich Text ==
 
 
=== changeRichText ===
 
This will change the contents of a rich text meter. 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. Unfortunately currently only when using absolute
 
paths.
 
<br><br>'''Synopsis:'''<br>
 
reference changeRichText(widget, richtext, value)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
* string value -- new text
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== changeRichTextFont ===
 
This will change the font of a richtext meter.
 
<br><br>'''Synopsis:'''<br>
 
long changeRichTextFont(widget, richtext, font)
 
<br><br>'''Arguments:'''<br>
 
* long widget -- karamba
 
* long richtext -- richtext
 
* string font -- name of the new font
 
<br>'''Return Value:'''<br>
 
1 if successful
 
 
=== changeRichTextSize ===
 
Sets the font size of a richtext meter.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeRichTextSize(widget, richtext, size)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
* long size -- new font point size
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== createRichText ===
 
This creates creates a new rich text meter. 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. Unfortunately currently only when using absolute
 
paths.
 
<br><br>'''Synopsis:'''<br>
 
reference createRichText(widget, text, underlineLinks)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string text -- text for richtext
 
* boolean underlineLinks -- should the links be underlined
 
<br>'''Return Value:'''<br>
 
reference to new richtext meter
 
 
=== deleteRichText ===
 
This removes the rich text from the widget. Please do not call
 
functions on "text" after calling deleteRichText, as it does not exist
 
anymore and that could cause crashes in some cases.
 
<br><br>'''Synopsis:'''<br>
 
boolean deleteRichText(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to widget -- richtext
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== getRichTextFont ===
 
Gets the font name of a richtext meter.
 
<br><br>'''Synopsis:'''<br>
 
string getRichTextFont(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
<br>'''Return Value:'''<br>
 
font name
 
 
=== getRichTextFontSize ===
 
Gets the font size of the richtext meter.
 
<br><br>'''Synopsis:'''<br>
 
integer getRichTextFontSize(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
<br>'''Return Value:'''<br>
 
font point size
 
 
=== getRichTextPos ===
 
Given a reference to a richtext object, this will return an array
 
containing the x and y coordinate of a richtext object.
 
<br><br>'''Synopsis:'''<br>
 
array getRichTextPos(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
<br>'''Return Value:'''<br>
 
x and y coordinates
 
 
=== getRichTextSensor ===
 
Gets the current sensor string
 
<br><br>'''Synopsis:'''<br>
 
string getRichTextSensor(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
<br>'''Return Value:'''<br>
 
current sensor string
 
 
=== getRichTextSize ===
 
Given a reference to a richtext object, this will return a tuple
 
containing the height and width of a richtext object.
 
<br><br>'''Synopsis:'''<br>
 
array getRichTextSize(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* long widget -- karamba
 
* long richtext -- richtext
 
<br>'''Return Value:'''<br>
 
width and height of the richtext
 
 
=== getRichTextValue ===
 
Returns the current richtext value.
 
<br><br>'''Synopsis:'''<br>
 
string getRichTextValue(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
<br>'''Return Value:'''<br>
 
text that is displayed in the rich text
 
 
=== getThemeRichText ===
 
You can reference richtext 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
 
createRichText, 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.
 
<br><br>'''Synopsis:'''<br>
 
reference getThemeRichText(widget, name)
 
<br><br>'''Arguments:'''<br>
 
* long widget -- karamba
 
* string name -- name of the richtext in the theme file
 
<br>'''Return Value:'''<br>
 
reference to richtext
 
 
=== hideRichText ===
 
This hides the richtext. In other words, during subsequent calls to
 
widgetUpdate(), this richtext will not be drawn.
 
<br><br>'''Synopsis:'''<br>
 
boolean hideRichText(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== moveRichText ===
 
This moves the rich text to a new x, y relative to your widget. In other
 
words, (0,0) is the top corner of your widget, not the screen.
 
<br><br>'''Synopsis:'''<br>
 
boolean moveRichText(widget, richtext, x, y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference richtext -- richtext
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== resizeRichText ===
 
This will resize richtext to the new height and width.
 
<br><br>'''Synopsis:'''<br>
 
boolean resizeRichText(widget, richtext, w, h)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
* integer w -- new width
 
* integer h -- new height
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setRichTextSensor ===
 
Sets a new sensor string
 
<br><br>'''Synopsis:'''<br>
 
boolean setRichTextSensor(widget, richtext, sensor)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
* string sensor -- new sensor string as in theme files
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setRichTextWidth ===
 
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.
 
<br><br>'''Synopsis:'''<br>
 
boolean setRichTextWidth(widget, richtext, width)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
* integer width -- new width in pixels
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== showRichText ===
 
This shows the richtext. In other words, during subsequent calls to
 
widgetUpdate(), this richtext will be drawn.
 
<br><br>'''Synopsis:'''<br>
 
boolean showRichText(widget, richtext)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to richtext -- richtext
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
== Task ==
 
 
=== getStartupInfo ===
 
This returns all of the info about a certain starting task in the form of
 
a 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().
 
<br><br>'''Synopsis:'''<br>
 
list getStartupInfo(widget, task)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to task -- task
 
<br>'''Return Value:'''<br>
 
Here is the format of the returned list by index value:
 
* 0 = Task name (The full name of the window)
 
* 1 = Icon name
 
* 2 = Executable name
 
* 3 = A reference back to the task you got info on
 
 
=== getStartupList ===
 
This returns a list 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.
 
<br><br>'''Synopsis:'''<br>
 
list getTaskList(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
list with references to startups
 
 
=== getTaskInfo ===
 
This returns all of the info about a certain task in the form of a
 
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().
 
<br><br>'''Synopsis:'''<br>
 
list getTaskInfo(widget, task)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to task -- task
 
<br>'''Return Value:'''<br>
 
Here is the format of the returned list by index value:
 
* 0 = Task name (The full name of the window)
 
* 1 = Icon name
 
* 2 = Class name - This is for grouping tasks. All tasks with the same
 
name can be grouped together because they are instances of the same
 
program.
 
* 3 = Desktop number - The desktop number this window is on
 
* 4 = Is this window maximized? false = no, true = yes
 
* 5 = Is this window iconified (minimized)? false = no, true = yes
 
* 6 = Is this window shaded (rolled up)? false = no, true = yes
 
* 7 = Is this window focused? fale = no, true = yes
 
* 8 = A reference back to the task you got info on
 
 
=== getTaskList ===
 
This returns a list 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.
 
<br><br>'''Synopsis:'''<br>
 
list getTaskList(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
list with references to the tasks
 
 
=== getTaskNames ===
 
This returns a 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()
 
<br><br>'''Synopsis:'''<br>
 
list getTaskNames(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
list with task names
 
 
=== performTaskAction ===
 
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:
 
* 1 = Maximize the window
 
* 2 = Restore the window (use on iconified windows)
 
* 3 = Iconify the window (minimize it)
 
* 4 = Close the window
 
* 5 = Activate (give focus to) the window
 
* 6 = Raise the window
 
* 7 = Lower the window
 
* 8 = Smart Focus/Minimize - This will what the KDE taskbar does when you click on a window. If it is iconified, raise it. If it has focus, iconify it.
 
* 9 = Toggle whether this window is always on top
 
* 10 = Toggle whether this window is shaded (rolled up)
 
<br><br>'''Synopsis:'''<br>
 
boolean performTaskAction(widget, task, action)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to task -- task
 
* integer action -- action number
 
<br>'''Return Value:'''<br>
 
boolean if successful
 
 
== Text ==
 
 
=== changeText ===
 
This will change the contents of a text widget.
 
<br><br>'''Synopsis:'''<br>
 
reference changeText(widget, text, value)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* long value -- new text to display
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== changeTextColor ===
 
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.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeTextColor(widget, text, r, g, b)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* integer red -- red component of color
 
* integer green -- green component of color
 
* integer blue -- blue component of color
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== changeTextFont ===
 
This will change the font of a text widget (only ones you created
 
through python currently). Text is the reference to the text
 
object to change that you saved from the createText() call. Font is a
 
string the the name of the font to use.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeTextFont(widget, text, font)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* string font -- font name
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== changeTextShadow ===
 
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.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeTextShadow(widget, text, shadow)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* integer shadow -- shadow offset
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== changeTextSize ===
 
This will change the font size of a text widget (only ones you created
 
through python currently). text is the reference to the text
 
object to change that you saved from the createText() call. size is the
 
new font point size.
 
<br><br>'''Synopsis:'''<br>
 
boolean changeTextSize(widget, text, size)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* integer size -- new size for text
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== createText ===
 
This creates a new text 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 text
 
field, such as changeText()
 
<br><br>'''Synopsis:'''<br>
 
reference createText(widget, x, y, w, h, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
* integer w -- width
 
* integer h -- height
 
* string text -- text for the textlabel
 
<br>'''Return Value:'''<br>
 
Pointer to new text meter
 
 
=== deleteText ===
 
This removes a text object from the widget. Please do not call functions on
 
"text" after calling deleteText, as it does not exist anymore and that
 
could cause crashes in some cases.
 
<br><br>'''Synopsis:'''<br>
 
boolean deleteText(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to widget -- text meter
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== getTextAlign ===
 
Gets the current text alignment.
 
<br><br>'''Synopsis:'''<br>
 
string getTextAlign(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
LEFT, CENTER or RIGHT as string
 
 
=== getTextColor ===
 
Gets the current text color
 
<br><br>'''Synopsis:'''<br>
 
array getTextColor(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
(red, green, blue)
 
 
=== getTextFont ===
 
Gets the current text font name
 
<br><br>'''Synopsis:'''<br>
 
string getTextFont(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
font name
 
 
=== getTextFontSize ===
 
Gets the current text font size.
 
<br><br>'''Synopsis:'''<br>
 
integer getTextFontSize(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
text font size
 
 
=== getTextPos ===
 
Given a reference to a text object, this will return an array
 
containing the x and y coordinate of the text object.
 
<br><br>'''Synopsis:'''<br>
 
array getTextPos(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
x and y coordinate
 
 
=== getTextSensor ===
 
Gets the current sensor string
 
<br><br>'''Synopsis:'''<br>
 
string getTextSensor(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
currently used sensor string
 
 
=== getTextShadow ===
 
Gets the current shadow offset
 
<br><br>'''Synopsis:'''<br>
 
integer getTextShadow(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
shadow offset
 
 
=== getTextSize ===
 
Given a reference to a text object, this will return an array
 
containing the height and width of a text object.
 
<br><br>'''Synopsis:'''<br>
 
array getTextSize(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
height and width of the text
 
 
=== getTextValue ===
 
Returns there current text value.
 
<br><br>'''Synopsis:'''<br>
 
string getTextValue(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
value
 
 
=== getThemeText ===
 
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.
 
<br><br>'''Synopsis:'''<br>
 
reference getThemeText(widget, name)
 
<br><br>'''Arguments:'''<br>
 
* long widget -- karamba
 
* string name -- name of the text in the theme file
 
<br>'''Return Value:'''<br>
 
reference to text
 
 
=== hideText ===
 
Hides text that is visible. You need to call redrawWidget() afterwords
 
to actually hide the text on screen.
 
<br><br>'''Synopsis:'''<br>
 
boolean hideText(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== moveText ===
 
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.
 
<br><br>'''Synopsis:'''<br>
 
boolean moveText(widget, text, x, y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== resizeText ===
 
This will resize text to the new height and width.
 
<br><br>'''Synopsis:'''<br>
 
boolean resizeText(widget, text, w, h)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* integer w -- new width
 
* integer h -- new height
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setTextAlign ===
 
Sets the text label align.
 
<br><br>'''Synopsis:'''<br>
 
boolean setTextAlign(widget, text, align)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* string align -- LEFT, CENTER or RIGHT as string
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== setTextSensor ===
 
Sets a new sensor string
 
<br><br>'''Synopsis:'''<br>
 
boolean setTextSensor(widget, text, sensor)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
* string sensor -- new sensor string as in theme files
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== showText ===
 
Shows text that has been hidden with hideText().
 
<br><br>'''Synopsis:'''<br>
 
boolean showText(widget, text)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* reference to text -- text meter
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
== Widget ==
 
 
=== createWidgetMask ===
 
This function doesn't work currently due to a bug in KDE. Please use
 
MASK= in your .theme file for the time being.
 
WARNING
 
This function does nothing in SuperKaramba 0.50 and later
 
<br><br>'''Synopsis:'''<br>
 
long createWidgetMask(widget, mask)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* string mask --  The path to the widget mask file.
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== getWidgetPosition ===
 
Returns an array containing the x and y position of you widget.
 
widget is a reference to the current widget.
 
<br><br>'''Synopsis:'''<br>
 
array getWidgetPosition(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
position of the widget
 
 
=== moveWidget ===
 
Moves the widget to the new screen location.
 
<br><br>'''Synopsis:'''<br>
 
boolean moveWidget(widget, x, y)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer x -- x coordinate
 
* integer y -- y coordinate
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== redrawWidget ===
 
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.
 
Redraws all meters.
 
<br><br>'''Synopsis:'''<br>
 
boolean redrawWidget(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== redrawWidgetBackground ===
 
Redraws the widget background.
 
WARNING
 
This function does nothing in SuperKaramba 0.50 and later
 
<br><br>'''Synopsis:'''<br>
 
boolean redrawWidgetBackground(widget)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== resizeWidget ===
 
Resizes the widget to the new width and height.
 
<br><br>'''Synopsis:'''<br>
 
boolean resizeWidget(widget, w, h)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* integer w -- width
 
* integer h -- height
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
=== toggleWidgetRedraw ===
 
Toggles widget redraw.
 
This function does nothing in SuperKaramba 0.50 and later
 
<br><br>'''Synopsis:'''<br>
 
boolean toggleWidgetRedraw(widget, b)
 
<br><br>'''Arguments:'''<br>
 
* reference to widget -- karamba
 
* boolean b -- 1 = widget is drawn
 
<br>'''Return Value:'''<br>
 
true if successful
 
 
= Wiki Markup Generation =
 
 
To generate this API documentation execute the make_api_doc.sh script from
 
the SuperKaramba docs dir.
 
 
<pre>
 
./make_api_doc.sh rtf
 
</pre>
 
 
This will generate a rtf file named superkaramba_api.rtf. Open the file in a word processor e.g. OpenOffice and save the file as plain text.
 
 
The next step is to modify the file contents to match the necessary wiki
 
markups. This can be done with the following command.
 
 
<pre>
 
cat sk_plain_api | sed -e "/DESCRIPTION/d;/^[ ]*$/d;s/^*//;s/SYNOPSIS/<br><br>'''Synopsis:'''<br>/;s/ARGUMENTS/<br><br>'''Arguments:'''<br>/;s/RETURN VALUE/<br>'''Return Value:'''<br>/;/\//{s/^/\r\n=== /};/\//{s/$/===/};s/robo[0-9]\{1,\}//g" > SK-API
 
</pre>
 
 
The contents of SK-API file can now be copied into the edit window of the wiki page.
 
 
{{tip|It is recommended to port the changes of this document to the KarambaInterface class to ensure a coherent API document in future.}}
 

Latest revision as of 16:40, 29 April 2007


This page was last edited on 29 April 2007, at 16:40. Content is available under Creative Commons License SA 4.0 unless otherwise noted.