<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "../docbook-xml/docbookx.dtd"
[
<!ENTITY % myents SYSTEM "../fvwm.ent" >
%myents;
]>

<!-- $Id: Menu.xml,v 1.6 2010/01/03 02:39:32 tadam Exp $ -->

<section id='Menu'>
<title>Menu</title>

<cmdsynopsis>
	<command>Menu</command
	><arg choice='plain'
		><replaceable>menu-name</replaceable
	></arg
	><arg choice='opt'
		><replaceable>position</replaceable
	></arg
	><arg choice='opt'
		><replaceable>double-click-action</replaceable
	></arg>
</cmdsynopsis>


<para>Causes a previously defined menu to be popped up in a sticky
manner.  That is, if the user invokes the menu with a click action
instead of a drag action, the menu stays up.  The command
<replaceable>double-click-action</replaceable>
is invoked if the user double-clicks a button (or hits the key
rapidly twice if the menu is bound to a key) when bringing up the
menu.  If the double click action is not specified, double
clicking on the menu does nothing.  However, if the menu begins
with a menu item (i.e. not with a title or a separator) and the
double click action is not given, double clicking invokes the
first item of the menu (but only if the pointer really was over
the item).</para>

<para>The pointer is warped to where it was when the menu was invoked if
it was both invoked and closed with a keystroke.</para>

<para>The
<replaceable>position</replaceable>
arguments allow placement of the menu somewhere on the screen, for
example centered on the visible screen or above a title bar.
Basically it works like this: you specify a
<replaceable>context-rectangle</replaceable>
and an offset to this rectangle by which the upper left corner of
the menu is moved from the upper left corner of the rectangle.
The
<replaceable>position</replaceable>
arguments consist of several parts:</para>

<cmdsynopsis>
	<arg choice='opt'
		><replaceable>context-rectangle</replaceable
	></arg
	><arg choice='plain'
		><replaceable>x</replaceable
	></arg
	><arg choice='plain'
		><replaceable>y</replaceable
	></arg
	><arg choice='opt'
		><replaceable>special-options</replaceable
	></arg>
</cmdsynopsis>


<para>The
<replaceable>context-rectangle</replaceable>
can be one of:</para>

<!-- possible change to variablelist to look more like the old manpage -->
<variablelist>
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Root"/></term>
	<listitem><para>the root window of the current screen.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="XineramaRoot"/></term>
	<listitem><para>the root window of the whole Xinerama screen.  Equivalent to "root" when Xinerama is not used.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Mouse"/></term>
	<listitem><para>a 1x1 rectangle at the mouse position.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Window"/></term>
	<listitem><para>the frame of the context window.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Interior"/></term>
	<listitem><para>the inside of the context window.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Title"/></term>
	<listitem><para>the title of the context window or icon.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Button"/>&lt;n&gt;</term>
	<listitem><para>button #n of the context window.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Icon"/></term>
	<listitem><para>the icon of the context window.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Menu"/></term>
	<listitem><para>the current menu.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Item"/></term>
	<listitem><para>the current menu item.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Context"/></term>
	<listitem><para>the current window, menu or icon.</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="This"/></term>
	<listitem><para>whatever widget the pointer is on (e.g. a corner of a window or the root window).</para></listitem>
</varlistentry>	
<varlistentry>
	<term><fvwmopt cmd="Menu" opt="Rectangle"/> &lt;<replaceable>geometry</replaceable>&gt;</term>
	<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>
</varlistentry>	
</variablelist>


<para>If the context-rectangle is omitted or illegal (e.g. "item" on a
window), "Mouse" is the default.  Note that not all of these make
sense under all circumstances (e.g. "Icon" if the pointer is on a
menu).</para>

<para>The offset values
<replaceable>x</replaceable>
and
<replaceable>y</replaceable>
specify how far the menu is moved from its default position.  By
default, the numeric value given is interpreted as a percentage of
the context rectangle's width (height), but with a trailing
'<fvwmopt cmd="Menu" opt="m"/>'
the menu's width (height) is used instead.  Furthermore a trailing
'<fvwmopt cmd="Menu" opt="p"/>'
changes the interpretation to mean pixels.</para>

<para>Instead of a single value you can use a list of values.  All
additional numbers after the first one are separated from their
predecessor by their sign.  Do not use any other separators.</para>

