There are three different types of menus in StumpWM; single selection menus; interactive menus; and batch menus. Single-selection menus, as the name suggests, are used to pick a single item from a list. Interactive menus are used for marking multiple selections. Batch menus are used for performing actions on multiple menu items. Both batch and interactive menus share the same navigational keybindings, which are found in the table below. These can be customized by modifying the *menu-map* variable. Commands specific to each menu type can be modified by *single-menu-map* and *batch-menu-map*.
Highlight the previous menu option.
Highlight the next menu option.
Scroll the entire page down one entry.
Scroll the entire page up one entry.
Scroll up one page.
Scroll down one page.
Abort the menu.
In addition, you can customize the number of items shown at a time (a
page) with the *menu-maximum-height* variable. The default
value, 50
, limits the menu size to 50 items. Setting it to
nil
will remove the limit on how many menu entries are shown
(be careful, this can crash X11 when attempting to display a large
amount of items).
The keymap used by the interactive menu.
Move a whole page down in the menu
Move a whole page up in the menu
Move menu cursor up
Move menu cursor down
Scroll the menu up
Scroll the menu down
What to do when exiting the menu without results. Must signal :menu-quit with the result.
What occurs when backspace is pressed in a menu
Apply FUNCTION to the data portion of the menu entry.
Generates a string suitable for displaying in a menu
What to do when exiting the menu with results. Must signal :menu-quit with the result.
Default Values:
prompt "Select:" initial-selection 0 extra-keymap nil
Use batch-menu to make selections and run commands specified in command-list.
SCREEN: The screen to display the menu on.
ITEMS: The items to be shown in the list. This is expected to be a list of menu-item
s.
COMMAND-LIST: A list of entries defining the commands associated with each mark. Only marks that are defined are allowed in the menu. The format for these entries is (mark-character function calling-options).
Available calling-options: :single (Default) Each value is passed separately to the supplied function. :all all values selected with this mark are passed to the function in a list.
Example: ’((#d ’delete-window) (#m ’move-multiple-windows :all))
Single selection menus can be searched; start typing when the menu is active, and the results are immediately filtered. Use RET to selected the highlighted option.
Select the highlighted option.
The keymap used by single selection menus in addition to *menu-map*
Default Values:
prompt "Search:" initial-selection 0 extra-keymap nil filter-pred #'stumpwm::menu-item-matches-regexp
Prompt the user to select from a menu on SCREEN. TABLE can be a list of values or a nested list. If it’s a nested list, the first element in the sublist is displayed in the menu. What is displayed as menu items must be strings.
EXTRA-KEYMAP can be a keymap whose bindings will take precedence over the default bindings.
FILTER-PRED should be a a function returning T when a certain menu item should be visible to the user. It should accept arguments
ITEM-STRING (the string shown to the user), ITEM-OBJECT (the object corresponding to the menu item), and USER-INPUT (the current user input). The default is MENU-ITEM-MATCHES-REGEXP. Returns the selected element in TABLE or nil if aborted.
Batch menus provide a menu that allows the user to mark items. Items are marked by highlighting an item, then pressing a corresponding key. The key pressed depends on the menu being shown, and the desired action. For example, in a menu allowing users to manage windows, windows to be closed/removed could be marked by d, and windows to be raised could be marked by r. All available actions and their keybindings are shown below. These can be customized with *batch-menu-map*.
Highlight the next item.
Highlight the previous item.
Unmark the selected item, then move the cursor down.
Unmark the selected item, then move the cursor up if it is not at the top of the menu.
Exit the menu and perform the actions associated with each mark.
The keymap used by batch-menu menus in addition to *menu-map*
Default Values:
prompt "Select:" allowed-markers nil initial-selection 0 extra-keymap nil
Prompt the user with a menu that allows them to mark each item with a character. They can exit the menu by pressing enter, or whatever key is mapped to ’menu-finish’ in *menu-map*. Value returned is an alist, where the cdr of each entry is a list of items that were marked with that character. Note that the lisp printer cannot distinguish between ’(a . (b c d)) and ’(a b c d).
Example when "foo" and "bar" are marked with ’#d’, and "baz" is not marked: ((#d "foo" "bar") (NIL "baz")) ALLOWED-MARKERS is a list of characters. If this parameter is specified, no other markers are allowed. EXTRA-KEYMAP can be a keymap whose bindings will take precedence over the default bindings.