"Borealis" superkaramba desktop monitoring tool
http://www.kde-look.org/content/show.php?content=13876
Version 2.3 (09/24/2004)

by Ivica Ico Bukvic (SlipStreamScapes)
ico at fuse net
http://meowing.ccm.uc.edu/~ico/


ACKNOWLEDGMENTS
===============
This theme is indebted to the work of:
Andreas Schneider http://www.kde-look.org/content/show.php?content=11405 (4 icons: cpu, memory, disk, and network)
Tomas Galvez http://www.kde-look.org/content/show.php?content=13500 (1 background icon)
Oskar Ellstram http://www.kde-look.org/content/show.php?content=12957 (resized 4 icons from Andreas Schneider's theme)
Adam Geitgey (detect resolution script and obviously superkaramba itself)
Others? (please let me know if I left you out by mistake)


OVERVIEW
========
IMPORTANT! THIS THEME REQUIRES SUPERKARAMBA V.0.35 OR HIGHER TO WORK! AT THE TIME OF THIS RELEASE V.0.35 IS OBTAINABLE ONLY VIA CVS OR USING THE TARBALL LINKED BELOW.

This desktop superkaramba theme has been inspired by the sound theme "Borealis" that I created and as such I see it as a visual counterpart to it (although obviously it does not require the sounds in order to be useful). For the sound theme please see:

http://www.kde-look.org/content/show.php?content=12584

The goal of this theme is to provide a visually appealing way of monitoring vital computer statistics as well as access to the most-common desktop interface features (i.e. virtual desktop and system tray) while generating minimal amounts of desktop clutter, as well as providing the on-the-fly ability to toggle visibility of individual groups of sensors. Finally, I've tried to optimize the script as much as possible in order to minimize the CPU footprint. Current version typically uses between 2-8% (not including the momentary spikes when minimizing/restoring monitoring bars) of CPU on a mobile Athlon64 3000+ running in powersave mode at 800MHz (using 32-bit version of Linux). Some optimizations available in the v.0.35 of the superkaramba are already a part of this theme, such as auto-resizable systray as well as auto-resizable and auto-highlighting desktop changing bar, all of which are result of my contributions to the superkaramba project. Further optimizations will become possible as soon as I add some more features to the superkaramba engine itself.


LICENSE
=======
The theme and its accompanying materials (i.e. README and installers) are distributed under the GPL license. The sounds are distributed under the Artistic license.


FEATURES
========
*8 retractable bars that are located on the right-hand top side of the desktop. They are:

1) System tray
2) Virtual desktops (uses either 3ddesktop or built-in KDE desktop switching)
3) Cpu monitoring
4) Memory monitoring
5) HD space monitoring (user-configurable, uses "/" and "/home" by default)
6) Network monitoring (user-configurable, uses "eth0" by default)
7) Wireless monitoring (user-configurable, uses "wlan0" by default)
8) Xmms bar

*User-friendly: the theme comes with an installer that offers auto-configuration as well as customization of the theme settings during install.

*Highly optimized: the theme uses between 2-8% of CPU on a 64-bit mobile XP 3000+ running in power-save mode at 800MHz (not including momentary spikes during sound playback and various animations). In addition, when bars are minimized, their redraw is suppressed in order to further minimize their impact on the processor and therefore your productivity.

