pop-up-lettered-menu

Arguments: strings &key sortp sort-predicate sort-key on-print

Calls pop-up-menu to display a list of choices, returning the choice selected by the user. The added feature of this function is that it prepends consecutive letters of the alphabet to the displayed menu-item strings to allow the user to quickly choose an item with the keyboard. If there are no more than 26 choices in the menu, then any choice may be made by typing the single shortcut letter displayed at the left end of the menu-item. If there are more than 26 choices, then multiple menu-items will share shortcut letters, and the user may need to type a shortcut letter multiple times until the desired item is highlighted, and then press the ENTER key to choose the highlighted item.

strings should be a list of strings and/or symbols to display in the menu from top to bottom. Shortcut letters are prepended to the displayed strings automatically. A list member may be the symbol menu-separator or its global value to insert a horizontal separator line into the menu at that position; this is suitable only when sortp is nil.

sortp, if specified, should be either true or nil. If true, then the items in the strings list will first be sorted by the sort-predicate function before being displayed. The default value is t, so :sortp nil should be specified to avoid sorting the items.

sort-predicate, if specified, should be a funcallable object (a function object or function name). The default value is the function string<. The function should take two arguments, as with the predicate argument to sort. If sortp is true, then the items in the strings list will be sorted by this function.

sort-key, if specified, should be a funcallable object (a function object or function name) or nil. The default value is nil, which acts as if the identity function were specified. The function should take one argument, as with the key argument to sort. If sortp is true, then the items will be passed to this function and the returned values will be compared with sort-predicate.

on-print, if specified, should be either nil, a function object, or a function name. The default value is nil. If nil, strings in the strings argument will appear as if printed by princ, and symbols will appear as if printed by prin1. If a function, the function should take a single argument, which is an item from the strings list, and all items will appear as if printed by the on-print function. Note that the sort, if done at all, is done on the actual items in the strings list rather than on the strings returned by the on-print function.

This function returns the item from the strings list that was chosen by the user, or nil if the user cancels from the menu by pressing the ESCAPE key or clicking off the menu.

Multiprocessing note: The keyboard shortcuts for a pop-up menu will work only if the window that had the keyboard focus at the time pop-up-menu was called was created by the process that is calling pop-up-lettered-menu. Otherwise the keystrokes will go to the focused window in the other process. For example, the keyboard shortcuts will not work when evaluating a call to pop-up-lettered-menu directly in the initial IDE listener pane, because the IDE will evaluate the expression in the Listener 1 process, though the currently focused window (the listener pane) was created in the IDE GUI process.

An alternative way to ask the user for a choice from a list is to call ask-user-for-choice-from-list. This function may be better when the list of choices is large, as it uses a scrolling single-item-list or multi-item-list. For four choices or fewer, ask-user-for-choice may be used.

Examples:

(pop-up-lettered-menu (list "one" "two" "three") :sortp nil)

displays a menu

a one
b two
c three

while

(pop-up-lettered-menu (list "one" "two" "three") :sortp t)

displays a menu with the entries alphabetical:

a one
b three
c two

and

(pop-up-lettered-menu (list "one" "two" "three") :sortp t 
                      :on-print 'capitalize-object)

displays a menu with the entries alphabetical and capitalized:

a One
b Three
c Two

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.