# Menus

Before a menu can be opened, it has to be populated with menu items using the command and bound to a key or mouse button with the , or command (there are many other ways to invoke a menu too). This is usually done in the configuration file.

Fvwm menus are extremely configurable in look and feel. Even the slightest nuances can be changed to the user's liking, including the menu item fonts, the background, delays before popping up sub menus, generating menus dynamically and many other features. Please refer to the command to learn more.

## Types of Menus

In fvwm there are four slightly different types of menus:

menus can appear everywhere on the screen on their own or attached to a part of a window. The command opens popup menus. If the popup menu was invoked with a mouse button held down, it is closed when the button is released. The item under the pointer is then activated and the associated action is executed.

is a very similar command, but the menus it opens are slightly less transient. When invoked by clicking a mouse button, it stays open and can be navigated with no button held. But if it is invoked by a button press followed by mouse motion, it behaves exactly like a popup menu.

Tear off menus or Pin up menus are menus from either of the above two commands that have been "torn off" their original context and pinned on the desktop like a normal window. They are created from other menus by certain key presses or mouse sequences or with the command from inside a menu.

Sub menus are menus inside menus. When a menu item that has the command as its action is selected, the named menu is opened as an inferior menu to the parent. Any type of menu can have sub menus.

## Menu Anatomy

Menus consist of any number of titles which are inactive menu items that usually appear at the top of the menu, normal items triggering various actions when selected, separator lines between the items, tear off bars (a horizontal broken line) that tear off the menu when selected, and sub menu items indicated with a triangle pointing left or right, depending on the direction in which the sub menu appears. All the above menu items are optional.

Additionally, if the menu is too long to fit on the screen, the excess menu items are put in a continuation menu and a sub menu with the string "More..." is placed at the bottom of the menu. The "More..." string honors the locale settings.

Finally, there may be a picture running up either side of the menu (a "side bar").

## Menu Navigation

Menus can be navigated either with the keyboard or with the mouse. Many people prefer to use the mouse, but it can be rather tedious. Once you get the hang of it, keyboard navigation can be much faster. While fvwm displays a menu, it can do nothing else. For example, new windows do not appear before the menu is closed. However, this is not exactly true for tear off menus. See the section for details.

## Mouse Navigation

Moving the pointer over a menu selects the item below it. Normally this is indicated by a 3d border around the item, but not all parts of a menu can be selected. Pressing any mouse button while a menu is open by default activates the item below it. Items of a popup menu are also activated by releasing a held mouse button. In case of an item that hides a sub menu, the sub menu is displayed if the pointer hovers over the item long enough or moves close to the triangle indicating the sub menu. This behaviour can be tuned with menu styles.

Scrolling a mouse wheel over a menu either wraps the pointer along the menu (default), scrolls the menu under the pointer or act as if the menu was clicked depending on the menu style.

Clicking on a selected item activates it - what happens exactly depends on the type of the item.

Clicking on a title, a separator, the side bar, or outside the menu closes the menu (exception: tear off menus can not be closed this way). Pressing mouse button 2 over a menu title or activating a tear off bar creates a tear off menu from the current menu. Clicking on a normal menu item invokes the command that is bound to it, and clicking on a sub menu item either closes all open menus and replaces them with the sub menu or posts the menu (default).

Posting menus is meant to ease mouse navigation. Once a sub menu is posted, only items from that sub menu can be selected. This can be very useful to navigate the menu if the pointer tends to stray off the menu. To unpost the menu and revert back to normal operation, either click on the same sub menu item or press any key.

## Keyboard Navigation

Just like with mouse navigation, the item below the pointer is selected. This is achieved by warping the pointer to the menu items when necessary. While a menu is open, all key presses are intercepted by the menu. No other application can get keyboard input (although this is not the case for tear off menus).

Items can be selected directly by pressing a hotkey that can be configured individually for each menu item. The hotkey is indicated by underlining it in the menu item label. With the menu style fvwm automatically assigns hotkeys to all menu items.

The most basic keys to navigate through menus are the cursor keys (move up or down one item, enter or leave a sub menu), Space (activate item) and Escape (close menu). Numerous other keys can be used to navigate through menus by default:

Enter, Return, Space activate the current item.

Escape, Delete, Ctrl-G exit the current sequence of menus or destroy a tear off menu.

J, N, Cursor-Down, Tab, Meta-Tab, Ctrl-F, move to the next item.

K, P, Cursor-Up, Shift-Tab, Shift-Meta-Tab, Ctrl-B, move to the prior item.

L, Cursor-Right, F enter a sub menu.

H, Cursor-Left, B return to the prior menu.

Ctrl-Cursor-Up, Ctrl-K Ctrl-P, Shift-Ctrl-Meta-Tab, Page-Up move up five items.

