### 14.1 Menus ¶

### 14.2 Menus ¶

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*.

`C-p`
`Up`
`k`

  Highlight the previous menu option.

`C-n`
`Down`
`j`

  Highlight the next menu option.

`S-Down`

  Scroll the entire page down one entry.

`S-Up`

  Scroll the entire page up one entry.

`PageUp`

  Scroll up one page.

`PageDown`

  Scroll down one page.

`C-g`
`ESC`

  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).

Variable: *menu-map* ¶

  The keymap used by the interactive menu.

Function: menu-page-up menu ¶

  Move a whole page down in the menu

Function: menu-page-down menu ¶

  Move a whole page up in the menu

Function: menu-up menu ¶

  Move menu cursor up

Function: menu-down menu ¶

  Move menu cursor down

Function: menu-scroll-up menu ¶

  Scroll the menu up

Function: menu-scroll-down menu ¶

  Scroll the menu down

Function: menu-abort menu ¶

  What to do when exiting the menu without results. Must signal :menu-quit with the result.

Function: menu-backspace menu ¶

  What occurs when backspace is pressed in a menu

Function: menu-entry-apply menu-entry function ¶

  Apply FUNCTION to the data portion of the menu entry.

Function: menu-entry-display menu-entry ¶

  Generates a string suitable for displaying in a menu

Function: menu-finish menu ¶

  What to do when exiting the menu with results. Must signal :menu-quit with the result.

Function: command-menu screen items command-list &key prompt initial-selection extra-keymap ¶

  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))

#### 14.2.1 Single Selection Menus ¶

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.

`RET`

  Select the highlighted option.

Variable: *single-menu-map* ¶

  The keymap used by single selection menus in addition to *menu-map*

Function: select-from-menu screen table &optional prompt initial-selection extra-keymap filter-pred ¶

  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.

#### 14.2.2 Batch Menus ¶

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*.

`n`
`Space`

  Highlight the next item.

`p`

  Highlight the previous item.

`u`

  Unmark the selected item, then move the cursor down.

`DEL`

  Unmark the selected item, then move the cursor up if it is not at the top of the menu.

`x`
`RET`

  Exit the menu and perform the actions associated with each mark.

Variable: *batch-menu-map* ¶

  The keymap used by batch-menu menus in addition to *menu-map*

Function: select-from-batch-menu screen table &key prompt allowed-markers initial-selection extra-keymap ¶

  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.