It probably seems like naming doesn't matter much - it does for a couple of reasons. First, you're likely to have two copies of your applet while you're working on it - one in the original directory where you created the applet, and a second in the kicker/applets directory that kicker loads it from. If you use the same name in both places, eventually you'll end up making changes to one copy and not the other, and (trust me) this leads to some odd debugging situations. If you use the same name in both places, and the script is in the current working directory, the Python interpreter will run the original script instead of the installed script if the names are the same.
The other problem is that applets and .so libs have to be installed in specified locations along with a lot of other (critical) KDE files, so identifying applets and being sure that what you're about to delete is your applet and not some other critical piece of KDE is important.
For those reasons, I've arrived at the following naming conventions. You don't have to follow these guidelines, but the panel applet installer enforces them.
First, when you create your applet, name it anything you'd like - preferably something short and descriptive. If you manually create a .desktop file, give it the same name. (other than extension of course). When the applet script and desktop files are installed, add the suffix "_py_applet" to the base name. This makes Python/PyKDE panel applets obvious and you'll be able to tell what file you're editing.
So, for example, if you want to create a 'foo' applet (the ultimate short and descriptive name), I recommend the following:
When you're ready to install the applet, the applet and the desktop file go in $KDEDIR/share/apps/kicker/applets (which is only writable by root and should stay that way for safety). I'd recommend the following names for the installed files:
Similarly, the libs for this applet will be named foo_py_applet.la and foo_py_applet.so.
Debugging panel applets isn't hard, unless you try to do it with kicker loading the applet. kicker doesn't report any errors when it fails to load an applet - it just puts an empty "handle" on the panel and forgets about it. There are at least three easier ways to diagnose and debug applets. The first way is just a simple syntax check - open up the Python interpreter, "import sys" and append the script's directory to sys.path (if you didn't open Python with the script's directory as the current directory), and:
You won't actually be able to run your applet from Python (it needs to borrow a KApplication from someplace). The interpreter checks don't guarantee your applet will work or that the program logic is correct, but if those fail, so will your applet.
The second method is to use a utility that comes with KDE: appletproxy (it should be in $KDEDIR/bin, which is normally in your $PATH). To use this utility you'll need to have your applet fully installed (see below). Then just type at the command prompt: "appletproxy <desktop file path>" with the full path to your desktop file (including desktop file name and extension). This utility runs almost exactly the same code as kicker does when loading your applet, but (when run from an xterm) prints messages to stdout and stderr. That allows you to debug using print statements. If appletproxy loads your applet successfully, it will appear on the screen (but not in the panel) and you can manipulate it to further check it out.
The third method doesn't require you to install your applet. You can simply take a Python script that creates a KApplication object (any of the scripts in templates/ will work) and instantiate your panel applet in the main window (with the KMainWindow widget as parent). You can use "None" for the configFile parameter. You can use 'createApplet' called from the main window to do the instantiation or you can simply construct your applet object there. This method should also allow you to use standard debugging tools if needed.
Installation isn't hard - it's just tedious when done repeatedly as part of a debug cycle. There are probably other ways to install applets successfully, but I recommend putting the desktop file and Python script in $KDEDIR/share/apps/kicker/applets. First, it works. Second, this directory is only writeable by root (and should stay that way). That reduces the likelihood that you'll slap an applet from an unknown source on your machine (or worse, automatically load it via email) and suffer unpleasant Windows-like consequences. It isn't necessarily a guarantee of security. Scripting languages as powerful as Python are ideal for writing viruses, worms, trojans, etc. Be careful. KDE (kicker) will load and run anything that's installed and written correctly.
Let's assume we're going to install the "demo" applet from PyKDE (you can actually do this if you want). First, decide on a name for the .so lib link you're going to create (I recommend demo_py_applet.so) and link that to libpykpanelapplet.so. On my system (SuSE), $KDEDIR is /opt/kde3 - on other systems it may be something else (like just plain /usr). Substitute your $KDEDIR value for ./opt/kde3 throughout the examples. $KDEDIR/lib/kde3 is only writable by root. Do the symlink:
ln -s /opt/kde3/lib/kde3/libpykpanelapplet.so /opt/kde3/lib/kde3/demo_py_applet.so |
Next, edit the demo.la file - replace all the *.so occurances with demo_py_applet.so, then copy the editied file to /opt/kde3/lib/kde3
# demo_py_applet.la - a fake libtool library file # Generated by installPanelApplet # # Please DO NOT delete this file! # It is necessary for linking the library. # The name that we can dlopen(3). dlname='demo_py_applet.so' # Names of this library. library_names='demo_py_applet.so demo_py_applet.so demo_py_applet.so' # The name of the static archive. old_library='' # Libraries that this one depends upon. dependency_libs='' # Version information for clock_panelapplet. current=0 age=0 revision=0 # Is this an already installed library? installed=yes # Files to dlopen/dlpreopen dlopen='' dlpreopen='' # Directory that this library needs to be installed in: libdir='/opt/kde3/lib/kde3' |
dependency_libs can be left blank - it still works - but kicker checks the .so file names, so dl_name and library_names need to point to your .so file.
Once those steps are accomplished, you shouldn't ever have to repeat them while debugging. Next, edit the demo.desktop file, and be sure that X_KDE_Library points to your .so file:
[Desktop Entry] Name=Demo Comment=Demo - Python X-KDE-Library=demo_py_applet X-KDE-UniqueApplet=false |
Lastly, copy both your Python script and desktop files to $KDEDIR/share/apps/kicker/applets (and rename them if you follow the suggested naming convention above).
The next page describes the Panel Applet Installer, which does most of this work for you.