gDesklets - GNOME Desktop Applets
=================================

1. Introduction
---------------
  'gDesklets' provides an advanced architecture for desktop applets - tiny
  displays sitting on your desktop in a symbiotic relationship of eye candy and
  usefulness.
  Populate your desktop with status meters, icon bars, weather sensors,
  news tickers... whatever you can imagine! Virtually anything is possible and
  maybe even available some day.



2. Requirements
---------------
  * Python 2.x or higher (2.3 recommended)

  * libgtop2

  * gnome-python 1.99.17 or higher (2.0.0 recommended)

  * SWIG 1.3 (if you want to compile a CVS version)

  * some sensors may have extra requirements



3. Installation
---------------
  Just the usual procedure:

   $ ./configure
   $ make
   $ su -c "make install"
   
  Make sure to install into the same prefix as GNOME if you want to have GNOME
  integration, e.g.:
   $ ./configure --prefix=/usr --sysconfdir=/etc

  Every user may install new sensors by copying them into the directory
  '~/.gdesklets/Sensors'. Usually, sensors come in the form of handy installers
  where you only have to run the installer in order to install the sensor.
  
  If you want to make sensors available system-wide, the sensor packages have
  to go to PREFIX/Sensors where PREFIX is the installation path of 'gDesklets',
  e.g. /usr/share/gDesklets



4. Usage
--------
  You can find an entry in the GNOME menu after a successful installation.
  When you start 'gDesklets' for the first time, your desktop will remain
  empty. 'gDesklets' is just a daemon running in the background.
  Open your file manager and click on a .display file in order to put that
  display onto the desktop. When you log out or quit 'gDesklets', the
  settings will be remembered for the next session.

  In case your file manager does not support starting displays you can
  alternatively call 'gdesklets' with some .display files as arguments. You can
  do this while the 'gDesklets' daemon is running.

  If your system supports it, 'gDesklets' is fully VFS aware and you may use
  GNOME VFS URIs instead of file paths.

  'gDesklets' understands the following command line options:

   --no-config                Runs 'gDesklets' without access to the
                              configuration base. This can be used for testing
                              individual displays without having to run other
                              displays, e.g.
                               $ gdesklets --no-config test.display

   --profile=<name>           Sets the profile to use. You may use any
                              alphanumeric string as a profile name. If the
                              profile doesn't yet exist, it will be created
                              empty. 'gDesklets' remembers the profile change
                              so you don't have to give this option each time.
                              Use '--profile=default' to switch back to the
                              default profile.

   --version                  Prints the version number and exits.


  Displays stick to your mouse pointer when you first run them. Choose the
  desired position and press the left button to place the it.
  You can move displays around by pressing and holding down the middle mouse
  button (or both mouse buttons if your mouse only has 2 buttons).
  'gDesklets' will remember the new position of the display for the future.

  If you press the right mouse button over a display, a popup menu will open.
  It depends on the display what you will see there, but the following items
  are always available:

   Configure display                Opens the configuration dialog for this
                                    display. It depends on the display what you
                                    can configure.
				    
   Restart display                  Restarts this display. This menu item is
                                    mainly for sensor debugging.

   Remove display                   Removes this display from your desktop.

   About                            Opens the "about" dialog to tell you more
                                    about 'gDesklets'.

   Quit                             This will quit 'gDesklets'. You don't
                                    really need this item, do you? It was only
                                    added for debugging purposes. :)



5. Supported Window Managers
----------------------------
Window managers which respect the EWMH specifications are currently supported.
EWMH compliant WM's are:

    * metacity
    * xfwm4
    * openbox
    * enlightenment (>= 0.16.6, see http://enlightenment.org/pages/news.html)
    * fvwm (2.5.x, see http://www.fvwm.org/features.php)
    * sawfish (+PATCH: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=210518)
    * kwin (partially, currently doesn't support _NET_WM_STATE_BELOW; please
            ask the KDE folks to fix this for 3.2)



6. Bugs
-------
  If you encounter bugs which are not listed here, please post a bug report
  at bugzilla.gnome.org for 'gdesklets'.

  * some versions of sawfish show displays with the 'below' flag set above
    other windows; please read section 5. "Supported Window Managers" for a
    patch for sawfish

  * some buggy versions of 'nautilus' can cause 'gDesklets' to crash when the
    desktop background is being changed; nautilus 2.4 does not have this bug

  * you cannot click on a .display file in nautilus 2.4 to launch the display;
    nautilus 2.4 uses a somewhat different MIME system

  * desklets displaying the system memory may be totally wrong on Linux kernel
    2.6; this is a bug in libgtop (the gnome-system-monitor suffers from this
    as well) and is supposed to be fixed in glibtop 2.5



7. Community
------------
  The site 'http://gdesklets.gnomedesktop.org' is the place where you can
  get new desklets or upload your own creations for sharing them with other
  users.

  There you can also find a link 'Discussion Forum' leading you to the official
  'gDesklets' discussion forum.

  You can meet the 'gDesklets' developers and other fans on the IRC channel
  #gdesklets on GIMPnet (irc.gimp.org).



8. Thanks
---------
  I'd like to thank all people who supported (and are still supporting) me so
  well with 'gDesklets'. Please complain if I forgot you... ;)

  * Christian Meyer -- ideas and sensor programming

  * Jesse Andrews -- sensor programming

  * Johannes "Waldgeist" Rebhan -- artwork

  * Christian Neumair -- installation

  * Sebastien Bacher -- man page and lots of other stuff

  * Benoit Dejean -- libgtop2 bindings

  * Luke Stroven -- gdesklets.gnomedesktop.org and 'gDesklets' forum

  * James Henstridge -- excellent GTK bindings for Python



9. License and Disclaimer
-------------------------
  This software is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY or FITNESS
  FOR A PARTICULAR PURPOSE. See the file 'COPYING' for more details.

  You should have received a copy of the GNU General Public License
  along with this software; if not, write to the 

    Free Software Foundation, Inc., 59 Temple Place, Suite 390, Boston,
    MA  02111-1307  USA

  This software is provided "as is" and the author is not and cannot be made
  responsible for any damage resulting from the use of this software.



-------------------------------------------------------------------------------
'gDesklets' is copyright (c) 2003 by Martin Grimme <martin@pycage.de>,
                                     Christian Meyer <chrisime@gnome-de.org>,
                                     Jesse Andrews <jdandr2@cs.uky.edu>

'glibtop Python wrapper' in libdesklets
            is copyright (c) 2003 by Benoit Dejean <bnet@ifrance.com>
            (see http://dejean.benoit.free.fr/software/glibtop/glibtop.html)

The latest version of 'gDesklets' can be found at http://www.pycage.de
The CVS repository is in GNOME CVS ('gdesklets' and 'gdesklets-extras').
