Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
FVWM-MENU-DESKTOP(1)					    FVWM-MENU-DESKTOP(1)

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

SYNOPSIS
     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 ] [
     --term-cmd CMD ] [ --dynamic ] [ --menu-error|-e ] [ --verbose|-v ]

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

MAIN OPTIONS
     --help
	 Show the help and exit.

     --version
	 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-XDG-
	 Menu-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, prefer-
	 ences, 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 error.

     --all-menus
	 This  option  will build all menus found on the system. If used in con-
	 junction with --desktop or --menu-type this will build all menus match-
	 ing those settings.

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

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

     --without-titles
	 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  re-
	 generate, 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-desk-
	 top`".

     --term-cmd CMD
	 This  option  sets the terminal emulator command CMD that is used to to
	 run terminal applications in. CMD needs to end with an execute  option,
	 such  as xterm's -e option, which will run the command that is appended
	 to CMD. The default is "xterm -e".

     --dynamic
	 This option is to be used with creating dynamic menus using DynamicPop-
	 UpAction and DynamicPopDownAction. This adds a 'recreate'  to	the  De-
	 stroyMenu  command  on  the top level menu so those actions are not De-
	 stroyed 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|-e
	 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.

     --verbose
	 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 pre-
     pared  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.

     --enable-mini-icons
	 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 di-
	 rectory specified with --mini-icon-dir option. Otherwise  no  icon  ap-
	 pears in the menu for that entry. With most distributions, all the menu
	 entries will have mini-icons appropriate to the application.

     --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  cre-
	 ates  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-applications'.

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

USAGE
     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  suit-
     able 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 de-
     fault  menus  are	stored	as  .menu  files  in /etc/xdg/menus, $HOME/.con-
     fig/menus or the location set  in	$XDG_MENU_PREFIX.  You	can  use  *--in-
     stall-prefix to specify another location search for menus.

     Though  a combination of command line options and the FvwmForm-XDGMenu-Con-
     fig 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 'desk-
     top*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  de-
     tails 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.

GUI
     FvwmForm-XDGMenu-Config is a FvwmForm interface that can be used to config-
     ure the defaults for fvwm-menu-desktop. You can access this from the  "Con-
     figure"  item  in the top level menu that is generated or run the following
     from within FvwmCommand or FvwmPrompt:

	 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.

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

	 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 XD-
     GRegen. 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 Func-
     tion 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 Regener-
     ate  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 --dy-
     namic 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

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

AUTHORS
     This script  is  based  on  fvwm-xdg-menu.py  written  by	Piotr  Zielinski
     (http://www.cl.cam.ac.uk/~pz215/) 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-workers.

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

				   2026-06-27		    FVWM-MENU-DESKTOP(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=fvwm-menu-desktop&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help