doc/commands/AddToMenu.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: AddToMenu.xml,v 1.4 2007/06/16 12:38:45 griph Exp $ -->
   3 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   4   "../docbook-xml/docbookx.dtd"
   5 [
   6 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   7 %myents;
   8 ]>
   9
  10
  11 <section id='addtomenu'>
  12 <title>AddToMenu</title>
  13
  14 <cmdsynopsis>
  15         <command>AddToMenu</command
  16         ><arg choice='plain'
  17                 ><replaceable>menu-name</replaceable
  18         ></arg
  19         ><arg choice='opt'
  20                 ><replaceable>menu-label</replaceable
  21                 > <replaceable>action</replaceable
  22         ></arg>
  23 </cmdsynopsis>
  24
  25 <para>Begins or adds to a menu definition.  Typically a menu definition
  26 looks like this:</para>
  27
  28 <programlisting>
  29 AddToMenu Utilities Utilities <fvwmref cmd="Title"/>
  30  + Xterm           <fvwmref cmd="Exec"/>  exec xterm -e tcsh
  31  + Rxvt            <fvwmref cmd="Exec"/>  exec rxvt
  32  + "Remote Logins" <fvwmref cmd="Popup"/> Remote-Logins
  33  + Top             <fvwmref cmd="Exec"/>  exec rxvt -T Top -n Top -e top
  34  + Calculator      <fvwmref cmd="Exec"/>  exec xcalc
  35  + Xman            <fvwmref cmd="Exec"/>  exec xman
  36  + Xmag            <fvwmref cmd="Exec"/>  exec xmag
  37  + emacs           <fvwmref cmd="Exec"/>  exec xemacs
  38  + Mail            MailFunction xmh "-font fixed"
  39  + ""              <fvwmref cmd="Nop"/>
  40  + Modules         <fvwmref cmd="Popup"/> Module-Popup
  41  + ""              <fvwmref cmd="Nop"/>
  42  + Exit Fvwm       <fvwmref cmd="Popup"/> Quit-Verify
  43 </programlisting>
  44
  45 <para>The menu could be invoked via</para>
  46
  47 <programlisting>
  48 <fvwmref cmd="Mouse"/> 1 R A <fvwmref cmd="Menu"/> Utilities Nop
  49 </programlisting>
  50
  51 <para>or</para>
  52
  53 <programlisting>
  54 <fvwmref cmd="Mouse"/> 1 R A <fvwmref cmd="Popup"/> Utilities
  55 </programlisting>
  56
  57 <para>There is no end-of-menu symbol.  Menus do not have to be defined
  58 in a contiguous region of the
  59 <filename>config</filename>
  60 file.  The quoted (or first word)
  61 portion in the above examples is the menu label,
  62 which appears in the menu when the user pops it up.  The remaining
  63 portion is an fvwm command which is executed if the user
  64 selects that menu item.  An empty menu-label ("") and the
  65 <fvwmref cmd="Nop"/>
  66 function are used to insert a separator into the menu.</para>
  67
  68 <para>The keywords
  69 <fvwmopt cmd="AddToMenu" opt="DynamicPopUpAction"/>
  70 and
  71 <fvwmopt cmd="AddToMenu" opt="DynamicPopDownAction"/>
  72 have a special meaning when used as the name of a menu item.  The
  73 action following the keyword is executed whenever the menu is
  74 popped up or down.  This way you can implement dynamic menus.  It
  75 is even possible to destroy itself with
  76 <fvwmref cmd="DestroyMenu"/>
  77 and the rebuild from scratch.  When the menu has been destroyed
  78 (unless you used the
  79 <fvwmref cmd="DestroyMenu" opt="recreate"/>
  80 option when destroying the menu), do not forget to add the dynamic
  81 action again.</para>
  82
  83 <para>Note: Do not trigger actions that require user interaction. They
  84 may fail and may screw up your menus.  See the
  85 <fvwmref cmd="Silent"/>
  86 command.</para>
  87
  88 <warning>Do not issue
  89 <fvwmref cmd="MenuStyle"/>
  90 commands as dynamic menu actions.  Chances are good that this
  91 crashes fvwm.</warning>
  92
  93
  94 <!-- TODO: add links to utility programs -->
  95 <para>There are several configurable scripts installed together with fvwm
  96 for automatic menu generation.  They have their own man pages.
  97 Some of them, specifically
  98 <command>fvwm-menu-directory</command> and
  99 <command>fvwm-menu-desktop</command>, may be used with
 100 <fvwmopt cmd="AddToMenu" opt="DynamicPopupAction"/>
 101 to create a directory listing or <acronym>GNOME</acronym>/<acronym>KDE</acronym>
 102 application listing.</para>
 103
 104 <para>Example (File browser):</para>
 105
 106 <programlisting>
 107 # You can find the shell script fvwm_make_browse_menu.sh
 108 # in the utils/ directory of the distribution.
 109 AddToMenu BrowseMenu
 110 + DynamicPopupAction <fvwmref cmd="PipeRead"/> \
 111   'fvwm_make_browse_menu.sh BrowseMenu'
 112 </programlisting>
 113
 114 <para>Example (Picture menu):</para>
 115
 116 <programlisting>
 117 # Build a menu of all .jpg files in
 118 # $HOME/Pictures
 119 AddToMenu JpgMenu foo title
 120 + DynamicPopupAction <fvwmref cmd="Function"/> MakeJpgMenu
 121
 122 <fvwmref cmd="AddToFunc"/> MakeJpgMenu
 123 + I <fvwmref cmd="DestroyMenu"/> recreate JpgMenu
 124 + I AddToMenu JpgMenu Pictures <fvwmref cmd="Title"/>
 125 + I <fvwmref cmd="PipeRead"/> 'for i in <envar>$HOME</envar>/Pictures/*.jpg; \
 126   do echo AddToMenu JpgMenu "`basename $i`" <fvwmref cmd="Exec"/> xv $i; done'
 127 </programlisting>
 128
 129 <para>The keyword
 130 <fvwmopt cmd="AddToMenu" opt="MissingSubmenuFunction"/>
 131 has a similar meaning.  It is executed whenever you try to pop up
 132 a sub menu that does not exist.  With this function you can define
 133 and destroy menus on the fly.  You can use any command after the
 134 keyword, but if the name of an item (that is a submenu) defined with
 135 <fvwmref cmd="AddToFunc"/>
 136 follows it, fvwm executes this command:</para>
 137
 138 <programlisting><fvwmref cmd="Function"/> &lt;function-name&gt; &lt;submenu-name&gt;</programlisting>
 139
 140 <para>i.e. the name is passed to the function as its first argument and
 141 can be referred to with "$0".</para>
 142
 143 <para>The
 144 <command>fvwm-menu-directory</command>
 145 script mentioned above may be used with
 146 <emphasis remap='I'>MissingSubmenuFunction</emphasis>
 147 to create an up to date recursive directory listing.</para>
 148
 149 <para>Example:</para>
 150
 151 <programlisting>
 152 # There is another shell script fvwm_make_directory_menu.sh
 153 # in the utils/ directory of the distribution. To use it,
 154 # define this function in your configuration file:
 155
 156 <fvwmref cmd="DestroyFunc"/> MakeMissingDirectoryMenu
 157 <fvwmref cmd="AddToFunc"/> MakeMissingDirectoryMenu
 158 + I <fvwmref cmd="PipeRead"/> fvwm_make_directory_menu.sh $0
 159
 160 <fvwmref cmd="DestroyMenu"/> SomeMenu
 161 AddToMenu SomeMenu
 162 + MissingSubmenuFunction MakeMissingDirectoryMenu
 163 + "Root directory" <fvwmref cmd="Popup"/> /
 164 </programlisting>
 165
 166 <para>This is another implementation of the file browser that uses
 167 sub menus for subdirectories.</para>
 168
 169 <para>Titles can be used within the menu. If you add the option
 170 <fvwmopt cmd="AddToMenu" opt="top"/>
 171 behind the keyword
 172 <fvwmref cmd="Title"/>,
 173 the title is added to the top of the menu.  If there was a title
 174 already, it is overwritten.</para>
 175
 176 <programlisting>AddToMenu Utilities Tools Title top</programlisting>
 177
 178 <para>All text up to the first
 179 <keysym>Tab</keysym>
 180 in the menu label is aligned to the left side of the menu, all
 181 text right of the first
 182 <keysym>Tab</keysym>
 183 is aligned to the left in a second column and all text thereafter
 184 is placed right aligned in the third column.  All other
 185 <keysym>Tab</keysym>s
 186 are replaced by spaces.  Note that you can change this format with
 187 the
 188 <fvwmref cmd="MenuStyle" opt="ItemFormat"/>
 189 option of the
 190 <fvwmref cmd="MenuStyle"/>
 191 command.</para>
 192
 193 <para>If the menu-label contains an ampersand ('&amp;'), the next character
 194 is taken as a hot-key for the menu item.  Hot-keys are underlined
 195 in the label.  To get a literal '&amp;', insert "&amp;&amp;".  Pressing the
 196 hot-key moves through the list of menu items with this hot-key or
 197 selects an item that is the only one with this hot-key.</para>
 198
 199 <para>If the menu-label contains a sub-string which is set off by stars,
 200 then the text between the stars is expected to be the name of an
 201 image file to insert in the menu.  To get a literal '*', insert "**".  For example</para>
 202
 203 <programlisting>+ Calculator*xcalc.xpm* <fvwmref cmd="Exec"/> exec xcalc</programlisting>
 204
 205 <para>inserts a menu item labeled "Calculator" with a picture of a
 206 calculator above it.  The following:</para>
 207
 208 <programlisting>+ *xcalc.xpm*           <fvwmref cmd="Exec"/> exec xcalc</programlisting>
 209
 210 <para>Omits the "Calculator" label, but leaves the picture.</para>
 211
 212 <para>If the menu-label contains a sub-string which is set off by
 213 percent signs, then the text between the percent signs is expected
 214 to be the name of image file (a so called mini icon to insert to
 215 the left of the menu label.  A second mini icon that is drawn at
 216 the right side of the menu can be given in the same way.  To get a
 217 literal '%', insert "%%". For example</para>
 218
 219 <programlisting>+ Calculator%xcalc.xpm% <fvwmref cmd="Exec"/> exec xcalc</programlisting>
 220
 221 <para>inserts a menu item labeled "Calculator" with a picture of a
 222 calculator to the left.  The following:</para>
 223
 224 <programlisting>+ %xcalc.xpm%           <fvwmref cmd="Exec"/> exec xcalc</programlisting>
 225
 226 <para>Omits the "Calculator" label, but leaves the picture.  The
 227 pictures used with this feature should be small (perhaps 16x16).</para>
 228
 229 <para>If the menu-name (not the label) contains a sub-string which is
 230 set off by at signs ('@'), then the text between them is expected
 231 to be the name of an image file to draw along the left
 232 side of the menu (a side pixmap).  You may want to use the
 233 <fvwmref cmd="MenuStyle" opt='SidePic' />
 234 option of the
 235 <fvwmref cmd="MenuStyle"/>
 236 command instead.  To get a literal '@', insert "@@".  For example</para>
 237
 238 <programlisting>AddToMenu StartMenu@linux-menu.xpm@</programlisting>
 239
 240 <para>creates a menu with a picture in its bottom left corner.</para>
 241
 242 <para>If the menu-name also contains a sub-string surrounded by '^'s, then
 243 the text between '^'s is expected to be the name of an X11 color
 244 and the column containing the side picture is colored with that
 245 color.  You can set this color for a menu style using the
 246 <fvwmref cmd="MenuStyle" opt="SideColor"/>
 247 option of the
 248 <fvwmref cmd="MenuStyle"/>
 249 command.  To get a literal '^', insert "^^".  Example:</para>
 250
 251 <programlisting>AddToMenu StartMenu@linux-menu.xpm@^blue^</programlisting>
 252
 253 <para>creates a menu with a picture in its bottom left corner and
 254 colors with blue the region of the menu containing the picture.</para>
 255
 256 <para>In all the above cases, the name of the resulting menu is name
 257 specified, stripped of the substrings between the various
 258 delimiters.</para>
 259
 260 </section>