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 (the package names are the debian ones!)
---------------
  * Python 2.3 or higher (some distributions ship broken Python 2.4 packages),
    if you want to compile gdesklets you'll have to install the development
    package, too!

  * python-gtk2 2.4 or higher

  * python-gtk2-dev if you want to compile gDesklets

  * python-pyorbit 2.0.x

  * python-gnome2 2.6.x or higher (on RPM-based distributions it is split
    into several packages, install every gnome-python2 package and you're
    safe!)

  * python-gnome2-dev if you want to compile gDesklets

  * libgtop2 (2.8.0 or higher is recommended)

  * libgtop2-dev if you want to compile gDesklets

  * librsvg (2.6.0 or higher from http://librsvg.sf.net)

  * librsvg-dev if you want to compile gDesklets

  * some sensors or controls may have extra requirements



3. Installation
---------------
  First sure that you have all necessary dependencies installed on your system!
  In addition to that you also need the (gtk/gnome) python devel packages.
  If you're new to linux please don't try to compile gDesklets; it's for your
  own protection.

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


  Sensors can be installed by copying them into the directory
  '~/.gdesklets/Sensors' or into 'PREFIX/Sensors' where PREFIX is the
  installation path of 'gDesklets', e.g. '/usr/share/gdesklets'.
  Most sensors come packaged as handy executable installer files which you just
  have to run in order to get the sensor installed.

  Controls can be installed by copying them into the directory
  '~/.gdesklets/Controls' or into 'PREFIX/Controls'.

  Displays don't get installed anywhere special. It's up to the distributors
  where to install the .display files. The preferred places, however, are
  '~/.gdesklets/Displays' and 'PREFIX/Displays'. The graphical shell assumes
  that the displays can be found there.

  The recommended way for users to install displays/sensors/controls is by
  using the graphical shell (see below).



4. Migrating from an older version
----------------------------------
  gDesklets 0.3x uses a slightly different way of storing configuration. If you
  want to keep your old configuration, you have to run

    $ gdesklets-migration-tool

  Many thanks to Dave Masterson for writing this handy wizard!



5. Usage
--------
  If you chose GNOME integration, the graphical shell will be available in
  the Accessories menu. Otherwise, you will have to run it by hand:

    $ gdesklets shell


5.1 The Command Line Tool
-------------------------
  The command line tool 'gdesklets' lets you perform all administration tasks
  from the command line.

  Display files can be opened using

    $ gdesklets open <displayfile> [displayfile] ...

  If the gdesklets-daemon wasn't running, this will start up the daemon as
  well. You can only have one daemon per X-display. The daemon can be stopped
  again by calling

    $ gdesklets stop


  Usage of the command line frontend:

    gdesklets [option] <command> [arguments...]

    <command>
               open <files>      (Opens the given display files)
               start             (Runs the gDesklets daemon)
               stop              (Stops the gDesklets daemon)
               list              (Lists open displays)
               restart           (Restarts the gDesklets daemon)
               profile <profile> (Switches to the given profile)
               profile           (Shows the current and the available profiles)
               shell             (Opens the graphical shell)
               slay              (Kills the daemon -- use in emergency)
               status            (Checks daemon status)
               about             (Prints information about gDesklets)
               version           (Prints gDesklets version)
               help              (Displays this text)

    [option]
               --translucent (enables translucency on the xorg servers)

  The '--translucent' option is still in an experimental state, though. It may
  or may not work as expected.
  If you don't pass a command, the script will fall back to "gdesklets start"
  which is the default.


5.2 The gDesklets-Shell
-----------------------
  The shell is a graphical frontend for managing your desklets. You can start
  it either by selecting it from the GNOME menu (Accessories -> gDesklets),
  by selecting it from the tray icon popup menu, or by calling:

    $ gdesklets shell

  The shell currently lets you create and switch between profiles, install new
  desklets and search for desklets. New desklets can be installed by dragging
  links from your web browser or files from the file manager into its window,
  or by selecting the menu item "File -> Install package...".


5.3 Working with Displays
-------------------------
  Displays stick to your mouse pointer when you first run them. Choose the
  desired position and press the left button to place 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.

    Move display                     Lets you move the display around. Press the
                                     left mouse button once you have found a
                                     good place.

    View Source                      Opens the default editor, so you can view
                                     and edit the display files. This is quite
                                     handy for developers and people who want to
                                     learn more about gDesklets.

    Restart display                  Restarts this display. This menu item is
                                     mainly for sensor debugging.

    Remove display                   Removes this display from your desktop.


5.4 Logfile
-----------
  The gdesklets-daemon writes a log file. That file can be found in
    ~/.gdesklets/gdesklets<display>.log
  where <display> is the name of the X-display.

  You can select the item "View log" in the popup menu of the tray icon to view
  the log messages.



6. 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
    * evilwm
    * fluxbox >= 0.99
    * waimea
    * ...and certainly some other which we forgot here.



7. Bugs
-------
  If you encounter bugs which are not listed here, please post a bug report
  at bugzilla.gnome.org for 'gdesklets'. Don't report useless bug reports, like
  "gDesklets crash" without checking the log file first. Also make sure, that
  you have all the necessary dependencies installed.
  If the log says: "ImportError: No module named X" then you clearly don't have
  the python module "X" installed on your system.
  We are going to close useless bug reports immediately(!), so please save your
  and our time and be smart!

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

  * 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



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

  Discussion and Help
  http://gnomesupport.org/forums/viewforum.php?f=23

  Distribution specific problems thread
  http://gnomesupport.org/forums/viewtopic.php?t=5525

  gDesklets' FAQ page:
  http://gdesklets.free.fr

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



9. 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, autotools tweaks and core/sensor programming

  * Jesse Andrews -- core/sensor programming

  * Johannes "Waldgeist" Rebhan -- artwork

  * Christian Neumair -- installation

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

  * Benoît Dejean -- libgtop2 bindings and lots of code improvements

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

  * James Henstridge -- excellent GTK bindings for Python



10. 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 - 2005 by
                             Martin Grimme   <martin@pycage.de>,
                             Christian Meyer <chrisime@gnome-de.org>,
                             Jesse Andrews   <jdandr2@cs.uky.edu>
                             Benoît Dejean   <tazforever@dlfp.org>

'glibtop Python wrapper' in libdesklets
            is copyright (c) 2003 - 2005 by Benoît Dejean <tazforever@dlfp.org>
            (see http://dejean.benoit.free.fr/software/glibtop/glibtop.html)

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