Commit | Line | Data |
---|---|---|
5a83c7dc | 1 | .TH XMENU 1 |
08f16589 | 2 | .SH NAME |
3 | xmenu \- menu utility for X | |
4 | .SH SYNOPSIS | |
5 | .B xmenu | |
78fb523f | 6 | .RB [ \-irw ] |
05cfe1a0 | 7 | .RB [ -p |
8 | .IR position ] | |
288a35e5 LS |
9 | .RB [ -x|-X |
10 | .RI [ modifier- ] button ] | |
3bec05ea | 11 | .RI [ title ] |
08f16589 | 12 | .SH DESCRIPTION |
13 | .B xmenu | |
14 | is a menu for X, | |
15 | it reads a list of newline-separated items from stdin, | |
16 | shows a menu for the user to select one of the items, | |
17 | and outputs the item selected to stdout. | |
18 | .PP | |
3bec05ea | 19 | The options are as follows: |
20 | .TP | |
71b4db92 | 21 | .B -i |
22 | Disable icons. | |
7832d2cf | 23 | This makes xmenu loading faster when not using icons. |
71b4db92 | 24 | .TP |
05cfe1a0 | 25 | .BI -p " position" |
26 | Set the position to spawn xmenu. | |
27 | Without this option, xmenu spawns next to the cursor. | |
28 | .I position | |
29 | is a string of the form | |
237da982 | 30 | .BR INTxINT[:MONITOR] , |
05cfe1a0 | 31 | where the first INT is the x position and the second INT is the y position. |
237da982 | 32 | The monitor part between brackets is optional. |
33 | .B MONITOR | |
34 | can be a number from 0 to the number of monitors minus 1; | |
35 | or it can be a string like | |
36 | .B current | |
37 | or | |
38 | .BR cursor . | |
39 | If present, the monitor specifies that the position is relative to the upper left corner | |
40 | of that monitor. | |
41 | If | |
42 | .B monitor | |
43 | is | |
44 | .B current | |
45 | or | |
46 | .BR cursor , | |
47 | the monitor to be used is that where the cursor is in. | |
48 | For example, | |
49 | .B -p 0x0:cursor | |
50 | specifies that | |
51 | .B xmenu | |
52 | must spawn at the position 0x0 of the monitor where the cursor is in. | |
53 | And | |
54 | .B -p 100x500:0 | |
55 | specifies that | |
56 | .B xmenu | |
57 | must spawn at the position 100x500 of the monitor 0. | |
05cfe1a0 | 58 | .TP |
1146fd81 | 59 | .B -r |
60 | If this option is set, the right mouse button is disabled; | |
61 | so pressing it will not trigger any menu item. | |
62 | .TP | |
3bec05ea | 63 | .B -w |
64 | Asks the window manager to draw a border around the menus. | |
71b4db92 | 65 | This option may be buggy in some window managers, |
66 | specially tiled ones that do not respect window hints. | |
45b2e22f | 67 | .TP |
68 | \fB\-x\fP [\fImod\fP-]\fIbutton\fP | |
69 | This option requires an argument of the form | |
70 | \fImod\fP-\fIbutton\fP or \fIbutton\fP; where | |
71 | .I mod | |
72 | is | |
73 | .B Mod1 | |
74 | to | |
75 | .BR Mod5 , | |
76 | or | |
77 | .B Alt | |
78 | (equivalent to | |
79 | .BR Mod1 ), | |
80 | or | |
81 | .B Super | |
82 | (equivalent to | |
83 | .BR Mod4 ); | |
84 | and | |
85 | .I button | |
86 | is the number of a mouse button. | |
87 | When this option is used, | |
6ec87501 | 88 | .B xmenu |
45b2e22f | 89 | listens to button presses on the root window, |
90 | and shows the pie menu when the given button is pressed, | |
91 | together with the given modifier, | |
92 | on the root window. | |
93 | For example, invoking | |
6ec87501 | 94 | .B xmenu |
45b2e22f | 95 | with the option |
96 | .B -x Super-3 | |
97 | makes a menu open when clicking with the third mouse button on the root window, | |
98 | or when clicking with the third mouse button together with the Super (Mod4) modifier on any window. | |
99 | This option makes | |
6ec87501 | 100 | .B xmenu |
45b2e22f | 101 | run continuously; |
102 | so it should be used when | |
6ec87501 | 103 | .B xmenu |
45b2e22f | 104 | is invoked in background on a X startup file (like |
105 | .BR "~/.xinitrc" ). | |
106 | .TP | |
107 | \fB\-X\fP [\fImod\fP-]\fIbutton\fP | |
108 | Just like | |
109 | .BR \-x , | |
110 | but also pass the click to the root window | |
111 | (for the window manager to use it, for example). | |
112 | This option is incompatible with | |
113 | .BR \-x . | |
3bec05ea | 114 | .PP |
08f16589 | 115 | Each item read from stdin has the following format: |
116 | .IP | |
117 | .EX | |
33376f54 | 118 | ITEM := [TABS] [[IMAGE TABS] LABEL [TABS OUTPUT]] NEWLINE |
08f16589 | 119 | .EE |
120 | .PP | |
6b5123e7 | 121 | That means that each item is composed by |
33376f54 | 122 | tabs, followed by an optional image specification, followed by tabs |
123 | followed by a label, followed by more tabs, followed by an output, | |
6b5123e7 | 124 | and ended by a newline. Brackets group optional elements. |
08f16589 | 125 | .IP |
126 | The initial tabs indicate the menu hierarchy: | |
127 | items indented with a tab is shown in a submenu of the preceding item not indented. | |
6b5123e7 | 128 | An item without initial tabs is a top-level item. |
08f16589 | 129 | .IP |
33376f54 | 130 | The image is a string of the form "IMG:/path/to/image.png". |
523b3d5e | 131 | It specifies the path to a image file to be shown as icon at the left of the entry. |
132 | If the path does not begin with "/", "./" or "../", | |
133 | the file is searched on the paths specified in the | |
134 | .B ICONPATH | |
135 | environment variable. | |
33376f54 | 136 | .IP |
08f16589 | 137 | The label is the string that will be shown as a item in the menu. |
138 | An item without label is considered a separator and is drawn as a thin line in the menu | |
139 | separating the item above from the item below. | |
140 | .IP | |
6b5123e7 | 141 | The output is the string that will be output after selecting the item. |
142 | If an item does not have an output, its label is used as its output. | |
08f16589 | 143 | .IP |
144 | The newline terminates the item specification. | |
3bec05ea | 145 | .PP |
146 | If the argument | |
147 | .I title | |
148 | is given, the title of the menu window is set to it. | |
858338d9 | 149 | .SH USAGE |
150 | .B xmenu | |
151 | is controlled by the mouse, | |
152 | but can also be controlled by the keyboard. | |
153 | Items can be selected using the arrow keys, | |
154 | Tab (with and without Shift), | |
45115feb | 155 | Home, End, |
2b0484b1 | 156 | Enter and Esc, and 1-9 keys. |
78fb523f | 157 | Items can also be selected by typing the first several characters in it. |
858338d9 | 158 | .TP |
45115feb | 159 | .BR Home |
160 | Select the first item in the menu. | |
161 | .TP | |
162 | .BR End | |
163 | Select the last item in the menu. | |
164 | .TP | |
28f784a7 | 165 | .BR Down |
166 | Cycle through the items in the regular direction. | |
167 | .TP | |
168 | .BR Tab | |
858338d9 | 169 | Cycle through the items in the regular direction. |
78fb523f | 170 | When the type\-to\-select feature is active, cycle through matching items instead. |
28f784a7 | 171 | .TP |
172 | .BR Up | |
173 | Cycle through the items in the reverse direction. | |
858338d9 | 174 | .TP |
28f784a7 | 175 | .BR Shift-Tab |
858338d9 | 176 | Cycle through the items in the reverse direction. |
78fb523f | 177 | When the type\-to\-select feature is active, cycle through matching items instead. |
858338d9 | 178 | .TP |
179 | .BR Right ", " Enter | |
180 | Select the highlighted item. | |
181 | .TP | |
182 | .B Left | |
183 | Go to the menu above. | |
184 | .TP | |
185 | .B Esc | |
186 | Go to the menu above or exit xmenu. | |
45115feb | 187 | .PP |
78fb523f | 188 | .B xmenu |
189 | features the type\-to\-select selecting style, | |
190 | where typing a string will select the first item matching it. | |
191 | .PP | |
45115feb | 192 | Additional key bindings can be set at compile time by changing the |
193 | .B config.h | |
194 | file. | |
f644b8bc | 195 | .SH RESOURCES |
196 | .B | |
197 | xmenu | |
198 | understands the following X resources. | |
199 | .TP | |
200 | .B xmenu.font | |
201 | The font in which the labels should be drawn. | |
cdeaefaa | 202 | Multiple fonts can be added as fallback fonts; |
203 | they must be separated by a comma. | |
f644b8bc | 204 | .TP |
205 | .B xmenu.background | |
5a83c7dc | 206 | The background color of non-selected items in the menu. |
f644b8bc | 207 | .TP |
208 | .B xmenu.foreground | |
5a83c7dc | 209 | The color of the label text of non-selected items in the menu. |
f644b8bc | 210 | .TP |
211 | .B xmenu.selbackground | |
5a83c7dc | 212 | The background color of selected items in the menu. |
f644b8bc | 213 | .TP |
214 | .B xmenu.selforeground | |
5a83c7dc | 215 | The color of the label text of selected items in the menu. |
f644b8bc | 216 | .TP |
217 | .B xmenu.border | |
218 | The color of the border around the menu. | |
219 | .TP | |
220 | .B xmenu.separator | |
5a83c7dc | 221 | The color of the separator between items in the menu. |
f644b8bc | 222 | .TP |
92e7609b | 223 | .B xmenu.gap |
224 | The gap, in pixels, between the menus. | |
225 | .TP | |
f644b8bc | 226 | .B xmenu.width |
227 | The minimum width, in pixels, of the items in the menu. | |
228 | .TP | |
685ca30d | 229 | .B xmenu.height |
230 | The size in pixels of the height of a single menu item. | |
f644b8bc | 231 | .TP |
fd530f3f | 232 | .B xmenu.borderWidth |
f644b8bc | 233 | The size in pixels of the border around the menu. |
234 | .TP | |
fd530f3f | 235 | .B xmenu.separatorWidth |
f644b8bc | 236 | The size in pixels of the item separator. |
27c03246 | 237 | .TP |
238 | .B xmenu.alignment | |
239 | If set to | |
240 | .BR "\(dqleft\(dq" , | |
241 | .BR "\(dqcenter\(dq" , | |
242 | or | |
243 | .BR "\(dqright\(dq" , | |
244 | text is aligned to the left, center, or right of the menu, respectively. | |
245 | By default, text is aligned to the left. | |
523b3d5e | 246 | .TP |
247 | .B xmenu.maxItems | |
248 | Maximum number of items to be displayed in a menu. | |
249 | If more a menu has more than this number of items, | |
250 | they will be scrolled with arrow buttons. | |
251 | .SH ENVIRONMENT | |
252 | The following environment variables affect the execution of | |
6ec87501 | 253 | .BR xmenu . |
523b3d5e | 254 | .TP |
255 | .B DISPLAY | |
256 | The display to start | |
6ec87501 | 257 | .B xmenu |
523b3d5e | 258 | on. |
259 | .TP | |
260 | .B ICONPATH | |
261 | A colon-separated list of directories used to search for the location of image files. | |
08f16589 | 262 | .SH EXAMPLES |
d584fba6 | 263 | The following script illustrates the use of |
08f16589 | 264 | .BR xmenu . |
c49dad28 | 265 | The output is redirected to |
266 | .IR sh (1), | |
267 | creating a command to be run by the shell. | |
08f16589 | 268 | .IP |
269 | .EX | |
270 | #!/bin/sh | |
271 | ||
6aee4109 | 272 | xmenu <<EOF | sh & |
08f16589 | 273 | Applications |
33376f54 | 274 | IMG:./web.png Web Browser firefox |
d584fba6 | 275 | IMG:./gimp.png Image editor gimp |
33376f54 | 276 | Terminal (xterm) xterm |
277 | Terminal (urxvt) urxvt | |
278 | Terminal (st) st | |
08f16589 | 279 | |
33376f54 | 280 | Shutdown poweroff |
281 | Reboot reboot | |
08f16589 | 282 | EOF |
283 | .EE | |
284 | .PP | |
285 | For example, by selecting \(lqApplications\(rq, a new menu will appear. | |
d584fba6 | 286 | Selecting \(lqWeb Browser\(rq in the new menu opens firefox. |
08f16589 | 287 | .SH SEE ALSO |
288 | .IR dmenu (1), | |
289 | .IR 9menu (1), | |
290 | .IR thingmenu (1) |