wmclockmon: update change-log
[dockapps.git] / wmmenu / wmmenu.1
blobba701a6444d0e9cf9ad07b49536affd068fd6920
1 .TH "wmmenu" "1" "1.1" "Fabien COUTANT" "WMaker dockapp"
2 .SH "NAME"
3 .LP
4 wmmenu \- A WindowMaker dockapp to launch programs with a popup pixmap menu
5 .SH "SYNTAX"
6 .LP
7 wmmenu [\fI<options>\fR] \fB\-m\fP \fI<MENUNAME>\fR
8 .br
9 wmmenu \fB\-v\fP
10 .br
11 wmmenu \fB\-h\fP
12 .SH "DESCRIPTION"
13 .LP
14 This is a "dock application" for Windowmaker, that provides a button bar to
15 launch applications from.
16 .LP
17 The bar opens automatically when either the mouse enters the button or you
18 click on it (this is configurable).
19 .LP
20 Multiple instances of the program can run at the same time:  each one provides
21 a menu that it reads from a separate file, so you can have as many different
22 menus as you want (you can also display the same menu more than once if you
23 want; dunno what it's useful for...).
24 .LP
25 NOTE: options can take place before or after "\-m", as long as each option is
26 correctly paired with its corresponding argument (when it has one).
27 .SH "OPTIONS"
28 .LP
29 .TP
30 \fB\-h\fR
31 print a help message listing known options.
32 .TP
33 \fB\-v\fR
34 print version information
35 .TP
36 \fB\-g\fR \fIW\fP\fBx\fR\fIH\fP
37 force width and height of tile
38 .TP
39 \fB\-l\fR \fIXPMFILE\fP
40 set filename of the pixmap used to highlight icon under cursor
41 .TP
42 \fB\-t\fR \fIXPMFILE\fP
43 set filename of the pixmap used as button bar background.
44 XPMFILE may also be '!COMMAND' to execute COMMAND and get the pixmap name to use
45 from its output.
46 .TP
47 \fB\-O click\fR
48 bar is only triggered by clicks on the tile, not moves
49 .TP
50 \fB\-O noautoscale\fR
51 disable automatic pixmap scaling to tile size
52 .TP
53 \fB\-O behind\fR
54 draw highlight pixmap behind icon, not above
55 .TP
56 \fB\-O hide=\fIN\fR
57 set bar hiding timeout in ms.  See hide_timeout description in Defaults.
58 .TP
59 \fB\-r\fR \fIROWS\fP
60 set number of menu rows (default one)
61 .LP
62 Please note, that \fB\-l\fR, \fB\-t\fR and \fB\-O behind\fR options
63 can also be specified with another syntax in the \fBdefaults\fR file
64 (described hereafter).
65 .SH "DEFAULTS FILE"
66 This is a configuration file that defines things common to all instances
67 of wmmenu.
68 It is located in "~/.wmmenu/defaults".
70 .LP
71 The syntax is as follows:
72 .LP
73 # comment or empty lines are ignored
74 .LP
75 xpmpath PATH1:PATH2:...
76 .br
77 xpmpath PATH3
78 .br
79 xpmpath PATH4
80 .br
81 ...
82 .br
83 # defines in which path to search for pixmaps
84 .LP
85 tile FILE.XPM
86 .br
87  or
88 .br
89 tile /SOME/PATH/TO/FILE.XPM
90 .br
91 # defines pixmap used as background tile in menu bar
92 .br
93  or
94 .br
95 tile !some_command with arguments
96 .br
97 # defines the command to call to get the pixmap name to be
98 # used: the name is read from its standard output.
99 # If the name read is empty, the internal default is used
100 # instead.
102 highlight FILE.XPM
104  or
106 highlight /SOME/PATH/TO/FILE.XPM
108 # defines pixmap used to highlight item under cursor
110 highlight_behind[ ANYTHING_NOT_EMPTY]
112 # (don't forget the separating space)
114 # request to draw highlight pixmap BEHIND icon,
116 # no more in front.
118 # To be used if your pixmap is designed to cover most
120 # of tile's surface
122 hide_timeout MS
124 # set the delay, in ms, necessary for the bar to close
126 # after the cursor has left wmmenu.  1 by default.
127 .SH "MENU FILES"
128 Those files each define a menu of their own.
129 Each menu file is located in "~/.wmmenu/\fI<MENUNAME>\fR";
130 The name of the file determines the name you must use on command\-line
131 to call it.
134 The syntax is the following:
136 # comment and blank lines are ignored
138 "MENUICON.XPM"  menu title
139 There is exactly one such line in each menu file,
140 and is the first significant line encountered.
141 It describes the menu name, which may be used by your window manager, and
142 the pixmap that is shown to trigger the menu.
143 The pixmap is specified using the same rules as the next item (read on).
145 "ICON.XPM"      command arguments &
146 \fIICON.XPM\fR is an image filename or path.
147 It can be an absolute path (begins with "/"),
148 a path relative to wmmenu's current directory (contains a "/" but not at the beginning),
149 a path relative to home directory (starts with "~/"),
150 or a simple file name (searched through all defined xpmpath elements).
151 If you compiled wmmenu with gdk\-pixbuf support, the image can be any format
152 supported by this library (GIF, PNG, TIFF, JPEG, etc...);
153 Otherwise only XPM is supported.
155 \fIcommand\fR and \fIarguments\fR are run with the system(3) library call,
156 hence:
157 1/ you can use any shell tricks you want, and
158 2/ wmmenu waits for command completion, so for X11 programs you have to add
159 "\fB&\fR" at the end.
160 .SH "FILES"
162 \fI~/.wmmenu/<MENUNAME>\fP
164 \fI~/.wmmenu/defaults\fP
165 .SH "ENVIRONMENT VARIABLES"
168 \fBHOME\fP
169 Specifies the home directory
170 .SH "EXAMPLES"
172 I personally use the following command line:
174 wmmenu \-m apps \-r 3
175 .SH "BUGS"
177 If wmmenu was not compiled with gdk\-pixbuf support,
178 application icons larger than tile overlap over icons next to them.
179 With gdk\-pixbuf support turned on, images in this case are
180 automatically scaled down to fit to tile
181 (unless "\-O noautoscale" was specified).
183 There is some flicker when the mouse goes from the dockapp to the
184 menu bar.  On fast displays this is not always apparent.
186 No editor is provided, to edit menu files.
187 However, editing by hand is not so difficult, and
188 menu files are automatically reloaded each time you save them.
189 You only have to restart wmmenu, if you change any setting in
190 the \fBdefaults\fR file.
191 .SH "AUTHORS"
193 Fabien COUTANT <fcoutant@freesurf.fr>
194 .SH "SEE ALSO"
196 rox\-menu, wmaker