Blob


1 .Dd $Mdocdate$
2 .Dt MYMENU 1
3 .Os
4 .Sh NAME
5 .Nm mymenu
6 .Nd simple menu for XOrg
7 .Sh SYNOPSIS
8 .Nm
9 .Bk -words
10 .Op Fl Aahmv
11 .Op Fl B Ar colors
12 .Op Fl b Ar size
13 .Op Fl C Ar color
14 .Op Fl c Ar color
15 .Op Fl d Ar separator
16 .Op Fl e Ar window
17 .Op Fl f Ar font
18 .Op Fl G Ar color
19 .Op Fl g Ar size
20 .Op Fl H Ar height
21 .Op Fl I Ar color
22 .Op Fl i Ar size
23 .Op Fl J Ar color
24 .Op Fl j Ar size
25 .Op Fl l Ar layout
26 .Op Fl P Ar padding
27 .Op Fl p Ar prompt
28 .Op Fl S Ar color
29 .Op Fl s Ar color
30 .Op Fl T Ar color
31 .Op Fl t Ar color
32 .Op Fl W Ar width
33 .Op Fl x Ar coord
34 .Op Fl y Ar coord
35 .Ek
36 .Sh DESCRIPTION
37 The
38 .Nm
39 utility a simple graphical menu for XOrg. It read the items from
40 .Ic stdin
41 and print the user selection to
42 .Ic stdout
43 on exit.
45 The following options are available and take the maximum precedence
46 over the (respective) ones defined in the
47 .Sy X Resource Database
48 .Bl -tag -width indent-two
49 .It Fl A
50 The user must chose one of the option (or none) and is not able to
51 arbitrary enter text
52 .It Fl a
53 The first completion (if any) is always selected. This is like dmenu.
54 .It Fl B Ar colors
55 Override the borders color. Parsed as MyMenu.border.color.
56 .It Fl b Ar borders
57 Override the borders size. Parsed as MyMenu.border.size.
58 .It Fl C Ar color
59 Override the completion background color. See
60 MyMenu.completion.background.
61 .It Fl c Ar color
62 Override the completion foreground color. See
63 MyMenu.completion.foreground.
64 .It Fl d Ar separator
65 Define a string to be used as a separator (mnemonic: delimiter). Only
66 the text after the separator will be rendered, but the original string
67 will be returned. Useful to embed custom data on every entry. See the
68 mpd example for hints on how this can be useful.
69 .It Fl e Ar windowid
70 Embed into the given window id.
71 .It Fl f Ar font
72 Override the font. See MyMenu.font.
73 .It Fl G Ar color
74 Override the border colors of the prompt. See
75 MyMenu.prompt.border.color.
76 .It Fl g Ar size
77 Override the border size of the prompt. See
78 MyMenu.prompt.border.size.
79 .It Fl H Ar val
80 Override the height. Parsed as MyMenu.height.
81 .It Fl h
82 Print a small usage message to stderr.
83 .It Fl I Ar color
84 Override the border colors of the completion. See
85 MyMenu.completion.border.color.
86 .It Fl i Ar size
87 Override the border size of the completion. See
88 MyMenu.completion.border.size.
89 .It Fl J Ar color
90 Override the border colors of the completion. See
91 MyMenu.completion_highlighted.border.color.
92 .It Fl j Ar size
93 Override the border size of the completion. See
94 MyMenu.completion_highlighted.border.size.
95 .It Fl l Ar layout
96 Override the layout. Parsed as MyMenu.layout.
97 .It Fl m
98 The user can select multiple entry via C-m. Please consult
99 .Sx KEYS
100 for more info.
101 .It Fl P Ar padding
102 Override the padding. See the MyMenu.prompt.padding resource.
103 .It Fl p Ar prompt
104 Override the prompt
105 .It Fl S Ar color
106 Override the highlighted completion background color. See
107 MyMenu.completion_highlighted.background.
108 .It Fl s Ar color
109 Override the highlighted completion foreground color. See
110 MyMenu.completion_highlighted.foreground.
111 .It Fl T Ar color
112 Override the prompt background color. See MyMenu.prompt.background.
113 .It Fl t Ar color
114 Override the prompt foreground color. See MyMenu.prompt.foreground.
115 .It Fl v
116 Print version and exit.
117 .It Fl W Ar val
118 Override the width. Parsed as MyMenu.width.
119 .It Fl x Ar val
120 Override the positioning on the X axis, parsed as the resource MyMenu.x
121 .It Fl y Ar val
122 Override the positioning on the Y axis, parsed as the resource MyMenu.y
123 .El
124 .Sh RESOURCES
125 .Bl -tag -width Ds
126 .It MyMenu.font
127 The font name to use. By default is set to "fixed" if compiled without
128 Xft(3) support, "monospace" otherwise. Without Xft(3) only bitmap font
129 are supported.
130 .It MyMenu.layout
131 The layout of the menu. The possible values are "horizontal" and
132 "vertical", with the default being "horizontal". Every other value
133 than "horizontal" is treated like "vertical", but this is kinda an
134 implementation detail and not something to be relied on, since in the
135 future other layout could be added as well.
136 .It MyMenu.prompt
137 A string that is rendered before the user input. Default to "$ ".
138 .It MyMenu.prompt.border.size
139 Parsed like MyMenu.border.size, but affects only the prompt. Default
140 to 0.
141 .It MyMenu.prompt.border.color
142 Parsed like MyMenu.border.color, but affects only the prompt. Default
143 to #000 (black).
144 .It MyMenu.prompt.padding
145 Parsed like MyMenu.border.size. The padding is the space between the
146 end of the borderd and the start of the text, in any direction (top,
147 bottom, left, right). Default to 10.
148 .It MyMenu.width
149 The width of the menu. If a numeric value is given (e.g. 400) is
150 interpreted as pixel, if it ends with a percentage symbol `%'
151 (e.g. 40%) the relative percentage will be computed (relative to the
152 monitor width).
153 .It MyMenu.height
154 The height of the menu. Like MyMenu.width if a numeric value is given
155 is interpreted as pixel, if it ends with a percentage symbol `%' the
156 relative percentage will be computed (relative to the monitor height).
157 .It MyMenu.x
158 The X coordinate of the topmost left corner of the window. Much like
159 MyMenu.height and MyMenu.width both a pixel dimension and percentage
160 could be supplied. In addition to it, some special value can be used.
161 .Bl -tag
162 .It start
163 Alias for 0;
164 .It middle or center
165 Compute the correct value to make sure that mymenu will be
166 horizontally centered;
167 .It end
168 Compute the correct value to make sure that mymenu will be right
169 aligned.
170 .It mx and my
171 These stands for x and y coordinate of the mouse respectively.
172 .El
173 .It MyMenu.y
174 The Y coordinate of the topmost left corner of the window. Like the X
175 coordinate a pixel dimension, percentage dimension or the special
176 value "start", "middle"/"center", "end" or "mx"/"my" could be supplied.
177 .It MyMenu.border.size
178 A list of number separated by spaces to specify the border of the
179 window. The field is parsed like some CSS properties (i.e. padding),
180 that is: if only one value is provided then it'll be used for all
181 borders; if two value are given than the first will be used for the
182 top and bottom border and the former for the left and right border;
183 with three value the first is used for the top border, the second for
184 the left and right border and the third for the bottom border. If four
185 value are given, they'll be applied to the respective border
186 clockwise. Other values will be ignored. The default value is 0.
188 This particular option accepts a percentage (e.g. 10%) relative to the
189 screen width.
190 .It MyMenu.border.color
191 A list of colors for the borders. This field is parsed like the
192 MyMenu.border.size. The default value is black.
193 .It MyMenu.prompt.background
194 The background of the prompt.
195 .It MyMenu.prompt.foreground
196 The text color (foreground) of the prompt.
197 .It MyMenu.completion.background
198 The background of the completions.
199 .It MyMenu.completion.foreground
200 The text color of the completions.
201 .It MyMenu.completion.border.size
202 Parsed like MyMenu.border.size, but affects only the
203 completion. Default to 0.
204 .It MyMenu.completion.border.color
205 Parsed like MyMenu.border.color, but affects only the
206 completion. Default to #000 (black).
207 .It MyMenu.completion.padding
208 Parsed like MyMenu.prompt.padding. Default to 10.
209 .It MyMenu.completion_highlighted.background
210 The background of the selected completion.
211 .It MyMenu.completion_highlighted.foreground
212 The foreground of the selected completion.
213 .It MyMenu.completion_highlighted.border.size
214 Parsed like MyMenu.border.size, but affects only the completion
215 highlighted. Default to 0.
216 .It MyMenu.completion_highlighted.border.color
217 Parsed like MyMenu.border.color, but affects only the completion
218 highlighted. Default to #000 (black).
219 .It MyMenu.completion_highlighted.padding
220 Parsed like MyMenu.prompt.padding. Default to 10.
221 .El
222 .Sh COLORS
223 MyMenu accept colors only in the form of:
224 .Bl -bullet
225 .It
226 #rgb
227 .It
228 #rrggbb
229 .It
230 #aarrggbb
231 .El
233 The opacity is assumed 0xff (no transparency) if not provided.
234 .Sh KEYS
235 This is the list of keybinding recognized by
236 .Li Nm Ns .
237 In the following examples, C-c means Control-c.
238 .Bl -tag -width indent-two
239 .It Esc
240 Close the menu without selecting any entry
241 .It C-c
242 The same as Esc
243 .It Enter
244 Close the menu and print to stdout what the user typed
245 .It C-m
246 Confirm but keep looping (if enabled), otherwise complete only
247 .It Tab
248 Expand the prompt to the next possible completion
249 .It Shift Tab
250 Expand the prompt to the previous possible completion
251 .It C-n
252 The same as Tab
253 .It C-p
254 The same as Shift-Tab
255 .It Backspace
256 Delete the last character
257 .It C-h
258 The same as Backspace
259 .It C-w
260 Delete the last word
261 .It C-u
262 Delete the whole line
263 .It C-i
264 Toggle the ``first selected'' style. Sometimes, especially with the -a
265 option, could be handy to disable that behaviour. Let's say that
266 you've typed ``fire'' and the first completion is ``firefox'' but you
267 really want to choose ``fire''. While you can type some spaces, this
268 keybinding is a more elegant way to change, at runtime, the behaviour
269 of the first completion.
270 .It Button1
271 Clicking on the prompt area closes mymenu, clicking on an item will
272 confirm it.
273 .It Button3
274 Clicking on the prompt area closes mymenu, clicking on an item will
275 confirm but keep looping (if enabled) the clicked item, like C-m
276 .It Button4,Button5 / scroll
277 Scroll through the completions (without changing the selection)
278 .El
279 .Sh EXIT STATUS
280 0 when the user select an entry, 1 when the user press Esc, EX_USAGE
281 if used with wrong flags and EX_UNAVAILABLE if the connection to X
282 fails.
283 .Sh EXAMPLES
284 .Bl -bullet -bullet
285 .It
286 Create a simple menu with a couple of entry
287 .Bd -literal -offset indent
288 cat <<EOF | $SHELL -c "$(mymenu -p "Exec: ")"
289 firefox
290 zzz
291 xcalc -stipple
292 xlock
293 gimp
294 EOF
295 .Ed
296 .It
297 Select and play a song from the current mpd playlist
298 .Bd -literal -offset indent
299 fmt="%position% %artist% - %title%"
300 if song=$(mpc playlist -f "$fmt" | mymenu -p "Song: " -A -d " "); then
301 mpc play $(echo $song | sed "s/ .*$//")
302 fi
303 .Ed
304 .El
306 .Sh SEE ALSO
307 .Xr dmenu 1
308 .Xr sysexits 3
310 .Sh AUTHORS
311 .An Omar Polo <omar.polo@europecom.net>
313 .Sh CAVEATS
314 .Bl -bullet
315 .It
316 If, instead of a numeric value, a not-valid number that terminates
317 with the % sign is supplied, then the default value for that field
318 will be treated as a percentage. Since this is a misuse of the
319 resources this behavior isn't strictly considered a bug.
320 .It
321 Keep in mind that sometimes the order of the options matter. First are
322 parsed (if any) the xrdb options, then the command line flags
323 .Sy in the provided order!
324 That meas that if you're providing first the x coordinate, let's say
325 "middle", and
326 .Sy after that
327 you are overriding the width, the window
328 .Sy will not be
329 centered.
331 As a general rule of thumb, if you're overriding the width and/or the
332 height of the window, remember to override the x and y coordinates as
333 well.
334 .It
335 Clicking past the last item will be equivalent to clicking the last item.
336 .El