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.2 or higher

  * libgtop2

  * gnome-python 1.99.17 or higher (2.0.0 recommended)

  * SWIG 1.3 (only required 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"
   
   If you want gdesklets to appear on the GNOME menu, be sure to
   put it where GNOME can find it, 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

  Displays don't get installed anywhere special. Currently, it's up to the
  distributors where to install the .display files. The preferred place for
  user-installed displays, however, is ~/.gdesklets/Displays.



4. Usage
--------
  If you chose GNOME integration, gDesklets will be under the Accessories
  menu. Otherwise, you will have to run it by hand.

  When you start 'gDesklets' for the first time, your desktop will remain
  empty. 'gDesklets' is just a daemon running in the background. If you're
  running GNOME or KDE (and have tray icons enabled), you can see a tray icon
  when the daemon is running.
  gDesklets does not automatically start up any displays. To start up a
  display, you should either put it on the gdesklets command line, or else
  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.

  Note that the MIME type system of GNOME 2.4 does not allow applications to
  register new data types. Therefore, you cannot start up a .display file with
  Nautilus 2.4.x in this fashion.

  To start a display after the 'gDesklets' daemon is running, run
  'gdesklets' with some .display files as arguments.

  If your system supports it, 'gDesklets' is fully VFS aware and you may use
  GNOME VFS URIs instead of file paths. You could e.g. have your desklets
  stored on some remote HTTP server.

  '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

   --orig-coords              Runs 'gDesklets' with every display put into the
                              top left corner. This is for debugging only.

   --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.

   --tray-icon                Displays an icon in the notification area to show
                              you that the 'gDesklets' daemon is running.

   --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 two 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;
    GNOME 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

  * transparency might be broken on Xinerama displays; we do not have Xinerama
    and thus cannot test it. If you want to help testing, please drop us a mail

  * the window shadows of many displays are wrong when running a composition
    manager on the freedesktop.org X server; we are aware of this issue and are
    investigating how to make 'gDesklets' use true transparency when running
    on a composition manager



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 and lots of code improvements

  * 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, 2004 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, 2004 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').
