dockapps/wmmenu/README

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

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
	- the new gdk-pixbuf (2.0) provided with Gtk+ 2.0 is currently
	    broken:  the Xlib part doesn't seem to be able to compile
	    without Gdk any more, making it useless.  I have included
	    Makefile definitions so that you can check by yourself (please
	    complain to the maintainer(s) of gdk-pixbuf-xlib).

LIBDOCKAPP WARNING
------------------

There is a bug in libdockapp-0.4.0: it does not setup the dockapp's title
correctly, and wmmenu appears as being named "DockApp".  This prevents
using several wmmenus in WMaker's dock.

To correct this, apply the following one-change patch:

========================================================================
diff -ru libdockapp-0.4.0.orig/src/damain.c libdockapp-0.4.0/src/damain.c
--- libdockapp-0.4.0.orig/src/damain.c	Mon Feb 14 11:08:04 2000
+++ libdockapp-0.4.0/src/damain.c	Sat May  4 13:59:30 2002
@@ -67,7 +67,7 @@
     /* Set ClassHint */
     if (!(classHint = XAllocClassHint()))
 	printf("%s: can't allocate memory for class hints!\n", progName), exit(1);
-    classHint->res_class = "DockApp";
+    classHint->res_class = name;
     classHint->res_name = name;

     XSetClassHint(DADisplay, DALeader, classHint);
========================================================================

I also found my Debian package "libdockapp-dev" version 0.61.1-5 to have a
bug regarding timers:  If you use the hide_timeout option, you should
definitely recompile your own version.

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
-l XPMFILE
	    set the pixmap used as highlight to track pointer
-O oldleaving
	    use old behavior for hiding the button bar: hide only when
	    leaving the bar, not when leaving the tile.
-O click
	    activate the button bar only when clicking on the tile, not
	    when the mouse moves in and out.
-O noautoscale
	    disable automatic scaling of pixmaps, that makes them fit
	    inside specified tile size.
-O behind
	    draw highlight pixmap behind icon, not above.
-O hide=N
	    set the time delay necessary for the bar to close after the
	    cursor has left wmmenu.  N is specified as a strictly positive
	    integer in milliseconds.  1 is used by default.
-r ROWS
	    arrange icons in the bar on multiple rows (specified as the
	    number ROWS).  The default is one.  Icons are arranged leftmost
	    from upper left corner.

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
and highlight pixmap names.  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; Or
		use !<cmd> to specify a command to execute, that will
		return the name of the pixmap file name.
    . highlight	<value> is the file name of the pixmap to use for pointer
		tracking

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

1.2	2002/05/04

	(Thanks to Daniel D<>chelotte for many bug fixes, patches and
	suggestions)

	New behaviour:
	- also show the bar when entering the dockapp's tile.  Hide it
	    after cursor has left all wmmenu windows (bar, icon or tile).
	- as a side effect, "oldleaving" option has been removed.

	Corrections:
	- remove flicker when cursor goes from icon/tile to bar and
	    vice-versa.
	- forgot to remove highlight pixmap when cursor leaves bar with
	    "-O click" behaviour.
	- fixed "garbaged" highlight effects after menu file changes
	- don't paint highlight pixmap on empty bar slots (those can occur
	    when spreading menu entries over several rows).
	- don't crash when WM terminates (or changes).  Gracefully handles
	    dock-less WM.  (useful when I try new WMs)
	- some updates to README (and warnings about libdockapp)

1.1	2002/04/14

	New feature:
	- the tile can now be specified by the value returned by an
	    external command.  A sample script, extract_icon_back, is
	    provided to get the icon pixmap used by WindowMaker.
	    NB: this command is only used once at startup.

	Correction:
	- default tile pixmap is now also used when no tile pixmap is
	    specified at all (or an empty one).

1.0	2002/03/23

	New feature: if you want to use a highlight pixmap that's designed
	to cover most of tile's surface, current highlighting is not
	adequate, because the highlight pixmap is drawn OVER other pixmaps.
	A new drawing mechanism has been added to draw it BEHIND other menu
	icons.

	Added option "-O behind" to trigger this behaviour.
	Also added "highlight_behind" directive in the defaults file, which
	also triggers this behaviour.
	Updated the sample defaults file.
	Updated man page to reflect changes (have a look at it for details).

	Corrections:
	- Disable autoscaling of the dockapp icon (didn't scale to the
	    appropriate size), until someone tells me how wmmenu/libdockapp
	    is supposed to work in case it's too big.
	    (reported by Daniel D<>chelotte)

	NB:  gdk-pixbuf 2.0 (provided with Gtk+ 2.0) is currently not
	compatible with wmmenu (see REQUIREMENTS section).

0.9	2001/10/20

	When using the gdk-pixbuf enabled version, pixmaps larger than tile
	(either the tile pixmap itself, or the size specified on command
	line) are automatically scaled to fit within the requested size.
	This affects the dock icon, tile, highlight and application icons.
	If you like pixmaps overriding each other (gasp!), this can be
	disabled with "-O noautoscale".

	Through the "highlight" feature you can set a pixmap, that is drawn
	over the menu item currently designated by the pointer, and that
	follows it.  This allows one to know for sure, which item will be
	launched if clicked.  A pixmap "target-white.xpm" is provided as a
	sample:  try adding its path after "-l" option on your wmmenu's
	command line.

	Pixmap file names and xpmpath elements accept "~/" at their
	beginning, to refer to your home directory (this was suggested a
	long time ago).

	I have written a man page (thanks to manedit).

0.8	2001/06/16

	Speedup startup by providing a different color allocation routine
	to gdk-pixbuf.  (Startup speedup is observed with gdk-pixbuf;
	Patch from Lukasz Pankowski)

0.7	2001/04/21

	Integrated "multi-rows" patch from Lukasz Pankowski: icons can be
	arranged in multiple rows on the button bar.  For this you have to
	specify "-r ROWS" on command line.

0.6	2001/03/24

	Added click-only behavior with "-O click" option.
	(Thanks to Matthew Gabeler-Lee for his patch)

0.5	2001/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