1VIS-MENU(1)               BSD General Commands Manual              VIS-MENU(1)
2

NAME

4     vis-menu — Interactively select an item from a list
5

SYNOPSIS

7     vis-menu [-i] [-t | -b] [-p prompt] [-l lines] [initial]
8     vis-menu [-v]
9

DESCRIPTION

11     vis-menu allows a user to interactively select one item from a list of
12     options.  A newline-separated list of items is read from standard input,
13     then the list of items is drawn directly onto the terminal so the user
14     may select one.  Finally, the selected item is printed to standard out‐
15     put.
16
17     For information on actually navigating the menu, see USAGE below.
18
19     -i    Use case-insensitive comparison when filtering items.
20
21     -t | -b
22           Normally, the menu is displayed on the current line of the termi‐
23           nal.  When -t is provided, the menu will always be drawn on the top
24           line of the terminal.  When -b is provided, the menu will always be
25           drawn on the bottom line.
26
27     -p prompt
28           Display prompt before the list of items.
29
30     -l lines
31           Normally, the list is displayed with all the items side-by-side on
32           a single line, which is space-efficient but does not show many
33           items at a time, especially if some of them are long.  When -l is
34           provided, the list is displayed with each item on its own line,
35           lines lines high.  If there are more than lines items in the list,
36           the user can scroll through them with the arrow keys, just like in
37           the regular horizontal mode.
38
39     initial
40           The user can type into a text field to filter the list of items as
41           well as scrolling through them.  If supplied, initial is used as
42           the initial content of the text field.
43
44     -v    Instead of displaying an interactive menu, vis-menu prints its ver‐
45           sion number to standard output and exits.
46

USAGE

48     vis-menu displays the prompt (if any), a text field, and a list of items.
49     Normally these are presented side-by-side in a single line, but if the -l
50     flag is given, the prompt and typing area will be on the first line, and
51     list items on the following lines.
52
53     The following commands are available:
54
55     Enter      selects the currently-highlighted list item and exits.
56
57     Control-\ or Control-]
58                selects the current contents of the text field (even if it
59                does not appear in the list) and exits.
60
61     ESC ESC or Control-C
62                exit without selecting any item.
63
64     Down or Control-N
65                scroll forward through the available list items.
66
67     Up or Control-P
68                scroll backward through the available list items.
69
70     Right or Control-F
71                move the cursor forward through the typed text, and scroll
72                through the available list items.
73
74     Left or Control-B
75                move the cursor backward through the typed text, and scroll
76                through the available list items.
77
78     PageUp or Control-V
79                scrolls to show the previous page of list items.
80
81     PageDown or Meta-v
82                scrolls to show the next page of list items.
83
84     Home or Control-A
85                move the cursor to the beginning of the text field or scroll
86                to the first item in the list.
87
88     End or Control-E
89                move the cursor to the end of the text field or scroll to the
90                last item in the list.
91
92     Meta-b     moves the cursor to the beginning of the current word in the
93                text field.
94
95     Meta-f     moves the cursor past the end of the current word in the text
96                field.
97
98     Tab        copies the content of the selected list item into the text
99                field.  This is almost, but not quite, like tab completion.
100
101     Delete or Control-D
102                delete the character in the text field under the cursor.
103
104     Backspace  deletes the character in the text field to the left of the
105                cursor.
106
107     Meta-d     deletes the characters in the text field from the character
108                under the cursor to the next space.
109
110     Control-K  deletes the characters in the text field from the character
111                under the cursor to the end.
112
113     Control-U  deletes the characters in the text field from the beginning up
114                to (but not including) the character under the cursor.
115
116     Control-W  deletes the characters in the text field from the previous
117                space up to (but not including) the character under the cur‐
118                sor.
119
120     All other non-control characters will be inserted into the text field at
121     the current cursor position.
122
123     When there is text in the text field, only list items that include the
124     given text will be shown.  If the text contains one or more spaces, each
125     space-delimited string is a separate filter and only items matching every
126     filter will be shown.
127
128     If the user filters out all the items from the list, then hits Enter to
129     select the “currently highlighted” item, the text they typed will be
130     returned instead.
131

EXAMPLES

133     Here's a shell-script that allows the user to choose a number from one to
134     10:
135
136           NUMBER=$(seq 1 10 | vis-menu -p "Choose a number")
137           if [ $? -eq 0 ]; then
138                   echo "You chose: $NUMBER"
139           else
140                   echo "You refused to choose a number, or an error occurred."
141           fi
142

DIAGNOSTICS

144     The vis-menu utility exits 0 if the user successfully selected an item
145     from the list, and 1 if the user cancelled.
146
147     If an internal error occurs, the vis-menu utility prints a message to
148     standard error and terminates with an exit status greater than 1.  Poten‐
149     tial error conditions include being unable to allocate memory, being
150     unable to read from standard input, or being run without a controlling
151     terminal.
152

SEE ALSO

154     dmenu(1), slmenu(1), vis(1)
155

HISTORY

157     The original model for a single line menu reading items from standard
158     input was dmenu(1) which implements the idea for X11.  dmenu is available
159     from http://tools.suckless.org/dmenu/
160
161     The code was subsequently re-worked for ANSI terminal output as slmenu(1)
162     which is available from https://bitbucket.org/rafaelgg/slmenu/
163
164     Since slmenu did not appear to be maintained, it was forked to become
165     vis-menu to be distributed with vis(1).
166
167Vis v0.7                       November 29, 2016                      Vis v0.7
Impressum