<para>If
<replaceable>x</replaceable> or <replaceable>y</replaceable>
are prefixed with "'<fvwmopt cmd="Menu" opt="o"/>&lt;number&gt;" where &lt;number&gt; is an integer, the
menu and the rectangle are moved to overlap at the specified
position before any other offsets are applied.  The menu and the
rectangle are placed so that the pixel at &lt;number&gt; percent of the
rectangle's width/height is right over the pixel at &lt;number&gt;
percent of the menu's width/height. So "o0" means that the
top/left borders of the menu and the rectangle overlap, with
"o100" it's the bottom/right borders and if you use "o50" they are
centered upon each other (try it and you will see it is much
simpler than this description).  The default is "o0".  The prefix
"o&lt;number&gt;" is an abbreviation for "+&lt;number&gt;-&lt;number&gt;m".</para>

<para>A prefix of
'<fvwmopt cmd="Menu" opt="c"/>'
is equivalent to "o50".  Examples:</para>

<programlisting>
# window list in the middle of the screen
<fvwmref cmd="WindowList"/> Root c c

# menu to the left of a window
Menu name window -100m c+0

# popup menu 8 pixels above the mouse pointer
<fvwmref cmd="Popup"/> name mouse c -100m-8p

# somewhere on the screen
Menu name rectangle 512x384+1+1 +0 +0

# centered vertically around a menu item
<fvwmref cmd="AddToMenu"/> foobar-menu
 + "first item" <fvwmref cmd="Nop"/>
 + "special item" <fvwmref cmd="Popup"/> "another menu" item +100 c
 + "last item" <fvwmref cmd="Nop"/>

# above the first menu item
<fvwmref cmd="AddToMenu"/> foobar-menu
 + "first item" <fvwmref cmd="Popup"/> "another menu" item +0 -100m
</programlisting>

<para>Note that you can put a sub menu far off the current menu so you
could not reach it with the mouse without leaving the menu.  If
the pointer leaves the current menu in the general direction of
the sub menu the menu stays up.</para>

<para>The
<replaceable>special-options</replaceable>:</para>

<para>To create a tear off menu without opening the normal menu, add the
option
<fvwmopt cmd="Menu" opt="TearOffImmediately"/>.
Normally the menu opens in normal state for a split second before
being torn off.  As tearing off places the menu like any other
window, a position should be specified explicitly:</para>

<programlisting>
# Forbid fvwm to place the menu window
<fvwmref cmd="Style"/> &lt;name of menu&gt; UsePPosition
# Menu at top left corner of screen
Menu Root 0p 0p TearOffImmediately
</programlisting>


<para>The
<fvwmref cmd="MenuStyle" opt="Animated"/> and
<fvwmref cmd="MenuStyle" opt="Mwm"/> or
<fvwmref cmd="MenuStyle" opt="Win"/>
menu styles may move a menu somewhere else on the screen.  If you
do not want this you can add
<fvwmopt cmd="Menu" opt="Fixed"/>
as an option.  This might happen for example if you want the menu
always in the top right corner of the screen.</para>

<para>Where do you want a menu to appear when you click on its menu
item? The default is to place the title under the cursor, but if
you want it where the position arguments say, use the
<fvwmopt cmd="Menu" opt="SelectInPlace"/>
option.  If you want the pointer on the title of the menu, use
<fvwmopt cmd="Menu" opt="SelectWarp"/>
too.  Note that these options apply only if the
<fvwmref cmd="MenuStyle" opt="PopupAsRootMenu"/> <fvwmref cmd="MenuStyle"/>
option is used.</para>

<para>The pointer is warped to the title of a sub menu whenever the
pointer would be on an item when the sub menu is popped up
(<emphasis>fvwm</emphasis>
menu style) or never warped to the title at all
(<fvwmref cmd="MenuStyle" opt="Mwm"/> or
<fvwmref cmd="MenuStyle" opt="Win"/>
menu styles).  You can force (forbid) warping whenever the
sub menu is opened with the
<fvwmopt cmd="Menu" opt="WarpTitle"/> (<fvwmopt cmd="Menu" opt="NoWarp"/>) option.</para>

<para>Note that the
<replaceable>special-options</replaceable>
do work with a normal menu that has no other position arguments.</para>

</section>