*First theme to incorporate sounds: most of the interactive events (i.e. minimizing/restoring bars, network connection detected, button clicked, etc.) produce accompanying sounds (KDE's Arts server required for multiple sound streams to play simultaneously). Sounds are furthermore spatially positioned to provide for the best possible feedback.

*Individual control: every bar can be minimized and restored inidividually enabling the user to have full control over their desktop.

*Full desktop integration: first theme to feature auto-resizable systray and virtual desktops bars. Both bars resize automatically to accomodate space for the interactively added/removed icons and/or virtual desktops , desks bar detects external changes of desktop (via mouse wheel or any other paging applet), hence posing as full-blown replacements for their kicker implementations. In addition, this theme is Xinerama-safe.

*Verbose information: even when minimized, some of the more time-critical bars (i.e. networking and xmms bars) provide needed information regarding their status.

*Additional options: several bars allow for additional functionality via pop-up menus which are accessible by middle-clicking onto the bars.

*Zero-config start-up: theme automatically detects resolution and repositiones itself appropriately (xwininfo required which is a part of the standard X server package; alternately you will be given an option to enter desktop width during install).

*Eye-candy: virtual desktops can be managed via built-in KDE switching (default) or via very nice looking 3ddesktop OpenGL tool (configurable during install).


MANUAL
======
Detailed manual is now available for online viewing at:

http://meowing.ccm.uc.edu/~ico/Linux/Borealis/Borealis_manual/index.html

It is also downloadable as a tarball for offline viewing at:
http://meowing.ccm.uc.edu/~ico/Linux/Borealis/Borealis_manual.tar.bz2 (2.7MB)


PREREQUISITES
=============
This package requires the following software:

xmmsctrl package for interacting with xmms (OPTIONAL -- configurable during install).
http://user.it.uu.se/~adavid/utils/

3ddesktop package for OpenGL virtual desktop switching (OPTIONAL -- configurable during install).
http://desk3d.sourceforge.net/

Superkaramba v.0.35 or higher (REQUIRED -- currently only available via CVS or using the tarball provided below).
http://netdragon.sourceforge.net

CVS tarball:
http://meowing.ccm.uc.edu/~ico/Linux/Borealis/superkaramba-cvssnapshot-0.35.tar.bz2 (958KB)

IMPORTANT! You need to uninstall the old version of the superkaramba before installing this one.

To install the CVS Superkaramba tarball simply do the following steps:
tar -jxvf superkaramba-cvssnapshot-0.35.tar.bz2
cd superkaramba
./configure (optionally add --prefix=/usr if you would like your binary to be installed in /usr/bin/ rather than /usr/local/bin/ directory)
make
make install (you need to be superuser for this last step)


INSTALL
=======
To install this theme do the following three steps:

1) Download the package

2) Decompress the package inside your $HOME directory (IMPORTANT! It must be in your $HOME directory if you do not want to do additional editing of the config files):
tar -jxvf Borealis_superkaramba-VERSION.tar.bz2

3) Run the installer and follow the instructions:
cd Karamba/Borealis
sh install.sh

That should be it!


UNINSTALL
=========
To uninstall the theme simply use the uninstall script included with the tarball:

sh uninstall.sh


FAQ
===
Q: Redrawing of the systray is still leaving white square background upon logging in. Why?
A: As of the version 2.0, this problem should be completely fixed.

Q: Why does my desktop cycle through virtual desktops once I log in?
A: You are likely using 3ddesktop which does so to gather snapshots of each desktop, eventually returning to the first desktop. If you don't like this behavior, you may want to edit the 3ddesktop file (usually found in the /usr/bin directory) and remove "--acquire" flag from the line invoking the 3ddeskd.

Q: How can I alter the settings of the networking and hd monitors? Is there an automated config for this functionality?
A: YES! As of version 1.5, you can configure these during install.

Q: The text and/or graphs are not very legible when I am using this theme with my background wallpaper. How can I change font and/or graph colors?
A: As of v.2.0 you will be given an option to modify the background bar color as well as the font colors during install. You can also modify the colors after install by running the colorcustomizer.sh script.

Q: I have other superkaramba scripts and I don't want to redundantly run multiple instances of superkaramba because this theme has its own startup script. How can I fix this?
A: This theme is started by running the main.theme file which simply invokes other themes using a string of theme files with their relative paths (each bar in this package is a separate "theme"). You can easily add other themes here and have them all start as soon as you login.
 
Q: Why use an Autostart script anyhow?
A: As of version 2.0, there is no more startup script because the Superkaramba bug that was preventing proper placement of the multiple themes has been fixed in the latest release. Now the theme should be saved within the KDE session.

Q: Why is there no info about my IP address on the networking bar when I am not connected to the internet? Wouldn't it be nicer to have some text stating like 'disconnected' or something similar?
A: This has been fixed in the version 2.0.

Q: How do I uninstall this theme?
A: As of version 1.4 there is an uninstall script "uninstall.sh" which must be run as superuser which reverts all the changes done to your system.

Q: I am using another theme with a systray in it and when I start this theme, all kinds of weird stuff happens. Why?
A: Superkaramba (and KDE desktop) support only one system tray and when multiple trays are invoked you get all kinds of weird things to happen including flickering icons that are positioned weirdly all accross the screen and even crashes. To fix this make sure to do the following:
1) disable other theme with a systray or edit the main.theme and comment out the systray.theme by putting a "#" at the beginning of that line.
2) make sure that your kpanel does not have a systray applet on it already.

Q: I have more systray icons than what can fit on the systray bar. How do I change size of the systray bar?
A: As of version 2.0, this has been fixed. The systray now resizes itself automatically.

