summaryrefslogtreecommitdiffstats
path: root/superkaramba/src/misc_python.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commit2bda8f7717adf28da4af0d34fb82f63d2868c31d (patch)
tree8d927b7b47a90c4adb646482a52613f58acd6f8c /superkaramba/src/misc_python.h
downloadtdeutils-2bda8f7717adf28da4af0d34fb82f63d2868c31d.tar.gz
tdeutils-2bda8f7717adf28da4af0d34fb82f63d2868c31d.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeutils@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'superkaramba/src/misc_python.h')
-rw-r--r--superkaramba/src/misc_python.h606
1 files changed, 606 insertions, 0 deletions
diff --git a/superkaramba/src/misc_python.h b/superkaramba/src/misc_python.h
new file mode 100644
index 0000000..46c0988
--- /dev/null
+++ b/superkaramba/src/misc_python.h
@@ -0,0 +1,606 @@
+/*
+* misc_python.h - Misc Functions for python api
+*
+* Copyright (C) 2003 Hans Karlsson <karlsson.h@home.se>
+* Copyright (C) 2003-2004 Adam Geitgey <adam@rootnode.org>
+* Copyright (C) 2004 Petri Damst� <damu@iki.fi>
+* Copyright (C) 2004,2005 Luke Kenneth Casson Leighton <lkcl@lkcl.net>
+*
+* This file is part of SuperKaramba.
+*
+* SuperKaramba is free software; you can redistribute it and/or modify
+* it under the terms of the GNU General Public License as published by
+* the Free Software Foundation; either version 2 of the License, or
+* (at your option) any later version.
+*
+* SuperKaramba is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+* GNU General Public License for more details.
+*
+* You should have received a copy of the GNU General Public License
+* along with SuperKaramba; if not, write to the Free Software
+* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+****************************************************************************/
+
+#ifndef MISC_PYTHON_H
+#define MISC_PYTHON_H
+
+/** @file
+*
+* These are global functions that are used to interpret
+* certain Python calls.
+*/
+
+/** Misc/acceptDrops
+*
+* SYNOPSIS
+* long acceptDrops(widget)
+* DESCRIPTION
+* Calling this enables your widget to receive Drop events. In other words,
+* the user will be able to drag icons from her desktop and drop them on
+* your widget. The "itemDropped" callback is called as a result with the
+* data about the icon that was dropped on your widget. This allows, for
+* example, icon bars where items are added to the icon bar by Drag and
+* Drop.
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_accept_drops(PyObject *self, PyObject *args);
+
+/** Misc/execute
+*
+* SYNOPSIS
+* long execute(command)
+* DESCRIPTION
+* 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.
+* ARGUMENTS
+* * string command -- command to execute
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_execute_command(PyObject* self, PyObject* args);
+
+/** Misc/executeInteractive
+*
+* SYNOPSIS
+* long executeInteractive(widget, command)
+* DESCRIPTION
+* This command executes a program or command on the system. But it allows
+* you to get any text that the program outputs. Futhermore, it won't freeze
+* up your widget while the command executes.
+*
+* To use it, call executeInteractive with the reference to your widget and
+* an array of command options. The array is simply a list that contains the
+* command as the first entry, and each option as a seperate list entry.
+* Make sure to catch the returning value from executeInteractive(); it will
+* be the identifier (process number) for the command.
+*
+* Output from the command triggers commandOutput callback. Among other items
+* commandOutput gives the process number of the command that gave the output.
+* This allows you to identify the output when running more than one command
+* at a time.
+*
+* Example:
+* To run the command "ls -la *.zip"
+*
+* myCommand = ["ls", "-la", "*.zip"]
+* procID = karamba.executeInteractive(widget, myCommand)
+*
+* To catch the output, screen commandOutput output for procID.
+*
+* ARGUMENTS
+* * long widget -- karamba
+* * list command -- command to execute
+* RETURN VALUE
+* identification number of the executed command process
+*/
+PyObject* py_execute_command_interactive(PyObject* self, PyObject* args);
+
+/** Misc/run
+*
+* SYNOPSIS
+* long run(name, command, icon, list_of_args)
+* DESCRIPTION
+* 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.
+* 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
+* 1 if successful
+*/
+PyObject* py_run_command(PyObject* self, PyObject* args);
+
+/** Misc/attachClickArea
+*
+* SYNOPSIS
+* long attachClickArea(widget, meter, lB, mB, rB)
+* DESCRIPTION
+* 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).
+*
+* ARGUMENTS
+* * long widget -- karamba
+* * long meter -- pointer to meter
+* * string lB -- command to left mouse button
+* * string mB -- command to middle mouse button
+* * string rB -- command to right mouse button
+*
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_attach_clickArea(PyObject* self, PyObject* args, PyObject* dict);
+
+/** Misc/toggleShowDesktop
+*
+* SYNOPSIS
+* long toggleShowDesktop(widget)
+* DESCRIPTION
+* 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.
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_toggle_show_desktop(PyObject *self, PyObject *args);
+
+/** Misc/getThemePath
+*
+* SYNOPSIS
+* string getThemePath(widget)
+* DESCRIPTION
+* Returns a string containing the directory where your theme was loaded
+* from. If you are running the theme from (compressed) skz (zip) file, the
+* return value will be the path of that file, including the file name.
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* path to theme
+*/
+PyObject* py_get_theme_path(PyObject *self, PyObject *args);
+
+/** Misc/language
+*
+* SYNOPSIS
+* string language(widget)
+* DESCRIPTION
+* Returns a string containing default language of a translation file.
+* Please, see userLanguage to obtain the preferred KDE interface language.
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* default language or empty string if no translation files found.
+*/
+PyObject* py_language(PyObject *self, PyObject *args);
+
+/** Misc/userLanguage
+*
+* SYNOPSIS
+* string userLanguage(widget)
+* DESCRIPTION
+* Returns a string containing the language name abbreviation for the
+* language user chose for the KDE session in Region & Language settings.
+* Implemented in version 0.40. Parse ~/.kde/share/config/kdeglobals
+* for 'Language' directly for earlier clients.
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* user language or empty string.
+*/
+PyObject* py_userLanguage(PyObject *self, PyObject *args);
+
+
+/** Misc/userLanguages
+*
+* SYNOPSIS
+* string userLanguages(widget)
+* DESCRIPTION
+* Returns a list (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.)
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* list (array) with user languages in the order of preference.
+*/
+PyObject* py_userLanguages(PyObject *self, PyObject *args);
+
+
+/** Misc/readThemeFile
+*
+* SYNOPSIS
+* string readThemeFile(widget, file)
+* DESCRIPTION
+* Returns a string containing the contents of the file.
+* ARGUMENTS
+* * long widget -- karamba
+* * string file -- name of the file to read
+* RETURN VALUE
+* file contents
+*/
+PyObject* py_read_theme_file(PyObject *self, PyObject *args);
+
+/** Misc/createClickArea
+*
+* SYNOPSIS
+* long createClickArea(widget, x, y, w, h, cmd_to_run)
+* DESCRIPTION
+* 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 while hovering over this area.
+* ARGUMENTS
+* * long widget -- karamba
+* * long x -- x coordinate
+* * long y -- y coordinate
+* * long w -- width
+* * long h -- height
+* * string cmd_to_run -- command to be run
+* RETURN VALUE
+* a handle to the click area
+*/
+PyObject* py_create_click_area(PyObject *self, PyObject *args);
+
+/** Misc/openTheme
+*
+* SYNOPSIS
+* long openTheme(theme)
+* DESCRIPTION
+* Opens new theme.
+* ARGUMENTS
+* * string theme -- path to new theme
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_open_theme(PyObject *self, PyObject *args);
+
+/** Misc/reloadTheme
+*
+* SYNOPSIS
+* long reloadTheme(theme)
+* DESCRIPTION
+* Reloads current theme.
+* ARGUMENTS
+* * string theme -- path to new theme
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_reload_theme(PyObject *self, PyObject *args);
+
+/** Misc/getNumberOfDesktop
+*
+* SYNOPSIS
+* long getNumberOfDesktop(widget)
+* DESCRIPTION
+* Returns number fo desktops
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* number of desktops
+*/
+PyObject* py_get_number_of_desktops(PyObject *self, PyObject *args);
+
+/** Misc/translateAll
+*
+* SYNOPSIS
+* long translateAll(widget, relative_x, relative_y)
+* DESCRIPTION
+* Moves all widgets within a theme in a particular direction relative to
+* the previous spot without moving the parent theme widget.
+* ARGUMENTS
+* * long widget -- karamba
+* * long translate_x -- move horizontally
+* * long translate_y -- move vertically
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_translate_all(PyObject *self, PyObject *args);
+
+/** Misc/show
+*
+* SYNOPSIS
+* string show(widget)
+* DESCRIPTION
+* show theme
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_show(PyObject *self, PyObject *args);
+
+/** Misc/hide
+*
+* SYNOPSIS
+* string hide(widget)
+* DESCRIPTION
+* hide theme
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_hide(PyObject *self, PyObject *args);
+
+/** Misc/getIp
+*
+* SYNOPSIS
+* string getIp(widget, interface_name)
+* DESCRIPTION
+* get current IP address of the interface_name interface.
+* ARGUMENTS
+* * long widget -- karamba
+* * string interface_name -- name of the interface to get ip
+* RETURN VALUE
+* ip address
+*/
+PyObject* py_get_ip(PyObject *self, PyObject *args);
+
+/** Misc/changeInterval
+*
+* SYNOPSIS
+* long changeInterval(widget, interval)
+* DESCRIPTION
+* Calling this changes your widget's refresh rate (ms)
+* ARGUMENTS
+* * long widget -- karamba
+* * int interval -- interval, in ms
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_change_interval(PyObject *self, PyObject *args);
+
+/** Misc/createServiceClickArea
+*
+* SYNOPSIS
+* long createServiceClickArea(widget, x, y, w, h, name_of_command, cmd_to_run, icon_to_display)
+* DESCRIPTION
+* 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.
+* ARGUMENTS
+* * long widget -- karamba
+* * long x -- x coordinate
+* * long y -- y coordinate
+* * long w -- width
+* * long 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
+* a handle to the click area
+*/
+PyObject* py_create_service_click_area(PyObject *self, PyObject *args);
+
+/** Misc/removeClickArea
+*
+* SYNOPSIS
+* long removeClickArea(widget, clickarea)
+* DESCRIPTION
+* This function deletes a clickable area.
+* ARGUMENTS
+* * long widget -- karamba
+* * long clickarea -- handle to the click area
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_remove_click_area(PyObject *self, PyObject *args);
+
+
+/** Misc/getPrettyThemeName
+*
+* SYNOPSIS
+* string getPrettyThemeName(theme)
+* DESCRIPTION
+* 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)
+* ARGUMENTS
+* * string theme -- path to the theme
+* RETURN VALUE
+* the pretty name of the theme
+*/
+PyObject* py_get_pretty_name(PyObject *self, PyObject *args);
+
+/** Misc/openNamedTheme
+*
+* SYNOPSIS
+* long openNamedTheme(theme, pretty_name, is_sub_theme)
+* DESCRIPTION
+* 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.
+* ARGUMENTS
+* * string theme -- path to new theme
+* * string pretty_name -- the name to be associated with the new widget
+* * long is_sub_theme -- sets persistence (save state) of the theme
+* RETURN VALUE
+* a handle to the widget created
+*/
+PyObject* py_open_named_theme(PyObject *self, PyObject *args);
+
+/** Misc/callTheme
+*
+* SYNOPSIS
+* long callTheme(widget, theme, info)
+* DESCRIPTION
+* Sends a string to the theme identified by the pretty name.
+* If you need to pass complex arguments (dictionaries, lists), use python
+* "repr" and "eval" functions to marshall and unmarshall the data structure.
+* (themeNotify Will be called in the target theme when message is received)
+*
+* Note: As a bug/feature of SuperKaramba version 0.40, multiple instances of
+* the same theme share global variables. If you want to communicate to other
+* instances of the same theme, just communicate through global variables.
+* ARGUMENTS
+* * long widget -- karamba
+* * string theme -- pretty name of the theme to be called
+* * string info -- a string containing the info to be passed to the theme
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_call_theme(PyObject *self, PyObject *args);
+
+/** Misc/setIncomingData
+*
+* SYNOPSIS
+* long setIncomingData(widget, theme, info)
+* DESCRIPTION
+* 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.
+* ARGUMENTS
+* * long widget -- karamba
+* * string theme -- pretty name of theme the information is passed to.
+* * string info -- a string containing the info to be passed to the theme
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_set_incoming_data(PyObject *self, PyObject *args);
+
+/** Misc/getIncomingData
+*
+* SYNOPSIS
+* long getIncomingData(widget)
+* DESCRIPTION
+* 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.
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* string containing last information received from setIncomingData
+*/
+PyObject* py_get_incoming_data(PyObject *self, PyObject *args);
+
+/** Misc/getUpdateTime
+*
+* SYNOPSIS
+* long getUpdateTime(widget)
+* DESCRIPTION
+* 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.
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* last stored update time (from setUpdateTime)
+*/
+PyObject* py_get_update_time(PyObject *self, PyObject *args);
+
+/** Misc/setWantRightButton
+*
+* SYNOPSIS
+* long setWantRightButton(widget, want_receive_right_button)
+* DESCRIPTION
+* There's a management menu for SuperKaramba themes which
+* allows themes to be loaded, closed, moved to other
+* screens. Not all themes will want this management
+* interface. call karamba.wantRightButton(widget, 1)
+* if you want to receive MouseUpdate button notifications.
+* ARGUMENTS
+* * long widget -- karamba
+* * long want_receive_right_button -- whether the widget will receive right clicks
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_want_right_button(PyObject *self, PyObject *args);
+
+/** Misc/setWantMeterWheelEvent
+*
+* SYNOPSIS
+* long setWantMeterWheelEvent(widget, want_receive_wheel_event)
+* DESCRIPTION
+* Enabling this allows themes to receive a wheel event when
+* the wheel is turned over a meter.
+* This function is available after version 0.42.
+* This behaviour is default in SuperKaramba 0.50 and later,
+* so this function will be not available after the 0.50 version.
+* ARGUMENTS
+* * long widget -- karamba
+* * long want_receive_wheel_event -- whether the theme will receive mouse wheel events
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_want_wheel_event(PyObject *, PyObject *args);
+
+/** Misc/managementPopup
+*
+* SYNOPSIS
+* long managementPopup(widget)
+* DESCRIPTION
+* There's a management menu for SuperKaramba themes which
+* allows themes to be loaded, closed, moved to other
+* screens. If you want this popup menu to appear, call
+* this function.
+* ARGUMENTS
+* * long widget -- karamba
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_management_popup(PyObject *self, PyObject *args);
+
+/** Misc/setUpdateTime
+*
+* SYNOPSIS
+* long getUpdateTime(widget, updated_time)
+* DESCRIPTION
+* 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.
+* ARGUMENTS
+* * long widget -- karamba
+* * long updated_time -- the update time to be associated with the widget
+* RETURN VALUE
+* 1 if successful
+*/
+PyObject* py_set_update_time(PyObject *self, PyObject *args);
+
+#endif /* MISC_PYTHON_H */
+