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.
This creates a bar at x, y with width and height w, h.
Synopsis:
reference createBar(widget, x, y, w, h, image)
Arguments:
Return Value:
Reference to new bar meter
This deletes the bar.
Synopsis:
boolean deleteBar(widget, bar)
Arguments:
Return Value:
true if successful
Get the path to the bar image.
Synopsis:
string getBarImage(widget, bar)
Arguments:
Return Value:
path to bar image
Returns possible min and max values of the bar.
Synopsis:
array getBarMinMax(widget, bar)
Arguments:
Return Value:
array with max & min values
Given a reference to a bar object, this will return a array
containing the x and y coordinate of a bar object.
Synopsis:
array getBarPos(widget, bar)
Arguments:
Return Value:
array with x and y coordinates
Gets the current sensor string.
Synopsis:
string getBarSensor(widget, bar)
Arguments:
Return Value:
sensor string
Given a reference to a bar object, this will return a array
containing the height and width of the bar object.
Synopsis:
array getBarSize(widget, bar)
Arguments:
Return Value:
array with width and height
Returns current bar value.
Synopsis:
integer getBarValue(widget, bar)
Arguments:
Return Value:
value
Check if bar is a vertical bar.
Synopsis:
boolean getBarVertical(widget, bar)
Arguments:
Return Value:
true if vertical
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:
Return Value:
reference to bar
This hides an bar. In other words, during subsequent calls to
widgetUpdate(), this bar will not be drawn.
Synopsis:
boolean hideBar(widget, bar)
Arguments:
Return Value:
true if successful
This will move the bar to new x and y coordinates.
Synopsis:
boolean moveBar(widget, bar, x, y)
Arguments:
Return Value:
boolean (true if successful)
This will resize bar to new height and width.
Synopsis:
boolean resizeBar(widget, bar, w, h)
Arguments:
Return Value:
true if successful
Use the image in path for the background as the bar
Synopsis:
boolean setBarImage(widget, bar, image)
Arguments:
Return Value:
true if successful
Returns current bar value.
Synopsis:
boolean setBarMinMax(widget, bar, min, max)
Arguments:
Return Value:
true if successful
Sets the sensor string of the bar.
Synopsis:
boolean setBarSensor(widget, bar, sensor)
Arguments:
Return Value:
true if successful
Sets current bar value.
Synopsis:
reference setBarValue(widget, bar, value)
Arguments:
Return Value:
reference to bar
Set bar vertical
Synopsis:
boolean setBarVertical(widget, bar)
Arguments:
Return Value:
true if successful
This shows an bar. In other words, during subsequent calls to
widgetUpdate(), this bar will be drawn.
Synopsis:
boolean showBar(widget, bar)
Arguments:
Return Value:
true if successful
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:
Return Value:
true if successful
This function reads an entry from the config file with the given key.
Synopsis:
string readConfigEntry(widget, key, value)
Arguments:
Return Value:
config value for key
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:
Return Value:
false is returned if it is not checked and true is returned if it is.
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:
Return Value:
true if successful
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:
Return Value:
true if successful
This creates a graph at x, y with width and height.
Synopsis:
reference createGraph(widget, x, y, width, height, points)
Arguments:
Return Value:
reference to new graph meter
This deletes graph.
Synopsis:
boolean deleteGraph(widget, graph)
Arguments:
Return Value:
true if successful
Gets the current graph color components.
Synopsis:
array getGraphColor(widget, graph)
Arguments:
Return Value:
(red, green, blue, alpha)
Returns current graph minimal and maximal values.
Synopsis:
array getGraphMinMax(widget, graph)
Arguments:
Return Value:
max and min values
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:
Return Value:
x and y coordinates
Gets the current sensor string of the graph.
Synopsis:
string getGraphSensor(widget, graph)
Arguments:
Return Value:
sensor string
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:
Return Value:
width and height of the graph
Returns current graph value.
Synopsis:
integer getGraphValue(widget, graph)
Arguments:
Return Value:
value
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:
Return Value:
reference to graph
This hides a graph. In other words, during subsequent calls to
widgetUpdate(), this graph will not be drawn.
Synopsis:
boolean hideGraph(widget, graph)
Arguments:
Return Value:
true if successful
This will move the graph to the new x and y coordinates.
Synopsis:
boolean moveGraph(widget, graph, x, y)
Arguments:
Return Value:
true if successful
This will resize graph to new height and width.
Synopsis:
boolean resizeGraph(widget, graph, width, height)
Arguments:
Return Value:
true if successful
Sets current graph color.
Synopsis:
boolean setGraphColor(widget, graph, red, green, blue, alpha=255)
Arguments:
Return Value:
true if successful
Sets the graphs min and max values.
Synopsis:
boolean setGraphMinMax(widget, graph, min, max)
Arguments:
Return Value:
true if successful
Sets current sensor string of the graph.
Synopsis:
boolean setGraphSensor(widget, graph, sensor)
Arguments:
Return Value:
true if successful
Sets current graph value.
Synopsis:
reference setGraphValue(widget, graph, value)
Arguments:
Return Value:
reference to graph
This shows a graph. In other words, during subsequent calls to
widgetUpdate(), this graph will be drawn.
Synopsis:
boolean showGraph(widget, graph)
Arguments:
Return Value:
true if successful
This creats a tooltip for image with text. Note:
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:
Return Value:
true if successful
Changes the "intensity" of the image color channel, which is similar to
it's brightness.
Synopsis:
boolean changeImageChannelIntensity(widget, image, ratio, channel, millisec)
Arguments:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
1 if successful
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:
Return Value:
reference to new image meter
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:
Return Value:
reference to new image meter
This creates a task image at x, y.
Synopsis:
reference createTaskIcon(widget, x, y, ctask)
Arguments:
Return Value:
reference to new image meter
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:
Return Value:
true if successful
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:
Return Value:
height of the image
Returns the current image path.
Synopsis:
string getImagePath(widget, image)
Arguments:
Return Value:
path
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:
Return Value:
x and y coordinates of the image
Gets the current sensor string.
Synopsis:
string getImageSensor(widget, image)
Arguments:
Return Value:
sensor string
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:
Return Value:
height and width of the image
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:
Return Value:
width of the image
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:
Return Value:
reference to image
This hides an image. In other words, during subsequent calls to
widgetUpdate(), this image will not be drawn.
Synopsis:
boolean hideImage(widget, image)
Arguments:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
This will change image of a image widget.
Synopsis:
reference setImagePath(widget, image, path)
Arguments:
Return Value:
reference to the image
Sets the current sensor string.
Synopsis:
long setImageSensor(widget, image, sensor)
Arguments:
Return Value:
true if successful
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:
Return Value:
true if successful
This function will change the contents of a input box widget.
Synopsis:
reference changeInputBox(widget, inputBox, value)
Arguments:
Return Value:
reference to input box
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
Releases the input focus from the Input Box.
Synopsis:
boolean clearInputFocus(widget, inputBox)
Arguments:
Return Value:
true if successful
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:
Return Value:
reference to new Input Box
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:
Return Value:
true if successful
Gets the current background color of a Input Box
Synopsis:
array getInputBoxBackgroundColor(widget, inputBox)
Arguments:
Return Value:
(red, green, blue, alpha)
Gets the current Input Box font name
Synopsis:
string getInputBoxFont(widget, inputBox)
Arguments:
Return Value:
font name
Gets the current text color of a Input Box
Synopsis:
array getInputBoxFontColor(widget, inputBox)
Arguments:
Return Value:
(red, green, blue, alpha)
Gets the current text font size.
Synopsis:
integer getInputBoxFontSize(widget, inputBox)
Arguments:
Return Value:
text font size
Gets the current frame color of a Input Box
Synopsis:
array getInputBoxFrameColor(widget, inputBox)
Arguments:
Return Value:
(red, green, blue, alpha)
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:
Return Value:
x and y coordinates of the inputBox
Gets the current selected text color of a Input Box.
Synopsis:
array getInputBoxSelectedTextColor(widget, inputBox)
Arguments:
Return Value:
(red, green, blue, alpha)
Gets the current selection color of a Input Box
Synopsis:
array getInputBoxSelectionColor(widget, inputBox)
Arguments:
Return Value:
(red, green, blue, alpha)
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:
Return Value:
width and hight of the input box
Returns current Input Box text.
Synopsis:
string getInputBoxValue(widget, inputBox)
Arguments:
Return Value:
input box text
Gets the Input Box that is currently focused.
Synopsis:
boolean getInputFocus(widget)
Arguments:
Return Value:
the input box or 0
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:
Return Value:
reference to Input Box
Hides a Input Box that is visible.
Synopsis:
boolean hideInputBox(widget, inputBox)
Arguments:
Return Value:
true if successful
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:
Return Value:
true if successful
This will resize Input Box to the new height and width.
Synopsis:
boolean resizeInputBox(widget, inputBox, w, h)
Arguments:
Return Value:
true if successful
Sets the input focus to the Input Box.
Synopsis:
boolean setInputFocus(widget, inputBox)
Arguments:
Return Value:
true if successful
Shows Input Box that has been hidden with hideInputBox()
Synopsis:
boolean showInputBox(widget, inputBox)
Arguments:
Return Value:
true if successful
Gets the width of the complete text of the Input Box.
Synopsis:
boolean getInputBoxTextWidth(widget, input)
Arguments:
Return Value:
The text width or -1
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:
Return Value:
true if successful
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:
boolean getInputBoxSelection(widget, inputBox)
Arguments:
Return Value:
array with the selection start and length in characters
This will clear the selection of the input box.
Synopsis:
boolean getInputBoxSelection(widget, inputBox)
Arguments:
Return Value:
true if successful
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:
Return Value:
reference to the menu item
This adds an menu separator to the given menu.
Synopsis:
reference addMenuSeparator(widget, menu)
Arguments:
Return Value:
reference to the separator
This creates an empty popup menu and returns a reference to the menu.
Synopsis:
reference createMenu(widget)
Arguments:
Return Value:
reference to menu
This deletes the referenced menu if that menu exists.
Synopsis:
boolean deleteMenu(widget, menu)
Arguments:
Return Value:
true if menu existed and was deleted, returns false otherwise.
This pops up the given menu at the given co-ordinates. The co-ordinates
are relative to the widget, not the screen. You can use negative
co-ordinates to make a menu appear to the right of or above your theme.
Synopsis:
boolean popupMenu(widget, menu, x, y)
Arguments:
Return Value:
true if the menu existed and was popped up, returns false otherwise.
This removes the menu if it exists.
Synopsis:
boolean removeMenuItem(widget, menu, id)
Arguments:
Return Value:
1 if the menu item existed and was removed or returns zero otherwise.
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:
Return Value:
true if successful
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:
Return Value:
true if successful
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:
Return Value:
true if successful
This function changes your widget's refresh rate (ms)
Synopsis:
boolean changeInterval(widget, interval)
Arguments:
Return Value:
true if successful
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:
Return Value:
reference to the new click area
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:
Return Value:
reference to the new click area
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:
Return Value:
process id of the executed command
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:
Return Value:
process id of the executed command
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:
Return Value:
string containing the last information received from setIncomingData()
Gets the current IP address of the interface_name interface.
Synopsis:
string getIp(widget, interface_name)
Arguments:
Return Value:
ip address as string
Returns number of desktops
Synopsis:
integer getNumberOfDesktop(widget)
Arguments:
Return Value:
number of desktops
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:
Return Value:
the pretty name of the theme
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.
Synopsis:
list getServiceGroups(widget, path)
Arguments:
Return Value:
List of Dictionaries of services and service groups
Returns a string containing the directory where your theme was loaded
from.
Synopsis:
string getThemePath(widget)
Arguments:
Return Value:
path to theme
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.
Synopsis:
decimal getUpdateTime(widget)
Arguments:
Return Value:
last stored update time (from setUpdateTime())
Hides the widget.
Synopsis:
boolean hide(widget)
Arguments:
Return Value:
true if successful
Returns a string containing the default language of a translation file.
Synopsis:
string language(widget)
Arguments:
Return Value:
default language or empty string if no translation files found.
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.
Synopsis:
boolean managementPopup(widget)
Arguments:
Return Value:
true if successful
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.
Synopsis:
reference openNamedTheme(theme, pretty_name, is_sub_theme)
Arguments:
Return Value:
reference to the new widget
Opens a new theme.
Synopsis:
reference openTheme(theme)
Arguments:
Return Value:
reference to the new widget
Returns a string with the contents of the theme file
Synopsis:
string readThemeFile(widget, file)
Arguments:
Return Value:
file contents
Reloads the current theme.
Synopsis:
boolean reloadTheme(theme)
Arguments:
Return Value:
true if successful
This function deletes a clickable area.
Synopsis:
boolean removeClickArea(widget, clickarea)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean run(name, command, icon, list_of_args)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean setIncomingData(widget, theme, info)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean getUpdateTime(widget, updated_time)
Arguments:
Return Value:
true if successful
Shows the widget.
Synopsis:
boolean show(widget)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean toggleShowDesktop(widget)
Arguments:
Return Value:
true if successful
Moves all widgets within a theme in a particular direction relative from
the previous spot without moving the parent theme widget.
Synopsis:
boolean translateAll(widget, relative_x, relative_y)
Arguments:
Return Value:
true if successful
Returns a string containing the global KDE user language.
Synopsis:
string userLanguage(widget)
Arguments:
Return Value:
user language or empty string
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.)
Synopsis:
array userLanguages(widget)
Arguments:
Return Value:
list (array) with user languages in the order of preference.
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.
Synopsis:
boolean wantRightButton(widget, want_receive_right_button)
Arguments:
Return Value:
true if successful
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.
Synopsis:
reference changeRichText(widget, richtext, value)
Arguments:
Return Value:
true if successful
This will change the font of a richtext meter.
Synopsis:
long changeRichTextFont(widget, richtext, font)
Arguments:
Return Value:
1 if successful
Sets the font size of a richtext meter.
Synopsis:
boolean changeRichTextSize(widget, richtext, size)
Arguments:
Return Value:
true if successful
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.
Synopsis:
reference createRichText(widget, text, underlineLinks)
Arguments:
Return Value:
reference to new richtext meter
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.
Synopsis:
boolean deleteRichText(widget, richtext)
Arguments:
Return Value:
true if successful
Gets the font name of a richtext meter.
Synopsis:
string getRichTextFont(widget, richtext)
Arguments:
Return Value:
font name
Gets the font size of the richtext meter.
Synopsis:
integer getRichTextFontSize(widget, richtext)
Arguments:
Return Value:
font point size
Given a reference to a richtext object, this will return an array
containing the x and y coordinate of a richtext object.
Synopsis:
array getRichTextPos(widget, richtext)
Arguments:
Return Value:
x and y coordinates
Gets the current sensor string
Synopsis:
string getRichTextSensor(widget, richtext)
Arguments:
Return Value:
current sensor string
Given a reference to a richtext object, this will return a tuple
containing the height and width of a richtext object.
Synopsis:
array getRichTextSize(widget, richtext)
Arguments:
Return Value:
width and height of the richtext
Returns the current richtext value.
Synopsis:
string getRichTextValue(widget, richtext)
Arguments:
Return Value:
text that is displayed in the rich text
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.
Synopsis:
reference getThemeRichText(widget, name)
Arguments:
Return Value:
reference to richtext
This hides the richtext. In other words, during subsequent calls to
widgetUpdate(), this richtext will not be drawn.
Synopsis:
boolean hideRichText(widget, richtext)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean moveRichText(widget, richtext, x, y)
Arguments:
Return Value:
true if successful
This will resize richtext to the new height and width.
Synopsis:
boolean resizeRichText(widget, richtext, w, h)
Arguments:
Return Value:
true if successful
Sets a new sensor string
Synopsis:
boolean setRichTextSensor(widget, richtext, sensor)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean setRichTextWidth(widget, richtext, width)
Arguments:
Return Value:
true if successful
This shows the richtext. In other words, during subsequent calls to
widgetUpdate(), this richtext will be drawn.
Synopsis:
boolean showRichText(widget, richtext)
Arguments:
Return Value:
true if successful
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().
Synopsis:
list getStartupInfo(widget, task)
Arguments:
Return Value:
Here is the format of the returned list by index value:
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.
Synopsis:
list getTaskList(widget)
Arguments:
Return Value:
list with references to startups
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().
Synopsis:
list getTaskInfo(widget, task)
Arguments:
Return Value:
Here is the format of the returned list by index value:
name can be grouped together because they are instances of the same program.
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.
Synopsis:
list getTaskList(widget)
Arguments:
Return Value:
list with references to the tasks
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()
Synopsis:
list getTaskNames(widget)
Arguments:
Return Value:
list with task names
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:
Synopsis:
boolean performTaskAction(widget, task, action)
Arguments:
Return Value:
boolean if successful
This will change the contents of a text widget.
Synopsis:
reference changeText(widget, text, value)
Arguments:
Return Value:
true if successful
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, blue and the alpha channel.
Synopsis:
boolean changeTextColor(widget, text, r, g, b, a=255)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean changeTextFont(widget, text, font)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean changeTextShadow(widget, text, shadow)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean changeTextSize(widget, text, size)
Arguments:
Return Value:
true if successful
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()
Synopsis:
reference createText(widget, x, y, w, h, text)
Arguments:
Return Value:
Pointer to new text meter
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.
Synopsis:
boolean deleteText(widget, text)
Arguments:
Return Value:
true if successful
Gets the current text alignment.
Synopsis:
string getTextAlign(widget, text)
Arguments:
Return Value:
LEFT, CENTER or RIGHT as string
Gets the current text color
Synopsis:
array getTextColor(widget, text)
Arguments:
Return Value:
(red, green, blue, alpha)
Gets the current text font name
Synopsis:
string getTextFont(widget, text)
Arguments:
Return Value:
font name
Gets the current text font size.
Synopsis:
integer getTextFontSize(widget, text)
Arguments:
Return Value:
text font size
Given a reference to a text object, this will return an array
containing the x and y coordinate of the text object.
Synopsis:
array getTextPos(widget, text)
Arguments:
Return Value:
x and y coordinate
Gets the current sensor string
Synopsis:
string getTextSensor(widget, text)
Arguments:
Return Value:
currently used sensor string
Gets the current shadow offset
Synopsis:
integer getTextShadow(widget, text)
Arguments:
Return Value:
shadow offset
Given a reference to a text object, this will return an array
containing the height and width of a text object.
Synopsis:
array getTextSize(widget, text)
Arguments:
Return Value:
height and width of the text
Returns there current text value.
Synopsis:
string getTextValue(widget, text)
Arguments:
Return Value:
value
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.
Synopsis:
reference getThemeText(widget, name)
Arguments:
Return Value:
reference to text
Hides text that is visible. You need to call redrawWidget() afterwords
to actually hide the text on screen.
Synopsis:
boolean hideText(widget, text)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean moveText(widget, text, x, y)
Arguments:
Return Value:
true if successful
This will resize text to the new height and width.
Synopsis:
boolean resizeText(widget, text, w, h)
Arguments:
Return Value:
true if successful
Sets the text label align.
Synopsis:
boolean setTextAlign(widget, text, align)
Arguments:
Return Value:
true if successful
Sets a new sensor string
Synopsis:
boolean setTextSensor(widget, text, sensor)
Arguments:
Return Value:
true if successful
Shows text that has been hidden with hideText().
Synopsis:
boolean showText(widget, text)
Arguments:
Return Value:
true if successful
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
Synopsis:
long createWidgetMask(widget, mask)
Arguments:
Return Value:
true if successful
Returns an array containing the x and y position of you widget.
widget is a reference to the current widget.
Synopsis:
array getWidgetPosition(widget)
Arguments:
Return Value:
position of the widget
Moves the widget to the new screen location.
Synopsis:
boolean moveWidget(widget, x, y)
Arguments:
Return Value:
true if successful
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.
Synopsis:
boolean redrawWidget(widget)
Arguments:
Return Value:
true if successful
Redraws the widget background.
WARNING
This function does nothing in SuperKaramba 0.50 and later
Synopsis:
boolean redrawWidgetBackground(widget)
Arguments:
Return Value:
true if successful
Resizes the widget to the new width and height.
Synopsis:
boolean resizeWidget(widget, w, h)
Arguments:
Return Value:
true if successful
Toggles widget redraw.
This function does nothing in SuperKaramba 0.50 and later
Synopsis:
boolean toggleWidgetRedraw(widget, b)
Arguments:
Return Value:
true if successful
To generate this API documentation execute the make_api_doc.sh script from the SuperKaramba docs dir.
./make_api_doc.sh rtf
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.
KDE TechBase
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
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. |
