= fvwm3-menu-desktop(1)

== NAME

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

== SYNOPSIS

fvwm3-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
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 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 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 *fvwm3-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
  `fvwm3-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 execute
  option, such as xterm's -e option, which will run the command that is
  appended to _CMD_. The default is "xterm -e".
+
Debian specific: Per Debian policy, default changed to
"x-terminal-emulator -e".
+
--dynamic ::
  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 |-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, fvwm3-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.

--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, fvwm3-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-applications'.
--dir-icon NAME::
  Sets the default directory icon if no others are found. Default is
  'gnome-fs-directory'.

== USAGE

*fvwm3-menu-desktop* outputs XDG .menu files in the syntax of fvwm menus.
When *fvwm3-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:

....
fvwm3-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 menus.

Though a combination of command line options and the
*FvwmForm-XDGMenu-Config* settings, *fvwm3-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 *fvwm3-menu-desktop* was run with no options.

....
fvwm3-menu-desktop --get-menus desktop
....

*fvwm3-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 *fvwm3-menu-desktop* will generate a menu whose top level name
is "XDGMenu". To tell fvwm to read the output of *fvwm3-menu-desktop* to
create the menu XDGMenu add the following to your fvwm config file:

....
PipeRead 'fvwm3-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
....

*fvwm3-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 *fvwm3-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 *fvwm3-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 *fvwm3-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
'fvwm3-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

....
fvwm3-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 'fvwm3-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, *fvwm3-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 'fvwm3-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 'fvwm3-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 'fvwm3-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 'fvwm3-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 `fvwm3-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 fvwm3-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.