# AddToMenu

`AddToMenu` menu-name menu-label action

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

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

The menu could be invoked via

     1 R A  Utilities Nop

or

     1 R A  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 function are used to insert a separator into the menu.

The keywords and 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 and the rebuild from scratch. When the menu has been destroyed (unless you used the 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 command.

Do not issue commands as dynamic menu actions. Chances are good that this crashes fvwm.

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 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  \
      'fvwm_make_browse_menu.sh BrowseMenu'

Example (Picture menu):

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

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

The keyword 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 follows it, fvwm executes this command:

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

     MakeMissingDirectoryMenu
     MakeMissingDirectoryMenu
    + I  fvwm_make_directory_menu.sh $0

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

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 behind the keyword , 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 option of the 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 xcalc

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

    + *xcalc.xpm*            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 xcalc

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

    + %xcalc.xpm%            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 option of the 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 option of the 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.