SYNOPSIS

DESCRIPTION

OPTIONS

-a, --no-angels

Do not show any cherubim flying up to heaven when a toon gets squashed.

-b, --no-blood

Do not show any gory death sequences.

-c dir, --config-dir dir

Look for config files and themes in this directory. The default is usually /usr/share/xpenguins.

-d display, --display display

Send the toons to the specified X display. In the absence of this option, the display specified by the DISPLAY environment variable is used.

-h, --help

Print out a message describing the available options.

-i, --theme-info

Print out the auxiliary information about a theme and exit. Use the -t option to select the theme to describe.

--random-theme

Start with a random theme.

-l, --list-themes

List the available themes, one on each line, and exit.

-m delay, --delay delay

Set the delay between each frame in milliseconds. The default is defined by the theme.

-n number, --penguins number

The number of toons to start, up to a maximum of 256. The default is defined by the theme.

-p, --ignorepopups

Toons fall through `popup' windows (those with the save-under attribute set), such as tooltips. Note that this also includes the KDE panel.

-r, --rectwin

Toons regard all windows as rectangular. This option results in faster calculation of window positions, but if you use one of those fancy new window managers with shaped windows then your toons might sometimes look like they're walking on thin air.

-s, --squish

Enable the penguins to be squished using any of the mouse buttons. Note that this disables any existing function of the mouse buttons on the root window.

-t theme, --theme theme

Use the named theme. The default is Penguins. If the theme has spaces in its name then you can use underscores instead, or alternatively just put the name in double quotes. This option can be called multiple times to run several themes simultaneously.

-q, --quiet

Suppress the exit message when an interupt is received.

-v, --version

Print out the current version number and quit.

--all

Load all available themes and run them simultaneously.

--id window

Send toons to the window with this ID, instead of the root window or whichever window is appropriate for the current desktop environment. Note that the ID of X clients reported by xwininfo is rarely that of the foremost visible window that should be used here.

--nice loadaverage1 loadaverage2

Start killing toons when the 1-min averaged system load exceeds loadaverage1; when it exceeds loadaverage2 kill them all. The toons will reappear when the load average comes down. The load is checked every 5 seconds by looking in /proc/loadavg, so this option only works under unices that implement this particular pseudo file (probably just Linux). When there are no toons on the screen, XPenguins uses only a miniscule amount of CPU time - it just wakes up every 5 seconds to recheck the load.

THEMES

In addition to the config file, the theme directory contains the toon images that make up the theme in the form of xpm image files. Additionally, there should be an about file which gives information on the creator of the theme, the license under which it is distributed and various other things. This file is principally for use by xpenguins_applet, an applet for GNOME that allows different themes to be selected at the click of a button.

The config file has a reasonably straightforward format. You can either read this rather terse description of it or you can have a look at the config file for the default Penguins theme, which is usually installed at /usr/share/xpenguins/themes/Penguins/config, and is reasonably well commented. We'll first establish some simple terminology. Say you have a Farmyard theme with cows and sheep. The cows and sheep are types of toon, while the various things they get up to (walking, mooing and so on) are termed activities. Each activity has its own xpm image file, in which the frames of the animation are laid out horizontally. Some activities (notably walking) use different images depending on the direction the toon is moving in. In this case the frames for the two directions are laid out one above the other in the image.

As in shell scripts, comments are initiated with the # character and hide the remainder of the line. The format is entirely free except that there is an arbitrary limit on the length of a line of 512 characters. Spaces, tabs and newlines all count equally as white space. Data is entered as a sequence of key value pairs, all separated by white space. Neither the keys nor the values are case sensitive, except where the value is a filename. The following keys are understood:

delay delay

Set the recommended delay between frames in milliseconds.

toon toon

Begin defining a new toon called toon. If only one type of toon is present in the theme then this key may be omitted.

number number

Set the default number of toons of the current type to start.

define activity

Begin defining an activity for the current toon. The currently understood activities are walker, faller, tumbler, climber, floater, runner, explosion, squashed, zapped, splatted, angel, exit and action?, where ? is a number between 0 and 6. Once you've seen the program in action you should be able to guess which is which. A valid theme must contain at least walkers and fallers. Additionally, you may define a default activity (with define default); any properties (such as width and speed) set here are then adopted by the activities defined from then on, if they do not themselves explicitly define those properties. After an activity has been declared with define, the following properties may be assigned:

pixmap xpmfile

The file containing the image data for the activity. Note that you may not set a default pixmap.

width width

The width of each frame of the animation in pixels.

height height

The height of each frame of the animation in pixels.

frames frames

The number of frames in the animation.

directions directions

The number of directions for the activity (can be 1 or 2).

speed speed

The initial speed of the toon when engaged in this activity, in pixels per frame.

acceleration acceleration

The rate at which the speed increases, in pixels per frame squared. This property is not utilised by all activities.

terminal_velocity terminal_velocity

The maximum speed in pixels per frame, again not utilised by all activities.

loop loop

Only understood by the actions; indicates how many times to repeat the action. If negative, then the probility of stopping the action every time the action is complete is -1/loop.

Some notes regarding the various activities. If you design a new theme, feel free to make the splatted, squashed, zapped and exit animations as gory and bloody as you like, but please keep the explosion activity nice and tame; that way those of a nervous disposition can employ the --no-blood option which replaces all these violent deaths with a tasteful explosion that wouldn't offend your grandmother. Xpm images files are a factor of two smaller if you can limit the number of colours in the image such that only one character need be used to represent each colour; this also makes XPenguins start up much more rapidly. Rarely are more than 64 colours required.

So that's about it for the config file, now for the about file. This is very simple. Again comments are initialised by a #. An entry consists of a key at the start of a line, followed by the corresponding value which is read up to the next newline. The following keys are understood, although none are compulsory.

artist

Used to list the artist(s) who created the original images.

maintainer

The person who compiled the images into an XPenguins theme. It is useful if an email address can also be provided.

date

The date when the theme was last modified. My preferred format is day of the month, name of the month in english, full year. For example: 24 April 2001.

icon

The name of an image file that can be used as an icon for the theme; XPM and PNG are suitable formats.

license

The name of the license under which the theme is distributed (e.g. GPL).

copyright

The year and holder of the copyright.

comment

Any other essential information, such as the theme's web site, as brief as possible.

Please test any about files you create by looking at how the information is displayed by the xpenguins_applet program.

AUTHOR

CREDITS

NOTES

The xpenguins homepage is located at:

http://xpenguins.seul.org/

FILES