gDeskCal
========

1. Introduction
---------------
  'gDeskCal' is a cute little eye-candy calendar for your desktop.
  It features transparency with smooth alpha-blending and its appearance can
  be changed completely by using skins.
  It can also read and display your 'Evolution' appointments, if available.



2. Requirements
---------------
  Your system has to meet the following requirements in order to be able to run
  'gDeskCal':

  * Python 2.x with basic XML support (PyXML is not required)

  * GTK 2 and its pygtk bindings

  * A window manager complying with the standards of www.freedesktop.org is
    recommended; exotic or antiquated window managers may yield strange results



3. Installation
---------------
  You don't have to install 'gDeskCal' before running it. You may run it from
  where you extracted it to.
  If you wish to install 'gDeskCal' globally on your system, do the following:

   * extract the archive to the place where you want 'gDeskCal' to be, e.g.
     '/usr/local/share'

   * put a link to the executable into the 'bin' directory, e.g.
       $ cd /usr/local/bin
       $ ln -s /usr/local/share/gDeskCal/gdeskcal



4. Usage
--------

4.1 Starting 'gDeskCal'
-----------------------
  'gDeskCal' accepts a number of command line options which are:

    --skin=<skin>       The name of the skin to use. A skin's name is the name
                        of its directory.

    --opaque            Causes the calendar to be opaque so you cannot see the
                        background through it. This setting will not be saved.

    --screenshot        Causes the calendar to simulate transparency by making
                        screenshots. You can use this when you want icons to
                        be visible through the calendar. This setting will not
                        be saved.

    --dpi=<resolution>  Tells 'gDeskCal' that the screen resolution is
                        <resolution> dots per inch. You normally don't have to
                        use this option since 'gDeskCal' can guess the value.
                        This option affects the scaling of fonts and will not
                        be saved.

    --dontsave          Tells 'gDeskCal' not to save any configuration changes.

    --first-day=<n>     The number of the first day of the week. Can be in the
                        range from 1 (Monday) to 7 (Sunday). The default is
                        Monday (the European norm).

    --numerals=<value>  Tells 'gDeskCal' which numerals it should use.
                        <value> can be one of:
                          * national - use the numerals defined by the current
                                       locale, e.g. Hindi numerals in the
                                       Arabic locale or Chinese numerals in
                                       the Chinese locale
                          * default  - use Arabic numerals no matter what the
                                       locale says; Arabic numerals are common
                                       in most regions of the world

    -x <value>          The x coordinate.

    -y <value>          The y coordinate.

    --help              Displays help about the command line options and exits.

  Settings from command line options override saved settings and unless you
  run the program with '--dontsave', settings from the command line will be
  saved.


4.2 Moving
----------
  You can move the calendar around by pressing and holding down the middle
  mouse button.


4.3 Menu
--------
  Pressing the right mouse button over 'gDeskCal' will show the following menu:

   Current Month             Jumps to the current month
   Previous Month            Goes back one month
   Next Month                Goes forward one month
   ---
   Change Skin...            Opens the skin browser (see 4.3)
   ---
   Quit                      Quits 'gDeskCal'


4.4 Skin Browser
----------------
  The skin browser displays a list of all available 'gDeskCal' skins on your
  system. To change the skin, just select an item from the list.
  The close button will make the browser window disappear.


4.5 Installing Skins
--------------------
  You can install new skins by dragging a skin archive from your file manager
  into the skin browser window.

  Alternatively, you may also copy the archive of the skin you want to install
  into ~/.gdeskcal/skins/ and extract it there. The skin browser will be
  updated as soon as you re-open it again.


4.6 Browsing through Months
---------------------------
  Use the navigation buttons to browse through the months. The buttons are:

   * previous month

   * current month

   * next month


  If you have a wheel mouse, you may also roll the wheel for browsing through
  the months:

   * up:   previous month

   * down: next month


  Please note that not all skins provide navigation buttons. The mouse wheel,
  however, will always work.


4.7 Transparency
----------------
  You can manually notify 'gDeskCal' to re-grab the background by pressing
  the Space key when 'gDeskCal' is the active window. However, this should
  not be necessary.


4.8 Evolution Support
---------------------
  If 'gDeskCal' can find a calendar file of the groupware application
  'Evolution', it will read it and display the appointments from there.
  Days with appointments are marked by underscores. You can view the
  appointments by moving the mouse over such days.

  The calendar file is being monitored and 'gDeskCal' updates as soon as the
  calendar changes.


4.9 Appointments Editor
----------------------
  Double-click on a day to open the appointments editor. Changes will be saved,
  but you cannot edit appointments imported from 'Evolution', since 'gDeskCal'
  treats the 'Evolution' calendar as read-only.


4.10 National Numerals
----------------------
  National numerals are numerals that are used instead of the international
  Arabic numerals in some languages. 'gDeskCal' supports national numerals for
  some languages. Pass the option '--numerals=national' to 'gDeskCal'
  to enable national numerals.

  E.g. to make 'gDeskCal' use Hindi numerals, which are set for the Arabic
  locale, set your system's locale to Arabic and start 'gDeskCal' with
  '--numerals=national', e.g.:

   $ export LANG=ar_EG
   $ gdeskcal --numerals=national

  The setting for national numerals will be saved, so you only have to give
  this option once.
  If you want to switch back to the international numerals, use the option
  '--numerals=default'.



5. Bugs
-------
  If you encounter bugs which are not listed here, please send a bug-report to
  'martin@pycage.de'.

  * There seems to be a bug in PyXML 0.7.1 which makes it incompatible with
    'gDeskCal'. Newer versions of PyXML ought to work.

  * Someone reported that 'gDeskCal' does not notice every background change
    caused by the program 'xplanet'.
    However, I did not experience any problems with 'xplanet'. Maybe this can
    happen on fast machines.

  * The window managers Afterstep and WindowMaker draw a border around the
    window. This seems to be their interpretation of undecorated windows.

  * Version 2.5.0 of the window manager metacity is reported to have problems
    with borderless windows. This affects other applications as well.
    Version 2.5.1 of metacity fixes this bug.



6. 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 'LICENSE' 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.



-------------------------------------------------------------------------------
'gDeskCal' is copyright (c) 2002, 2003 by Martin Grimme
eMail: martin@pycage.de

The latest version can be found at http://www.pycage.de