README

   1 XPENGUINS - cool little penguins walking along the tops of your windows
   2 Copyright (C) 1999-2001  Robin Hogan
   3 Version: 2.2 (1 October 2001)
   4
   5 INTRODUCTION
   6
   7 XPenguins is a program for animating cute cartoons/animals in your
   8 root window. By default it will be penguins - they fall from the top
   9 of the screen, walk along the top of windows, up the side of windows
  10 and do various other stuff. Other themes in the base package are "Big
  11 Penguins" (50% bigger), "Classic Penguins" (reproducing XPenguins
  12 version 1.2), "Turtles", and "Bill".  More themes can be downloaded
  13 from the XPenguins web site (http://xpenguins.seul.org/) - version 0.9
  14 of the xpenguins_themes package contains "The Simpsons", "Sonic the
  15 Hedgehog", "Lemmings" and "Winnie the Pooh".
  16
  17 To run the program, type "xpenguins" at the console. Type "xpenguins
  18 --help" to see the available options, or read the man page (type "man
  19 xpenguins"). If you want to make your own theme, read the THEMES
  20 section of the man page and have a look at the config file for the
  21 default theme (which is usually installed in
  22 /usr/share/xpenguins/themes/Penguins/config). You may also find the
  23 gimp scripts "lay-out-frames.scm" and "resize-frames.scm" useful - the
  24 first lays out the frames of an animated gif side by side in a way
  25 that can be used by XPenguins, and the second resizes an XPenguins
  26 image frame by frame to avoid bleeding of colors between adjacent
  27 frames.
  28
  29
  30 INSTALLATION
  31
  32 Do the following:
  33
  34         ./configure
  35         make
  36         make install (as root)
  37
  38 By default everything will be installed in /usr/local. Use
  39 "./configure --prefix=/usr" (or similar) to install it somewhere
  40 else. For more information, read the INSTALL file, or type "./configre
  41 --help". If you have problems with the make process then try using
  42 "gmake" instead of "make".
  43
  44
  45 LICENSE
  46
  47 This program is released under the GNU general public license - see
  48 the COPYING file. This license applies to everything in the base
  49 distribution, including the themes "Penguins", "Classic Penguins",
  50 "Big Penguins", "Turtles" and "Bill".
  51
  52
  53 FREQUENTLY ASKED QUESTION
  54
  55 "The program is running but I can't see any penguins. Why?"
  56
  57 "KDE 2, CDE, Enlightenment 0.16 (for desktops > 0), the Nautilus file
  58 mangler, and possibly others, all put a big X window over the root
  59 window. In the case of KDE 2.0 and 2.1, Enlightenment and Nautilus
  60 1.0, XPenguins should be able to find this window and draw to it
  61 instead of drawing to the root window. It then reports "Drawing to XXX
  62 Desktop" when it runs. Unfortunately there is no standardised way to
  63 find the correct window, so in later versions of any of these programs
  64 it might fail. When this happens the program looks like it's running
  65 but no toons are visible. Also, hybrid combinations such as KDE plus
  66 enlightenment might fail. CDE will probably never work, although
  67 XPenguins should definitely work with simpler window managers like
  68 sawfish and blackbox.  I have had reports of problems with KDE 2.2.
  69 This will be fixed when I get access to a machine running KDE 2.2."
  70
  71
  72 TOP TIP
  73
  74 If you have gtk-shell installed, try this courtesy of Carles Amigó. At
  75 the end of your ~/.bashrc file add the line:
  76
  77   alias xpselect="xpenguins -t \`gtk-shell -l \"Select a Theme:\" -c \\\`xpenguins -l |sed s/\" \"/_/g\\\` -t xpenguins -b \"Ok\"\`"
  78
  79 Now from a new terminal "xpselect" will allow you to select the theme
  80 in a handy dialog box.  If you run Korn shell, put the line in your
  81 ~/.kshrc file instead.  It'll probably work with csh too, but will
  82 need some modification.
  83
  84
  85 CODE GUIDE
  86
  87 You are welcome to modify or borrow any of this code, under the
  88 conditions of the GNU GPL.  The code is in the src directory and is
  89 organised as follows:
  90
  91 The toon_*.c files contain functions for animating images on the root
  92 (or other) window. They also hide the X calls from higher-level
  93 code. Each function is prefixed with "Toon" - you can see which
  94 functions are in which file by looking at the header file toon.h. One
  95 function that might be useful in other programs is ToonGetRootWindow()
  96 in toon_root.c; this finds the appropriate window to draw to when
  97 Nautilus/Enlightenment/KDE and so on are running. Certainly there are
  98 programs out there (e.g. xearth and xplanet) that sometimes don't work
  99 properly in these environments.
 100
 101 The xpenguins_*.c files contain functions (prefixed with xpenguins_)
 102 that load themes and govern the behaviour of the penguins. The header
 103 file xpenguins.h describes briefly what each function does. The user
 104 interface code then interprets the various user-supplied options and
 105 implements them by calling xpenguins functions; in this way different
 106 XPenguins front ends produce penguins that behave in the same
 107 way. This package is the command-line version - the front-end code is
 108 in main.c. The GNOME graphical front (the xpenguins_applet package)
 109 uses exactly the same toon and xpenguins files. Therefore if you make
 110 a modification to the program that you would like me to include in a
 111 future release, please do it in such a way that it will work in all
 112 versions.
 113
 114
 115 ACKNOWLEDGEMENTS
 116
 117 Inspiration was provided by Rick Jansen <rick@sara.nl> in the form of
 118 the classic "xsnow".
 119
 120 Many of the penguin images were taken from "Pingus", a free lemmings
 121 clone for Linux (http://pingus.seul.org/), and were designed by Joel
 122 Fauche <joel.fauche@wanadoo.fr> and Craig Timpany
 123 <timpany@es.co.nz>. Rob Gietema <tycoon@planetdescent.com> provided
 124 some new penguin images now used in the default theme.
 125
 126
 127 AUTHOR
 128
 129 Robin Hogan <R.J.Hogan@reading.ac.uk>
 130
 131 The XPenguins homepage is located at http://xpenguins.seul.org/
 132
 133
 134 SEE ALSO
 135
 136 Michael Vines <isamu@neomueller.org> has rewritten the program (as of
 137 version 1.1) for Microsoft Windows and called it "WinPenguins" -
 138 visit http://neomueller.org/~isamu/winpenguins/
 139