added the -i option
[xmenu] / xmenu.1
CommitLineData
5a83c7dc 1.TH XMENU 1
08f16589 2.SH NAME
3xmenu \- menu utility for X
4.SH SYNOPSIS
5.B xmenu
71b4db92 6.RB [ \-iw ]
3bec05ea 7.RI [ title ]
08f16589 8.SH DESCRIPTION
9.B xmenu
10is a menu for X,
11it reads a list of newline-separated items from stdin,
12shows a menu for the user to select one of the items,
13and outputs the item selected to stdout.
14.PP
3bec05ea 15The options are as follows:
16.TP
71b4db92 17.B -i
18Disable icons.
19.B xmenu
20allocates a space at the left side of the menu for the icons;
21if there is no icon, then this space will be blank.
22Setting the
23.B -i
24option removes this space, making the menu narrower.
25.TP
3bec05ea 26.B -w
27Asks the window manager to draw a border around the menus.
71b4db92 28This option may be buggy in some window managers,
29specially tiled ones that do not respect window hints.
3bec05ea 30.PP
08f16589 31Each item read from stdin has the following format:
32.IP
33.EX
33376f54 34ITEM := [TABS] [[IMAGE TABS] LABEL [TABS OUTPUT]] NEWLINE
08f16589 35.EE
36.PP
6b5123e7 37That means that each item is composed by
33376f54 38tabs, followed by an optional image specification, followed by tabs
39followed by a label, followed by more tabs, followed by an output,
6b5123e7 40and ended by a newline. Brackets group optional elements.
08f16589 41.IP
42The initial tabs indicate the menu hierarchy:
43items indented with a tab is shown in a submenu of the preceding item not indented.
6b5123e7 44An item without initial tabs is a top-level item.
08f16589 45.IP
33376f54 46The image is a string of the form "IMG:/path/to/image.png".
47It specifies a image to be shown as icon at the left of the entry.
48.IP
08f16589 49The label is the string that will be shown as a item in the menu.
50An item without label is considered a separator and is drawn as a thin line in the menu
51separating the item above from the item below.
52.IP
6b5123e7 53The output is the string that will be output after selecting the item.
54If an item does not have an output, its label is used as its output.
08f16589 55.IP
56The newline terminates the item specification.
3bec05ea 57.PP
58If the argument
59.I title
60is given, the title of the menu window is set to it.
858338d9 61.SH USAGE
62.B xmenu
63is controlled by the mouse,
64but can also be controlled by the keyboard.
65Items can be selected using the arrow keys,
66Tab (with and without Shift),
67Enter and Esc.
68.TP
69.BR Down ", " Tab
70Cycle through the items in the regular direction.
71.TP
72.BR Up ", " Shift-Tab
73Cycle through the items in the reverse direction.
74.TP
75.BR Right ", " Enter
76Select the highlighted item.
77.TP
78.B Left
79Go to the menu above.
80.TP
81.B Esc
82Go to the menu above or exit xmenu.
f644b8bc 83.SH RESOURCES
84.B
85xmenu
86understands the following X resources.
87.TP
88.B xmenu.font
89The font in which the labels should be drawn.
90.TP
91.B xmenu.background
5a83c7dc 92The background color of non-selected items in the menu.
f644b8bc 93.TP
94.B xmenu.foreground
5a83c7dc 95The color of the label text of non-selected items in the menu.
f644b8bc 96.TP
97.B xmenu.selbackground
5a83c7dc 98The background color of selected items in the menu.
f644b8bc 99.TP
100.B xmenu.selforeground
5a83c7dc 101The color of the label text of selected items in the menu.
f644b8bc 102.TP
103.B xmenu.border
104The color of the border around the menu.
105.TP
106.B xmenu.separator
5a83c7dc 107The color of the separator between items in the menu.
f644b8bc 108.TP
92e7609b 109.B xmenu.gap
110The gap, in pixels, between the menus.
111.TP
f644b8bc 112.B xmenu.width
113The minimum width, in pixels, of the items in the menu.
114.TP
685ca30d 115.B xmenu.height
116The size in pixels of the height of a single menu item.
f644b8bc 117.TP
fd530f3f 118.B xmenu.borderWidth
f644b8bc 119The size in pixels of the border around the menu.
120.TP
fd530f3f 121.B xmenu.separatorWidth
f644b8bc 122The size in pixels of the item separator.
123
08f16589 124.SH EXAMPLES
d584fba6 125The following script illustrates the use of
08f16589 126.BR xmenu .
c49dad28 127The output is redirected to
128.IR sh (1),
129creating a command to be run by the shell.
08f16589 130.IP
131.EX
132#!/bin/sh
133
6b5123e7 134cat <<EOF | xmenu | sh &
08f16589 135Applications
33376f54 136 IMG:./web.png Web Browser firefox
d584fba6 137 IMG:./gimp.png Image editor gimp
33376f54 138Terminal (xterm) xterm
139Terminal (urxvt) urxvt
140Terminal (st) st
08f16589 141
33376f54 142Shutdown poweroff
143Reboot reboot
08f16589 144EOF
145.EE
146.PP
147For example, by selecting \(lqApplications\(rq, a new menu will appear.
d584fba6 148Selecting \(lqWeb Browser\(rq in the new menu opens firefox.
08f16589 149.SH SEE ALSO
150.IR dmenu (1),
151.IR 9menu (1),
152.IR thingmenu (1)