1= fvwm-menu-desktop(1) 2 3== NAME 4 5fvwm-menu-desktop - Reads XDG menu files and creates Fvwm menus 6 7== SYNOPSIS 8 9fvwm-menu-desktop [ **--help**|*-h* ] [ *--version* ] [ 10*--install-prefix* _DIR_ ] [ *--desktop* _NAME_ ] [ *--menu-type* _NAME_ 11] [ *--theme* _NAME_ ] [ **--with-titles**|*-w* ] [ *--without-titles* ] 12[ *--enable-mini-icons* ] [ **--size**|*-s* _NUM_ ] [ *--mini-icon-dir* 13_DIR_ ] [ *--app-icon* _NAME_ ] [ *--dir-icon* _NAME_ ] [ 14**--title**|*-t* _NAME_ ] [ *--insert-in-menu* _NAME_ ] [ *--get-menus* 15__all__|_desktop_ ] [ *--set-menus* _menu_paths_ ] [ *--all-menus* ] [ 16*--include-items* _NAME_ ] [ *--regen-cmd* _CMD_ ] [ *--term-cmd* _CMD_ 17] [ *--dynamic* ] [ **--menu-error**|*-e* ] [ **--verbose**|*-v* ] 18 19== DESCRIPTION 20 21This is a python script which parses XDG menus definitions to build 22corresponding fvwm menus. This script depends on python-xdg to run. 23 24== OPTIONS 25 26Main Options:: 27--help:: 28 Show the help and exit. 29--version:: 30 Show the version and exit. 31--get-menus all|desktop:: 32 Prints a space separated list of full menu paths found on the system. 33 _all_ will print all menus found on the system except empty ones. 34 _desktop_ will print the menu(s) that would be generated by the 35 script. 36 37No menu generation is done. 38 39--desktop NAME:: 40 Optional parameter to set the _NAME_ of the desktop XDG .menu file(s) 41 to use. This option will override any default menus set via 42 *FvwmForm-XDGMenu-Config* and cause the script to find menus in which 43 _NAME_ is a part of the file name. Possible names are: _gnome_, _kde_, 44 _xfce_, _lxde_, _debian_, etc. 45 46This option can be used in conjunction with *--menu-type* to control 47which .menu file(s) are used. 48 49--menu-type NAME:: 50 Optional parameter to set the _NAME_ of the XDG menu type to use. This 51 option will override any default menus set via 52 *FvwmForm-XDGMenu-Config* and cause the script to find menus in which 53 _NAME_ is a part of the file name. Possible _NAME_ types could be: 54 _applications_, _settings_, _preferences_, etc. 55 56When used in conjunction with *--desktop*, only menus whose file name 57matches '*destkop*menutype*' are found. If no menus are found, the 58script exits with an error. 59 60--all-menus:: 61 This option will build all menus found on the system. If used in 62 conjunction with *--desktop* or *--menu-type* this will build all 63 menus matching those settings. 64--install-prefix DIR:: 65 Optional parameter to override the standard locations for XDG menu 66 definitions. Tells *fvwm-menu-desktop* to look in _DIR_ for .menu 67 files instead of the standard locations /etc/xdg/menus (and 68 $HOME/.config/menus if it exists). 69--with-titles|-w:: 70 If this option is set menus are generated with titles. This is the 71 default. This option can be used to override the 72 *FvwmForm-XDGMenu-Config* default setting. 73--without-titles:: 74 If this option is set menus are generated without titles. The default 75 is to generate with titles. 76--title|-t NAME :: 77 Option to define the menu title _NAME_ of the top menu used by Fvwm's 78 *Menu* or *Popup* commands. Default is "XDGMenu". 79--include-items NAME :: 80 This option controls if the additional menu items 'Regenerate' and 81 'Configure' are included in the top level menu. _NAME_ can be one of 82 _regenerate_, _config_, _both_, or _none_. The default is _both_. 83--regen-cmd CMD :: 84 This option sets the fvwm command _CMD_ that is run when the menu item 85 'Regenerate' is selected. The default is "PipeRead 86 `fvwm-menu-desktop`". 87--term-cmd CMD :: 88 This option sets the terminal emulator command _CMD_ that is used to 89 to run terminal applications in. _CMD_ needs to end with an execute 90 option, such as xterm's -e option, which will run the command that is 91 appended to _CMD_. The default is "xterm -e". 92--dynamic :: 93 This option is to be used with creating dynamic menus using 94 *DynamicPopUpAction* and *DynamicPopDownAction*. This adds a 95 'recreate' to the *DestroyMenu* command on the top level menu so those 96 actions are not Destroyed when the menu is regenerated. 97--insert-in-menu NAME:: 98 Option to insert generated menu(s) *IN* a menu _NAME_ (its top title). 99 This option makes it so the top level menu is not Destroyed and the 100 items are added to the end. 101 102Note menus regenerated with this option will append the menu items at 103the end of the existing menu. Each time the menu is regenerated new menu 104items appear giving a growing menu of duplicate items. You have to 105regenerate the whole menu via a function or restart fvwm. See *EXAMPLES* 106below for some solutions. 107 108--set-menus menu_paths:: 109 Generates all menus listed in a space separated list of full menu 110 paths. This option overrides any defaults and 111 **--desktop**|*--menu-type* settings. 112--menu-error |-e:: 113 If this option is present and python-xdg is not found, the script will 114 print the error in the generated menu. Used in the default-config. 115--verbose:: 116 Enables additional information printouts on STDERR. 117Icons Options:: 118 By default, fvwm-menu-desktop builds menus without mini-icons. To 119 enable mini-icons use the following options. 120 121If ImageMagick is installed on the system, the script will resize and 122copy the icons to $FVWM_USERDIR/.icons. This can take awhile. You should 123be prepared to wait the first time you generate the icons. Once the 124icons have been generated the script should run faster. If it is still 125to slow using icons, see *EXAMPLES* for ways to limit how often the menu 126is generated to speed things up. 127 128--enable-mini-icons:: 129 This option enables mini-icons in the menus. If set, 24x24 mini-icons 130 are used. If the specified icon isn't that size it will be converted 131 if *ImageMagick* is installed and saved in $HOME/.fvwm/icons or to the 132 directory specified with --mini-icon-dir option. Otherwise no icon 133 appears in the menu for that entry. With most distributions, all the 134 menu entries will have mini-icons appropriate to the application. 135--theme NAME:: 136 Defines the used icon theme. Default is _gnome_ but all others found 137 in /usr/share/icons could be used except the _hicolor_ theme because 138 it's the default fallback theme if no icon is found. 139--size|-s NUM:: 140 If --enable-mini-icons is used the _size_ of the icons can changed 141 with this parameter. Default is 24. 142--mini-icon-dir DIR:: 143 When the right size mini-icon isn't available, fvwm-menu-desktop 144 creates icons with the right size in $HOME/.fvwm/icons. If you don't 145 want to use the default directory, $HOME/.fvwm/icons, use this option 146 to specify a different folder. 147--app-icon NAME:: 148 Sets the default application icon if no others are found. Default is 149 'gnome-applications'. 150--dir-icon NAME:: 151 Sets the default directory icon if no others are found. Default is 152 'gnome-fs-directory'. 153 154== USAGE 155 156*fvwm-menu-desktop* outputs XDG .menu files in the syntax of fvwm menus. 157When *fvwm-menu-desktop* is run with no options, it will load defaults 158from the *FvwmForm-XDGMenu-Config* file (see below) then search your 159system for suitable menu file(s). To see which menus are available on 160your system run: 161 162.... 163fvwm-menu-desktop --get-menus all 164.... 165 166If no menus are found you may not have any installed on your system. By 167default menus are stored as *.menu files in /etc/xdg/menus, 168$HOME/.config/menus or the location set in $XDG_MENU_PREFIX. You can use 169*--install-prefix* to specify another location search for menus. 170 171Though a combination of command line options and the 172*FvwmForm-XDGMenu-Config* settings, *fvwm-menu-desktop* can generate any 173combination of the menus found. To get a list of what menu(s) would be 174generated use the *--get-menus* _desktop_ option. The following will 175list all menus generated if *fvwm-menu-desktop* was run with no options. 176 177.... 178fvwm-menu-desktop --get-menus desktop 179.... 180 181*fvwm-menu-desktop* determines which menu(s) to generate as follows 182 183If no config file is found, all menus will be weighted and the script 184will generate the best (highest weight) menu found. 185 186If a config file is found (and override options are not used) the script 187will generate all menus selected in *FvwmForm-XDGMenu-Config*. 188 189*--desktop*, *--menu-type*, *--set-menus* and *--all-menus* will 190override any menus selected in *FvwmForm-XDGMenu-Config*. 191 192*--desktop* and *--menu-type* will only include menus whose name matches 193'*desktop*menutype*'. If used with *--all-menus*, all matching menus are 194generated. If used without *--all-menus*, only the highest weighted menu 195is generated. 196 197*--set-menus* generates menus from the list of full path menu file 198names. 199 200*--all-menus* by itself will generate all menus found. 201 202By default *fvwm-menu-desktop* will generate a menu whose top level name 203is "XDGMenu". To tell fvwm to read the output of *fvwm-menu-desktop* to 204create the menu XDGMenu add the following to your fvwm config file: 205 206.... 207PipeRead 'fvwm-menu-desktop' 208.... 209 210*Warning:* Depending on the options used this command may be slow and 211fvwm will pause until this command is complete. See *EXAMPLES* below for 212more details and possible workarounds. 213 214Once the menu is generated you can open the menu by using the command 215"Menu XDGMenu". You can also include this in the MenuFvwmRoot menu by: 216 217.... 218AddToMenu MenuFvwmRoot "XDG Menu" Popup XDGMenu 219.... 220 221*fvwm-menu-desktop* can be configured though both command line options 222and a *FvwmForm* GUI to customize the menu(s) that get generated. 223 224== GUI 225 226*FvwmForm-XDGMenu-Config* is a *FvwmForm* interface that can be used to 227configure the defaults for *fvwm-menu-desktop*. You can access this from 228the "Configure" item in the top level menu that is generated or run the 229following from within *FvwmConsole* 230 231.... 232Module FvwmPerl -l fvwm-menu-desktop-config.fpl 233.... 234 235This form can be used to select which menu(s) get generated by default 236along with setting many (but not all) of the available options. When you 237click "Save Settings" the form will write a config file located at 238$FVWM_USERDIR/.FvwmForm-XDGMenu-Config that *fvwm-menu-desktop* will 239parse for defaults when run. 240 241See the help inside of *FvwmForm-XDGMenu-Config* for more information. 242 243== EXAMPLES 244 245There are many ways to setup when fvwm runs *fvwm-menu-desktop* to 246generate the menu. One method is to just generate the menu when fvwm 247loads and then use the GUI config tool to change any options. To do this 248you only need to add the following to the fvwm config file: 249 250.... 251AddToMenu MenuFvwmRoot "XDG Menu" Popup XDGMenu PipeRead 252'fvwm-menu-desktop' 253.... 254 255The menu is created once when fvwm loads. Since menu creation can 256sometimes be slow, this could cause fvwm to take longer to load than one 257wants. 258 259The menu is only generated when fvwm starts. If software is installed or 260removed you will have to select the 'Regenerate' option to rebuild the 261menu. 262 263One way to speed things up is to save the menu in a file and only 264generate the menu when 'Regenerate' is selected. To do this use 265*--regen-cmd* to call a custom function and write the menu to a file 266using a command like 267 268.... 269fvwm-menu-desktop --regen-cmd XDGRegen > $FVWM_USERDIR/.XDGMenu 270.... 271 272Then add the following to the fvwm config file to define the function 273XDGRegen. The second to last line will generate the menu if the menu 274file doesn't exist when fvwm starts. 275 276.... 277DestroyFunc XDGRegen 278AddToFunc XDGRegen 279+ I PipeRead 'fvwm-menu-desktop --regen-cmd XDGRegen > \ 280 $[FVWM_USERDIR]/.XDGMenu; echo "Nop"' 281+ I Read $[FVWM_USERDIR]/.XDGMenu 282 283Test (!f $[FVWM_USERDIR]/.XDGMenu) XDGRegen Read $[FVWM_USERDIR]/.XDGMenu 284.... 285 286Besides creating a top level menu, *fvwm-menu-desktop* can insert the 287menu into an existing menu using the *--insert-in-menu* option. For 288example one could create the menu MenuFvwmRoot and include the XDG items 289at the end. 290 291.... 292DestroyMenu MenuFvwmRoot 293AddToMenu MenuFvwmRoot "Fvwm" Title 294+ "Item1" Action1 ... 295+ "ItemN" ActionN 296+ "" Nop 297 298PipeRead 'fvwm-menu-desktop --insert-in-menu MenuFvwmRoot' 299.... 300 301In this case the menu items are inserted at the end of the MenuFvwmRoot 302menu. If no items are in the menu, this menu becomes MenuFvwmRoot. The 303problem here is, that you have to restart fvwm or rebuild the whole menu 304to Regenerate it because menu items cannot be removed. To do this you 305could use a function like 306 307.... 308DestroyFunc XDGRegen 309AddToFunc XDGRegen 310+ I DestroyMenu MenuFvwmRoot 311+ I AddToMenu MenuFvwmRoot "Fvwm" Title 312+ I AddToMenu MenuFvwmRoot "Item1" Action1 ... 313+ I AddToMenu MenuFvwmRoot "ItemN" ActionN 314+ I AddToMenu MenuFvwmRoot "" Nop 315+ I PipeRead 'fvwm-menu-desktop --insert-in-menu MenuFvwmRoot \ 316 --regen-cmd XDGRegen' 317.... 318 319Fvwm can also create menus dynamically by using *DynamicPopUpAction* 320and/or *DynamicPopDownAction*. These commands when used with a Menu will 321run a Function when the menu is opened. For example one could create the 322menu XDGMenu when it is opened using 323 324.... 325AddToMenu XDGMenu "XDGMenu" Title 326+ DynamicPopUpAction PipeRead 'fvwm-menu-desktop' 327.... 328 329This will create the menu when it is opened. One issue here is it will 330only create the menu the first time it is opened, and you still have to 331Regenerate the menu to see any changes. To create the menu each time it 332is open used the *--dynamic* option 333 334.... 335AddToMenu XDGMenu "XDGMenu" Title 336+ DynamicPopUpAction PipeRead 'fvwm-menu-desktop \ 337 --dynamic --include-items config' 338+ DynamicPopDownAction DestroyMenu recreate XDGMenu 339.... 340 341This will now Destroy the menu when it closed so it can be rebuilt the 342next time it is opened. The recreate flag doesn't completely destroy the 343menu keeping the DynamicPopUpAction and DynamicPopDownAction actions. 344The *--dynamic* flag includes the recreate option in the generated 345menus. 346 347To insert a menu into MenuFvwmRoot and still be dynamic you need to use 348a function that generates the whole menu. For example 349 350.... 351DestroyFunc GenRootMenu 352AddToFunc GenRootMenu 353+ I DestroyMenu recreate MenuFvwmRoot 354+ I AddToMenu MenuFvwmRoot "Fvwm" Title 355+ I AddToMenu MenuFvwmRoot "Item1" Action1 ... 356+ I AddToMenu MenuFvwmRoot "ItemN" ActionN 357+ I AddToMenu MenuFvwmRoot "" Nop 358+ PipeRead `fvwm-menu-desktop --insert-in-menu MenuFvwmRoot \ 359 --include-items config` 360 361AddToMenu MenuFvwmRoot "Fvwm" Title 362+ DynamicPopUpAction GenRootMenu 363+ DynamicPopDownAction DestroyMenu recreate MenuFvwmRoot 364.... 365 366== BUGS 367 368The whole process of creating menus from files is slow. Otherwise report 369bugs to the fvwm-workers mailing list <fvwm-workers@fvwm.org>. 370 371== AUTHORS 372 373This script is based on fvwm-xdg-menu.py written by Piotr Zielinski 374(http://www.cl.cam.ac.uk/~pz215/) who assigned Licence: GPL 2 Date: 37503.12.2005. 376 377The script was reworked to replace the existing fvwm-menu-desktop perl 378script by the fvwm-workers. 379 380== COPYING 381 382The script is distributed by the same terms as fvwm itself. See GNU 383General Public License for details. 384