| ijmenu 1.1 |
ijmenu - minimalist scrollable menu for shell scripts
ijmenu CURSOR PAGE_SIZE PAGE_TOP ITEM [ITEM ...]
ijmenu -n CURSOR PAGE_SIZE PAGE_TOP ITEM [ITEM ...]
ijmenu -v
# Examples
ijmenu 0 0 0 zero one two three four five six seven
# initially displayed items and [cursor]:
# [zero], one, two, three, four
ijmenu 6 3 5 zero one two three four five six seven
# five, [six], seven
ijmenu -2 3 -3 zero one two three four five six seven
# the same: args #1 and #3 wrap once if < 0
# it is best to check the exit code, e.g. (bash):
choice=$( ijmenu 0 0 0 "(1) uno" "(2) due" "(3) tre" )
if [ "$?" -ne 0 ]; then choice=; fi
# multiple selection, implemented using numeric mode (-n)
unset fruit
for x in apple cherry grape lime mango orange plum; do
fruit[${#fruit[@]}]=" $x";
done
nums="0 0 0"
echo "Press Enter to select/unselect items, Q to finish."
while nums=`ijmenu -n $nums "${fruit[@]}"`; do
n=${nums%% *}
fruit[$n]=`echo "${fruit[$n]}"|sed 's/^\*/ /;t;s/^ /*/'`
done
echo "You chose these items:"
for o in "${fruit[@]}"; do echo "$o"|sed -n 's/^\* //p'; doneThe initial cursor position, 0 for the first menu item. A negative number counts from the end, starting with -1 for the last item. A number outside the range [-(num items) .. (num items)-1] will be changed to the first (if negative) or last item.
The scrollable page size, that is, the number of menu items visible at any time. Automatically reduced for a smaller screen or fewer items. Specify 0 and ijmenu will choose a page size for you (see "Automatic page sizing" below).
The first visible item in the initially displayed page, numbered in the same way as the first argument. This will be adjusted if out of range or if necessary to ensure the cursor is positioned at a visible item.
The fourth and subsequent arguments are the menu items. These should not contain newlines, tabs, or other special characters.
ijmenu displays a scrollable menu in an xterm or similar terminal emulator. Compared to alternatives like whiptail, it takes a simple, minimalist approach: by default, it uses only a few lines of the screen, and it does not display a scroll bar (for an indicator of relative list position, numbering the menu items is an effective alternative to a scroll bar).
All navigation functions are accessible by alphabetic keys in addition to the usual cursor movement keys, and the item at the cursor is selected by pressing either Enter or the space bar:
i/j = Up/Down I/J = PgUp/PgDn k = i
a|h = Home z|l = End q = Esc EnterThe scrolling menu is displayed via standard error.
Normally, the text of the selected item is written to standard output. If nothing is selected, there is no output (though in the event of an error this is not guaranteed, so it is best to check the exit code).
However, in numeric mode, enabled with the '-n' option, ijmenu instead outputs its last state, that is, the new values corresponding to the three numbers passed to it: the index of the cursor, the page size, and the index of the first visible item. In numeric mode, it does this even if the user presses Esc instead of Enter, so the exit code must be checked.
Exit code: this is 0 if a selection is made or if the version number is output ('-v' option). If the user presses Q or Esc to quit without selecting an item then the exit code is 66. In the event of an error, the exit code is non-zero.
If you specify 0 for the page size then ijmenu will choose an optimal page size for you. For shorter lists, the scrollable window shows 5 items. For longer lists, this number increases to roughly the square root of the list length: to a good approximation, this minimizes the average number of key presses needed to move the cursor to a given item (you might want to think about why this is so); it also means that the number of visible items can provide an indication of the overall list length - and over a greater range than a linear scale.
Revision 1.1 added the '-n' option, allowed the use of the space bar to select an item, and changed the exit codes (ijmenu 1.0 was publicly available only briefly, so invoking code should not need to allow for this).
The program assumes escape sequences as used by different flavours of xterm, rxvt, and related vt100-type terminal emulators. No particular effort is made at universal compatibility.
The help text which appears when an unrecognized key is pressed may also appear if keys are pressed faster than they can be processed.
Copyright 2011 Michael Breen. This is free software WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Licensed under the GNU General Public License version 3 (see http://www.gnu.org/licenses/).
dialog(1), whiptail(1).
Updates: http://mbreen.com/ij.html
| ijmenu 1.1 |