Provided by: fvwm_2.6.7-3_amd64 bug


       fvwm-menu-desktop - Reads XDG menu files and creates Fvwm menus


       fvwm-menu-desktop  [ --help|-h ] [ --version ] [ --install-prefix DIR ] [ --desktop NAME ]
       [ --menu-type NAME ] [ --theme  NAME  ]  [  --with-titles|-w  ]  [  --without-titles  ]  [
       --enable-mini-icons  ]  [  --size|-s  NUM  ] [ --mini-icon-dir DIR ] [ --app-icon NAME ] [
       --dir-icon NAME ] [ --title|-t NAME ] [ --insert-in-menu NAME ] [ --get-menus  all|desktop
       ]  [ --set-menus menu_paths ] [ --all-menus ] [ --include-items NAME ] [ --regen-cmd CMD ]
       [ --dynamic ] [ --menu-error|-e ] [ --verbose|-v ]


       This is a python script which parses XDG menus definitions  to  build  corresponding  fvwm
       menus. This script depends on python-xdg to run.


       Main Options

       --help Show the help and exit.

              Show the version and exit.

       --get-menus all|desktop
              Prints  a  space  separated  list of full menu paths found on the system.  all will
              print all menus found on the system except empty  ones.   desktop  will  print  the
              menu(s) that would be generated by the script.

              No menu generation is done.

       --desktop NAME
              Optional  parameter  to  set the NAME of the desktop XDG .menu file(s) to use. This
              option will override any default menus set via  FvwmForm-XDGMenu-Config  and  cause
              the  script to find menus in which NAME is a part of the file name.  Possible names
              are: gnome, kde, xfce, lxde, debian, etc.

              This option can be used in conjunction with  --menu-type  to  control  which  .menu
              file(s) are used.

       --menu-type NAME
              Optional  parameter  to  set the NAME of the XDG menu type to use. This option will
              override any default menus set via FvwmForm-XDGMenu-Config and cause the script  to
              find menus in which NAME is a part of the file name.  Possible NAME types could be:
              applications, settings, preferences, etc.

              When used in conjunction  with  --desktop,  only  menus  whose  file  name  matches
              '*destkop*menutype*'  are  found.  If  no menus are found, the script exits with an

              This option will build all menus found on the system. If used in  conjunction  with
              --desktop or --menu-type this will build all menus matching those settings.

       --install-prefix DIR
              Optional  parameter  to  override  the standard locations for XDG menu definitions.
              Tells fvwm-menu-desktop to look in DIR for .menu  files  instead  of  the  standard
              locations /etc/xdg/menus (and $HOME/.config/menus if it exists).

              If  this  option is set menus are generated with titles. This is the default.  This
              option can be used to override the FvwmForm-XDGMenu-Config default setting.

              If this option is set menus  are  generated  without  titles.  The  default  is  to
              generate with titles.

       --title|-t NAME
              Option  to  define the menu title NAME of the top menu used by Fvwm's Menu or Popup
              commands. Default is "XDGMenu".

       --include-items NAME
              This option controls if the additional menu items 'Regenerate' and 'Configure'  are
              included  in  the  top level menu. NAME can be one of regen, config, both, or none.
              The default is both.

       --regen-cmd CMD
              This option sets the fvwm command CMD that is run when the menu  item  ´Regenerate'
              is selected. The default is "PipeRead `fvwm-menu-desktop`".

              This  option is to be used with creating dynamic menus using DynamicPopUpAction and
              DynamicPopDownAction. This adds a 'recreate' to the DestroyMenu command on the  top
              level menu so those actions are not Destroyed when the menu is regenerated.

       --insert-in-menu NAME
              Option  to  insert  generated  menu(s)  IN a menu NAME (its top title). This option
              makes it so the top level menu is not Destroyed and the items are added to the end.

              Note menus regenerated with this option will append the menu items at  the  end  of
              the existing menu. Each time the menu is regenerated new menu items appear giving a
              growing menu of duplicate items.  You have to  regenerate  the  whole  menu  via  a
              function or restart fvwm. See EXAMPLES below for some solutions.

       --set-menus menu_paths
              Generates  all  menus  listed  in  a space separated list of full menu paths.  This
              option overrides any defaults and --desktop|--menu-type settings.

       --menu-error |-t
              If this option is present and python-xdg is not found, the script  will  print  the
              error in the generated menu. Used in the default-config.

              Enables additional information printouts on STDERR.

       Icons Options

              By default, fvwm-menu-desktop builds menus without mini-icons. To enable mini-icons
              use the following options.

              If ImageMagick is installed on the system, the script  will  resize  and  copy  the
              icons to $FVWM_USERDIR/.icons. This can take awhile. You should be prepared to wait
              the first time you generate the icons. Once  the  icons  have  been  generated  the
              script should run faster. If it is still to slow using icons, see EXAMPLES for ways
              to limit how often the menu is generated to speed things up.

              This option enables mini-icons in the menus. If set, 24x24 mini-icons are used.  If
              the specified icon isn't that size it will be converted if ImageMagick is installed
              and saved in $HOME/.fvwm/icons or to the directory specified  with  --mini-icon-dir
              option.  Otherwise  no  icon  appears  in  the  menu  for  that  entry.   With most
              distributions, all the  menu  entries  will  have  mini-icons  appropriate  to  the

       --theme NAME
              Defines   the   used  icon  theme.  Default  is  gnome  but  all  others  found  in
              /usr/share/icons could be used except the hicolor theme because  it's  the  default
              fallback theme if no icon is found.

       --size|-s NUM
              If  --enable-mini-icons  is  used  the  size  of  the  icons  can changed with this
              parameter. Default is 24.

       --mini-icon-dir DIR
              When the right size mini-icon isn't available, fvwm-menu-desktop creates icons with
              the  right  size  in  $HOME/.fvwm/icons.   If  you  don't  want  to use the default
              directory, $HOME/.fvwm/icons, use this option to specify a different folder.

       --app-icon NAME
              Sets the default application icon if  no  others  are  found.  Default  is  ´gnome-

       --dir-icon NAME
              Sets  the  default  directory  icon  if  no others are found. Default is ´gnome-fs-


       fvwm-menu-desktop outputs XDG .menu files in the syntax of  fvwm  menus.  When  fvwm-menu-
       desktop  is  run  with  no options, it will load defaults from the FvwmForm-XDGMenu-Config
       file (see below) then search your system for suitable menu file(s). To see which menus are
       available on your system run:

              fvwm-menu-desktop --get-menus all

       If  no menus are found you may not have any installed on your system. By default menus are
       stored as *.menu files in /etc/xdg/menus,  $HOME/.config/menus  or  the  location  set  in
       $XDG_MENU_PREFIX.  You  can  use  --install-prefix  to specify another location search for

       Though a combination of command line options  and  the  FvwmForm-XDGMenu-Config  settings,
       fvwm-menu-desktop  can  generate any combination of the menus found. To get a list of what
       menu(s) would be generated use the --get-menus desktop option. The following will list all
       menus generated if fvwm-menu-desktop was run with no options.

              fvwm-menu-desktop --get-menus desktop

       fvwm-menu-desktop determines which menu(s) to generate as follows

              If no config file is found, all menus will be weighted and the script will generate
              the best (highest weight) menu found.

              If a config file is found (and override options  are  not  used)  the  script  will
              generate all menus selected in FvwmForm-XDGMenu-Config.

              --desktop,  --menu-type,  --set-menus  and  --all-menus  will  override  any  menus
              selected in FvwmForm-XDGMenu-Config.

              --desktop  and  --menu-type  will   only   include   menus   whose   name   matches
              '*desktop*menutype*'.  If  used with --all-menus, all matching menus are generated.
              If used without --all-menus, only the highest weighted menu is generated.

              --set-menus generates menus from the list of full path menu file names.

              --all-menus by itself will generate all menus found.

       By default fvwm-menu-desktop will generate a menu whose top level name  is  "XDGMenu".  To
       tell  fvwm  to  read  the  output  of fvwm-menu-desktop to create the menu XDGMenu add the
       following to your fvwm config file:

              PipeRead 'fvwm-menu-desktop'

       Warning: Depending on the options used this command may be slow and fvwm will pause  until
       this command is complete. See EXAMPLES below for more details and possible workarounds.

       Once  the menu is generated you can open the menu by using the command "Menu XDGMenu". You
       can also include this in the MenuFvwmRoot menu by:

              AddToMenu MenuFvwmRoot "XDG Menu" Popup XDGMenu

       fvwm-menu-desktop can be configured though both command line options and a FvwmForm GUI to
       customize the menu(s) that get generated.


       FvwmForm-XDGMenu-Config is a FvwmForm interface that can be used to configure the defaults
       for fvwm-menu-desktop. You can access this from the "Configure" item in the top level menu
       that is generated or run the following from within FvwmConsole

              Module FvwmPerl -l fvwm-menu-desktop-config.fpl

       This  form can be used to select which menu(s) get generated by default along with setting
       many (but not all) of the available options. When you click "Save Settings" the form  will
       write  a  config  file  located  at $FVWM_USERDIR/.FvwmForm-XDGMenu-Config that fvwm-menu-
       desktop will parse for defaults when run.

       See the help inside of FvwmForm-XDGMenu-Config for more information.


       There are many ways to setup when fvwm runs fvwm-menu-desktop to generate  the  menu.  One
       method  is  to  just generate the menu when fvwm loads and then use the GUI config tool to
       change any options.  To do this you only need to add the  following  to  the  fvwm  config

              AddToMenu MenuFvwmRoot "XDG Menu" Popup XDGMenu
              PipeRead 'fvwm-menu-desktop'

       The  menu is created once when fvwm loads. Since menu creation can sometimes be slow, this
       could cause fvwm to take longer to load than one wants.

       The menu is only generated when fvwm starts. If software is installed or removed you  will
       have to select the 'Regenerate' option to rebuild the menu.

       One  way  to speed things up is to save the menu in a file and only generate the menu when
       'Regenerate' is selected. To do this use --regen-cmd to call a custom function  and  write
       the menu to a file using a command like

              fvwm-menu-desktop --regen-cmd XDGRegen > $FVWM_USERDIR/.XDGMenu

       Then add the following to the fvwm config file to define the function XDGRegen. The second
       to last line will generate the menu if the menu file doesn't exist when fvwm starts.

              DestroyFunc XDGRegen
              AddToFunc XDGRegen
              + I PipeRead 'fvwm-menu-desktop --regen-cmd XDGRegen > \
                  $[FVWM_USERDIR]/.XDGMenu; echo "Nop"'
              + I Read $[FVWM_USERDIR]/.XDGMenu

              Test (!f $[FVWM_USERDIR]/.XDGMenu) XDGRegen
              Read $[FVWM_USERDIR]/.XDGMenu

       Besides creating a top level menu, fvwm-menu-desktop can insert the menu into an  existing
       menu using the --insert-in-menu option. For example one could create the menu MenuFvwmRoot
       and include the XDG items at the end.

              DestroyMenu MenuFvwmRoot
              AddToMenu MenuFvwmRoot "Fvwm" Title
              + "Item1" Action1
              + "ItemN" ActionN
              + "" Nop
              PipeRead 'fvwm-menu-desktop --insert-in-menu MenuFvwmRoot'

       In this case the menu items are inserted at the end of the MenuFvwmRoot menu.  If no items
       are  in  the  menu,  this menu becomes MenuFvwmRoot. The problem here is, that you have to
       restart fvwm or rebuild the whole menu to Regenerate  it  because  menu  items  cannot  be
       removed.  To do this you could use a function like

              DestroyFunc XDGRegen
              AddToFunc XDGRegen
              + I DestroyMenu MenuFvwmRoot
              + I AddToMenu MenuFvwmRoot "Fvwm" Title
              + I AddToMenu MenuFvwmRoot "Item1" Action1
              + I AddToMenu MenuFvwmRoot "ItemN" ActionN
              + I AddToMenu MenuFvwmRoot "" Nop
              + I PipeRead 'fvwm-menu-desktop --insert-in-menu MenuFvwmRoot \
                            --regen-cmd XDGRegen'

       Fvwm   can   also   create   menus   dynamically   by   using   DynamicPopUpAction  and/or
       DynamicPopDownAction. These commands when used with a Menu will run a  Function  when  the
       menu is opened. For example one could create the menu XDGMenu when it is opened using

              AddToMenu XDGMenu "XDGMenu" Title
              + DynamicPopUpAction PipeRead 'fvwm-menu-desktop'

       This  will  create  the  menu when it is opened. One issue here is it will only create the
       menu the first time it is opened, and you still have to Regenerate the  menu  to  see  any
       changes. To create the menu each time it is open used the --dynamic option

              AddToMenu XDGMenu "XDGMenu" Title
              + DynamicPopUpAction PipeRead 'fvwm-menu-desktop \
                                   --dynamic --include-items config'
              + DynamicPopDownAction DestroyMenu recreate XDGMenu

       This  will  now  Destroy  the menu when it closed so it can be rebuilt the next time it is
       opened.  The  recreate  flag   doesn't   completely   destroy   the   menu   keeping   the
       DynamicPopUpAction  and  DynamicPopDownAction  actions.   The  --dynamic flag includes the
       recreate option in the generated menus.

       To insert a menu into MenuFvwmRoot and still be dynamic you need to use  a  function  that
       generates the whole menu. For example

              DestroyFunc GenRootMenu
              AddToFunc GenRootMenu
              + I DestroyMenu recreate MenuFvwmRoot
              + I AddToMenu MenuFvwmRoot "Fvwm" Title
              + I AddToMenu MenuFvwmRoot "Item1" Action1
              + I AddToMenu MenuFvwmRoot "ItemN" ActionN
              + I AddToMenu MenuFvwmRoot "" Nop
              + PipeRead `fvwm-menu-desktop --insert-in-menu MenuFvwmRoot \
                         --include-items config`

              AddToMenu MenuFvwmRoot "Fvwm" Title
              + DynamicPopUpAction GenRootMenu
              + DynamicPopDownAction DestroyMenu recreate MenuFvwmRoot


       The  whole  process  of  creating  menus from files is slow.  Otherwise report bugs to the
       fvwm-workers mailing list <>.


       This   script   is   based   on    written    by    Piotr    Zielinski
       ( who assigned Licence: GPL 2 Date: 03.12.2005.

       The script was reworked to replace the existing fvwm-menu-desktop perl script by the fvwm-


       The script is distributed by the same terms as fvwm itself. See GNU General Public License
       for details.