doc/commands/Menu.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3   "../docbook-xml/docbookx.dtd"
   4 [
   5 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   6 %myents;
   7 ]>
   8
   9 <!-- $Id: Menu.xml,v 1.6 2010/01/03 02:39:32 tadam Exp $ -->
  10
  11 <section id='Menu'>
  12 <title>Menu</title>
  13
  14 <cmdsynopsis>
  15         <command>Menu</command
  16         ><arg choice='plain'
  17                 ><replaceable>menu-name</replaceable
  18         ></arg
  19         ><arg choice='opt'
  20                 ><replaceable>position</replaceable
  21         ></arg
  22         ><arg choice='opt'
  23                 ><replaceable>double-click-action</replaceable
  24         ></arg>
  25 </cmdsynopsis>
  26
  27
  28 <para>Causes a previously defined menu to be popped up in a sticky
  29 manner.  That is, if the user invokes the menu with a click action
  30 instead of a drag action, the menu stays up.  The command
  31 <replaceable>double-click-action</replaceable>
  32 is invoked if the user double-clicks a button (or hits the key
  33 rapidly twice if the menu is bound to a key) when bringing up the
  34 menu.  If the double click action is not specified, double
  35 clicking on the menu does nothing.  However, if the menu begins
  36 with a menu item (i.e. not with a title or a separator) and the
  37 double click action is not given, double clicking invokes the
  38 first item of the menu (but only if the pointer really was over
  39 the item).</para>
  40
  41 <para>The pointer is warped to where it was when the menu was invoked if
  42 it was both invoked and closed with a keystroke.</para>
  43
  44 <para>The
  45 <replaceable>position</replaceable>
  46 arguments allow placement of the menu somewhere on the screen, for
  47 example centered on the visible screen or above a title bar.
  48 Basically it works like this: you specify a
  49 <replaceable>context-rectangle</replaceable>
  50 and an offset to this rectangle by which the upper left corner of
  51 the menu is moved from the upper left corner of the rectangle.
  52 The
  53 <replaceable>position</replaceable>
  54 arguments consist of several parts:</para>
  55
  56 <cmdsynopsis>
  57         <arg choice='opt'
  58                 ><replaceable>context-rectangle</replaceable
  59         ></arg
  60         ><arg choice='plain'
  61                 ><replaceable>x</replaceable
  62         ></arg
  63         ><arg choice='plain'
  64                 ><replaceable>y</replaceable
  65         ></arg
  66         ><arg choice='opt'
  67                 ><replaceable>special-options</replaceable
  68         ></arg>
  69 </cmdsynopsis>
  70
  71
  72 <para>The
  73 <replaceable>context-rectangle</replaceable>
  74 can be one of:</para>
  75
  76 <!-- possible change to variablelist to look more like the old manpage -->
  77 <variablelist>
  78 <varlistentry>
  79         <term><fvwmopt cmd="Menu" opt="Root"/></term>
  80         <listitem><para>the root window of the current screen.</para></listitem>
  81 </varlistentry>
  82 <varlistentry>
  83         <term><fvwmopt cmd="Menu" opt="XineramaRoot"/></term>
  84         <listitem><para>the root window of the whole Xinerama screen.  Equivalent to "root" when Xinerama is not used.</para></listitem>
  85 </varlistentry>
  86 <varlistentry>
  87         <term><fvwmopt cmd="Menu" opt="Mouse"/></term>
  88         <listitem><para>a 1x1 rectangle at the mouse position.</para></listitem>
  89 </varlistentry>
  90 <varlistentry>
  91         <term><fvwmopt cmd="Menu" opt="Window"/></term>
  92         <listitem><para>the frame of the context window.</para></listitem>
  93 </varlistentry>
  94 <varlistentry>
  95         <term><fvwmopt cmd="Menu" opt="Interior"/></term>
  96         <listitem><para>the inside of the context window.</para></listitem>
  97 </varlistentry>
  98 <varlistentry>
  99         <term><fvwmopt cmd="Menu" opt="Title"/></term>
 100         <listitem><para>the title of the context window or icon.</para></listitem>
 101 </varlistentry>
 102 <varlistentry>
 103         <term><fvwmopt cmd="Menu" opt="Button"/>&lt;n&gt;</term>
 104         <listitem><para>button #n of the context window.</para></listitem>
 105 </varlistentry>
 106 <varlistentry>
 107         <term><fvwmopt cmd="Menu" opt="Icon"/></term>
 108         <listitem><para>the icon of the context window.</para></listitem>
 109 </varlistentry>
 110 <varlistentry>
 111         <term><fvwmopt cmd="Menu" opt="Menu"/></term>
 112         <listitem><para>the current menu.</para></listitem>
 113 </varlistentry>
 114 <varlistentry>
 115         <term><fvwmopt cmd="Menu" opt="Item"/></term>
 116         <listitem><para>the current menu item.</para></listitem>
 117 </varlistentry>
 118 <varlistentry>
 119         <term><fvwmopt cmd="Menu" opt="Context"/></term>
 120         <listitem><para>the current window, menu or icon.</para></listitem>
 121 </varlistentry>
 122 <varlistentry>
 123         <term><fvwmopt cmd="Menu" opt="This"/></term>
 124         <listitem><para>whatever widget the pointer is on (e.g. a corner of a window or the root window).</para></listitem>
 125 </varlistentry>
 126 <varlistentry>
 127         <term><fvwmopt cmd="Menu" opt="Rectangle"/> &lt;<replaceable>geometry</replaceable>&gt;</term>
 128         <listitem><para>the rectangle defined by &lt;<replaceable>geometry</replaceable>&gt; in X geometry format.  Width and height default to 1 if omitted.</para></listitem>
 129 </varlistentry>
 130 </variablelist>
 131
 132
 133 <para>If the context-rectangle is omitted or illegal (e.g. "item" on a
 134 window), "Mouse" is the default.  Note that not all of these make
 135 sense under all circumstances (e.g. "Icon" if the pointer is on a
 136 menu).</para>
 137
 138 <para>The offset values
 139 <replaceable>x</replaceable>
 140 and
 141 <replaceable>y</replaceable>
 142 specify how far the menu is moved from its default position.  By
 143 default, the numeric value given is interpreted as a percentage of
 144 the context rectangle's width (height), but with a trailing
 145 '<fvwmopt cmd="Menu" opt="m"/>'
 146 the menu's width (height) is used instead.  Furthermore a trailing
 147 '<fvwmopt cmd="Menu" opt="p"/>'
 148 changes the interpretation to mean pixels.</para>
 149
 150 <para>Instead of a single value you can use a list of values.  All
 151 additional numbers after the first one are separated from their
 152 predecessor by their sign.  Do not use any other separators.</para>
 153
 154 <para>If
 155 <replaceable>x</replaceable> or <replaceable>y</replaceable>
 156 are prefixed with "'<fvwmopt cmd="Menu" opt="o"/>&lt;number&gt;" where &lt;number&gt; is an integer, the
 157 menu and the rectangle are moved to overlap at the specified
 158 position before any other offsets are applied.  The menu and the
 159 rectangle are placed so that the pixel at &lt;number&gt; percent of the
 160 rectangle's width/height is right over the pixel at &lt;number&gt;
 161 percent of the menu's width/height. So "o0" means that the
 162 top/left borders of the menu and the rectangle overlap, with
 163 "o100" it's the bottom/right borders and if you use "o50" they are
 164 centered upon each other (try it and you will see it is much
 165 simpler than this description).  The default is "o0".  The prefix
 166 "o&lt;number&gt;" is an abbreviation for "+&lt;number&gt;-&lt;number&gt;m".</para>
 167
 168 <para>A prefix of
 169 '<fvwmopt cmd="Menu" opt="c"/>'
 170 is equivalent to "o50".  Examples:</para>
 171
 172 <programlisting>
 173 # window list in the middle of the screen
 174 <fvwmref cmd="WindowList"/> Root c c
 175
 176 # menu to the left of a window
 177 Menu name window -100m c+0
 178
 179 # popup menu 8 pixels above the mouse pointer
 180 <fvwmref cmd="Popup"/> name mouse c -100m-8p
 181
 182 # somewhere on the screen
 183 Menu name rectangle 512x384+1+1 +0 +0
 184
 185 # centered vertically around a menu item
 186 <fvwmref cmd="AddToMenu"/> foobar-menu
 187  + "first item" <fvwmref cmd="Nop"/>
 188  + "special item" <fvwmref cmd="Popup"/> "another menu" item +100 c
 189  + "last item" <fvwmref cmd="Nop"/>
 190
 191 # above the first menu item
 192 <fvwmref cmd="AddToMenu"/> foobar-menu
 193  + "first item" <fvwmref cmd="Popup"/> "another menu" item +0 -100m
 194 </programlisting>
 195
 196 <para>Note that you can put a sub menu far off the current menu so you
 197 could not reach it with the mouse without leaving the menu.  If
 198 the pointer leaves the current menu in the general direction of
 199 the sub menu the menu stays up.</para>
 200
 201 <para>The
 202 <replaceable>special-options</replaceable>:</para>
 203
 204 <para>To create a tear off menu without opening the normal menu, add the
 205 option
 206 <fvwmopt cmd="Menu" opt="TearOffImmediately"/>.
 207 Normally the menu opens in normal state for a split second before
 208 being torn off.  As tearing off places the menu like any other
 209 window, a position should be specified explicitly:</para>
 210
 211 <programlisting>
 212 # Forbid fvwm to place the menu window
 213 <fvwmref cmd="Style"/> &lt;name of menu&gt; UsePPosition
 214 # Menu at top left corner of screen
 215 Menu Root 0p 0p TearOffImmediately
 216 </programlisting>
 217
 218
 219 <para>The
 220 <fvwmref cmd="MenuStyle" opt="Animated"/> and
 221 <fvwmref cmd="MenuStyle" opt="Mwm"/> or
 222 <fvwmref cmd="MenuStyle" opt="Win"/>
 223 menu styles may move a menu somewhere else on the screen.  If you
 224 do not want this you can add
 225 <fvwmopt cmd="Menu" opt="Fixed"/>
 226 as an option.  This might happen for example if you want the menu
 227 always in the top right corner of the screen.</para>
 228
 229 <para>Where do you want a menu to appear when you click on its menu
 230 item? The default is to place the title under the cursor, but if
 231 you want it where the position arguments say, use the
 232 <fvwmopt cmd="Menu" opt="SelectInPlace"/>
 233 option.  If you want the pointer on the title of the menu, use
 234 <fvwmopt cmd="Menu" opt="SelectWarp"/>
 235 too.  Note that these options apply only if the
 236 <fvwmref cmd="MenuStyle" opt="PopupAsRootMenu"/> <fvwmref cmd="MenuStyle"/>
 237 option is used.</para>
 238
 239 <para>The pointer is warped to the title of a sub menu whenever the
 240 pointer would be on an item when the sub menu is popped up
 241 (<emphasis>fvwm</emphasis>
 242 menu style) or never warped to the title at all
 243 (<fvwmref cmd="MenuStyle" opt="Mwm"/> or
 244 <fvwmref cmd="MenuStyle" opt="Win"/>
 245 menu styles).  You can force (forbid) warping whenever the
 246 sub menu is opened with the
 247 <fvwmopt cmd="Menu" opt="WarpTitle"/> (<fvwmopt cmd="Menu" opt="NoWarp"/>) option.</para>
 248
 249 <para>Note that the
 250 <replaceable>special-options</replaceable>
 251 do work with a normal menu that has no other position arguments.</para>
 252
 253 </section>