wmbutton: Use version number from autoconf.
[dockapps.git] / wmmenu / README
blob8325d882e1e1ec33af170e8a456388653895b924
1 WHAT IS IT
2 ----------
4 This is a "dock application" for Windowmaker, that provides a button bar to
5 launch applications from.
7 The bar opens automatically when either the mouse enters the button or you
8 click on it (this is configurable).
10 Multiple instances of the program can run at the same time:  each one provides
11 a menu that it reads from a separate file, so you can have as many different
12 menus as you want (you can also display the same menu more than once if you
13 want; dunno what it's useful for...).
15 REQUIREMENTS
16 ------------
18         Xlib, Xpm, libdockapp.
20         By default only XPM format icons can be loaded.  If you have
21         gdk-pixbuf (>= 0.9.0) installed, you can build wmmenu with it and all
22         image types supported by gdk-pixbuf will be loadable by wmmenu.
24         NB:
25         - gdk-pixbuf 0.8.0 might work, but I didn't check
26         - the new gdk-pixbuf (2.0) provided with Gtk+ 2.0 is currently
27             broken:  the Xlib part doesn't seem to be able to compile
28             without Gdk any more, making it useless.  I have included
29             Makefile definitions so that you can check by yourself (please
30             complain to the maintainer(s) of gdk-pixbuf-xlib).
32 LIBDOCKAPP WARNING
33 ------------------
35 There is a bug in libdockapp-0.4.0: it does not setup the dockapp's title
36 correctly, and wmmenu appears as being named "DockApp".  This prevents
37 using several wmmenus in WMaker's dock.
39 To correct this, apply the following one-change patch:
41 ========================================================================
42 diff -ru libdockapp-0.4.0.orig/src/damain.c libdockapp-0.4.0/src/damain.c
43 --- libdockapp-0.4.0.orig/src/damain.c  Mon Feb 14 11:08:04 2000
44 +++ libdockapp-0.4.0/src/damain.c       Sat May  4 13:59:30 2002
45 @@ -67,7 +67,7 @@
46      /* Set ClassHint */
47      if (!(classHint = XAllocClassHint()))
48         printf("%s: can't allocate memory for class hints!\n", progName), exit(1);
49 -    classHint->res_class = "DockApp";
50 +    classHint->res_class = name;
51      classHint->res_name = name;
53      XSetClassHint(DADisplay, DALeader, classHint);
54 ========================================================================
56 I also found my Debian package "libdockapp-dev" version 0.61.1-5 to have a
57 bug regarding timers:  If you use the hide_timeout option, you should
58 definitely recompile your own version.
60 QUICKSTART
61 ----------
63 1.  Make a ".wmmenu" directory in your home directory:
65         mkdir ~/.wmmenu
67 2.  You have to make at least one file containing the menu definition.  It's
68     also strongly advised to make a second file named "defaults", to contain
69     general settings such as pixmaps paths.
70     The syntax of those files is quite easy (and is detailed below) but as a
71     start point you can copy the example files and edit them:
73         [from the sources main directory]
74         cp example/[ad]* ~/.wmmenu
75         vi ~/.wmmenu/*
77     The menu would then be named "apps".
79 3.  The file in ~/.wmmenu you have put a menu definition in, must have its
80     name (relative to ~/.wmmenu) passed as argument to wmmenu like this:
82         wmmenu -m apps
84 USAGE
85 -----
87 wmmenu [<options>...]
90             show help message
91 -m MENUNAME (mandatory)
92             set the name of the menu file to load from ~/.wmmenu
93 -g WxH
94             set width and height of tile
95 -t XPMFILE
96             set the pixmap used as tile
97 -l XPMFILE
98             set the pixmap used as highlight to track pointer
99 -O oldleaving
100             use old behavior for hiding the button bar: hide only when
101             leaving the bar, not when leaving the tile.
102 -O click
103             activate the button bar only when clicking on the tile, not
104             when the mouse moves in and out.
105 -O noautoscale
106             disable automatic scaling of pixmaps, that makes them fit
107             inside specified tile size.
108 -O behind
109             draw highlight pixmap behind icon, not above.
110 -O hide=N
111             set the time delay necessary for the bar to close after the
112             cursor has left wmmenu.  N is specified as a strictly positive
113             integer in milliseconds.  1 is used by default.
114 -r ROWS
115             arrange icons in the bar on multiple rows (specified as the
116             number ROWS).  The default is one.  Icons are arranged leftmost
117             from upper left corner.
119 The tile is used in conjunction with transparent pixmaps as a background. When
120 drawing the button bar, for each button, the tile is drawn first, then the
121 specified icon is drawn over it.
123 The tile also determines the width and height of the button bar, as each
124 button pixmap is cut to the size of the tile if it's bigger, or centered over
125 it if it's smaller.  The height of the bar is the height of the tile, and the
126 width of the bar is the width of the tile multiplied by the number of entries
127 specified for the displayed menu.
129 I have included a facility to arbitrarily set tile geometry independently of
130 the pixmap tile's size, but not sure it's useful.
133 When run, wmmenu first reads a file named "defaults" in ~/.wmmenu, from which
134 it gets settings common to all menus, currently the pixmap path and tile
135 and highlight pixmap names.  The pixmap path is used to set a list of paths
136 from which to search pixmap file names; At each place a pixmap file name is
137 requested, you can then use the file name without it's directory prepended
138 (leaving only the "basename").
140 The syntax of this file is roughly the following: comments start with # and
141 end at the end of the line they start on. Blank lines are allowed and always
142 meaningless. Other lines are variable setting and take the form
143 <variable><blanks><value> where <blanks> does NOT contain newlines (all this
144 must be on the same line). <variable> can be:
145     . xpmpath   <value> is a colon-separated list of path indicating where to
146                 search for pixmap files (i.e. /some/path1:/some/path2).
147     . tile      <value> is the file name of the pixmap to use as tile; Or
148                 use !<cmd> to specify a command to execute, that will
149                 return the name of the pixmap file name.
150     . highlight <value> is the file name of the pixmap to use for pointer
151                 tracking
153 Multiple xpmpath definitions can occur and are merged together.  A default
154 path of ~/.wmmenu is always prepended to the path list.
157 Then wmmenu reads the file specified by "-m" option from ~/.wmmenu directory.
158 This file specifies a list of buttons for the resulting menu, with the pixmap
159 to be used for the button and the command to be run when the corresponding
160 button is pressed.
162 The syntax is the following: the file is a suite of lines. Each line can be:
163     . blank, it is ignored
164     . a comment: it starts with # and is ignored too
165     . a menu entry: the line is written as "<pixmap>"<blanks><command>.
167 For each menu entry <pixmap> specifies the file name of the pixmap to be used
168 for the button, and <command> specifies a shell command to be run when the
169 button is pressed. <pixmap> can specify an absolute file name as well as a
170 path-less name, in which case it is searched in the pixmap path specified in
171 the "defaults" file. <command> usually has & at the end because wmmenu runs it
172 synchronously (it waits for its termination); since this is run by the shell
173 you can also use redirections and all sort of things if you want to. You are
174 free to embed blanks in <command> as well as <pixmap>, since the syntax has
175 been done to allow it; you can also use double-quotes in <command>, though
176 obviously you cannot use them for the name of the pixmap file.
178 Finally the first entry defined is not used as a command button but for wmmenu
179 itself. The <pixmap> of this first entry is used as dockapp icon, and in the
180 future it's <command> will be used as title appearing in WindowMaker's dockapp
181 balloon.
183 STATUS
184 ------
186 1.3     2015/01/24
188         Now maintained by the Window Maker Developers Team
189         <wmaker-dev@lists.windowmaker.org>.
191         Remove trailing whitespace.
193         Update COPYING from http://www.gnu.org/licenses/gpl-2.0.txt.
195         Fix -Wsign-compare compiler warning.  Use size_t instead of int since
196         comparing with sizeof.
198         Fix -Wunused-value compiler warnings
200         Fix -Woverlength-strings compiler warning.  Instead of printing one
201         giant string for the help text, we print each line individually.
203         Fix -Wdeprecated-declarations compiler warnings.  The function
204         gdk_pixbuf_unref is deprecated.  We replace it with g_object_unref.
205         This requires linking against gobject-2.0.
207         Fix -Wunused-result compiler warning.  Print a warning message if
208         system() fails.
210         Replace deprecated DAInitialize() from libdockapp.  Patch from
211         Gentoo [1].
213         Update to compile with modern GDK-PixBuf.  In particular,
214         - We need to link against gdk_pixbuf-2.0 in addition to
215           gdk_pixbuf_xlib-2.0.
216         - The header gdk-pixbuf-xlib.h has been moved to the gdk-pixbuf-xlib
217           directory.
218         - The function gdk_pixbuf_new_from_file now requires two arguments.
219         - We need to define GdkColor ourselves since we don't include gdk.h.
220         Inspired by a patch by Nerijus Baliunas [2].
222         Update Makefile.  In particular,
223         - Remove option to compile with deprecated GDK-PixBuf 1.0.
224         - Remove *ROOT variables; libdockapp should be in the default include
225           search path and X11R6 directories are deprecated.
226         - Remove /opt/gtk2/bin from PIXBUF_CFG; pkg-config is likely elsewhere.
227         - Remove CPPFLAGS from CFLAGS and INCDIRS and DEFINES from CFLAGS; we
228           don't want these to disappear if user defines different flags.
229         Inspired in part by similar patches in Gentoo [3] and by Nerijus
230         Baliunas [2].
232         [1] http://mirrors.telepoint.bg/gentoo-portage/x11-plugins/wmmenu/files/
233             wmmenu-1.2-support-libdockapp-0.5.0.patch
234         [2] http://lists.windowmaker.org/dev/msg07994.html
235         [3] http://mirrors.telepoint.bg/gentoo-portage/x11-plugins/wmmenu/files/
236             wmmenu-1.2-Makefile.patch
238 1.2     2002/05/04
240         (Thanks to Daniel Déchelotte for many bug fixes, patches and
241         suggestions)
243         New behaviour:
244         - also show the bar when entering the dockapp's tile.  Hide it
245             after cursor has left all wmmenu windows (bar, icon or tile).
246         - as a side effect, "oldleaving" option has been removed.
248         Corrections:
249         - remove flicker when cursor goes from icon/tile to bar and
250             vice-versa.
251         - forgot to remove highlight pixmap when cursor leaves bar with
252             "-O click" behaviour.
253         - fixed "garbaged" highlight effects after menu file changes
254         - don't paint highlight pixmap on empty bar slots (those can occur
255             when spreading menu entries over several rows).
256         - don't crash when WM terminates (or changes).  Gracefully handles
257             dock-less WM.  (useful when I try new WMs)
258         - some updates to README (and warnings about libdockapp)
260 1.1     2002/04/14
262         New feature:
263         - the tile can now be specified by the value returned by an
264             external command.  A sample script, extract_icon_back, is
265             provided to get the icon pixmap used by WindowMaker.
266             NB: this command is only used once at startup.
268         Correction:
269         - default tile pixmap is now also used when no tile pixmap is
270             specified at all (or an empty one).
272 1.0     2002/03/23
274         New feature: if you want to use a highlight pixmap that's designed
275         to cover most of tile's surface, current highlighting is not
276         adequate, because the highlight pixmap is drawn OVER other pixmaps.
277         A new drawing mechanism has been added to draw it BEHIND other menu
278         icons.
280         Added option "-O behind" to trigger this behaviour.
281         Also added "highlight_behind" directive in the defaults file, which
282         also triggers this behaviour.
283         Updated the sample defaults file.
284         Updated man page to reflect changes (have a look at it for details).
286         Corrections:
287         - Disable autoscaling of the dockapp icon (didn't scale to the
288             appropriate size), until someone tells me how wmmenu/libdockapp
289             is supposed to work in case it's too big.
290             (reported by Daniel Déchelotte)
292         NB:  gdk-pixbuf 2.0 (provided with Gtk+ 2.0) is currently not
293         compatible with wmmenu (see REQUIREMENTS section).
295 0.9     2001/10/20
297         When using the gdk-pixbuf enabled version, pixmaps larger than tile
298         (either the tile pixmap itself, or the size specified on command
299         line) are automatically scaled to fit within the requested size.
300         This affects the dock icon, tile, highlight and application icons.
301         If you like pixmaps overriding each other (gasp!), this can be
302         disabled with "-O noautoscale".
304         Through the "highlight" feature you can set a pixmap, that is drawn
305         over the menu item currently designated by the pointer, and that
306         follows it.  This allows one to know for sure, which item will be
307         launched if clicked.  A pixmap "target-white.xpm" is provided as a
308         sample:  try adding its path after "-l" option on your wmmenu's
309         command line.
311         Pixmap file names and xpmpath elements accept "~/" at their
312         beginning, to refer to your home directory (this was suggested a
313         long time ago).
315         I have written a man page (thanks to manedit).
317 0.8     2001/06/16
319         Speedup startup by providing a different color allocation routine
320         to gdk-pixbuf.  (Startup speedup is observed with gdk-pixbuf;
321         Patch from Lukasz Pankowski)
323 0.7     2001/04/21
325         Integrated "multi-rows" patch from Lukasz Pankowski: icons can be
326         arranged in multiple rows on the button bar.  For this you have to
327         specify "-r ROWS" on command line.
329 0.6     2001/03/24
331         Added click-only behavior with "-O click" option.
332         (Thanks to Matthew Gabeler-Lee for his patch)
334 0.5     2001/02/03
336         The button bar is now hidden when the cursor leaves the dockapp
337         tile, and not only when it leaves the button bar (behavior
338         suggested by Guido Falsi).
340         I added an option the get the previous behavior.  Please report
341         whether you need it, else it will disappear in next releases since
342         I consider the new behavior to be more user firendly.
344 0.4     2000/12/30
346         Simplify gdk-pixbuf selection as build option in Makefile.
348         New feature: automatic menu reloading on menu file change.
349         Default icons are used for app and tile when specified pixmap is not
350         found or not loadable (helps to not exit prematurely when doing
351         changes).
353 0.3     2000/11/01
355         Optionally (choice made at compile-time) use gdk-pixbuf(-xlib) to load
356         images.  This provides loading ability for many image types: BMP, GIF,
357         ICO, JPEG, PNG, PNM, RAS, TIFF and XPM (on my host at least).  Don't
358         forget that transparency is not available with BMP, PNM and (?) RAS.
360         Caveat: may not work very well on pseudo-color displays (not tested)
361         because of bad (blind) color allocation strategy.  This was already
362         the case with libXpm, so it's not a so great change.
364 0.2     2000/08/05
366         install target in Makefile.
367         Accept multiple xpmpath specifications in defaults file, they are
368         appended to each other.
369         More documentation (and more explicit on usage).
370         Missing Xext link library on some systems.
372 0.1     2000/06/25
374         First public release.
376 COPYRIGHT
377 ---------
379 This software is copyright (c)2000 F.COUTANT, and is placed under the GNU
380 General Public License (GPL), which is given in the file COPYING.
382 E-mail: fcoutant@freesurf.fr