| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |