wmix: call `XSetCommand()`.

[dockapps.git] / 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.3     2015/01/24

        Now maintained by the Window Maker Developers Team
        <wmaker-dev@googlegroups.com>.

        Remove trailing whitespace.

        Update COPYING from http://www.gnu.org/licenses/gpl-2.0.txt.

        Fix -Wsign-compare compiler warning.  Use size_t instead of int since
        comparing with sizeof.

        Fix -Wunused-value compiler warnings

        Fix -Woverlength-strings compiler warning.  Instead of printing one
        giant string for the help text, we print each line individually.

        Fix -Wdeprecated-declarations compiler warnings.  The function
        gdk_pixbuf_unref is deprecated.  We replace it with g_object_unref.
        This requires linking against gobject-2.0.

        Fix -Wunused-result compiler warning.  Print a warning message if
        system() fails.

        Replace deprecated DAInitialize() from libdockapp.  Patch from
        Gentoo [1].

        Update to compile with modern GDK-PixBuf.  In particular,
        - We need to link against gdk_pixbuf-2.0 in addition to
          gdk_pixbuf_xlib-2.0.
        - The header gdk-pixbuf-xlib.h has been moved to the gdk-pixbuf-xlib
          directory.
        - The function gdk_pixbuf_new_from_file now requires two arguments.
        - We need to define GdkColor ourselves since we don't include gdk.h.
        Inspired by a patch by Nerijus Baliunas [2].

        Update Makefile.  In particular,
        - Remove option to compile with deprecated GDK-PixBuf 1.0.
        - Remove *ROOT variables; libdockapp should be in the default include
          search path and X11R6 directories are deprecated.
        - Remove /opt/gtk2/bin from PIXBUF_CFG; pkg-config is likely elsewhere.
        - Remove CPPFLAGS from CFLAGS and INCDIRS and DEFINES from CFLAGS; we
          don't want these to disappear if user defines different flags.
        Inspired in part by similar patches in Gentoo [3] and by Nerijus
        Baliunas [2].

        [1] http://mirrors.telepoint.bg/gentoo-portage/x11-plugins/wmmenu/files/
            wmmenu-1.2-support-libdockapp-0.5.0.patch
        [2] http://lists.windowmaker.org/dev/msg07994.html
        [3] http://mirrors.telepoint.bg/gentoo-portage/x11-plugins/wmmenu/files/
            wmmenu-1.2-Makefile.patch

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