|Allegro CL version 10.0|
Unrevised from 9.0 to 10.0.
Arguments: choices &key (sortp t) (sort-predicate (function string<)) (sort-key (function identity)) on-print (stream (screen *system*)) position on-help
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.
choices arbitrary values
from which the user can choose. The on-print
function will convert these values to strings to display on 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
sortp, if specified, should be either true
nil. If true, then the items in the
choices list will first be sorted by the
sort-predicate function before being
displayed. The default value is
:sortp nil should be specified to avoid sorting the
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 choices 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
on-print, if specified, should be either
nil, a function object, or a function name.
The default value is
nil, strings in the choices
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
choices 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
choices list rather than on the strings returned
by the on-print function.
stream is either the screen or else a window that will serve as the owner of the pop-up menu. The default value is the screen (see screen). The position argument is relative to this stream.
position is the position relative to the upper-left interior corner of the specified stream at which the upper-left corner of the pop-up menu will appear. The default is offset a bit from the current position of the mouse cursor.
on-help, if specified, should be a
funcallable object (a function object or function name)
nil. The default
nil. A function may be used for
displaying status bar messages as the user highlights individual menu
items. The function should take a single argument, which will be one
of the values in the choices list, and it should
return a string that can be displayed in a status bar. The strings
will be displayed in the status bar of the specified stream, if it has
a status bar, or else in the status bar of the first ancestor window
of that stream that has a status bar, if any.
This function returns the item from the choices
list that was chosen by the user, or
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
This function may be better when the list of choices is large, as it
uses a scrolling
four choices or fewer, ask-user-for-choice may be used.
(pop-up-lettered-menu (list "one" "two" "three") :sortp nil)
displays a menu
a one b two c three
(pop-up-lettered-menu (list "one" "two" "three") :sortp t)
displays a menu with the entries alphabetical:
a one b three c two
(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-2017, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
|Allegro CL version 10.0|
Unrevised from 9.0 to 10.0.