Begins or adds to a menu definition. Typically a menu definition looks like this:

AddToMenu Utilities Utilities Title
 + Xterm           Exec  exec xterm -e tcsh
 + Rxvt            Exec  exec rxvt
 + "Remote Logins" Popup Remote-Logins
 + Top             Exec  exec rxvt -T Top -n Top -e top
 + Calculator      Exec  exec xcalc
 + Xman            Exec  exec xman
 + Xmag            Exec  exec xmag
 + emacs           Exec  exec xemacs
 + Mail            MailFunction xmh "-font fixed"
 + ""              Nop
 + Modules         Popup Module-Popup
 + ""              Nop
 + Exit Fvwm       Popup Quit-Verify

The menu could be invoked via

Mouse 1 R A Menu Utilities Nop

or

Mouse 1 R A Popup Utilities

There is no end-of-menu symbol. Menus do not have to be defined in a contiguous region of the config file. The quoted (or first word) portion in the above examples is the menu label, which appears in the menu when the user pops it up. The remaining portion is an fvwm command which is executed if the user selects that menu item. An empty menu-label ("") and the Nop function are used to insert a separator into the menu.

The keywords DynamicPopUpAction and DynamicPopDownAction have a special meaning when used as the name of a menu item. The action following the keyword is executed whenever the menu is popped up or down. This way you can implement dynamic menus. It is even possible to destroy itself with DestroyMenu and the rebuild from scratch. When the menu has been destroyed (unless you used the recreate option when destroying the menu), do not forget to add the dynamic action again.

Note: Do not trigger actions that require user interaction. They may fail and may screw up your menus. See the Silent command.

There are several configurable scripts installed together with fvwm for automatic menu generation. They have their own man pages. Some of them, specifically fvwm-menu-directory and fvwm-menu-desktop, may be used with DynamicPopupAction to create a directory listing or GNOME/KDE application listing.

Example (File browser):

# You can find the shell script fvwm_make_browse_menu.sh
# in the utils/ directory of the distribution.
AddToMenu BrowseMenu
+ DynamicPopupAction PipeRead \
  'fvwm_make_browse_menu.sh BrowseMenu'

Example (Picture menu):

# Build a menu of all .jpg files in
# $HOME/Pictures
AddToMenu JpgMenu foo title
+ DynamicPopupAction Function MakeJpgMenu

AddToFunc MakeJpgMenu
+ I DestroyMenu recreate JpgMenu
+ I AddToMenu JpgMenu Pictures Title
+ I PipeRead 'for i in $HOME/Pictures/*.jpg; \
  do echo AddToMenu JpgMenu "`basename $i`" Exec xv $i; done'

The keyword MissingSubmenuFunction has a similar meaning. It is executed whenever you try to pop up a sub menu that does not exist. With this function you can define and destroy menus on the fly. You can use any command after the keyword, but if the name of an item (that is a submenu) defined with AddToFunc follows it, fvwm executes this command:

Function <function-name> <submenu-name>

i.e. the name is passed to the function as its first argument and can be referred to with "$0".

The fvwm-menu-directory script mentioned above may be used with MissingSubmenuFunction to create an up to date recursive directory listing.

Example:

# There is another shell script fvwm_make_directory_menu.sh
# in the utils/ directory of the distribution. To use it,
# define this function in your configuration file:

DestroyFunc MakeMissingDirectoryMenu
AddToFunc MakeMissingDirectoryMenu
+ I PipeRead fvwm_make_directory_menu.sh $0

DestroyMenu SomeMenu
AddToMenu SomeMenu
+ MissingSubmenuFunction MakeMissingDirectoryMenu
+ "Root directory" Popup /

This is another implementation of the file browser that uses sub menus for subdirectories.

Titles can be used within the menu. If you add the option top behind the keyword Title, the title is added to the top of the menu. If there was a title already, it is overwritten.

AddToMenu Utilities Tools Title top

All text up to the first Tab in the menu label is aligned to the left side of the menu, all text right of the first Tab is aligned to the left in a second column and all text thereafter is placed right aligned in the third column. All other Tabs are replaced by spaces. Note that you can change this format with the ItemFormat option of the MenuStyle command.

If the menu-label contains an ampersand ('&'), the next character is taken as a hot-key for the menu item. Hot-keys are underlined in the label. To get a literal '&', insert "&&". Pressing the hot-key moves through the list of menu items with this hot-key or selects an item that is the only one with this hot-key.

If the menu-label contains a sub-string which is set off by stars, then the text between the stars is expected to be the name of an image file to insert in the menu. To get a literal '*', insert "**". For example

+ Calculator*xcalc.xpm* Exec exec xcalc

inserts a menu item labeled "Calculator" with a picture of a calculator above it. The following:

+ *xcalc.xpm*           Exec exec xcalc

Omits the "Calculator" label, but leaves the picture.

If the menu-label contains a sub-string which is set off by percent signs, then the text between the percent signs is expected to be the name of image file (a so called mini icon to insert to the left of the menu label. A second mini icon that is drawn at the right side of the menu can be given in the same way. To get a literal '%', insert "%%". For example

+ Calculator%xcalc.xpm% Exec exec xcalc

inserts a menu item labeled "Calculator" with a picture of a calculator to the left. The following:

+ %xcalc.xpm%           Exec exec xcalc

Omits the "Calculator" label, but leaves the picture. The pictures used with this feature should be small (perhaps 16x16).

If the menu-name (not the label) contains a sub-string which is set off by at signs ('@'), then the text between them is expected to be the name of an image file to draw along the left side of the menu (a side pixmap). You may want to use the SidePic option of the MenuStyle command instead. To get a literal '@', insert "@@". For example

AddToMenu StartMenu@linux-menu.xpm@

creates a menu with a picture in its bottom left corner.

If the menu-name also contains a sub-string surrounded by '^'s, then the text between '^'s is expected to be the name of an X11 color and the column containing the side picture is colored with that color. You can set this color for a menu style using the SideColor option of the MenuStyle command. To get a literal '^', insert "^^". Example:

AddToMenu StartMenu@linux-menu.xpm@^blue^

creates a menu with a picture in its bottom left corner and colors with blue the region of the menu containing the picture.

In all the above cases, the name of the resulting menu is name specified, stripped of the substrings between the various delimiters.