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