Q: I do not see the cpu speed in the cpu bar and I get all these periodic errors outputted from the superkaramba in the console. What is going on?
A: As of version 1.5, the installer chooses the most appropriate way of monitoring cpu speed. Should you still encounter these errors that means that your kernel has been compiled in such a way that it does not allow any of the 3 possible ways of monitoring cpu speed.

Q: Considering that the widgets move off-screen, is this theme Xinerama-safe?
A: Yes.


CHANGELOG
=========
09/24/2004 -- ver.2.3 Bug-fix release
*REQUIRES SUPERKARAMBA V.0.35
*Fixed bug that caused premature exit from the install script due to some leftover debugging code
*Fixed "Borealis.sh not found error" bug during uninstall (thanks to "willi" for pointing this out)
*Fixed desks.py.template file so that the 3ddesktop is disabled by default (again, thanks to "willi" for pointing this one as well)
*Polished uninstall script to remove files only if they exist

09/01/2004 -- ver.2.2 Bug-fix release
*REQUIRES SUPERKARAMBA V.0.35
*Fixed bug where desks bar was positioned incorrectly after installing
*Fixed bug that caused incorrect writing of the x and y positions for the systray and desks bars during initialization

08/14/2004 -- ver.2.1 Bug-fix release
*REQUIRES SUPERKARAMBA V.0.35
*Fixed the garbled background on the systray when the bar starts minimized
*Fixed desks bar to properly minimize itself at startup
*Updated superkaramba v.0.35 CVS snapshot to fix some of the compile errors including:
karamba_python.cpp:344: error: invalid conversion from `const char*' to `char*'

08/06/2004 -- ver.2.0 (a.k.a. "Quantum Leap")
*REQUIRES SUPERKARAMBA V.0.35
*Tons of optimizations and script improvements.
*Tons of bug-fixes.
*Utilizes latest additions to the superkaramba package (CVS).
*Inclusion of sound events.
*Completely revamped drawing and animation engine.
*Systray and desks bars resize automatically to accomodate space for externally added desktops and systray icons.
*Included script for background and font color customization.
*8 variations of background bar designs included.
*CPU footprint is now down to 2-8%.
*Expanded documentation.
*Added new wireless networking bar.
*Many additional features (consult the new Manual for more info).

07/10/2004 -- ver.1.5 (a.k.a. "It's 5:43am and the birds are chirping outside")
*Added Xmms bar. Please consult screenshot3.jpg for more info how to use it.
*Improved installer (added Xmms bar configuration and autodetection of compatible cpu sensor).
*Improved icons for pop-up menus.
*Some cosmetic improvements.
*Updated install info (added xmmsctrl as a prerequisite).
*Much smaller tarball (removed screenshots).
*Announcement: I just found out that this theme was chosen as the default theme in the MDK superkaramba RPM (soon to be available in the contrib repositories) Yay! :-)

07/05/2004 -- ver.1.4
*Added user-configurable option to the install script to use KDE virtual desktops even if the 3ddeskd is found.
*Added uninstall script.
*Expanded FAQ.

07/01/2004 -- ver.1.3
*Fixed install script to properly add applications which are to be ignored when saving session at logout. The problem apparently affected setups where no "excludeapps" setting was found in the ksmserverrc file.
*Optimized the CPU, memory, and hd monitoring bars, resulting in typical CPU usage between 2-9% on my notebook (specs provided in the overview), which is a 2% lower than before.
*Provided alternative ways of displaying cpu speed (depending if you have ACPI and other stuff installed). See cpu.theme for more info.

07/01/2004 -- ver.1.2
*Redrawing of the systray bug has been resolved by using the redrawWidgetBackground() superkaramba API call.
*Fixed bug where on other resolutions the y-axis repositioning did not work correctly.
*Added install of default .rc files to the install script.
*Saving of the bar state now works correctly.
*Sliding of the bars should be a lot smoother and there should be less artifacts during the animation.

06/29/2004 -- ver.1.1a
*Minor fix to the install script to detect whether the user has the $HOME/.3ddesktop folder already created (and if not, then the script automatically creates it) prior to installing 3ddesktop settings.

06/28/2004 -- ver.1.1
*Install script now includes configuration of hd and network bars so that users can specify which drives and network devices they wish to monitor.
*Several minor bug-fixes to the install script.
*Minor fix to the cpu.theme and memory.theme by adding quotes around the 'align' parameter value in order to correct a problem that was pointed out by HermanR.

06/27/2004 -- ver.1.0
*Initial release.


TODO
====
*Allow easier customization of graph colors
*Possibly add more bars with other functionalities

Your votes, comments, and suggestions are most welcome and appreciated. Thanks!

Enjoy!