logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

vis-menu.1 (6018B)


  1. .Dd November 29, 2016
  2. .Dt VIS-MENU 1
  3. .Os Vis v0.9
  4. .Sh NAME
  5. .Nm vis-menu
  6. .Nd Interactively select an item from a list
  7. .
  8. .Sh SYNOPSIS
  9. .Nm vis-menu
  10. .Op Fl i
  11. .Op Fl t | Fl b
  12. .Op Fl p Ar prompt
  13. .Op Fl l Ar lines
  14. .Op Ar initial
  15. .Nm vis-menu
  16. .Op Fl v
  17. .
  18. .Sh DESCRIPTION
  19. .Nm vis-menu
  20. allows a user to interactively select one item from a list of options.
  21. A newline-separated list of items is read from standard input,
  22. then the list of items is drawn directly onto the terminal
  23. so the user may select one.
  24. Finally,
  25. the selected item is printed to standard output.
  26. .Pp
  27. For information on actually navigating the menu,
  28. see
  29. .Sx USAGE
  30. below.
  31. .Bl -tag -width flag
  32. .It Fl i
  33. Use case-insensitive comparison when filtering items.
  34. .It Fl t | Fl b
  35. Normally,
  36. the menu is displayed on the current line of the terminal.
  37. When
  38. .Fl t
  39. is provided, the menu will always be drawn on the top line of the terminal.
  40. When
  41. .Fl b
  42. is provided, the menu will always be drawn on the bottom line.
  43. .It Fl p Ar prompt
  44. Display
  45. .Ar prompt
  46. before the list of items.
  47. .It Fl l Ar lines
  48. Normally,
  49. the list is displayed with all the items side-by-side on a single line,
  50. which is space-efficient
  51. but does not show many items at a time,
  52. especially if some of them are long.
  53. When
  54. .Fl l
  55. is provided,
  56. the list is displayed with each item on its own line,
  57. .Ar lines
  58. lines high.
  59. If there are more than
  60. .Ar lines
  61. items in the list,
  62. the user can scroll through them with the arrow keys,
  63. just like in the regular horizontal mode.
  64. .It Ar initial
  65. The user can type into a text field
  66. to filter the list of items
  67. as well as scrolling through them.
  68. If supplied,
  69. .Ar initial
  70. is used as the initial content of the text field.
  71. .It Fl v
  72. Instead of displaying an interactive menu,
  73. .Nm vis-menu
  74. prints its version number to standard output and exits.
  75. .El
  76. .
  77. .Sh USAGE
  78. .Nm vis-menu
  79. displays the prompt (if any),
  80. a text field,
  81. and a list of items.
  82. Normally these are presented side-by-side in a single line,
  83. but if the
  84. .Fl l
  85. flag is given,
  86. the prompt and typing area will be on the first line,
  87. and list items on the following lines.
  88. .Pp
  89. The following commands are available:
  90. .Bl -tag -width ".Sy Control-A"
  91. .It Sy Enter
  92. selects the currently-highlighted list item and exits.
  93. .It Xo Sy Control-\e
  94. or
  95. .Sy Control-\&]
  96. .Xc
  97. selects the current contents of the text field
  98. (even if it does not appear in the list)
  99. and exits.
  100. .It Xo Sy "ESC ESC"
  101. or
  102. .Sy Control-C
  103. .Xc
  104. exit without selecting any item.
  105. .It Xo Sy Down
  106. or
  107. .Sy Control-N
  108. .Xc
  109. scroll forward through the available list items.
  110. .It Xo Sy Up
  111. or
  112. .Sy Control-P
  113. .Xc
  114. scroll backward through the available list items.
  115. .It Xo Sy Right
  116. or
  117. .Sy Control-F
  118. .Xc
  119. move the cursor forward through the typed text,
  120. and scroll through the available list items.
  121. .It Xo Sy Left
  122. or
  123. .Sy Control-B
  124. .Xc
  125. move the cursor backward through the typed text,
  126. and scroll through the available list items.
  127. .It Xo Sy PageUp
  128. or
  129. .Sy Control-V
  130. .Xc
  131. scrolls to show the previous page of list items.
  132. .It Xo Sy PageDown
  133. or
  134. .Sy Meta-v
  135. .Xc
  136. scrolls to show the next page of list items.
  137. .It Xo Sy Home
  138. or
  139. .Sy Control-A
  140. .Xc
  141. move the cursor to the beginning of the text field
  142. or scroll to the first item in the list.
  143. .It Xo Sy End
  144. or
  145. .Sy Control-E
  146. .Xc
  147. move the cursor to the end of the text field
  148. or scroll to the last item in the list.
  149. .It Sy Meta-b
  150. moves the cursor to the beginning of the current word in the text field.
  151. .It Sy Meta-f
  152. moves the cursor past the end of the current word in the text field.
  153. .It Sy Tab
  154. copies the content of the selected list item into the text field.
  155. This is almost, but not quite, like tab completion.
  156. .It Xo Sy Delete
  157. or
  158. .Sy Control-D
  159. .Xc
  160. delete the character in the text field under the cursor.
  161. .It Sy Backspace
  162. deletes the character in the text field to the left of the cursor.
  163. .It Sy Meta-d
  164. deletes the characters in the text field
  165. from the character under the cursor
  166. to the next space.
  167. .It Sy Control-K
  168. deletes the characters in the text field
  169. from the character under the cursor to the end.
  170. .It Sy Control-U
  171. deletes the characters in the text field
  172. from the beginning up to
  173. (but not including)
  174. the character under the cursor.
  175. .It Sy Control-W
  176. deletes the characters in the text field
  177. from the previous space up to
  178. (but not including)
  179. the character under the cursor.
  180. .El
  181. .Pp
  182. All other non-control characters will be inserted into the text field
  183. at the current cursor position.
  184. .Pp
  185. When there is text in the text field,
  186. only list items that include the given text will be shown.
  187. If the text contains one or more spaces,
  188. each space-delimited string is a separate filter
  189. and only items matching every filter will be shown.
  190. .Pp
  191. If the user filters out all the items from the list,
  192. then hits Enter to select the
  193. .Dq currently highlighted
  194. item,
  195. the text they typed will be returned instead.
  196. .
  197. .Sh EXAMPLES
  198. Here's a shell-script that allows the user to choose a number from one to 10:
  199. .Bd -literal -offset indent
  200. NUMBER=$(seq 1 10 | vis-menu -p "Choose a number")
  201. if [ $? -eq 0 ]; then
  202. echo "You chose: $NUMBER"
  203. else
  204. echo "You refused to choose a number, or an error occurred."
  205. fi
  206. .Ed
  207. .
  208. .Sh DIAGNOSTICS
  209. The
  210. .Nm vis-menu
  211. utility exits 0 if the user successfully selected an item from the list,
  212. and 1 if the user cancelled.
  213. .Pp
  214. If an internal error occurs,
  215. the
  216. .Nm vis-menu
  217. utility prints a message to standard error and terminates with an exit
  218. status greater than 1.
  219. Potential error conditions include
  220. being unable to allocate memory,
  221. being unable to read from standard input,
  222. or being run without a controlling terminal.
  223. .
  224. .Sh SEE ALSO
  225. .Xr dmenu 1 ,
  226. .Xr slmenu 1 ,
  227. .Xr vis 1
  228. .
  229. .Sh HISTORY
  230. The original model for a single line menu reading items from standard input was
  231. .Xr dmenu 1
  232. which implements the idea for X11.
  233. .Nm dmenu
  234. is available from
  235. .Li http://tools.suckless.org/dmenu/
  236. .Pp
  237. The code was subsequently re-worked for ANSI terminal output as
  238. .Xr slmenu 1
  239. which is available from
  240. .Li https://bitbucket.org/rafaelgg/slmenu/
  241. .Pp
  242. Since
  243. .Nm slmenu
  244. did not appear to be maintained,
  245. it was forked to become
  246. .Nm vis-menu
  247. to be distributed with
  248. .Xr vis 1 .