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
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 .El
171 .It MyMenu.y
172 The Y coordinate of the topmost left corner of the window. Like the X
173 coordinate a pixel dimension, percentage dimension or the special
174 value "start", "middle", "end" could be supplied.
175 .It MyMenu.border.size
176 A list of number separated by spaces to specify the border of the
177 window. The field is parsed like some CSS properties (i.e. padding),
178 that is: if only one value is provided then it'll be used for all
179 borders; if two value are given than the first will be used for the
180 top and bottom border and the former for the left and right border;
181 with three value the first is used for the top border, the second for
182 the left and right border and the third for the bottom border. If four
183 value are given, they'll be applied to the respective border
184 clockwise. Other values will be ignored. The default value is 0.
186 This particular option accepts a percentage (e.g. 10%) relative to the
187 screen width.
188 .It MyMenu.border.color
189 A list of colors for the borders. This field is parsed like the
190 MyMenu.border.size. The default value is black.
191 .It MyMenu.prompt.background
192 The background of the prompt.
193 .It MyMenu.prompt.foreground
194 The text color (foreground) of the prompt.
195 .It MyMenu.completion.background
196 The background of the completions.
197 .It MyMenu.completion.foreground
198 The text color of the completions.
199 .It MyMenu.completion.border.size
200 Parsed like MyMenu.border.size, but affects only the
201 completion. Default to 0.
202 .It MyMenu.completion.border.color
203 Parsed like MyMenu.border.color, but affects only the
204 completion. Default to #000 (black).
205 .It MyMenu.completion.padding
206 Parsed like MyMenu.prompt.padding. Default to 10.
207 .It MyMenu.completion_highlighted.background
208 The background of the selected completion.
209 .It MyMenu.completion_highlighted.foreground
210 The foreground of the selected completion.
211 .It MyMenu.completion_highlighted.border.size
212 Parsed like MyMenu.border.size, but affects only the completion
213 highlighted. Default to 0.
214 .It MyMenu.completion_highlighted.border.color
215 Parsed like MyMenu.border.color, but affects only the completion
216 highlighted. Default to #000 (black).
217 .It MyMenu.completion_highlighted.padding
218 Parsed like MyMenu.prompt.padding. Default to 10.
219 .El
220 .Sh COLORS
221 MyMenu accept colors only in the form of:
222 .Bl -bullet
223 .It
224 #rgb
225 .It
226 #rrggbb
227 .It
228 #aarrggbb
229 .El
231 The opacity is assumed 0xff (no transparency) if not provided.
232 .Sh KEYS
233 This is the list of keybinding recognized by
234 .Li Nm Ns .
235 In the following examples, C-c means Control-c.
236 .Bl -tag -width indent-two
237 .It Esc
238 Close the menu without selecting any entry
239 .It C-c
240 The same as Esc
241 .It Enter
242 Close the menu and print to stdout what the user typed
243 .It C-m
244 Confirm but keep looping (if enabled), otherwise complete only
245 .It Tab
246 Expand the prompt to the next possible completion
247 .It Shift Tab
248 Expand the prompt to the previous possible completion
249 .It C-n
250 The same as Tab
251 .It C-p
252 The same as Shift-Tab
253 .It Backspace
254 Delete the last character
255 .It C-h
256 The same as Backspace
257 .It C-w
258 Delete the last word
259 .It C-u
260 Delete the whole line
261 .It C-i
262 Toggle the ``first selected'' style. Sometimes, especially with the -a
263 option, could be handy to disable that behaviour. Let's say that
264 you've typed ``fire'' and the first completion is ``firefox'' but you
265 really want to choose ``fire''. While you can type some spaces, this
266 keybinding is a more elegant way to change, at runtime, the behaviour
267 of the first completion.
268 .El
269 .Sh EXIT STATUS
270 0 when the user select an entry, 1 when the user press Esc, EX_USAGE
271 if used with wrong flags and EX_UNAVAILABLE if the connection to X
272 fails.
273 .Sh EXAMPLES
274 .Bl -bullet -bullet
275 .It
276 Create a simple menu with a couple of entry
277 .Bd -literal -offset indent
278 cat <<EOF | $SHELL -c "$(mymenu -p "Exec: ")"
279 firefox
280 zzz
281 xcalc -stipple
282 xlock
283 gimp
284 EOF
285 .Ed
286 .It
287 Select and play a song from the current mpd playlist
288 .Bd -literal -offset indent
289 fmt="%position% %artist% - %title%"
290 if song=$(mpc playlist -f "$fmt" | mymenu -p "Song: " -A -d " "); then
291 mpc play $(echo $song | sed "s/ .*$//")
292 fi
293 .Ed
294 .El
296 .Sh SEE ALSO
297 .Xr dmenu 1
298 .Xr sysexits 3
300 .Sh AUTHORS
301 .An Omar Polo <omar.polo@europecom.net>
303 .Sh CAVEATS
304 .Bl -bullet
305 .It
306 If, instead of a numeric value, a not-valid number that terminates
307 with the % sign is supplied, then the default value for that field
308 will be treated as a percentage. Since this is a misuse of the
309 resources this behavior isn't strictly considered a bug.
310 .It
311 Keep in mind that sometimes the order of the options matter. First are
312 parsed (if any) the xrdb options, then the command line flags
313 .Sy in the provided order!
314 That meas that if you're providing first the x coordinate, let's say
315 "middle", and
316 .Sy after that
317 you are overriding the width, the window
318 .Sy will not be
319 centered.
321 As a general rule of thumb, if you're overriding the width and/or the
322 height of the window, remember to override the x and y coordinates as
323 well.
324 .El