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

FreeBSD Manual Pages

  
 
  

home | help
fvwm-menu-desktop(1)		 Fvwm Modules		  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-ti-
       tles|-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
       corresponding fvwm menus. This script depends on	python-xdg to run.

OPTIONS
       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	gener-
	      ated 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  con-
	      trol 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:  ap-
	      plications, 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 error.

       --all-menus
	      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).

       --with-titles|-w
	      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.

       --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 regenerate, 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`".

       --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 ex-
	      ecute option, such as xterm's -e option, which will run the com-
	      mand that	is appended to CMD. The	default	is "xterm -e".

       --dynamic
	      This  option is to be used with creating dynamic menus using Dy-
	      namicPopUpAction and DynamicPopDownAction. This adds  a  'recre-
	      ate'  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  ti-
	      tle).  This  option  makes  it  so the top level menu is not De-
	      stroyed 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 re-
	      generated	new menu items appear giving a growing menu of	dupli-
	      cate  items.   You have to regenerate the	whole menu via a func-
	      tion 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 --desk-
	      top|--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.

       --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 re-
	      size and copy the	icons to $FVWM_USERDIR/.icons. This  can  take
	      awhile. You should be prepared to	wait the first time you	gener-
	      ate the icons. Once the icons have  been	generated  the	script
	      should run faster. If it is still	to slow	using icons, see EXAM-
	      PLES 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	  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 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
	      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. De-
	      fault 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 sys-
       tem 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/.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-
       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 over-
	      ride 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.

GUI
       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.

EXAMPLES
       There are many ways to setup when fvwm runs fvwm-menu-desktop to	gener-
       ate 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 some-
       times  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  gen-
       erate  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 com-
       mand 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 exam-
       ple 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  ac-
       tions.	The  --dynamic flag includes the recreate option in the	gener-
       ated 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 re-
       port 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.

3rd Berkeley Distribution  05 September	2019 (2.6.9)	  fvwm-menu-desktop(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USAGE | GUI | EXAMPLES | BUGS | AUTHORS | COPYING

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

home | help