WHAT IS IT
----------

This is a "dock application" for Windowmaker, that provides a button bar to
launch applications from.

The bar opens automatically when either the mouse enters the button or you
click on it (this is configurable) [not yet implemented: you don't have to
click].

Multiple instances of the program can run at the same time:  each one provides
a menu that it reads from a separate file, so you can have as many different
menus as you want (you can also display the same menu more than once if you
want; dunno what it's useful for...).

REQUIREMENTS
------------

	Xlib, Xpm, libdockapp.

	By default only XPM format icons can be loaded.  If you have
	gdk-pixbuf (>= 0.9.0) installed, you can build wmmenu with it and all
	image types supported by gdk-pixbuf will be loadable by wmmenu.

	(NB: gdk-pixbuf 0.8.0 might work, but I didn't check)

QUICKSTART
----------

1.  Make a ".wmmenu" directory in your home directory:

	mkdir ~/.wmmenu

2.  You have to make at least one file containing the menu definition.  It's
    also strongly advised to make a second file named "defaults", to contain
    general settings such as pixmaps paths.
    The syntax of those files is quite easy (and is detailed below) but as a
    start point you can copy the example files and edit them:

	[from the sources main directory]
	cp example/[ad]* ~/.wmmenu
	vi ~/.wmmenu/*

    The menu would then be named "apps".

3.  The file in ~/.wmmenu you have put a menu definition in, must have its
    name (relative to ~/.wmmenu) passed as argument to wmmenu like this:

	wmmenu -m apps

USAGE
-----

wmmenu [<options>...]

-h
	    show help message
-m MENUNAME (mandatory)
	    set the name of the menu file to load from ~/.wmmenu
-g WxH
	    set width and height of tile
-t XPMFILE
	    set the pixmap used as tile
-O oldleaving
	    use old behavior for hiding the button bar: hide only when
	    leaving the bar, not when leaving the tile.

The tile is used in conjunction with transparent pixmaps as a background. When
drawing the button bar, for each button, the tile is drawn first, then the
specified icon is drawn over it.

The tile also determines the width and height of the button bar, as each
button pixmap is cut to the size of the tile if it's bigger, or centered over
it if it's smaller.  The height of the bar is the height of the tile, and the
width of the bar is the width of the tile multiplied by the number of entries
specified for the displayed menu.

I have included a facility to arbitrarily set tile geometry independently of
the pixmap tile's size, but not sure it's useful.


When run, wmmenu first reads a file named "defaults" in ~/.wmmenu, from which
it gets settings common to all menus, currently the pixmap path and tile
pixmap name.  The pixmap path is used to set a list of paths from which to
search pixmap file names; At each place a pixmap file name is requested, you
can then use the file name without it's directory prepended (leaving only the
"basename").

The syntax of this file is roughly the following: comments start with # and
end at the end of the line they start on. Blank lines are allowed and always
meaningless. Other lines are variable setting and take the form
<variable><blanks><value> where <blanks> does NOT contain newlines (all this
must be on the same line). <variable> can be:
    . xpmpath   <value> is a colon-separated list of path indicating where to
		search for pixmap files (i.e. /some/path1:/some/path2).
    . tile	<value> is the file name of the pixmap to use as tile.

Multiple xpmpath definitions can occur and are merged together.  A default
path of ~/.wmmenu is always prepended to the path list.


Then wmmenu reads the file specified by "-m" option from ~/.wmmenu directory.
This file specifies a list of buttons for the resulting menu, with the pixmap
to be used for the button and the command to be run when the corresponding
button is pressed.

The syntax is the following: the file is a suite of lines. Each line can be:
    . blank, it is ignored
    . a comment: it starts with # and is ignored too
    . a menu entry: the line is written as "<pixmap>"<blanks><command>.

For each menu entry <pixmap> specifies the file name of the pixmap to be used
for the button, and <command> specifies a shell command to be run when the
button is pressed. <pixmap> can specify an absolute file name as well as a
path-less name, in which case it is searched in the pixmap path specified in
the "defaults" file. <command> usually has & at the end because wmmenu runs it
synchronously (it waits for its termination); since this is run by the shell
you can also use redirections and all sort of things if you want to. You are
free to embed blanks in <command> as well as <pixmap>, since the syntax has
been done to allow it; you can also use double-quotes in <command>, though
obviously you cannot use them for the name of the pixmap file.

Finally the first entry defined is not used as a command button but for wmmenu
itself. The <pixmap> of this first entry is used as dockapp icon, and in the
future it's <command> will be used as title appearing in WindowMaker's dockapp
balloon.

STATUS
------

0.5	2000/02/03

	The button bar is now hidden when the cursor leaves the dockapp
	tile, and not only when it leaves the button bar (behavior
	suggested by Guido Falsi).

	I added an option the get the previous behavior.  Please report
	whether you need it, else it will disappear in next releases since
	I consider the new behavior to be more user firendly.

0.4	2000/12/30

	Simplify gdk-pixbuf selection as build option in Makefile.

	New feature: automatic menu reloading on menu file change.
	Default icons are used for app and tile when specified pixmap is not
	found or not loadable (helps to not exit prematurely when doing
	changes).

0.3	2000/11/01

	Optionally (choice made at compile-time) use gdk-pixbuf(-xlib) to load
	images.  This provides loading ability for many image types: BMP, GIF,
	ICO, JPEG, PNG, PNM, RAS, TIFF and XPM (on my host at least).  Don't
	forget that transparency is not available with BMP, PNM and (?) RAS.

	Caveat: may not work very well on pseudo-color displays (not tested)
	because of bad (blind) color allocation strategy.  This was already
	the case with libXpm, so it's not a so great change.

0.2	2000/08/05

	install target in Makefile.
	Accept multiple xpmpath specifications in defaults file, they are
	appended to each other.
	More documentation (and more explicit on usage).
	Missing Xext link library on some systems.

0.1	2000/06/25

	First public release.

COPYRIGHT
---------

This software is copyright (c)2000 F.COUTANT, and is placed under the GNU
General Public License (GPL), which is given in the file COPYING.

E-mail: fcoutant@freesurf.fr

