pop-up-lettered-menu

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 is nil.

sortp, if specified, should be either true or 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 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 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 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 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) or nil. The default is 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 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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 9.0 release; see the Release Notes.
Created 2019.8.20.