Projects/SuperKaramba/API

    From KDE TechBase
    Revision as of 00:34, 24 May 2007 by Suslik (talk | contribs) (→‎setImagePath: added note about new support of SVG in this fn.)

    SuperKaramba API

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

    Bar

    createBar

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

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

    Arguments:

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


    Return Value:
    Reference to new bar meter

    deleteBar

    This deletes the bar.

    Synopsis:
    boolean deleteBar(widget, bar)

    Arguments:

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


    Return Value:
    true if successful

    getBarImage

    Get the path to the bar image.

    Synopsis:
    string getBarImage(widget, bar)

    Arguments:

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


    Return Value:
    path to bar image

    getBarMinMax

    Returns possible min and max values of the bar.

    Synopsis:
    array getBarMinMax(widget, bar)

    Arguments:

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


    Return Value:
    array with max & min values

    getBarPos

    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:

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


    Return Value:
    array with x and y coordinates

    getBarSensor

    Gets the current sensor string.

    Synopsis:
    string getBarSensor(widget, bar)

    Arguments:

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


    Return Value:
    sensor string

    getBarSize

    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:

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


    Return Value:
    array with width and height

    getBarValue

    Returns current bar value.

    Synopsis:
    integer getBarValue(widget, bar)

    Arguments:

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


    Return Value:
    value

    getBarVertical

    Check if bar is a vertical bar.

    Synopsis:
    boolean getBarVertical(widget, bar)

    Arguments:

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


    Return Value:
    true if vertical

    getThemeBar

    You can reference a bar in your python code that was created in the theme file. Basically, you just add a NAME= value to the BAR line in the .theme file. Then if you want to use that object, instead of calling createBar(), you can call this function. The name you pass to the function is the same one that you gave it for the NAME= parameter in the .theme file.

    Synopsis:
    reference getThemeBar(widget, name)

    Arguments:

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


    Return Value:
    reference to bar

    hideBar

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

    Synopsis:
    boolean hideBar(widget, bar)

    Arguments:

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


    Return Value:
    true if successful

    moveBar

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

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

    Arguments:

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


    Return Value:
    boolean (true if successful)

    resizeBar

    This will resize bar to new height and width.

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

    Arguments:

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


    Return Value:
    true if successful

    setBarImage

    Use the image in path for the background as the bar

    Synopsis:
    boolean setBarImage(widget, bar, image)

    Arguments:

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


    Return Value:
    true if successful

    setBarMinMax

    Returns current bar value.

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

    Arguments:

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


    Return Value:
    true if successful

    setBarSensor

    Sets the sensor string of the bar.

    Synopsis:
    boolean setBarSensor(widget, bar, sensor)

    Arguments:

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


    Return Value:
    true if successful

    setBarValue

    Sets current bar value.

    Synopsis:
    reference setBarValue(widget, bar, value)

    Arguments:

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


    Return Value:
    reference to bar

    setBarVertical

    Set bar vertical

    Synopsis:
    boolean setBarVertical(widget, bar)

    Arguments:

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


    Return Value:
    true if successful

    showBar

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

    Synopsis:
    boolean showBar(widget, bar)

    Arguments:

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


    Return Value:
    true if successful


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

    Synopsis:
    boolean addMenuConfigOption(widget, key, name)

    Arguments:

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


    Return Value:
    true if successful

    readConfigEntry

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

    Synopsis:
    string readConfigEntry(widget, key, value)

    Arguments:

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


    Return Value:
    config value for key

    readMenuConfigOption

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

    Synopsis:
    boolean readMenuConfigOption(widget, key)

    Arguments:

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


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

    setMenuConfigOption

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

    Synopsis:
    boolean setMenuConfigOption(widget, key, value)

    Arguments:

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


    Return Value:
    true if successful

    writeConfigEntry

    SuperKaramba automatically supports configuration files for each theme. These files will be saved in /your/home/dir/.superkaramba/ and will be named themenamerc where themename is the name of the theme. This function writes an entry into the config file with the given key and value. For example, to save my favorite color, I would do karamba.writeConfigEntry(widget, "FavColor", "Red")

    Synopsis:
    boolean writeConfigEntry(widget, key, value)

    Arguments:

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


    Return Value:
    true if successful

    Graph

    createGraph

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

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

    Arguments:

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


    Return Value:
    reference to new graph meter

    deleteGraph

    This deletes graph.

    Synopsis:
    boolean deleteGraph(widget, graph)

    Arguments:

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


    Return Value:
    true if successful

    getGraphColor

    Gets the current graph color components.

    Synopsis:
    array getGraphColor(widget, graph)

    Arguments:

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


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

    getGraphMinMax

    Returns current graph minimal and maximal values.

    Synopsis:
    array getGraphMinMax(widget, graph)

    Arguments:

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


    Return Value:
    max and min values

    getGraphPos

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

    Synopsis:
    array getGraphPos(widget, graph)

    Arguments:

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


    Return Value:
    x and y coordinates

    getGraphSensor

    Gets the current sensor string of the graph.

    Synopsis:
    string getGraphSensor(widget, graph)

    Arguments:

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


    Return Value:
    sensor string

    getGraphSize

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

    Synopsis:
    array getGraphSize(widget, graph)

    Arguments:

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


    Return Value:
    width and height of the graph

    getGraphValue

    Returns current graph value.

    Synopsis:
    integer getGraphValue(widget, graph)

    Arguments:

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


    Return Value:
    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.

    Synopsis:
    reference getThemeGraph(widget, name)

    Arguments:

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


    Return Value:
    reference to graph

    hideGraph

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

    Synopsis:
    boolean hideGraph(widget, graph)

    Arguments:

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


    Return Value:
    true if successful

    moveGraph

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

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

    Arguments:

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


    Return Value:
    true if successful

    resizeGraph

    This will resize graph to new height and width.

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

    Arguments:

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


    Return Value:
    true if successful

    setGraphColor

    Sets current graph color.

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

    Arguments:

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


    Return Value:
    true if successful

    setGraphMinMax

    Sets the graphs min and max values.

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

    Arguments:

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


    Return Value:
    true if successful

    setGraphSensor

    Sets current sensor string of the graph.

    Synopsis:
    boolean setGraphSensor(widget, graph, sensor)

    Arguments:

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


    Return Value:
    true if successful

    setGraphValue

    Sets current graph value.

    Synopsis:
    reference setGraphValue(widget, graph, value)

    Arguments:

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


    Return Value:
    reference to graph

    showGraph

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

    Synopsis:
    boolean showGraph(widget, graph)

    Arguments:

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


    Return Value:
    true if successful

    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.

    Synopsis:
    boolean addImageTooltip(widget, image, text)

    Arguments:

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


    Return Value:
    true if successful

    changeImageChannelIntensity

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

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

    Arguments:

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


    Return Value:
    true if successful

    changeImageIntensity

    Changes the "intensity" of the image, which is similar to it's brightness. ratio is a floating point number from -1.0 to 1.0 that determines how much to brighten or darken the image. Millisec specifies how long in milliseconds before the image is restored to it's original form. This is useful for "mouse over" type animations. Using 0 for millisec disables this feature and leaves the image permanently affected.

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

    Arguments:

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


    Return Value:
    true if successful

    changeImageToGray

    Turns the given image into a grayscale image. Millisec specifies how long in milliseconds before the image is restored to it's original form. This is useful for "mouse over" type animations. Using 0 for millisec disables this feature and leaves the image permanently affected.

    Synopsis:
    boolean changeImageToGray(widget, image, millisec)

    Arguments:

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


    Return Value:
    true if successful

    changeImageToAlpha

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

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

    Arguments:

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


    Return Value:
    true if successful

    Note to wirr: what is the actual default millisec value?' Is it really -1, or 0?'

    createBackgroundImage

    This creates an background image on your widget at x, y. The filename should be given as the path parameter. In theory the image could be local or could be a url. It works just like adding an image in your theme file. You will need to save the return value to be able to call other functions on your image, such as moveImage()

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

    Arguments:

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


    Return Value:
    reference to new image meter

    createImage

    This creates an image on your widget at x, y. The filename should be given as the path parameter. In theory the image could be local or could be a url. It works just like adding an image in your theme file. You will need to save the return value to be able to call other functions on your image, such as moveImage()

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

    Arguments:

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


    Return Value:
    reference to new image meter

    createEmptyImage

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

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

    Arguments:

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


    Return Value:
    reference to new image meter

    createTaskIcon

    This creates a task image at x, y.

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

    Arguments:

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


    Return Value:
    reference to new image meter

    deleteImage

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

    Synopsis:
    boolean deleteImage(widget, image)

    Arguments:

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


    Return Value:
    true if successful

    getImageHeight

    This returns the height of an image. This is useful if you have rotated an image and its size changed, so you do not know how big it is anymore.

    Synopsis:
    integer getImageHeight(widget, image)

    Arguments:

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


    Return Value:
    height of the image

    getImagePath

    Returns the current image path.

    Synopsis:
    string getImagePath(widget, image)

    Arguments:

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


    Return Value:
    path

    getImagePos

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

    Synopsis:
    array getImagePos(widget, image)

    Arguments:

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


    Return Value:
    x and y coordinates of the image

    getImageSensor

    Gets the current sensor string.

    Synopsis:
    string getImageSensor(widget, image)

    Arguments:

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


    Return Value:
    sensor string

    getImageSize

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

    Synopsis:
    array getImageSize(widget, image)

    Arguments:

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


    Return Value:
    height and width of the image

    getImageWidth

    This returns the width of an image. This is useful if you have rotated an image and its size changed, so you do not know how big it is anymore.

    Synopsis:
    integer getImageWidth(widget, image)

    Arguments:

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


    Return Value:
    width of the image

    getThemeImage

    You can reference an image in your python code that was created in the .theme file. Basically, you just add a NAME= value to the IMAGE line in the .theme file. Then if you want to use that object, instead of calling createImage(), you can call this function. The name you pass to the function is the same one that you gave it for the NAME= parameter in the .theme file.

    Synopsis:
    long getThemeImage(widget, name)

    Arguments:

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


    Return Value:
    reference to image

    hideImage

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

    Synopsis:
    boolean hideImage(widget, image)

    Arguments:

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


    Return Value:
    true if successful

    moveImage

    This moves an image to a new x, y relative to your widget. In other words, (0,0) is the top corner of your widget, not the screen. The imageToMove parameter is a reference to the image to move that you saved as the return value from createImage()

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

    Arguments:

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


    Return Value:
    true if successful

    removeImageEffects

    If you have called image effect commands on your image (ex: changeImageIntensity(), you can call this to restore your image to it's original form.

    Synopsis:
    boolean removeImageEffects(widget, image)

    Arguments:

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


    Return Value:
    true if successful

    removeImageTransformations

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

    Synopsis:
    boolean removeImageTransformations(widget, image)

    Arguments:

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


    Return Value:
    true if successful

    resizeImage

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

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

    Arguments:

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


    Return Value:
    true if successful

    resizeImageSmooth

    DEPRECATED: resizeImage() now allows the user to pick whether to use fast or smooth resizing from the SuperKaramba menu - This resizes your image to width, height. The imageToResize parameter is a reference to an image that you saved as the return value from createImage() In version 0.50 and later this function works exactly as resizeImage().

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

    Arguments:

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


    Return Value:
    true if successful

    rotateImage

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

    Synopsis:
    long rotateImage(widget, image, deg)

    Arguments:

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


    Return Value:
    true if successful

    setImagePath

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

    Synopsis:
    reference setImagePath(widget, image, path)

    Arguments:

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


    Return Value:
    reference to the image

    setImageSensor

    Sets the current sensor string.

    Synopsis:
    long setImageSensor(widget, image, sensor)

    Arguments:

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


    Return Value:
    true if successful

    showImage

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

    Synopsis:
    boolean showImage(widget, image)

    Arguments:

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


    Return Value:
    true if successful

    setPixel

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

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

    Arguments:

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


    Return Value:
    true if successful

    changeImageAnimation

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

    Synopsis:
    boolean changeImageAnimation(widget, image, enable)

    Arguments:

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


    Return Value:
    true if successful

    getImageAnimation

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

    Synopsis:
    boolean getImageAnimation(widget, image)

    Arguments:

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


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

    setImageElement

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

    Synopsis:
    boolean setImageElement(widget, image, element)

    Arguments:

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


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

    resetImageElement

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

    Synopsis:
    boolean resetImageElement(widget, image)

    Arguments:

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


    Return Value:
    true if successful

    getImageElement

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

    Synopsis:
    string getImageElement(widget, image)

    Arguments:

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


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

    Input Box

    changeInputBox

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

    Synopsis:
    reference changeInputBox(widget, inputBox, value)

    Arguments:

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


    Return Value:
    reference to input box

    changeInputBoxBackgroundColor

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

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

    Arguments:

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


    Return Value:
    true if successful

    changeInputBoxFont

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

    Synopsis:
    boolean changeInputBoxFont(widget, inputBox, font)

    Arguments:

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


    Return Value:
    true if successful

    changeInputBoxFontColor

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

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

    Arguments:

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


    Return Value:
    true if successful

    changeInputBoxFontSize

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

    Synopsis:
    boolean changeInputBoxFontSize(widget, text, size)

    Arguments:

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


    Return Value:
    true if successful

    changeInputBoxFrameColor

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

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

    Arguments:

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


    Return Value:
    true if successful

    changeInputBoxSelectedTextColor

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

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

    Arguments:

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


    Return Value:
    true if successful

    changeInputBoxSelectionColor

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

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

    Arguments:

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


    Return Value:
    true if successful

    clearInputFocus

    Releases the input focus from the Input Box.

    Synopsis:
    boolean clearInputFocus(widget, inputBox)

    Arguments:

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


    Return Value:
    true if successful

    createInputBox

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

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

    Arguments:

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


    Return Value:
    reference to new Input Box

    deleteInputBox

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

    Synopsis:
    boolean deleteInputBox(widget, inputBox)

    Arguments:

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


    Return Value:
    true if successful

    getInputBoxBackgroundColor

    Gets the current background color of a Input Box

    Synopsis:
    array getInputBoxBackgroundColor(widget, inputBox)

    Arguments:

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


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

    getInputBoxFont

    Gets the current Input Box font name

    Synopsis:
    string getInputBoxFont(widget, inputBox)

    Arguments:

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


    Return Value:
    font name

    getInputBoxFontColor

    Gets the current text color of a Input Box

    Synopsis:
    array getInputBoxFontColor(widget, inputBox)

    Arguments:

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


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

    getInputBoxFontSize

    Gets the current text font size.

    Synopsis:
    integer getInputBoxFontSize(widget, inputBox)

    Arguments:

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


    Return Value:
    text font size

    getInputBoxFrameColor

    Gets the current frame color of a Input Box

    Synopsis:
    array getInputBoxFrameColor(widget, inputBox)

    Arguments:

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


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

    getInputBoxPos

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

    Synopsis:
    array getInputBoxPos(widget, inputBox)

    Arguments:

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


    Return Value:
    x and y coordinates of the inputBox

    getInputBoxSelectedTextColor

    Gets the current selected text color of a Input Box.

    Synopsis:
    array getInputBoxSelectedTextColor(widget, inputBox)

    Arguments:

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


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

    getInputBoxSelectionColor

    Gets the current selection color of a Input Box

    Synopsis:
    array getInputBoxSelectionColor(widget, inputBox)

    Arguments:

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


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

    getInputBoxSize

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

    Synopsis:
    array getInputBoxSize(widget, inputBox)

    Arguments:

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


    Return Value:
    width and hight of the input box

    getInputBoxValue

    Returns current Input Box text.

    Synopsis:
    string getInputBoxValue(widget, inputBox)

    Arguments:

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


    Return Value:
    input box text

    getInputFocus

    Gets the Input Box that is currently focused.

    Synopsis:
    boolean getInputFocus(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    the input box or 0

    getThemeInputBox

    You can reference text in your python code that was created in the theme file. Basically, you just add a NAME= value to the INPUT line in the .theme file. Then if you want to use that object, instead of calling createInputBox(), you can call this function. The name you pass to the function is the same one that you gave it for the NAME= parameter in the .theme file.

    Synopsis:
    reference getThemeInputBox(widget, name)

    Arguments:

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


    Return Value:
    reference to Input Box

    hideInputBox

    Hides a Input Box that is visible.

    Synopsis:
    boolean hideInputBox(widget, inputBox)

    Arguments:

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


    Return Value:
    true if successful

    moveInputBox

    This moves a Input Box object to a new x, y relative to your widget. In other words, (0,0) is the top corner of your widget, not the screen.

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

    Arguments:

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


    Return Value:
    true if successful

    resizeInputBox

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

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

    Arguments:

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


    Return Value:
    true if successful

    setInputFocus

    Sets the input focus to the Input Box.

    Synopsis:
    boolean setInputFocus(widget, inputBox)

    Arguments:

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


    Return Value:
    true if successful

    showInputBox

    Shows Input Box that has been hidden with hideInputBox()

    Synopsis:
    boolean showInputBox(widget, inputBox)

    Arguments:

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


    Return Value:
    true if successful

    getInputBoxTextWidth

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

    Synopsis:
    integer getInputBoxTextWidth(widget, input)

    Arguments:

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


    Return Value:
    The text width or -1

    changeInputBoxSelection

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

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

    Arguments:

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


    Return Value:
    true if successful

    getInputBoxSelection

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

    Synopsis:
    array getInputBoxSelection(widget, inputBox)

    Arguments:

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


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

    clearInputBoxSelection

    This will clear the selection of the input box.

    Synopsis:
    boolean getInputBoxSelection(widget, inputBox)

    Arguments:

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


    Return Value:
    true if successful

    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.

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

    Arguments:

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


    Return Value:
    reference to the menu item

    addMenuSeparator

    This adds an menu separator to the given menu.

    Synopsis:
    reference addMenuSeparator(widget, menu)

    Arguments:

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


    Return Value:
    reference to the separator

    createMenu

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

    Synopsis:
    reference createMenu(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    reference to menu

    deleteMenu

    This deletes the referenced menu if that menu exists.

    Synopsis:
    boolean deleteMenu(widget, menu)

    Arguments:

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


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

    popupMenu

    This pops up the given menu at the given co-ordinates. The co-ordinates are relative to the widget, not the screen. You can use negative co-ordinates to make a menu appear to the right of or above your theme.

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

    Arguments:

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


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

    removeMenuItem

    This removes the menu if it exists.

    Synopsis:
    boolean removeMenuItem(widget, menu, id)

    Arguments:

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


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

    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.

    Synopsis:
    boolean acceptDrops(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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).

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

    Arguments:

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


    Return Value:
    true if successful

    callTheme

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

    Synopsis:
    boolean callTheme(widget, theme, info)

    Arguments:

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


    Return Value:
    true if successful

    changeInterval

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

    Synopsis:
    boolean changeInterval(widget, interval)

    Arguments:

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


    Return Value:
    true if successful

    createClickArea

    This creates a clickable area at x, y with width and height w, h. When this area is clicked, cmd_to_run will be executed. The mouse will change over this area.

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

    Arguments:

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


    Return Value:
    reference to the new click area

    createServiceClickArea

    This creates a clickable area at x, y with width and height w, h. When this area is clicked, cmd_to_run will be executed. The mouse will change to the clickable icon when over this area. For more information on the difference between createClickArea() and createServiceClickArea, see the KDE documentation about KService, and the difference between KRun::run() and KRun::runCommand.

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

    Arguments:

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


    Return Value:
    reference to the new click area

    execute

    This command simply executes a program or command on the system. This is just for convience (IE you could accomplish this directly through python, but sometimes threading problems crop up that way). The only option is a string containing the command to execute.

    Synopsis:
    integer execute(command)

    Arguments:

    • string command -- command to execute


    Return Value:
    process id of the executed command

    executeInteractive

    This command executes a program or command on the system. Additionally it allows you to get any text that the program outputs. Futhermore, it won't freeze up your widget while the command executes. To use it, call executeInteractive with the reference to your widget and a list of command options. The array is simply a list that contains the command as the first entry, and each option as a separate list entry. Output from the command is returned via the commandOutput callback. The command returns the process number of the command. This is useful if you want to run() more than one program at a time. The number will allow you to figure out which program is outputting in the commandOutput callback. Example: Run the command "ls -la *.zip" myCommand = ["ls", "-la", "*.zip"] karamba.executeInteractive(widget, myCommand)

    Synopsis:
    integer executeInteractive(widget, command)

    Arguments:

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


    Return Value:
    process id of the executed command

    getIncomingData

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

    Synopsis:
    string getIncomingData(widget)

    Arguments:

    • reference to widget -- karamba


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

    getIp

    Gets the current IP address of the interface_name interface.

    Synopsis:
    string getIp(widget, interface_name)

    Arguments:

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


    Return Value:
    ip address as string

    getNumberOfDesktop

    Returns number of desktops

    Synopsis:
    integer getNumberOfDesktop(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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()

    Synopsis:
    string getPrettyName(theme)

    Arguments:

    • string theme -- path to new theme


    Return Value:
    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.

    Synopsis:
    list getServiceGroups(widget, path)

    Arguments:

    • reference to widget -- karamba
    • string path -- path to the Service Group you wish to retrieve


    Return Value:
    List of Dictionaries of services and service groups

    getThemePath

    Returns a string containing the directory where your theme was loaded from. The as argument passed widget instance is optional and if not defined, the current karamba-widget will be used.

    Synopsis:
    string getThemePath(widget)

    Arguments:

    • Optional reference to widget -- karamba


    Return Value:
    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.

    Synopsis:
    decimal getUpdateTime(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    last stored update time (from setUpdateTime())

    hide

    Hides the widget.

    Synopsis:
    boolean hide(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    true if successful

    language

    Returns a string containing the default language of a translation file.

    Synopsis:
    string language(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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.

    Synopsis:
    boolean managementPopup(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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.

    Synopsis:
    reference openNamedTheme(theme, pretty_name, is_sub_theme)

    Arguments:

    • 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


    Return Value:
    reference to the new widget

    openTheme

    Opens a new theme.

    Synopsis:
    reference openTheme(theme)

    Arguments:

    • string theme -- path to theme that will be opened


    Return Value:
    reference to the new widget

    readThemeFile

    Returns a string with the contents of the theme file

    Synopsis:
    string readThemeFile(widget, file)

    Arguments:

    • reference to widget -- karamba
    • string file -- name of the file to read


    Return Value:
    file contents

    reloadTheme

    Reloads the current theme.

    Synopsis:
    boolean reloadTheme(theme)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    true if successful

    removeClickArea

    This function deletes a clickable area.

    Synopsis:
    boolean removeClickArea(widget, clickarea)

    Arguments:

    • reference to widget -- karamba
    • reference to clickarea -- click area


    Return Value:
    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.

    Synopsis:
    boolean run(name, command, icon, list_of_args)

    Arguments:

    • 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


    Return Value:
    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.

    Synopsis:
    boolean setIncomingData(widget, theme, info)

    Arguments:

    • 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


    Return Value:
    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.

    Synopsis:
    boolean getUpdateTime(widget, updated_time)

    Arguments:

    • reference to widget -- karamba
    • integer updated_time -- the update time to be associated with the widget


    Return Value:
    true if successful

    show

    Shows the widget.

    Synopsis:
    boolean show(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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.

    Synopsis:
    boolean toggleShowDesktop(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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.

    Synopsis:
    boolean translateAll(widget, relative_x, relative_y)

    Arguments:

    • reference to widget -- karamba
    • integer translate_x -- move horizontally
    • integer translate_y -- move vertically


    Return Value:
    true if successful

    userLanguage

    Returns a string containing the global KDE user language.

    Synopsis:
    string userLanguage(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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.)

    Synopsis:
    array userLanguages(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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.

    Synopsis:
    boolean wantRightButton(widget, want_receive_right_button)

    Arguments:

    • reference to widget -- karamba
    • boolean want_receive_right_button -- whether the widget will receive right clicks


    Return Value:
    true if successful

    version

    Returns the (API) version of the running SuperKaramba. his allows theme writers to use new functionality with keeping backward compatibility.

    Synopsis:
    array version()
    Return Value:
    array with SuperKaramba version and API version

    desktopSize

    Returns the screen size of the display.

    Synopsis:
    array desktopSize()
    Return Value:
    array with width and height of the screen

    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.

    Synopsis:
    reference changeRichText(widget, richtext, value)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext
    • string value -- new text


    Return Value:
    true if successful

    changeRichTextFont

    This will change the font of a richtext meter.

    Synopsis:
    long changeRichTextFont(widget, richtext, font)

    Arguments:

    • long widget -- karamba
    • long richtext -- richtext
    • string font -- name of the new font


    Return Value:
    1 if successful

    changeRichTextSize

    Sets the font size of a richtext meter.

    Synopsis:
    boolean changeRichTextSize(widget, richtext, size)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext
    • long size -- new font point size


    Return Value:
    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.

    Synopsis:
    reference createRichText(widget, text, underlineLinks)

    Arguments:

    • reference to widget -- karamba
    • string text -- text for richtext
    • boolean underlineLinks -- should the links be underlined


    Return Value:
    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.

    Synopsis:
    boolean deleteRichText(widget, richtext)

    Arguments:

    • reference to widget -- karamba
    • reference to widget -- richtext


    Return Value:
    true if successful

    getRichTextFont

    Gets the font name of a richtext meter.

    Synopsis:
    string getRichTextFont(widget, richtext)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext


    Return Value:
    font name

    getRichTextFontSize

    Gets the font size of the richtext meter.

    Synopsis:
    integer getRichTextFontSize(widget, richtext)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext


    Return Value:
    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.

    Synopsis:
    array getRichTextPos(widget, richtext)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext


    Return Value:
    x and y coordinates

    getRichTextSensor

    Gets the current sensor string

    Synopsis:
    string getRichTextSensor(widget, richtext)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext


    Return Value:
    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.

    Synopsis:
    array getRichTextSize(widget, richtext)

    Arguments:

    • long widget -- karamba
    • long richtext -- richtext


    Return Value:
    width and height of the richtext

    getRichTextValue

    Returns the current richtext value.

    Synopsis:
    string getRichTextValue(widget, richtext)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext


    Return Value:
    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.

    Synopsis:
    reference getThemeRichText(widget, name)

    Arguments:

    • long widget -- karamba
    • string name -- name of the richtext in the theme file


    Return Value:
    reference to richtext

    hideRichText

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

    Synopsis:
    boolean hideRichText(widget, richtext)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext


    Return Value:
    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.

    Synopsis:
    boolean moveRichText(widget, richtext, x, y)

    Arguments:

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


    Return Value:
    true if successful

    resizeRichText

    This will resize richtext to the new height and width.

    Synopsis:
    boolean resizeRichText(widget, richtext, w, h)

    Arguments:

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


    Return Value:
    true if successful

    setRichTextSensor

    Sets a new sensor string

    Synopsis:
    boolean setRichTextSensor(widget, richtext, sensor)

    Arguments:

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


    Return Value:
    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.

    Synopsis:
    boolean setRichTextWidth(widget, richtext, width)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext
    • integer width -- new width in pixels


    Return Value:
    true if successful

    showRichText

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

    Synopsis:
    boolean showRichText(widget, richtext)

    Arguments:

    • reference to widget -- karamba
    • reference to richtext -- richtext


    Return Value:
    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().

    Synopsis:
    list getStartupInfo(widget, task)

    Arguments:

    • reference to widget -- karamba
    • reference to task -- task


    Return Value:
    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.

    Synopsis:
    list getTaskList(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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().

    Synopsis:
    list getTaskInfo(widget, task)

    Arguments:

    • reference to widget -- karamba
    • reference to task -- task


    Return Value:
    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.

    Synopsis:
    list getTaskList(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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()

    Synopsis:
    list getTaskNames(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    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)



    Synopsis:
    boolean performTaskAction(widget, task, action)

    Arguments:

    • reference to widget -- karamba
    • reference to task -- task
    • integer action -- action number


    Return Value:
    boolean if successful

    Text

    changeText

    This will change the contents of a text widget.

    Synopsis:
    reference changeText(widget, text, value)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter
    • long value -- new text to display


    Return Value:
    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, blue and the alpha channel.

    Synopsis:
    boolean changeTextColor(widget, text, r, g, b, a=255)

    Arguments:

    • 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
    • integer alpha -- alpha component of color (optional)


    Return Value:
    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.

    Synopsis:
    boolean changeTextFont(widget, text, font)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter
    • string font -- font name


    Return Value:
    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.

    Synopsis:
    boolean changeTextShadow(widget, text, shadow)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter
    • integer shadow -- shadow offset


    Return Value:
    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.

    Synopsis:
    boolean changeTextSize(widget, text, size)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter
    • integer size -- new size for text


    Return Value:
    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()

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

    Arguments:

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


    Return Value:
    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.

    Synopsis:
    boolean deleteText(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to widget -- text meter


    Return Value:
    true if successful

    getTextAlign

    Gets the current text alignment.

    Synopsis:
    string getTextAlign(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    LEFT, CENTER or RIGHT as string

    getTextColor

    Gets the current text color

    Synopsis:
    array getTextColor(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


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

    getTextFont

    Gets the current text font name

    Synopsis:
    string getTextFont(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    font name

    getTextFontSize

    Gets the current text font size.

    Synopsis:
    integer getTextFontSize(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    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.

    Synopsis:
    array getTextPos(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    x and y coordinate

    getTextSensor

    Gets the current sensor string

    Synopsis:
    string getTextSensor(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    currently used sensor string

    getTextShadow

    Gets the current shadow offset

    Synopsis:
    integer getTextShadow(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    shadow offset

    getTextSize

    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:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    height and width of the text

    getTextValue

    Returns there current text value.

    Synopsis:
    string getTextValue(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    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.

    Synopsis:
    reference getThemeText(widget, name)

    Arguments:

    • long widget -- karamba
    • string name -- name of the text in the theme file


    Return Value:
    reference to text

    hideText

    Hides text that is visible. You need to call redrawWidget() afterwords to actually hide the text on screen.

    Synopsis:
    boolean hideText(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    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.

    Synopsis:
    boolean moveText(widget, text, x, y)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter
    • integer x -- x coordinate
    • integer y -- y coordinate


    Return Value:
    true if successful

    resizeText

    This will resize text to the new height and width.

    Synopsis:
    boolean resizeText(widget, text, w, h)

    Arguments:

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


    Return Value:
    true if successful

    setTextAlign

    Sets the text label align.

    Synopsis:
    boolean setTextAlign(widget, text, align)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter
    • string align -- LEFT, CENTER or RIGHT as string


    Return Value:
    true if successful

    setTextSensor

    Sets a new sensor string

    Synopsis:
    boolean setTextSensor(widget, text, sensor)

    Arguments:

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


    Return Value:
    true if successful

    showText

    Shows text that has been hidden with hideText().

    Synopsis:
    boolean showText(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    true if successful

    getTextTextWidth

    Gets the current text width.

    Synopsis:
    integer getTextTextWidth(widget, text)

    Arguments:

    • reference to widget -- karamba
    • reference to text -- text meter


    Return Value:
    text width

    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

    Synopsis:
    long createWidgetMask(widget, mask)

    Arguments:

    • reference to widget -- karamba
    • string mask -- The path to the widget mask file.


    Return Value:
    true if successful

    getWidgetPosition

    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:

    • reference to widget -- karamba


    Return Value:
    position of the widget

    moveWidget

    Moves the widget to the new screen location.

    Synopsis:
    boolean moveWidget(widget, x, y)

    Arguments:

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


    Return Value:
    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.

    Synopsis:
    boolean redrawWidget(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    true if successful

    redrawWidgetBackground

    Redraws the widget background. WARNING This function does nothing in SuperKaramba 0.50 and later

    Synopsis:
    boolean redrawWidgetBackground(widget)

    Arguments:

    • reference to widget -- karamba


    Return Value:
    true if successful

    resizeWidget

    Resizes the widget to the new width and height.

    Synopsis:
    boolean resizeWidget(widget, w, h)

    Arguments:

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


    Return Value:
    true if successful

    toggleWidgetRedraw

    Toggles widget redraw. This function does nothing in SuperKaramba 0.50 and later

    Synopsis:
    boolean toggleWidgetRedraw(widget, b)

    Arguments:

    • reference to widget -- karamba
    • boolean b -- 1 = widget is drawn


    Return Value:
    true if successful

    Wiki Markup Generation

    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.

    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.