doc/commands/MenuStyle.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: MenuStyle.xml,v 1.7 2008/03/14 17:22:42 domivogt 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='MenuStyle'>
  12 <title>MenuStyle</title>
  13
  14 <cmdsynopsis>
  15         <command>MenuStyle</command
  16         ><arg choice='plain'
  17                 ><replaceable>stylename</replaceable
  18         ></arg
  19         ><arg choice='opt'
  20                 ><replaceable>options</replaceable
  21         ></arg>
  22 </cmdsynopsis>
  23
  24 <para>Sets a new menu style or changes a previously defined style.  The
  25 <replaceable>stylename</replaceable>
  26 is the style name; if it contains spaces or tabs it has to be
  27 quoted.  The name "*" is reserved for the default menu style. The
  28 default menu style is used for every menu-like object (e.g. the
  29 window created by the
  30 <fvwmref cmd="WindowList"/>
  31 command) that had not be assigned a style using the
  32 <fvwmref cmd="ChangeMenuStyle"/>.
  33 See also
  34 <fvwmref cmd="DestroyMenuStyle"/>.
  35 When using monochrome color options are ignored.</para>
  36
  37 <para><replaceable>options</replaceable>
  38 is a comma separated list containing some of the keywords
  39 Fvwm / Mwm / Win,
  40 BorderWidth,
  41 Foreground,
  42 Background,
  43 Greyed,
  44 HilightBack / !HilightBack,
  45 HilightTitleBack,
  46 ActiveFore / !ActiveFore,
  47 MenuColorset,
  48 ActiveColorset,
  49 GreyedColorset,
  50 TitleColorset,
  51 Hilight3DThick / Hilight3DThin / Hilight3DOff,
  52 Hilight3DThickness,
  53 Animation / !Animation,
  54 Font,
  55 TitleFont,
  56 MenuFace,
  57 PopupDelay,
  58 PopupOffset,
  59 TitleWarp / !TitleWarp,
  60 TitleUnderlines0 / TitleUnderlines1 / TitleUnderlines2,
  61 SeparatorsLong / SeparatorsShort,
  62 TrianglesSolid / TrianglesRelief,
  63 PopupImmediately / PopupDelayed,
  64 PopdownImmediately / PopdownDelayed,
  65 PopupActiveArea,
  66 DoubleClickTime,
  67 SidePic,
  68 SideColor,
  69 PopupAsRootMenu / PopupAsSubmenu / PopupIgnore / PopupClose,
  70 RemoveSubmenus / HoldSubmenus,
  71 SubmenusRight / SubmenusLeft,
  72 SelectOnRelease,
  73 ItemFormat,
  74 VerticalItemSpacing,
  75 VerticalMargins,
  76 VerticalTitleSpacing,
  77 AutomaticHotkeys / !AutomaticHotkeys,
  78 MouseWheel,
  79 ScrollOffPage / !ScrollOffPage,
  80 TrianglesUseFore / !TrianglesUseFore.</para>
  81
  82 <para>In the above list some options are listed as option pairs or
  83 triples with a '/' in between.  These options exclude each other.
  84 All paired options can be negated to have the effect of the
  85 counterpart option by prefixing ! to the option.</para>
  86
  87 <para>Some options are now negated by prefixing ! to the option. This
  88 is the preferred form for all such options. The other negative
  89 forms are now deprecated and will be removed in the future.</para>
  90
  91 <para>This is a list of MenuStyle deprecated negative options:
  92 ActiveForeOff, AnimationOff, AutomaticHotkeysOff, HilightBackOff,
  93 TitleWarpOff</para>
  94
  95 <para>
  96 <fvwmopt cmd="MenuStyle" opt="Fvwm"/>,
  97 <fvwmopt cmd="MenuStyle" opt="Mwm"/>,
  98 <fvwmopt cmd="MenuStyle" opt="Win"/>
  99 reset all options to the style with the same name in former
 100 versions of fvwm.  The default for new menu styles is
 101 <emphasis remap='I'>Fvwm</emphasis>
 102 style.  These options override all others except
 103 <emphasis remap='I'>Foreground</emphasis>, <emphasis remap='I'>Background</emphasis>, <emphasis remap='I'>Greyed</emphasis>, <emphasis remap='I'>HilightBack</emphasis>,
 104 <emphasis remap='I'>ActiveFore</emphasis> and <emphasis remap='I'>PopupDelay</emphasis>,
 105 so they should be used only as the first option specified for a
 106 menu style or to reset the style to defined behavior.  The same
 107 effect can be created by setting all the other options one by one.</para>
 108
 109 <para><emphasis remap='I'>Mwm</emphasis> and <emphasis remap='I'>Win</emphasis>
 110 style menus popup sub menus automatically.
 111 <emphasis remap='I'>Win</emphasis>
 112 menus indicate the current menu item by changing the background to
 113 dark.
 114 <emphasis remap='I'>Fvwm</emphasis>
 115 sub menus overlap the parent menu,
 116 <emphasis remap='I'>Mwm</emphasis> and <emphasis remap='I'>Win</emphasis>
 117 style menus never overlap the parent menu.</para>
 118
 119 <para><emphasis remap='I'>Fvwm</emphasis>
 120 style is equivalent to !HilightBack, Hilight3DThin,
 121 !ActiveFore,
 122 !Animation, Font, MenuFace, PopupOffset 0 67,
 123 TitleWarp, TitleUnderlines1, SeparatorsShort, TrianglesRelief,
 124 PopupDelayed, PopdownDelayed, PopupDelay 150, PopdownDelay 150,
 125 PopupAsSubmenu, HoldSubmenus,
 126 SubmenusRight, BorderWidth 2, !AutomaticHotkeys,
 127 PopupActiveArea 75.</para>
 128
 129 <para><emphasis remap='I'>Mwm</emphasis>
 130 style is equivalent to !HilightBack, Hilight3DThick,
 131 !ActiveFore,
 132 !Animation, Font, MenuFace, PopupOffset -3 100,
 133 !TitleWarp, TitleUnderlines2, SeparatorsLong, TrianglesRelief,
 134 PopupImmediately, PopdownDelayed, PopdownDelay 150,
 135 PopupAsSubmenu, HoldSubmenus, SubmenusRight, BorderWidth 2,
 136 !AutomaticHotkeys, PopupActiveArea 75.</para>
 137
 138 <para><emphasis remap='I'>Win</emphasis>
 139 style is equivalent to HilightBack, Hilight3DOff, ActiveFore,
 140 !Animation, Font, MenuFace, PopupOffset -5 100, !TitleWarp,
 141 TitleUnderlines1, SeparatorsShort, TrianglesSolid,
 142 PopupImmediately, PopdownDelayed, PopdownDelay 150,
 143 PopupAsSubmenu, RemoveSubmenus, SubmenusRight, BorderWidth 2,
 144 !AutomaticHotkeys, PopupActiveArea 75.</para>
 145
 146 <para>
 147 <fvwmopt cmd="MenuStyle" opt="BorderWidth"/>
 148 takes the thickness of the border around the menus in pixels. It
 149 may be zero to 50 pixels.  The default is 2.  Using an illegal
 150 value reverts the border width to the default.</para>
 151
 152 <para>
 153 <fvwmopt cmd="MenuStyle" opt="Foreground"/> and
 154 <fvwmopt cmd="MenuStyle" opt="Background"/>
 155 may have a color name as an argument.  This color is used for menu
 156 text or the menu's background.  You can omit the color name to
 157 reset these colors to the built-in default.</para>
 158
 159 <para>
 160 <fvwmopt cmd="MenuStyle" opt="Greyed"/>
 161 may have a color name as an argument.  This color is the one used
 162 to draw a menu-selection which is prohibited (or not recommended)
 163 by the Mwm hints which an application has specified. If the color
 164 is omitted the color of greyed menu entries is based on the
 165 background color of the menu.</para>
 166
 167 <para>
 168 <fvwmopt cmd="MenuStyle" opt="HilightBack"/> and
 169 <emphasis remap='I'>!HilightBack</emphasis>
 170 switch hilighting the background of the selected menu item on and
 171 off.  A specific background color may be used by providing the
 172 color name as an argument to
 173 <emphasis remap='I'>HilightBack</emphasis>.
 174 If you use this option without an argument the color is based on
 175 the menu's background color.  The
 176 <emphasis remap='I'>ActiveColorset</emphasis>
 177 option overrides the specified color. If the colorset has a
 178 non solid background it is used for the hilighting.</para>
 179
 180 <para>
 181 <fvwmopt cmd="MenuStyle" opt="HilightTitleBack"/>
 182 switches hilighting the background of menu titles on.  If a
 183 <emphasis remap='I'>TitleColorset</emphasis>
 184 was used, the background colour is taken from there.  Otherwise
 185 the color is based on the menu's background color. If the colorset
 186 has a non solid background it is used for the hilighting.</para>
 187
 188 <para>
 189 <fvwmopt cmd="MenuStyle" opt="ActiveFore"/> and
 190 <emphasis>!ActiveFore</emphasis>
 191 switch hilighting the foreground of the selected menu item on and
 192 off.  A specific foreground color may be used by providing the
 193 color name as an argument to
 194 <emphasis remap='I'>ActiveFore</emphasis>.
 195 Omitting the color turns hilighting on when an
 196 <emphasis remap='I'>ActiveColorset</emphasis>
 197 is used.
 198 <emphasis remap='I'>ActiveFore</emphasis>
 199 turns off hilighting the foreground completely.  The
 200 <emphasis remap='I'>ActiveColorset</emphasis>
 201 option overrides the specified color.</para>
 202
 203 <para>
 204 <fvwmopt cmd="MenuStyle" opt="MenuColorset"/>
 205 controls if a colorset is used instead of the
 206 <emphasis remap='I'>Foreground</emphasis>, <emphasis remap='I'>Background</emphasis> and <emphasis remap='I'>MenuFace</emphasis>
 207 menu styles.  If the
 208 <emphasis remap='I'>MenuColorset</emphasis>
 209 keyword is followed by a number equal to zero or greater, this
 210 number is taken as the number of the colorset to use.  If the
 211 number is omitted, the colorset is switched off and the regular
 212 menu styles are used again.  The foreground and background colors
 213 of the menu items are replaced by the colors from the colorset. If
 214 the colorset has a pixmap defined, this pixmap is used as the
 215 background of the menu.  Note that the
 216 <emphasis remap='I'>MenuFace</emphasis>
 217 menu style has been optimized for memory consumption and may use
 218 less memory than the background from a colorset.  The shape mask
 219 from the colorset is used to shape the menu.  Please refer to the
 220 <fvwmref sect="colorsets" opt="colorsets" name="Colorsets"/>
 221 section for details about colorsets.</para>
 222
 223 <para>
 224 <fvwmopt cmd="MenuStyle" opt="ActiveColorset"/>
 225 works exactly like
 226 <emphasis remap='I'>MenuColorset</emphasis>,
 227 but the foreground from the colorset replaces the color given with
 228 the
 229 <emphasis remap='I'>ActiveFore</emphasis>
 230 menu style and the colorset's background color replaces the color
 231 given with the
 232 <emphasis remap='I'>HilightBack</emphasis>
 233 command (to turn on background hilighting you have to use the
 234 <emphasis remap='I'>HilightBack</emphasis>
 235 menu style too).  If specified, the hilight and shadow colors
 236 from the colorset are used too.  The pixmap and shape mask from
 237 the colorset are not used.  Hilighting the background or
 238 foreground can be turned off individually with the
 239 <emphasis remap='I'>!ActiveFore</emphasis> or <emphasis remap='I'>!HilightBack</emphasis>
 240 menu styles.</para>
 241
 242 <para>
 243 <fvwmopt cmd="MenuStyle" opt="GreyedColorset"/>
 244 works exactly like
 245 <emphasis remap='I'>MenuColorset</emphasis>,
 246 but the foreground from the colorset replaces the color given with
 247 the
 248 <emphasis remap='I'>Greyed</emphasis>
 249 menu style.  No other parts of the colorset are used.</para>
 250
 251 <para>
 252 <fvwmopt cmd="MenuStyle" opt="TitleColorset"/>
 253 works exactly like
 254 <emphasis remap='I'>MenuColorset</emphasis>,
 255 but is used only for menu titles.</para>
 256
 257 <para>
 258 <fvwmopt cmd="MenuStyle" opt="Hilight3DThick"/>,
 259 <fvwmopt cmd="MenuStyle" opt="Hilight3DThin"/> and
 260 <fvwmopt cmd="MenuStyle" opt="Hilight3DOff"/>
 261 determine if the selected menu item is hilighted with a 3D
 262 relief. Thick reliefs are two pixels wide, thin reliefs are one
 263 pixel wide.</para>
 264
 265 <para>
 266 <fvwmopt cmd="MenuStyle" opt="Hilight3DThickness"/>
 267 takes one numeric argument that may be between -50 and +50
 268 pixels. With negative values the menu item gets a pressed in look.
 269 The above three commands are equivalent to a thickness of 2, 1 and
 270 0.</para>
 271
 272 <para>
 273 <fvwmopt cmd="MenuStyle" opt="Animation"/> and
 274 <emphasis remap='I'>!Animation</emphasis>
 275 turn menu animation on or off.  When animation is on, sub menus
 276 that do not fit on the screen cause the parent menu to be shifted
 277 to the left so the sub menu can be seen.</para>
 278
 279 <para>
 280 <fvwmopt cmd="MenuStyle" opt="Font"/> and
 281 <fvwmopt cmd="MenuStyle" opt="TitleFont"/>
 282 take a font name as an argument.  If a font by this name exists
 283 it is used for the text of all menu items.  If it does not exist
 284 or if the name is left blank the built-in default is used.  If a
 285 <emphasis remap='I'>TitleFont</emphasis>
 286 is given, it is used for all menu titles instead of the normal font.</para>
 287
 288 <para>
 289 <fvwmopt cmd="MenuStyle" opt="MenuFace"/>
 290 enforces a fancy background upon the menus.  You can use the same
 291 options for
 292 <emphasis remap='I'>MenuFace</emphasis>
 293 as for the
 294 <fvwmref cmd="ButtonStyle"/>.
 295 See description of
 296 <fvwmref cmd="ButtonStyle"/>
 297 command and the
 298
 299 <fvwmref sect="colorGradients" opt="color_gradients" name="Color Gradients"/>
 300 sections for more information.  If you use
 301 <emphasis remap='I'>MenuFace</emphasis>
 302 without arguments the style is reverted back to normal.</para>
 303
 304 <para>Some examples of MenuFaces are:</para>
 305
 306
 307 <programlisting>
 308 MenuFace DGradient 128 2 lightgrey 50 blue 50 white
 309 MenuFace TiledPixmap texture10.xpm
 310 MenuFace HGradient 128 2 Red 40 Maroon 60 White
 311 MenuFace Solid Maroon
 312 </programlisting>
 313
 314 <para>Note: The gradient styles H, V, B and D are optimized for high
 315 speed and low memory consumption in menus.  This is not the case
 316 for all the other gradient styles.  They may be slow and consume
 317 huge amounts of memory, so if you encounter performance problems
 318 with them you may be better off by not using them.  To improve
 319 performance you can try one or all of the following:</para>
 320
 321 <para>Turn hilighting of the active menu item other than foreground
 322 color off:</para>
 323
 324 <programlisting>
 325 MenuStyle &lt;style&gt; Hilight3DOff, !HilightBack
 326 MenuStyle &lt;style&gt; ActiveFore &lt;preferred color&gt;
 327 </programlisting>
 328
 329 <para>Make sure sub menus do not overlap the parent menu. This can
 330 prevent menus being redrawn every time a sub menu pops up or down.</para>
 331
 332 <programlisting>
 333 MenuStyle &lt;style&gt; PopupOffset 1 100
 334 </programlisting>
 335
 336 <para>Run your X server with backing storage.  If your X Server is
 337 started with the -bs option, turn it off.  If not try the -wm
 338 and +bs options:</para>
 339
 340 <command>startx -- -wm +bs</command>
 341
 342 <para>You may have to adapt this example to your system (e.g. if you use
 343 xinit to start X).</para>
 344
 345 <para>
 346 <fvwmopt cmd="MenuStyle" opt="PopupDelay"/>
 347 requires one numeric argument.  This value is the delay in
 348 milliseconds before a sub menu is popped up when the pointer moves
 349 over a menu item that has a sub menu.  If the value is zero no
 350 automatic pop up is done.  If the argument is omitted the built-in
 351 default is used. Note that the popup delay has no effect if the
 352 <emphasis remap='I'>PopupImmediately</emphasis>
 353 option is used since sub menus pop up immediately then.</para>
 354
 355 <para>
 356 <fvwmopt cmd="MenuStyle" opt="PopupImmediately"/>
 357 makes menu items with sub menus pop up it up as soon as the
 358 pointer enters the item.  The
 359 <emphasis remap='I'>PopupDelay option</emphasis>
 360 is ignored then.  If
 361 <emphasis remap='I'>PopupDelayed</emphasis>
 362 is used fvwm looks at the
 363 <emphasis remap='I'>PopupDelay</emphasis>
 364 option if or when this automatic popup happens.</para>
 365
 366 <para>
 367 <fvwmopt cmd="MenuStyle" opt="PopdownDelay"/>
 368 works exactly like
 369 <emphasis remap='I'>PopupDelay</emphasis>
 370 but determines the timeout of the
 371 <emphasis remap='I'>PopupDelayed</emphasis>
 372 style.</para>
 373
 374 <para>
 375 <fvwmopt cmd="MenuStyle" opt="PopdownImmediately"/>
 376 makes sub menus vanish as soon as the pointer leaves the sub menu
 377 and the correspondent item in the parent menu.  With the opposite
 378 option
 379 <emphasis remap='I'>PopdownDelayed</emphasis>
 380 the sub menu only pops down after the time specified with the
 381 <emphasis remap='I'>PopdownDelay</emphasis>
 382 option.  This comes handy when the pointer often strays off the
 383 menu item when trying to move into the sub menu.  Whenever there
 384 is a conflict between the
 385 <emphasis remap='I'>PopupImmediately</emphasis>, <emphasis remap='I'>PopupDelayed</emphasis>, <emphasis remap='I'>PopupDelay</emphasis>
 386 styles and the
 387 <emphasis remap='I'>PopdownImmediately</emphasis>, <emphasis remap='I'>PopdownDelayed</emphasis>, <emphasis remap='I'>PopdownDelay</emphasis>
 388 styles, the
 389 <emphasis remap='I'>Popup...</emphasis>
 390 styles win when using mouse navigation and the
 391 <emphasis remap='I'>Popdown...</emphasis>
 392 styles win when navigating with the keyboard.</para>
 393
 394 <para>
 395 <fvwmopt cmd="MenuStyle" opt="PopupOffset"/>
 396 requires two integer arguments.  Both values affect where sub
 397 menus are placed relative to the parent menu.  If both values are
 398 zero, the left edge of the sub menu overlaps the left edge of the
 399 parent menu.  If the first value is non-zero the sub menu is
 400 shifted that many pixels to the right (or left if negative).  If
 401 the second value is non-zero the menu is moved by that many
 402 percent of the parent menu's width to the right or left.</para>
 403
 404 <para>
 405 <fvwmopt cmd="MenuStyle" opt="PopupActiveArea"/>
 406 requires an integer value between 51 and 100.  Normally, when the
 407 pointer is over a menu item with a sub menu and the pointer enters
 408 the area that starts at 75% of the menu width, the sub menu is
 409 shown immediately.  This percentage can be changed with
 410 <emphasis remap='I'>PopupActiveArea</emphasis>.
 411 Setting this value to 100 disables this kind of automatic popups
 412 altogether.  The default value is restored if no or an illegal
 413 value is given.</para>
 414
 415 <para>
 416 <fvwmopt cmd="MenuStyle" opt="TitleWarp"/> and <emphasis remap='I'>!TitleWarp</emphasis>
 417 affect if the pointer warps to the menu title when a sub menu is
 418 opened or not. Note that regardless of this setting the pointer is
 419 not warped if the menu does not pop up under the pointer.</para>
 420
 421 <para>
 422 <fvwmopt cmd="MenuStyle" opt="TitleUnderlines0"/>,
 423 <fvwmopt cmd="MenuStyle" opt="TitleUnderlines1"/> and
 424 <fvwmopt cmd="MenuStyle" opt="TitleUnderlines2"/>
 425 specify how many lines are drawn below a menu title.</para>
 426
 427 <para>
 428 <fvwmopt cmd="MenuStyle" opt="SeparatorsLong"/> and
 429 <fvwmopt cmd="MenuStyle" opt="SeparatorsShort"/>
 430 set the length of menu separators.  Long separators run from the
 431 left edge all the way to the right edge.  Short separators leave a
 432 few pixels to the edges of the menu.</para>
 433
 434 <para>
 435 <fvwmopt cmd="MenuStyle" opt="TrianglesSolid"/> and
 436 <fvwmopt cmd="MenuStyle" opt="TrianglesRelief"/>
 437 affect how the small triangles for sub menus is drawn.  Solid
 438 triangles are filled with a color while relief triangles are
 439 hollow.</para>
 440
 441 <para>
 442 <fvwmopt cmd="MenuStyle" opt="DoubleClickTime"/>
 443 requires one numeric argument.  This value is the time in
 444 milliseconds between two mouse clicks in a menu to be considered
 445 as a double click.  The default is 450 milliseconds.  If the
 446 argument is omitted the double click time is reset to this
 447 default.</para>
 448
 449 <para>
 450 <fvwmopt cmd="MenuStyle" opt="SidePic"/>
 451 takes the name of an image file as an argument. The
 452 picture is drawn along the left side of the menu.  The
 453 <emphasis remap='I'>SidePic</emphasis>
 454 option can be overridden by a menu specific side pixmap (see
 455 <fvwmref cmd="AddToMenu"/>).
 456 If the file name is omitted an existing side pixmap is removed from
 457 the menu style.</para>
 458
 459 <para>
 460 <fvwmopt cmd="MenuStyle" opt="SideColor"/>
 461 takes the name of an X11 color as an argument. This color is used
 462 to color the column containing the side picture (see
 463 above). The SideColor option can be overridden by a menu specific
 464 side color (see
 465 <fvwmref cmd="AddToMenu"/>).
 466 If the color name is omitted the side color option is switched off.</para>
 467
 468 <para>
 469 <fvwmopt cmd="MenuStyle" opt="PopupAsRootMenu"/>,
 470 <fvwmopt cmd="MenuStyle" opt="PopupAsSubmenu"/>,
 471 <fvwmopt cmd="MenuStyle" opt="PopupIgnore"/> and
 472 <fvwmopt cmd="MenuStyle" opt="PopupClose"/>
 473 change the behavior when you click on a menu item that opens a
 474 sub menu. With
 475 <emphasis remap='I'>PopupAsRootMenu</emphasis>
 476 the original menu is closed before the sub menu appears, with
 477 <emphasis remap='I'>PopupAsSubmenu</emphasis>
 478 it is not, so you can navigate back into the
 479 parent menu.  Furthermore, with
 480 <emphasis remap='I'>PopupAsSubmenu</emphasis>
 481 the sub menu is held open (posted) regardless of where you move
 482 the mouse.  Depending on your menu style this may simplify
 483 navigating through the menu.  <fvwmref cmd="Any"/> keystroke while a menu is posted
 484 reverts the menu back to the normal behavior.  With
 485 <emphasis remap='I'>PopupClose</emphasis>
 486 the menu is closed when a sub menu item is activated, and the menu
 487 stays open if
 488 <emphasis remap='I'>PopupIgnore</emphasis>
 489 is used (even if the menu was invoked with the
 490 <fvwmref cmd="Popup"/>
 491 command).
 492 <emphasis remap='I'>PopupAsSubmenu</emphasis>
 493 is the default.</para>
 494
 495 <para>
 496 <fvwmopt cmd="MenuStyle" opt="RemoveSubmenus"/>
 497 instructs fvwm to remove sub menu when you move back into the
 498 parent menu.  With
 499 <fvwmopt cmd="MenuStyle" opt="HoldSubmenus"/>
 500 the sub menu remains visible.  You probably want to use
 501 <emphasis remap='I'>HoldSubmenus</emphasis>
 502 if you are using the
 503 <emphasis remap='I'>PopupDelayed</emphasis>
 504 style.
 505 <emphasis remap='I'>RemoveSubmenus</emphasis>
 506 affects menu navigation with the keyboard.</para>
 507
 508 <para>
 509 <fvwmopt cmd="MenuStyle" opt="SelectOnRelease"/>
 510 takes an optional key name as an argument.  If the given key is
 511 released in a menu using this style, the current menu item is
 512 selected.  This is intended for
 513 <keysym>Alt-Tab</keysym>
 514 <fvwmref cmd="WindowList"/>
 515 navigation.
 516 The key name is a standard X11 key name as defined in
 517 <filename>/usr/include/X11/keysymdef.h</filename>,
 518 (without the
 519 <emphasis remap='I'>XK_</emphasis>
 520 prefix), or the keysym database
 521 <filename>/usr/X11R6/lib/X11/XKeysymDB</filename>.
 522 To disable this behavior, omit
 523 the key name.</para>
 524
 525 <para>Note: Some X servers do not support KeyRelease events.
 526 <emphasis remap='I'>SelectOnRelease</emphasis>
 527 does not work on such a machine.</para>
 528
 529 <para>
 530 <fvwmopt cmd="MenuStyle" opt="ItemFormat"/>
 531 takes a special string as its argument that determines the layout
 532 of the menu items.  Think of the format string as if it were a
 533 menu item. All you have to do is tell fvwm where to place the
 534 different parts of the menu item (i.e. the labels, the triangle
 535 denoting a sub menu, the mini icons and the side pic) in the blank
 536 area.  The string consists of spaces,
 537 <keysym>Tab</keysym>
 538 characters and formatting directives beginning with '%'. Any
 539 illegal characters and formatting directives are silently ignored:</para>
 540
 541 <variablelist>
 542 <varlistentry>
 543         <term><emphasis remap='B'>%l</emphasis>,
 544           <emphasis remap='B'>%c</emphasis>
 545           and <emphasis remap='B'>%r</emphasis></term>
 546         <listitem><para>Insert the next item label. Up to three labels
 547         can be used. The item column is left-aligned
 548         (<emphasis remap='B'>%l</emphasis>), centered
 549         (<emphasis remap='B'>%c</emphasis>) or right-aligned
 550         (<emphasis remap='B'>%r</emphasis>).</para></listitem>
 551 </varlistentry>
 552 <varlistentry>
 553         <term><emphasis remap='B'>%i</emphasis></term>
 554         <listitem><para>Inserts the mini icon.</para></listitem>
 555 </varlistentry>
 556 <varlistentry>
 557         <term><emphasis remap='B'>%&gt;</emphasis>
 558         and <emphasis remap='B'>%&lt;</emphasis></term>
 559         <listitem><para>Insert the sub menu triangle pointing either
 560         to the right (<emphasis remap='B'>%&gt;</emphasis>) or to the
 561         left (<emphasis remap='B'>%&lt;</emphasis>).</para></listitem>
 562 </varlistentry>
 563 <varlistentry>
 564         <term><emphasis remap='B'>%|</emphasis></term>
 565         <listitem>
 566           <para>The first <emphasis remap='B'>%|</emphasis> denotes
 567             the beginning of the area that is highlighted either with
 568             a background color or a relief (or both). The
 569             second <emphasis remap='B'>%|</emphasis> marks the end of
 570             this area.  <emphasis remap='B'>%|</emphasis> can be used
 571             up to twice in the string.  If you do not add one or both
 572             of them, fvwm sets the margins to the margins of the whole
 573             item (not counting the side picture).</para></listitem>
 574 </varlistentry>
 575 <varlistentry>
 576         <term><emphasis remap='B'>%s</emphasis></term>
 577         <listitem><para>Places the side picture either at the
 578         beginning or the end of the menu. This directive may be used
 579         only once and only as the first or last in the format
 580         string. If the <emphasis remap='B'>%s</emphasis> is not at the
 581         beginning of the string, menus are not drawn
 582         properly.</para></listitem>
 583 </varlistentry>
 584 <varlistentry>
 585         <term><emphasis remap='B'>Space</emphasis>,
 586           <emphasis remap='B'>Tab</emphasis>,
 587           <emphasis remap='B'>%Space</emphasis>
 588           and <emphasis remap='B'>%Tab</emphasis></term>
 589         <listitem><para>Add gap of one space, or a tab, using the
 590         width of the menu font. When using a tab, the size of the gap
 591         can be one to 8 spaces since the tab position is a multiple of
 592         8 from the edge of the menu. The whole string must be quoted
 593         if spaces or tabs are used.</para></listitem>
 594 </varlistentry>
 595 <varlistentry>
 596         <term><emphasis remap='B'>%p</emphasis></term>
 597         <listitem><para>Like Space and
 598         Tab <emphasis remap='B'>%p</emphasis> inserts an empty area
 599         into the item, but with better control of its size (see
 600         below).</para></listitem></varlistentry>
 601
 602 </variablelist>
 603
 604
 605
 606 <para>You can define an additional space before and after each of the
 607 objects like this:</para>
 608
 609 <programlisting>
 610 <emphasis remap='B'>%</emphasis><replaceable>left</replaceable><emphasis remap='B'>.</emphasis><replaceable>right</replaceable><emphasis remap='B'>p</emphasis>
 611 </programlisting>
 612
 613
 614 <para>This means: if the object is defined in the menu (e.g. if it is
 615 <emphasis remap='B'>%s</emphasis>
 616 and you use a side picture, or it is
 617 <emphasis remap='B'>%l</emphasis>
 618 for the third column and there are items defined that actually
 619 have a third column), then add
 620 <replaceable>left</replaceable>
 621 pixels before the object and
 622 <replaceable>right</replaceable>
 623 pixels after it.  You may leave out the
 624 <replaceable>left</replaceable>
 625 or the <emphasis>.right</emphasis>
 626 parts if you do not need them.  All values up to the screen width
 627 are allowed.  Even negative values can be used with care.  The
 628 <emphasis remap='B'>p</emphasis>
 629 may be replaced with any other formatting directives described
 630 above.</para>
 631
 632 <para>Note: Only items defined in the format string are visible in the
 633 menus. So if you do not put a
 634 <emphasis remap='B'>%s</emphasis>
 635 in there you do not see a side picture, even if one is specified.</para>
 636
 637 <para>Note: The
 638 <emphasis remap='I'>SubmenusLeft</emphasis>
 639 style changes the default
 640 <emphasis remap='I'>ItemFormat</emphasis>
 641 string, but if it was set manually it is not modified.</para>
 642
 643 <para>Note: If any unformatted title of the menu is wider than the
 644 widest menu item, the spaces between the different parts of the
 645 menu items are enlarged to match the width of the title.  Leading
 646 left aligned objects in the format string
 647 (<emphasis remap='B'>%l</emphasis>, <emphasis remap='B'>%i</emphasis>,
 648 <emphasis remap='B'>%&lt;</emphasis>, first <emphasis remap='B'>%|</emphasis>)
 649 stick to the left edge of the menu and trailing right aligned
 650 objects
 651 (<emphasis remap='B'>%r</emphasis>, <emphasis remap='B'>%i</emphasis>,
 652 <emphasis remap='B'>%&gt;</emphasis>, second <emphasis remap='B'>%|</emphasis>)
 653 stick to the right edge.  The gaps between the remaining items are
 654 enlarged equally.</para>
 655
 656 <para>Examples:</para>
 657
 658 <programlisting>
 659 MenuStyle * ItemFormat "%.4s%.1|%.5i%.5l%.5l%.5r%.5i%2.3&gt;%1|"
 660 </programlisting>
 661
 662 <para>Is the default string used by fvwm: (side picture + 4 pixels gap)
 663 (beginning of the hilighted area + 1 pixel gap) (mini icon + 5p)
 664 (first column left aligned + 5p) (second column left aligned + 5p)
 665 (third column right aligned + 5p) (second mini icon + 5p) (2p +
 666 sub menu triangle + 3p) (1p + end of hilighted area).</para>
 667
 668 <programlisting>
 669 MenuStyle * ItemFormat "%.1|%3.2&lt;%5i%5l%5l%5r%5i%1|%4s"
 670 </programlisting>
 671
 672 <para>Is used by fvwm with the
 673 <emphasis remap='I'>SubmenusLeft</emphasis>
 674 option below.</para>
 675
 676 <para>
 677 <fvwmopt cmd="MenuStyle" opt="VerticalItemSpacing"/> and
 678 <fvwmopt cmd="MenuStyle" opt="VerticalTitleSpacing"/>
 679 control the vertical spacing of menu items and titles like
 680 <emphasis remap='I'>ItemFormat</emphasis>
 681 controls the horizontal spacing.  Both take two numeric arguments
 682 that may range from -100 to +100.  The first is the gap in pixels
 683 above a normal menu item (or a menu title), the second is the gap
 684 in pixels below it.  Negative numbers do not make much sense and
 685 may screw up the menu completely.  If no arguments are given or
 686 the given arguments are invalid, the built-in defaults are used:
 687 one pixel above the item or title and two below.</para>
 688
 689 <para>
 690 <fvwmopt cmd="MenuStyle" opt="VerticalMargins"/>
 691 can be used to add some padding at the top and bottom of menus.
 692 It takes two numeric arguments that must be positive integers (or
 693 zero).  If the number of arguments or its values are incorrect,
 694 fvwm defaults both to 0, which means no padding at all.  If the
 695 values are correct, the first one is used for the top margin, and
 696 the second one is used for the bottom margin.</para>
 697
 698 <para>
 699 <fvwmopt cmd="MenuStyle" opt="SubmenusLeft"/>
 700 mirrors the menu layout and behavior.  Sub menus pop up to the
 701 left, the sub menu triangle is drawn left and the mini icon and
 702 side picture are drawn at the right side of the menu.  The default
 703 is
 704 <fvwmopt cmd="MenuStyle" opt="SubmenusRight"/>.
 705 The position hints of a menu are also affected by this setting,
 706 i.e. position hints using
 707 <emphasis remap='I'>item</emphasis> or <emphasis remap='I'>menu</emphasis>
 708 as context rectangle and position hints using
 709 <emphasis remap='I'>m</emphasis>
 710 offsets.</para>
 711
 712 <para>
 713 <fvwmopt cmd="MenuStyle" opt="AutomaticHotkeys"/> and
 714 <emphasis remap='I'>!AutomaticHotkeys</emphasis>
 715 control the menu's ability to automatically provide hot-keys on
 716 the first character of each menu item's label.  This behavior is
 717 always overridden if an explicit hot-key is assigned in the
 718 <emphasis remap='B'>AddToMenu</emphasis>
 719 command.</para>
 720
 721 <para>
 722 <fvwmopt cmd="MenuStyle" opt="MouseWheel"/>
 723 controls the ability to scroll the menu using a mouse wheel. It takes
 724 one argument, that can be one of
 725 ScrollsPointer, ScrollsMenu, ScrollsMenuBackwards or ActivatesItem.
 726 ScrollsPointer makes the mouse wheel scroll the pointer over a menu.
 727 This is the default. ScrollsMenu and ScrollsMenuBackwards scroll the menu
 728 beneath the pointer. ActivatesItem disables scrolling by mouse wheel and
 729 makes the use of a mouse wheel act as if the menu was clicked.
 730 If no argument is supplied the default setting is restored.</para>
 731
 732 <para>
 733 <fvwmopt cmd="MenuStyle" opt="ScrollOffPage"/>
 734 allows a menu to be scrolled out of the visible area if
 735 <emphasis remap='I'>MouseWheel</emphasis>
 736 is set to ScrollsMenu or ScrollsMenuBackwards. This is the default.
 737 The opposite,
 738 <emphasis remap='I'>!ScrollOffPage</emphasis>
 739 disables this behaviour.</para>
 740
 741 <para>
 742 <fvwmopt cmd="MenuStyle" opt="TrianglesUseFore"/>
 743 draws sub menu triangles with the foreground color of the menu colorset
 744 (normally drawn with the hilight color).
 745 <emphasis remap='I'>!TrianglesUseFore</emphasis>
 746 disables this behaviour.</para>
 747
 748 <para>Examples:</para>
 749
 750 <programlisting>
 751 MenuStyle * Mwm
 752 MenuStyle * Foreground Black, Background gray40
 753 MenuStyle * Greyed gray70, ActiveFore White
 754 MenuStyle * !HilightBack, Hilight3DOff
 755 MenuStyle * Font lucidasanstypewriter-14
 756 MenuStyle * MenuFace DGradient 64 darkgray MidnightBlue
 757
 758 MenuStyle red Mwm
 759 MenuStyle red Foreground Yellow
 760 MenuStyle red Background Maroon
 761 MenuStyle red Greyed Red, ActiveFore Red
 762 MenuStyle red !HilightBack, Hilight3DOff
 763 MenuStyle red Font lucidasanstypewriter-12
 764 MenuStyle red MenuFace DGradient 64 Red Black
 765 </programlisting>
 766
 767 <para>Note that all style options could be placed on a single line for
 768 each style name.</para>
 769
 770 <cmdsynopsis>
 771         <command>MenuStyle</command
 772         ><arg choice='plain'
 773                 ><replaceable>forecolor</replaceable
 774         ></arg
 775         ><arg choice='plain'
 776                 ><replaceable>backcolor</replaceable
 777         ></arg
 778         ><arg choice='plain'
 779                 ><replaceable>shadecolor</replaceable
 780         ></arg
 781         ><arg choice='plain'
 782                 ><replaceable>font</replaceable
 783         ></arg
 784         ><arg choice='plain'
 785                 ><replaceable>style</replaceable
 786         ></arg
 787         ><arg choice='opt'
 788                 ><replaceable>anim</replaceable
 789         ></arg>
 790 </cmdsynopsis>
 791
 792 <para>This is the old syntax of the
 793 <emphasis remap='B'>MenuStyle</emphasis>
 794 command.  It is obsolete and may be removed in the future.  Please
 795 use the new syntax as described above.</para>
 796
 797 <para>Sets the menu style.  When using monochrome the colors are
 798 ignored.  The
 799 <replaceable>shadecolor</replaceable>
 800 is the one used to draw a menu-selection which is prohibited (or
 801 not recommended) by the Mwm hints which an application has
 802 specified.  The style option is either
 803 <emphasis remap='I'>Fvwm</emphasis>, <emphasis remap='I'>Mwm</emphasis> or <emphasis remap='I'>Win</emphasis>,
 804 which changes the appearance and operation of the menus.</para>
 805
 806 <para><emphasis remap='I'>Mwm</emphasis> and <emphasis remap='I'>Win</emphasis>
 807 style menus popup sub menus automatically.
 808 <emphasis remap='I'>Win</emphasis>
 809 menus indicate the current menu item by changing the background to
 810 black.
 811 <emphasis remap='I'>Fvwm</emphasis>
 812 sub menus overlap the parent menu,
 813 <emphasis remap='I'>Mwm</emphasis> and <emphasis remap='I'>Win</emphasis>
 814 style menus never overlap the parent menu.</para>
 815
 816 <para>When the
 817 <replaceable>anim</replaceable>
 818 option is given, sub menus that do not fit on the screen cause the
 819 parent menu to be shifted to the left so the sub menu can be
 820 seen. See also
 821 <fvwmref cmd="SetAnimation"/>
 822 command.</para>
 823
 824 </section>