1VIS-MENU(1) BSD General Commands Manual VIS-MENU(1)
2
4 vis-menu — Interactively select an item from a list
5
7 vis-menu [-i] [-t | -b] [-p prompt] [-l lines] [initial]
8 vis-menu [-v]
9
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 For information on actually navigating the menu, see USAGE below.
18 -i Use case-insensitive comparison when filtering items.
20 -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 -p prompt
28 Display prompt before the list of items.
29 -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 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 -v Instead of displaying an interactive menu, vis-menu prints its ver‐
45 sion number to standard output and exits.
46
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 The following commands are available:
54 Enter selects the currently-highlighted list item and exits.
56 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 ESC ESC or Control-C
62 exit without selecting any item.
63 Down or Control-N
65 scroll forward through the available list items.
66 Up or Control-P
68 scroll backward through the available list items.
69 Right or Control-F
71 move the cursor forward through the typed text, and scroll
72 through the available list items.
73 Left or Control-B
75 move the cursor backward through the typed text, and scroll
76 through the available list items.
77 PageUp or Control-V
79 scrolls to show the previous page of list items.
80 PageDown or Meta-v
82 scrolls to show the next page of list items.
83 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 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 Meta-b moves the cursor to the beginning of the current word in the
93 text field.
94 Meta-f moves the cursor past the end of the current word in the text
96 field.
97 Tab copies the content of the selected list item into the text
99 field. This is almost, but not quite, like tab completion.
100 Delete or Control-D
102 delete the character in the text field under the cursor.
103 Backspace deletes the character in the text field to the left of the
105 cursor.
106 Meta-d deletes the characters in the text field from the character
108 under the cursor to the next space.
109 Control-K deletes the characters in the text field from the character
111 under the cursor to the end.
112 Control-U deletes the characters in the text field from the beginning up
114 to (but not including) the character under the cursor.
115 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 All other non-control characters will be inserted into the text field at
121 the current cursor position.
122 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 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
133 Here's a shell-script that allows the user to choose a number from one to
134 10:
135 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
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 If an internal error occurs, the vis-menu utility prints a message to
148 standard error and exits 1. Potential error conditions include being
149 unable to allocate memory, being unable to read from standard input, or
150 being run without a controlling terminal.
151
153 dmenu(1), slmenu(1), vis(1)
154
156 The original model for a single line menu reading items from standard
157 input was dmenu(1) which implements the idea for X11. dmenu is available
158 from http://tools.suckless.org/dmenu/
159 The code was subsequently re-worked for ANSI terminal output as slmenu(1)
161 which is available from https://bitbucket.org/rafaelgg/slmenu/
162 Since slmenu did not appear to be maintained, it was forked to become
164 vis-menu to be distributed with vis(1).
165Vis v0.5 November 29, 2016 Vis v0.5