Ctrl-Cursor-Down, Ctrl-J Ctrl-N, Ctrl-Meta-Tab Page-Down move down five items.

Shift-P, Home, Shift-Cursor-Up, Ctrl-A move to the first item.

Shift-N, End, Shift-Cursor-Down, Ctrl-E move to the last item.

Meta-P, Meta-Cursor-Up, Ctrl-Cursor-Left, Shift-Ctrl-Tab, move up just below the next separator.

Meta-N, Meta-Cursor-Down, Ctrl-Cursor-Right, Ctrl-Tab, move down just below the next separator.

Insert opens the "More..." sub menu if any.

Backspace tears off the menu.

## Menu Bindings

The keys and mouse buttons used to navigate the menu can be configured using the and commands with the special context 'M', possible combined with 'T' for the menu title, 'I' for other menu items, 'S' for any border or sidepic, '[' for left border including a left sidepic, ']' for right border including a right sidepic, '-' for top border, '_' for bottom border. The menu context uses its own set of actions that can be bound to keys and mouse buttons. These are MenuClose, MenuCloseAndExec, MenuEnterContinuation, MenuEnterSubmenu, MenuLeaveSubmenu, MenuMoveCursor, MenuCursorLeft, MenuCursorRight, MenuSelectItem, MenuScroll and MenuTearOff.

It is not possible to override the key Escape with no modifiers for closing the menu. Neither is it possible to undefine mouse button 1, the arrow keys or the enter key for minimal navigation.

MenuClose exits from the current sequence of menus or destroys a tear off menu.

MenuCloseAndExec exits from the current sequence of menus or destroys a tear off menu and executes the rest of the line as a command.

MenuEnterContinuation opens the "More..." sub menu if any.

MenuEnterSubmenu enters a sub menu.

MenuLeaveSubmenu returns to the prior menu.

MenuMoveCursor n m moves the selection to another item. If the first argument is zero the second argument specifies an absolute item in the menu to move the pointer to. Negative items are counted from the end of the menu. If the first argument is non-zero, the second argument must be omitted, and the first argument specifies a relative change in the selected item. The positions may be suffixed with a 's' to indicate that the items should refer only to the first items after separators.

MenuCursorLeft enters a sub menu with the menu style, and returns to the prior menu with the menu style.

MenuCursorRight enters a sub menu with the menu style, and returns to the prior menu with the menu style.

MenuSelectItem triggers the action for the menu item.

MenuScroll n performs menu scrolling according to the menu style with n items. The distance can be suffixed with an 's' to indicate the items should refer only to the first items after separators.

MenuTearOff turns a normal menu into a "torn off" menu. See for details.

## Tear Off Menus

A tear off menu is any menu that has been "torn off" the window it was attached to and pinned to the root window. There are three ways to tear off a menu: click on the menu title with mouse button 2, press Backspace in the menu or activate its tear off bar (a horizontal bar with a broken line). Tear off bars must be added to the menu as any other item by assigning them the command .

The builtin tear off actions can be overridden by undefining the builtin menu actions bound to tear off. To remove the builtin mouse button 2 binding, use:

     2 MT A -

and to remove the builtin backspace binding, use:

     Backspace M A -

See the section for details on how to assign other bindings for tear off.

Note that prior to fvwm 2.5.20 the tear off mouse bindings were redefined in different way, which no longer work.

The window containing the menu is placed as any other window would be. If you find it confusing to have your tear off menus appear at random positions on the screen, put this line in your configuration file:

     fvwm_menu

To remove borders and buttons from a tear-off menu but keep the menu title, you can use

     fvwm_menu ! 0, ! 1
     fvwm_menu ! 2, ! 3
     fvwm_menu ! 4, ! 5
     fvwm_menu ! 6, ! 7
     fvwm_menu ! 8, ! 9
     fvwm_menu ,  0

A tear off menu is a cross breeding between a window and a menu. The menu is swallowed by a window and its title is stripped off and displayed in the window title. The main advantage is that the menu becomes permanent - activating an item does not close the menu. Therefore, it can be used multiple times without reopening it. To destroy such a menu, close its window or press the Escape key.

Tear off menus behave somewhat differently than normal menus and windows. They do not take the keyboard focus, but while the pointer is over one of them, all key presses are sent to the menu. Other fvwm key bindings are disabled as long as the pointer is inside the tear off menu or one of its sub menus. When the pointer leaves this area, all sub menus are closed immediately. Note that the window containing a tear off menu is never hilighted as if it had the focus.

A tear off menu is an independent copy of the menu it originated from. As such, it is not affected by adding items to that menu or changing its menu style.

To create a tear off menu without opening the normal menu first, the option can be added to the or command.