1fvwm-menu-desktop(1)             Fvwm Modules             fvwm-menu-desktop(1)
2
3
4

NAME

6       fvwm-menu-desktop - Reads XDG menu files and creates Fvwm menus
7
8

SYNOPSIS

10       fvwm-menu-desktop  [ --help|-h ] [ --version ] [ --install-prefix DIR ]
11       [ --desktop NAME ] [ --menu-type NAME ] [ --theme NAME ]  [  --with-ti‐
12       tles|-w  ] [ --without-titles ] [ --enable-mini-icons ] [ --size|-s NUM
13       ] [ --mini-icon-dir DIR ] [ --app-icon NAME ] [  --dir-icon  NAME  ]  [
14       --title|-t NAME ] [ --insert-in-menu NAME ] [ --get-menus all|desktop ]
15       [ --set-menus menu_paths ] [ --all-menus ] [ --include-items NAME  ]  [
16       --regen-cmd  CMD ] [ --term-cmd CMD ] [ --dynamic ] [ --menu-error|-e ]
17       [ --verbose|-v ]
18
19
20

DESCRIPTION

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

OPTIONS

28       Main Options
29
30
31       --help Show the help and exit.
32
33
34       --version
35              Show the version and exit.
36
37
38       --get-menus all|desktop
39              Prints  a  space  separated list of full menu paths found on the
40              system.  all will print all menus found  on  the  system  except
41              empty ones.  desktop will print the menu(s) that would be gener‐
42              ated by the script.
43
44              No menu generation is done.
45
46
47       --desktop NAME
48              Optional parameter to set the NAME  of  the  desktop  XDG  .menu
49              file(s)  to use. This option will override any default menus set
50              via FvwmForm-XDGMenu-Config and cause the script to  find  menus
51              in  which  NAME is a part of the file name.  Possible names are:
52              gnome, kde, xfce, lxde, debian, etc.
53
54              This option can be used in conjunction with --menu-type to  con‐
55              trol which .menu file(s) are used.
56
57
58       --menu-type NAME
59              Optional  parameter to set the NAME of the XDG menu type to use.
60              This option will override any default menus  set  via  FvwmForm-
61              XDGMenu-Config  and cause the script to find menus in which NAME
62              is a part of the file name.  Possible NAME types could  be:  ap‐
63              plications, settings, preferences, etc.
64
65              When  used  in conjunction with --desktop, only menus whose file
66              name matches '*destkop*menutype*' are found.  If  no  menus  are
67              found, the script exits with an error.
68
69
70       --all-menus
71              This option will build all menus found on the system. If used in
72              conjunction with --desktop or --menu-type this  will  build  all
73              menus matching those settings.
74
75
76       --install-prefix DIR
77              Optional  parameter  to  override the standard locations for XDG
78              menu definitions. Tells fvwm-menu-desktop to  look  in  DIR  for
79              .menu  files  instead  of  the standard locations /etc/xdg/menus
80              (and $HOME/.config/menus if it exists).
81
82
83       --with-titles|-w
84              If this option is set menus are generated with titles.  This  is
85              the  default.  This option can be used to override the FvwmForm-
86              XDGMenu-Config default setting.
87
88
89       --without-titles
90              If this option is set menus are generated  without  titles.  The
91              default is to generate with titles.
92
93
94       --title|-t NAME
95              Option  to  define  the  menu title NAME of the top menu used by
96              Fvwm's Menu or Popup commands. Default is "XDGMenu".
97
98
99       --include-items NAME
100              This option controls if the additional menu  items  'Regenerate'
101              and  'Configure' are included in the top level menu. NAME can be
102              one of regenerate, config, both, or none. The default is both.
103
104
105       --regen-cmd CMD
106              This option sets the fvwm command CMD that is run when the  menu
107              item  'Regenerate'  is selected. The default is "PipeRead `fvwm-
108              menu-desktop`".
109
110
111       --term-cmd CMD
112              This option sets the terminal emulator command CMD that is  used
113              to to run terminal applications in. CMD needs to end with an ex‐
114              ecute option, such as xterm's -e option, which will run the com‐
115              mand that is appended to CMD. The default is "xterm -e".
116
117
118       --dynamic
119              This  option is to be used with creating dynamic menus using Dy‐
120              namicPopUpAction and DynamicPopDownAction. This adds  a  'recre‐
121              ate'  to  the DestroyMenu command on the top level menu so those
122              actions are not Destroyed when the menu is regenerated.
123
124
125       --insert-in-menu NAME
126              Option to insert generated menu(s) IN a menu NAME (its  top  ti‐
127              tle).  This  option  makes  it  so the top level menu is not De‐
128              stroyed and the items are added to the end.
129
130              Note menus regenerated with this option  will  append  the  menu
131              items at the end of the existing menu. Each time the menu is re‐
132              generated new menu items appear giving a growing menu of  dupli‐
133              cate  items.   You have to regenerate the whole menu via a func‐
134              tion or restart fvwm. See EXAMPLES below for some solutions.
135
136
137       --set-menus menu_paths
138              Generates all menus listed in a space  separated  list  of  full
139              menu  paths.   This  option  overrides  any defaults and --desk‐
140              top|--menu-type settings.
141
142
143       --menu-error |-t
144              If this option is present  and  python-xdg  is  not  found,  the
145              script  will  print the error in the generated menu. Used in the
146              default-config.
147
148
149       --verbose
150              Enables additional information printouts on STDERR.
151
152
153       Icons Options
154
155              By default, fvwm-menu-desktop builds menus  without  mini-icons.
156              To enable mini-icons use the following options.
157
158              If  ImageMagick  is installed on the system, the script will re‐
159              size and copy the icons to $FVWM_USERDIR/.icons. This  can  take
160              awhile. You should be prepared to wait the first time you gener‐
161              ate the icons. Once the icons have  been  generated  the  script
162              should run faster. If it is still to slow using icons, see EXAM‐
163              PLES for ways to limit how often the menu is generated to  speed
164              things up.
165
166
167       --enable-mini-icons
168              This option enables mini-icons in the menus. If set, 24x24 mini-
169              icons are used. If the specified icon isn't that size it will be
170              converted   if   ImageMagick   is   installed   and   saved   in
171              $HOME/.fvwm/icons   or   to   the   directory   specified   with
172              --mini-icon-dir  option.  Otherwise  no icon appears in the menu
173              for that entry.  With most distributions, all the  menu  entries
174              will have mini-icons appropriate to the application.
175
176
177       --theme NAME
178              Defines  the  used  icon  theme. Default is gnome but all others
179              found in /usr/share/icons could be used except the hicolor theme
180              because it's the default fallback theme if no icon is found.
181
182
183       --size|-s NUM
184              If --enable-mini-icons is used the size of the icons can changed
185              with this parameter. Default is 24.
186
187
188       --mini-icon-dir DIR
189              When the right size mini-icon isn't available, fvwm-menu-desktop
190              creates  icons with the right size in $HOME/.fvwm/icons.  If you
191              don't want to use the default directory, $HOME/.fvwm/icons,  use
192              this option to specify a different folder.
193
194
195       --app-icon NAME
196              Sets  the  default  application icon if no others are found. De‐
197              fault is 'gnome-applications'.
198
199
200       --dir-icon NAME
201              Sets the default directory icon if no others are found.  Default
202              is 'gnome-fs-directory'.
203
204

USAGE

206       fvwm-menu-desktop  outputs XDG .menu files in the syntax of fvwm menus.
207       When fvwm-menu-desktop is run with no options, it  will  load  defaults
208       from the FvwmForm-XDGMenu-Config file (see below) then search your sys‐
209       tem for suitable menu file(s). To see which menus are available on your
210       system run:
211
212              fvwm-menu-desktop --get-menus all
213
214       If no menus are found you may not have any installed on your system. By
215       default menus are stored as *.menu files in /etc/xdg/menus, $HOME/.con‐
216       fig/menus  or  the  location set in $XDG_MENU_PREFIX. You can use --in‐
217       stall-prefix to specify another location search for menus.
218
219       Though a combination of command line options and the  FvwmForm-XDGMenu-
220       Config  settings, fvwm-menu-desktop can generate any combination of the
221       menus found. To get a list of what menu(s) would be generated  use  the
222       --get-menus desktop option. The following will list all menus generated
223       if fvwm-menu-desktop was run with no options.
224
225              fvwm-menu-desktop --get-menus desktop
226
227       fvwm-menu-desktop determines which menu(s) to generate as follows
228
229              If no config file is found, all menus will be weighted  and  the
230              script will generate the best (highest weight) menu found.
231
232              If  a  config  file is found (and override options are not used)
233              the script will generate all menus selected in FvwmForm-XDGMenu-
234              Config.
235
236              --desktop,  --menu-type,  --set-menus and --all-menus will over‐
237              ride any menus selected in FvwmForm-XDGMenu-Config.
238
239              --desktop and --menu-type will only  include  menus  whose  name
240              matches  '*desktop*menutype*'.  If  used  with  --all-menus, all
241              matching menus are generated. If used without --all-menus,  only
242              the highest weighted menu is generated.
243
244              --set-menus generates menus from the list of full path menu file
245              names.
246
247              --all-menus by itself will generate all menus found.
248
249       By default fvwm-menu-desktop will generate a menu whose top level  name
250       is  "XDGMenu".  To tell fvwm to read the output of fvwm-menu-desktop to
251       create the menu XDGMenu add the following to your fvwm config file:
252
253              PipeRead 'fvwm-menu-desktop'
254
255       Warning: Depending on the options used this command  may  be  slow  and
256       fvwm  will pause until this command is complete. See EXAMPLES below for
257       more details and possible workarounds.
258
259       Once the menu is generated you can open the menu by using  the  command
260       "Menu XDGMenu". You can also include this in the MenuFvwmRoot menu by:
261
262              AddToMenu MenuFvwmRoot "XDG Menu" Popup XDGMenu
263
264       fvwm-menu-desktop  can  be  configured though both command line options
265       and a FvwmForm GUI to customize the menu(s) that get generated.
266
267

GUI

269       FvwmForm-XDGMenu-Config is a FvwmForm interface that  can  be  used  to
270       configure  the defaults for fvwm-menu-desktop. You can access this from
271       the "Configure" item in the top level menu that is generated or run the
272       following from within FvwmConsole
273
274              Module FvwmPerl -l fvwm-menu-desktop-config.fpl
275
276       This  form can be used to select which menu(s) get generated by default
277       along with setting many (but not all) of the  available  options.  When
278       you  click "Save Settings" the form will write a config file located at
279       $FVWM_USERDIR/.FvwmForm-XDGMenu-Config  that   fvwm-menu-desktop   will
280       parse for defaults when run.
281
282       See the help inside of FvwmForm-XDGMenu-Config for more information.
283
284
285

EXAMPLES

287       There are many ways to setup when fvwm runs fvwm-menu-desktop to gener‐
288       ate the menu. One method is to just generate the menu when  fvwm  loads
289       and then use the GUI config tool to change any options.  To do this you
290       only need to add the following to the fvwm config file:
291
292              AddToMenu MenuFvwmRoot "XDG Menu" Popup XDGMenu
293              PipeRead 'fvwm-menu-desktop'
294
295       The menu is created once when fvwm loads. Since menu creation can some‐
296       times  be  slow,  this could cause fvwm to take longer to load than one
297       wants.
298
299       The menu is only generated when fvwm starts. If software  is  installed
300       or  removed  you will have to select the 'Regenerate' option to rebuild
301       the menu.
302
303       One way to speed things up is to save the menu in a file and only  gen‐
304       erate  the  menu when 'Regenerate' is selected. To do this use --regen-
305       cmd to call a custom function and write the menu to a file using a com‐
306       mand like
307
308              fvwm-menu-desktop --regen-cmd XDGRegen > $FVWM_USERDIR/.XDGMenu
309
310       Then  add  the following to the fvwm config file to define the function
311       XDGRegen. The second to last line will generate the menu  if  the  menu
312       file doesn't exist when fvwm starts.
313
314              DestroyFunc XDGRegen
315              AddToFunc XDGRegen
316              + I PipeRead 'fvwm-menu-desktop --regen-cmd XDGRegen > \
317                  $[FVWM_USERDIR]/.XDGMenu; echo "Nop"'
318              + I Read $[FVWM_USERDIR]/.XDGMenu
319
320              Test (!f $[FVWM_USERDIR]/.XDGMenu) XDGRegen
321              Read $[FVWM_USERDIR]/.XDGMenu
322
323       Besides  creating  a  top  level menu, fvwm-menu-desktop can insert the
324       menu into an existing menu using the --insert-in-menu option. For exam‐
325       ple one could create the menu MenuFvwmRoot and include the XDG items at
326       the end.
327
328              DestroyMenu MenuFvwmRoot
329              AddToMenu MenuFvwmRoot "Fvwm" Title
330              + "Item1" Action1
331                ...
332              + "ItemN" ActionN
333              + "" Nop
334              PipeRead 'fvwm-menu-desktop --insert-in-menu MenuFvwmRoot'
335
336       In this case the menu items are inserted at the end of the MenuFvwmRoot
337       menu.  If no items are in the menu, this menu becomes MenuFvwmRoot. The
338       problem here is, that you have to restart fvwm  or  rebuild  the  whole
339       menu to Regenerate it because menu items cannot be removed.  To do this
340       you could use a function like
341
342              DestroyFunc XDGRegen
343              AddToFunc XDGRegen
344              + I DestroyMenu MenuFvwmRoot
345              + I AddToMenu MenuFvwmRoot "Fvwm" Title
346              + I AddToMenu MenuFvwmRoot "Item1" Action1
347                ...
348              + I AddToMenu MenuFvwmRoot "ItemN" ActionN
349              + I AddToMenu MenuFvwmRoot "" Nop
350              + I PipeRead 'fvwm-menu-desktop --insert-in-menu MenuFvwmRoot \
351                            --regen-cmd XDGRegen'
352
353       Fvwm can also create  menus  dynamically  by  using  DynamicPopUpAction
354       and/or  DynamicPopDownAction. These commands when used with a Menu will
355       run a Function when the menu is opened. For example  one  could  create
356       the menu XDGMenu when it is opened using
357
358              AddToMenu XDGMenu "XDGMenu" Title
359              + DynamicPopUpAction PipeRead 'fvwm-menu-desktop'
360
361       This  will create the menu when it is opened. One issue here is it will
362       only create the menu the first time it is opened, and you still have to
363       Regenerate the menu to see any changes. To create the menu each time it
364       is open used the --dynamic option
365
366              AddToMenu XDGMenu "XDGMenu" Title
367              + DynamicPopUpAction PipeRead 'fvwm-menu-desktop \
368                                   --dynamic --include-items config'
369              + DynamicPopDownAction DestroyMenu recreate XDGMenu
370
371       This will now Destroy the menu when it closed so it can be rebuilt  the
372       next  time  it  is opened. The recreate flag doesn't completely destroy
373       the menu keeping the DynamicPopUpAction  and  DynamicPopDownAction  ac‐
374       tions.   The  --dynamic flag includes the recreate option in the gener‐
375       ated menus.
376
377       To insert a menu into MenuFvwmRoot and still be dynamic you need to use
378       a function that generates the whole menu. For example
379
380              DestroyFunc GenRootMenu
381              AddToFunc GenRootMenu
382              + I DestroyMenu recreate MenuFvwmRoot
383              + I AddToMenu MenuFvwmRoot "Fvwm" Title
384              + I AddToMenu MenuFvwmRoot "Item1" Action1
385                ...
386              + I AddToMenu MenuFvwmRoot "ItemN" ActionN
387              + I AddToMenu MenuFvwmRoot "" Nop
388              + PipeRead `fvwm-menu-desktop --insert-in-menu MenuFvwmRoot \
389                         --include-items config`
390
391              AddToMenu MenuFvwmRoot "Fvwm" Title
392              + DynamicPopUpAction GenRootMenu
393              + DynamicPopDownAction DestroyMenu recreate MenuFvwmRoot
394
395

BUGS

397       The  whole process of creating menus from files is slow.  Otherwise re‐
398       port bugs to the fvwm-workers mailing list <fvwm-workers@fvwm.org>.
399
400
401

AUTHORS

403       This script is based on fvwm-xdg-menu.py  written  by  Piotr  Zielinski
404       (http://www.cl.cam.ac.uk/~pz215/)  who  assigned  Licence:  GPL 2 Date:
405       03.12.2005.
406
407       The script was reworked to replace the existing fvwm-menu-desktop  perl
408       script by the fvwm-workers.
409
410
411

COPYING

413       The  script  is  distributed  by the same terms as fvwm itself. See GNU
414       General Public License for details.
415
416
417
4183rd Berkeley Distribution   19 October 2022 (2.7.0)       fvwm-menu-desktop(1)
Impressum