* NEWS:

[fvwm.git] / fvwm / fvwm.1.in

.\"                                                                  -*-nroff-*-
.\"
.\"
.\"
.\"
@MANPAGE_PREAMBLE@
.\"
.\"
.\"
.\"
.\"
.\" Formatting instructions for the fvwm man page:
.\"
.\"  - Do not use \f... formatting instructions
.\"    unless you have to, see below.
.\"  - Avoid single and double quotes wherever possible.
.\"
.\" For further details, please refer to the Linux Man-Page how-to.
.\"
.\"  context                            typeface        example
.\"  ---------------------------------- --------------  -----------------
.\"  filenames:                         italics (.I)    .I .fvwm/config
.\"  command line options of fvwm cmd:  bold (.B)       .B \-cmd
.\"  arguments of command line options: italics (.I)    .BI "\-cmd " command
.\"  fvwm commands:                     bold (.B)       .B Move
.\"  references to commands:            bold (.B)       .RB "See " Move
.\"  references to man page sections:   bold (.B)       .RB "See " SYNOPSIS
.\"  references to style options:       italics (.I)    .RI "See " Lenience
.\"  command options:                   italics (.I)    .BI "Move " "0 0"
.\"  command syntax:                    bold/ita. (.BI) .BI "Move [" "x y" "]"
.\"  environment variables:             italics (.I)    .I $DISPLAY
.\"  key names:                         small (.SM)     .SM Tab
.\"  style names and strings:           double quotes   "stylename", "x"
.\"  single characters:                 single quotes   '@'
.\"  module names:                      bold (.B)       .B FvwmPager
.\"  links to web pages:                bold (.B)       .B @FVWMHOMEPAGE@
.\"  acronyms:                          small (.SM)     .SM ICCCM
.\"
.\"
.\" The name fvwm is written in lower case throughout this man
.\" page.  Fvwm is written without a version number, i.e. fvwm,
.\" not fvwm2.  The latter is currently used only in the .fvwm2rc
.\" file name; if there is a need to specify this old name, place
.\" it as an accompaniment to the preferred ~/.fvwm/config name.
.\"
.\" Note that the word "will" is rarely correct in a man page or
.\" any document. Describe what fvwm does, not what it will do,
.\" even if you haven't written the feature yet. dje 2/3/01
.\" (3/Feb/2001).
.\"
.\" A note to everyone who needs to write dates.  Don't use 2/3/01
.\" notation, a non-american person simply can't parse such
.\" sequence of digits.  Please use 3-Feb-2001 or 2001-02-03 forms.
.\" migo 16/May/2001.
.\"
.\" A note about the rule against \f... formatting.  On Solaris,
.\" AIX, and HPUX the ".BI" type commands are limited to 6
.\" arguments. use \f... formatting in that case.  See the lines
.\" formatted with ".IP".
.\"  dje 15/June/2001.
.\" Note:  .IP does not work very well as it sometimes indents
.\" from the right too.  Instead, begin these paragraphs with
.\"   .TP
.\"   .B text
.\" This even saves the \fB...\fP pairs.
.\"  dv 19-Jun-2003.
.\"
.\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
.de EX          \"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.ta .3i .6i .9i 1.2i 1.5i 1.8i
.TH FVWM 1 "@RELDATELONG@" FVWM "FVWM @VERSION@@VERSIONINFO@"
.UC
.SH NAME

fvwm \- @FVWMNAMELONG@ for X11
.SH SYNOPSIS

.B fvwm
.RB [ \-c
.IR       config-command ]
.RB [ \-d
.IR       displayname ]
.RB [ \-f
.IR       config-file ]
.RB [ \-r ]
.RB [ \-s
.IR       [screen_num] ]
.RB [ \-V ]
.RB [ \-C
.IR       visual-class
.RB "| " \-I
.IR       visual-id ]
.RB [ \-l
.IR       colors
.RB [ \-L ]
.RB [ \-A ]
.RB [ \-S ]
.RB [ \-P ]]
.RB [ \-D ]
.RB [ \-h ]
.RB [ \-i
.IR       client-id ]
.RB [ \-F
.IR       state-file ]
.RB [ \-\-debug-stack-ring ]
.RB [ \-blackout ]
.SH DESCRIPTION

Fvwm is a window manager for X11.  It is designed to minimize
memory consumption, provide a 3D look to window frames, and a
virtual desktop.

Note that there are several window managers around that have
"fvwm" in their name.  In the past, version 2.x of fvwm was
commonly called fvwm2 to distinguish it from the former version
1.x (fvwm or even fvwm1).  Since version 1.x has been replaced by
version 2.x a long time ago we simply call version 2.x and all
versions to come, fvwm, throughout this document, and the
executable program is named fvwm.  There is an fvwm offspring
called fvwm95, it is mostly a patched version of fvwm-2.0.43.  The
main goal of fvwm95 was to supply a Windows 95 like look and
feel. Since then, fvwm has been greatly enhanced and practically
all fvwm95 features can be achieved by fvwm.

Fvwm provides both, a large
.I virtual desktop
and
.I multiple disjoint desktops
which can be used separately or together.  The virtual desktop
allows you to pretend that your video screen is really quite
large, and you can scroll around within the desktop.  The multiple
disjoint desktops allow you to pretend that you really have
several screens to work at, but each screen is completely
unrelated to the others.

Fvwm provides
.I keyboard accelerators
which allow you to perform most window manager functions,
including moving and resizing windows, and operating the menus,
using keyboard shortcuts.

Fvwm has also overcome the distinction between configuration
commands and action commands that most window managers
make. Configuration commands typically set fonts, colors, menu
contents, key and mouse function bindings, while action commands
do things like raise and lower windows.  Fvwm makes no such
distinction, and allows anything to be changed at any time.

Other noteworthy differences between fvwm and other X11 window
managers are the introduction of the
.IR SloppyFocus " and " NeverFocus
focus methods.  Focus policy can be separately specified for
different window groups.  Windows using
.I SloppyFocus
acquire focus when the pointer moves into them and retain focus
until some other window acquires it.  Such windows do not lose
focus when the pointer moves into the root window.  The
.I NeverFocus
policy is provided for use with windows into which one never types
(e.g. xclock, oclock, xbiff, xeyes, tuxeyes) - for example, if a
SloppyFocus terminal window has focus, moving the pointer over a
.I NeverFocus
decoration window does not deprive the terminal of focus.

.SH OPTIONS

These are the command line options that are recognized by fvwm:
.TP
.BR "-i" " | " "--clientid"
.I id
This option is used when fvwm is started by a session
manager. Should not be used by a user.
.TP
.BR "-c" " | " "--cmd "
.I config-command
Causes fvwm to use
.I config-command
instead of
.RB "'" "Read"
.IR "config" "'"
.RB "(or '" "Read"
.IR ".fvwm2rc" "')"
as its initialization command.  (Note that up to 10
.BR \-f " and " \-c
parameters can be given, and they are executed in the order
specified.)

Any module started by command line arguments is assumed to be a
module that sends back config commands.  All command line modules
have to quit before fvwm proceeds on to the StartFunction and
setting border decorations and styles.  There is a potential
deadlock if you start a module other than FvwmCpp/FvwmM4/FvwmPerl
but there is a timeout so fvwm will eventually get going.

As an example, starting the pager this way hangs fvwm until
the timeout, but the following should work well:
.EX
fvwm -c "AddToFunc StartFunction I Module FvwmPager"
.EE
.TP
.BR "-d" " | " "--display "
.I displayname
Manage the display called
.I displayname
instead of the name obtained from the environment variable
.IR "$DISPLAY" .
.TP
.BR "-D" " | " "--debug"
Puts X transactions in synchronous mode, which dramatically slows
things down, but guarantees that fvwm's internal error messages
are correct. Also causes fvwm to output debug messages while
running.
.TP
.BI "-f " config-file
Causes fvwm to read
.I config-file
instead of
.I ~/.fvwm/config
as its initialization file.  This is equivalent to
.RB "-c 'Read"
.IR "config-file'."
.TP
.BR "-h" " | " "--help"
A short usage description is printed.
.TP
.BR "-r" " | " "--replace"
Try to take over from a previously running wm.  This does not work
unless the other wm is
.SM ICCCM
2.0 compliant.
.TP
.BR "-F" " | " "--restore "
.I state-file
This option is used when fvwm is started by a session manager.
Should not be used by a user.
.TP
.BR "-s" " | " "--single-screen"
.RI "[" screen_num "]"
On a multi-screen display, run fvwm only on the screen named in
the
.I $DISPLAY
environment variable or provided through the
.B -d
option. The optional argument
.I screen_num
should be positive or null and override the screen number.
Normally, fvwm attempts to start up on all screens of a
multi-screen display.
.TP
.BR "-V" " | " "--version"
Prints the version of fvwm to
.IR stderr .
Also prints an information about the compiled in support for
readline, rplay, stroke, xpm, png, gnome hints, EWMH hints,
session management, bidirectional text, multibyte characters,
xinerama and Xft aa font rendering.
.TP
.BR "-C" " | " "--visual "
.I visual-class
Causes fvwm to use
.I visual-class
for the window borders and menus.
.I visual-class
can be "StaticGray", "GrayScale", "StaticColor", "PseudoColor",
"TrueColor" or "DirectColor".
.TP
.BR "-I" " | " "--visualid "
.I id
Causes fvwm to use
.I id
as the visual id for the window borders and menus.
.I id
can be specified as N for decimal or 0xN for hexadecimal. See man
page of xdpyinfo for a list of supported visuals.
.TP
.BR "-l" " | " "--color-limit "
.I limit
Specifies a
.I limit
on the colors used in image, gradient and possibly simple colors
used by fvwm. In fact, fvwm (and all the modules) uses a palette
with at most
.I limit
colors. This option is only useful with screens that display 256
colors (or less) with a dynamic visual (PseudoColor, GrayScale or
DirectColor). The default depends on your X server and how you run
fvwm. In most case this default is reasonable. The
.B "-l"
option should be used only if you encounter problems with colors.
By default, fvwm tries to detect "large" pre-allocated
palettes. If such a palette is detected fvwm uses it and a priori
the
.B "-l"
must not be used. Moreover, in this case the
.BR "-A" " and " "-S"
options are forced. Note that XFree-4.2 pre-allocate 244 colors
(if you use a driver with Render support) leaving only a few free
colors. This may leads to some colors problems (and nothing can be
done). XFree-4.3 or better pre-allocate only 85 colors.  If no
pre-allocated palette is auto detected the defaults are as follow:
.EX
            | depth 8 (256 colors)| depth 4 (16 colors)
------------|---------------------|--------------------
PseudoColor | 68 (4 cc + 4 grey)  | 10 (2 cc + 2 grey)
------------|---------------------|--------------------
GrayScale   | 64 regular grey     |  8 regular grey
----------- |---------------------|--------------------
DirectColor | 32 (3 cc + 5 grey)  | 10 (2 cc + 2 grey)
------------|------------------------------------------
where "I cc" means a "IxIxI color cube"
.EE
These defaults may change before version 2.6. Note that if you use a
private color map (i.e., fvwm is started with the
.BR "-C" " or the " "-I"
options), then others defaults are used.

Now what to do if you encounter problems with colors? The first
thing to do is to check if you really cannot run your X server
with depth 15, 16 or better.  Check your X server
documentation. Note that some hardware can support two different
depths on the same screen (typically depth 8 and depth 24). If
depth 8 is the default, you can force fvwm to use the best depth
by using the
.B C
option with
.I TrueColor
as argument.  So now we assume that you are forced to run in depth
8 with a dynamic visual because your hardware/driver cannot do
better or because you need to use an application which needs to
run under this mode (e.g., because this application needs
read-write colors). What it should be understand is that you have
only 256 colors and that all the applications which uses the
default color map must share these colors. The main problem is
that there are applications which use a lot or even all the
colors.  If you use such application you will have no more free
colors and some applications (which used only a few colors) may
fail to start or are unusable. There are three things that can be
done (and fvwm does not really play a particular role, all
applications are concerned). The first is to run the applications
which waste your (default) color map with a private color map. For
example, run netscape with the -install option, run KDE/QT
applications with the --cmap option, use the
.B "-C"
option for fvwm. The disadvantage of this method is that it is
visually disturbing (see the
.B ColormapFocus
command for a better control of the color maps switching). The
second method is to limit the number of colors that the
applications used. Again, some applications have options to
specify a given color limit. With fvwm you may try various values,
61 (a special "visual" palette), 56 (a 4x4x3 color cubes plus 6
grey), 29 (a 3x3x3 color cube plus 2 grey), 10 or 9. Also, you may
use the
.B "-L"
option.  However, limiting the number of colors is not the
definitive solution. The definitive solution is to try cause
applications which use a lot of colors use the same colors. This
is a difficult task as there are no formal standards for this
goal. However, some toolkits as QT and GTK use color cubes as
palettes. So, the idea is to configure your applications/toolkits
to all use the same color cube. Moreover, you can use the colors
in this color cube in your X resources configuration files and/or
as arguments to colors options.
Fvwm can use any color cube of the form RxGxB with 2 <= R <= 6, R
= G, R-1 =< B <= R and B >= 2. To get an RxGxB color cube give an
argument to
.B "-l"
an integer c >= R*G*B and < (R+1)*(G+1)*B if B=R and < R*G*(B+1)
if B < R (and different from 61). If c > R*G*B, then some grey may
be added to the color cube. You can use the
.BI "PrintInfo " Colors " " [1]
command to get information on your fvwm colors setting. In
particular, this command prints the palette used by fvwm in rgb
format (the last integer gives the number of times fvwm has
allocated the colors).
.TP
.BR "-L" " | " "--strict-color-limit"
If the screens display 256 colors (or less) and has a dynamic visual,
causes fvwm to use its palette for all the colors. By default, the
palette is used only for images and gradients.
.TP
.BR "-P" " | " "--visual-palette"
If the screen displays 256 colors (or less) and has a dynamic
visual, this option causes fvwm to use a palette designed for
limiting the "visual" color distance between the points of the
palette. Moreover, for better color sharing, if possible colors
with a name in the X rgb data base are used for defining the
colors (with the hope that applications and images will prefer to
use named colors). If the
.B "-l"
option is not used this palette has 61 colors. This palette is
also automatically selected if  61 or 9 is used as argument to the
.B "-l"
option.
.TP
.BR "-A" " | " "--allocate-palette"
If the screen displays 256 colors (or less) and has a dynamic
visual this option causes fvwm to allocate all the colors of its
palette at start up for reserving these colors for future
use. This option forces the .B -static-palette option. By default,
fvwm allocates (reserves) a color in its palette only if it needs
this color.
.TP
.BR "-S" " | " "--static-palette"
If the screen displays 256 colors (or less) and has a dynamic
visual this option causes fvwm to never free the colors in its
palette. By default, when fvwm does not need a color any more it
frees this color so that a new color can be used. This option may
speed up image loading and save a few bits of memory.
.TP
.BI "-blackout"
This option is provided for backward compatibility only.  Blacking
out the screen during startup is not necessary anymore.
.TP
.BI "--debug-stack-ring"
Enables stack ring debugging.  This option is only intended for
internal debugging and should only be used by developers.

.SH ANATOMY OF A WINDOW

Fvwm puts a decorative border around most windows.  This border
consists of a bar on each side and a small L-shaped section on
each corner.  There is an additional top bar called the title-bar
which is used to display the name of the window.  In addition,
there are up to 10 title-bar buttons.  The top, side, and bottom
bars are collectively known as the side-bars.  The corner pieces
are called the frame.

With the built-in minimal configuration, dragging mouse button 1
in the frame or side-bars begins a resize operation on the window.
Dragging mouse button 2 in the frame or side-bars begins a move
operation.  There are raise/lower operations bound to a single
clicking on borders.  Similarly for the window title.

Up to ten title-bar buttons may exist.  Their use is completely
user definable.  One popular configuration uses one button on the
left that is used to bring up a list of window options and two
buttons on the right used to iconify and maximize the window.
Another popular configuration adds a close button to the right.
The number of title-bar buttons used depends on which ones have
mouse actions bound to them.  See the section on the
.B Mouse
command below.

.SH THE VIRTUAL DESKTOP

Fvwm provides multiple virtual desktops for users who wish to use
them.  The screen is a viewport onto a
.I desktop
which may be larger than the screen.  Several distinct desktops
can be accessed (concept: one desktop for each project, or one
desktop for each application, when view applications are
distinct).  Since each desktop can be larger than the physical
screen, divided into m by n
.I pages
which are each the size of the physical screen, windows which are
larger than the screen or large groups of related windows can
easily be viewed.

The (m by n) size (i.e. number of pages) of the virtual desktops
can be changed any time, by using the
.B DeskTopSize
command.  All virtual desktops must be (are) the same
size.  The total number of distinct desktops does not need to be
specified, but is limited to approximately 4 billion total. All
windows on a range of desktops can be viewed in the
.BR FvwmPager ,
a miniature view of the desktops.  The pager is an accessory
program, called a module, which is not essential for the window
manager to operate.  Windows may also be listed, along with their
geometries, in a window list, accessible as a pop-up menu, or as a
separate window, called the
.B FvwmWinList
(another module).

Fvwm keeps the windows on the desktop in a layered stacking order;
a window in a lower layer never obscures a window in a higher
layer. The layer of a window can be changed by using the
.B Layer
command.  The concept of layers is a generalization of the
.I StaysOnTop
flag of older fvwm versions. The
.IR StaysOnTop " and " StaysPut
.B Style
options are now implemented by putting the windows in suitable
layers and the previously missing
.IB "StaysOnBottom " Style
option has been added.

.B Sticky
windows are windows which transcend the virtual desktop by
"Sticking to the screen's glass".  They always stay put on the
screen. This is convenient for things like clocks and xbiff's, so
you only need to run one such gadget and it always stays with you.
Icons can also be made to stick to the glass, if desired.

Window geometries are specified relative to the current viewport.
That is:
.EX
xterm -geometry +0+0
.EE
creates a window in the upper left hand corner of the visible
portion of the screen.  It is permissible to specify geometries
which place windows on the virtual desktop, but off the screen.
For example, if the visible screen is 1000 by 1000 pixels, and the
desktop size is 3x3, and the current viewport is at the upper left
hand corner of the desktop, invoking:
.EX
xterm -geometry +1000+1000
.EE
places a window just off of the lower right hand corner of the
screen.  It can be found by moving the mouse to the lower right
hand corner of the screen and waiting for it to scroll into view.
A geometry specified as something like:
.EX
xterm -geometry -5-5
.EE
places the window's lower right hand corner 5 pixels from the
lower right corner of the visible portion of the screen.  Not all
applications support window geometries with negative offsets.
Some applications place the window's upper right hand corner 5
pixels above and to the left of the upper left hand corner of the
screen; others may do just plain bizarre things.

There are several ways to cause a window to map onto a desktop or
page other than the currently active one. The geometry technique
mentioned above (specifying x,y coordinates larger than the
physical screen size), however, suffers from the limitation of
being interpreted relative to the current viewport: the window may
not consistently appear on a specific page, unless you always
invoke the application from the same page.

A better way to place windows on a different page, screen or desk
from the currently mapped viewport is to use the
.IR StartsOnPage " or " StartsOnScreen
style specification (the successors to the older
.I StartsOnDesk
style) in your
.I config
file.  The placement is consistent: it does
not depend on your current location on the virtual desktop.

Some applications that understand standard Xt command line
arguments and X resources, like xterm and xfontsel, allow the user
to specify the start-up desk or page on the command line:
.EX
xterm -xrm "*Desk:1"
.EE
starts an xterm on desk number 1;
.EX
xterm -xrm "*Page:3 2 1"
.EE
starts an xterm two pages to the right and one down from the upper
left hand page of desk number 3.  Not all applications understand
the use of these options, however.  You could achieve the same
results with the following lines in your
.I .Xdefaults
file:
.EX
XTerm*Desk: 1
.EE
or
.EX
XTerm*Page: 3 2 1
.EE


.SH USE ON MULTI-SCREEN DISPLAYS

If the
.B -s
command line argument is not given, fvwm automatically starts up
on every screen on the specified display.  After fvwm starts each
screen is treated independently.  Restarts of fvwm need to be
performed separately on each screen.  The use of
.EX
 EdgeScroll 0 0
.EE
is strongly recommended for multi-screen displays.  You may need
to quit on each screen to quit from the X session completely.
This is not to be confused with Xinerama support.

.SH XINERAMA SUPPORT

Fvwm supports the Xinerama extension of newer X servers which
is similar to multi head support (multiple screens) but allows for
move windows between screens.  If Xinerama support has been
compiled into fvwm, it is used whenever fvwm runs on an X server
that supports and uses multiple screens via Xinerama.  Without
this option, the whole desktop is treated as one big screen.  For
example, menus might pop up right between two screens.  The
.BI EdgeResistance
command allows for specifying an explicit resistance value for moving
windows over the screen edge between two Xinerama screens.
Xinerama support can be enabled or disabled on the fly or from the
configuration file with the
.B Xinerama
command.  Many modules and commands work nicely with Xinerama
displays.

Everywhere where a geometry in the usual X format can be supplied,
fvwm's Xinerama extension allows for specifying a screen in addition
to the geometry (or even the screen alone).  To do this, a '@' is
added to the end of the geometry string followed by either the
screen number or a letter.  A number is taken as the number of the
Xinerama screen to be used (as configured in the X server).  The
letter can be one of 'g' for the global screen (the rectangle that
encloses all Xinerama screens), 'p' for the primary screen (see
below), 'c' for the current screen (the one that currently
contains the pointer).  If the X server does not support Xinerama
or only one screen is used, the screen bit is ignored.

.EX
Style * IconBox 64x300-0-0@p
.EE

Xinerama support can be configured to use a primary screen.  Fvwm
can be configured to place new windows and icons on this screen.
The primary screen is screen 0 by default but can be changed with
the
.B XineramaPrimaryScreen
command.

Xinerama support was designed to work out of the box with the same
configurations file that would work on a single screen.  It may
not work too well if the involved screens use different screen
resolutions.  In this situation, windows may get stuck in the
portion of the whole desktop that belongs to neither screen.  If
this happens, the windows or icons can be retrieved with the
command

.EX
All MoveToScreen
.EE

that can be entered in an FvwmConsole window or with FvwmCommand.

For multi-screen implementations other than Xinerama, such as
Single Logical Screen, it is possible to simulate a Xinerama
configuration if the total screen seen by fvwm is made up of
equal sized monitors in a rectangular grid.  The commands
.BR XineramaSls ", " XineramaSlsSize " and " XineramaSlsScreens
are used to configure this feature.

.SH INITIALIZATION

During initialization, fvwm searches for a configuration file
which describes key and button bindings, and many other
things. The format of these files is described later.  Fvwm first
searches for configuration files using the command
.EX
.BI "Read " config
.EE
This looks for file
.IR config " in " "$FVWM_USERDIR" " and " "$FVWM_DATADIR"
directories, as described in
.B Read
below.  If this fails more files are queried for backward
compatibility.  Here is the complete list of all file locations
queried in the default installation (only the first found file
is used):
.EX
$HOME/.fvwm/config
/usr/local/share/fvwm/config

$HOME/.fvwm/.fvwm2rc
$HOME/.fvwm2rc
/usr/local/share/fvwm/.fvwm2rc
/usr/local/share/fvwm/system.fvwm2rc
/etc/system.fvwm2rc
.EE
Please note, the last 5 locations are not guarranteed to be
supported in the future.

If a configuration file is not found, the left mouse button, or
.SM Help
or
.SM F1
keys on the root window bring up menus and forms that can create
a starting configuration file.

Fvwm sets two environment variables which are inherited by its
children.  These are
.I $DISPLAY
which describes the display on which fvwm is running.
.I $DISPLAY
may be
.I unix:0.0
or
.IR ":0.0" ,
which doesn't work too well when passed through rsh to another
machine, so
.I $HOSTDISPLAY
is set to a network-ready description of the display.
.I $HOSTDISPLAY
always uses the TCP/IP transport protocol (even for a local
connection) so
.I $DISPLAY
should be used for local connections, as it may use Unix-domain
sockets, which are faster.

If you want to start some applications or modules with fvwm, you
can simply put
.EX
Exec app
.EE
or
.EX
Module FvwmXxx
.EE
into your
.IR config ,
but it is not recommended; do this only if you know what you are
doing. It is usually critical to start applications or modules
after the entire config is read, because it contains styles or
module configurations which can affect window appearance and
functionality.

The standard way to start applications or modules on fvwm's start
up is to add them to an initialization function (usually
.BR StartFunction " or " InitFunction ).
This way they are only started after fvwm finishes to read and
execute
.I config
file.

Fvwm has three special functions for initialization:
.BR StartFunction ,
which is executed on startups and restarts;
.BR InitFunction " and " RestartFunction ,
which are executed during initialization and restarts
(respectively) just after StartFunction.  These functions may be
customized in a user's
.I config
file using the
.B AddToFunc
command (described later) to start up modules, xterms, or whatever
you'd like to have started by fvwm.

Fvwm has also a special exit function:
. BR ExitFunction ,
executed when exiting or restarting before actually quitting.
It could be used to explicitly kill modules, etc.

If fvwm is run under a session manager, functions
.BR SessionInitFunction " and " SessionRestartFunction
are executed instead of InitFunction and RestartFunction.
This helps to define the user's
.I config
file to be good for both running under a session manager and
without it.  Generally it is a bad idea to start xterms or other
applications in "Session*" functions.  Also someone can decide to
start different modules while running under a session manager or
not.  For the similar purposes
.B SessionExitFunction
is used instead of ExitFunction.
.EX
DestroyFunc StartFunction
AddToFunc StartFunction
 + I Module FvwmPager * *
 + I Module FvwmButtons

DestroyFunc InitFunction
AddToFunc InitFunction
 + I Module FvwmBanner
 + I Module FvwmTaskBar
 + I xsetroot -solid cyan
 + I Exec xterm
 + I Exec netscape

DestroyFunc RestartFunction
AddToFunc RestartFunction
 + I Module FvwmTaskBar

DestroyFunc SessionInitFunction
AddToFunc SessionInitFunction
 + I Module FvwmBanner

DestroyFunc SessionRestartFunction
AddToFunc SessionRestartFunction
 + I Nop
.EE
You don't need to define all special functions if some are empty.
Also note, all these special functions may be emulated now using
.BR StartFunction " and " ExitFunction,
like this:
.EX
DestroyFunc StartFunction
AddToFunc StartFunction
+ I Test (Init) Module FvwmBanner
+ I Module FvwmPager * *
+ I Test (Restart) Beep

DestroyFunc ExitFunction
AddToFunc ExitFunction
+ I Test (Quit) Echo Bye-bye
+ I KillModule MyBuggyModule
+ I Test (ToRestart) Beep
.EE

.SH COMPILATION OPTIONS

Fvwm has a number of compile-time options.  If you have trouble
using a certain command or feature, check to see if support for it
was included at compile time.  Optional features are described in
the
.I config.h
file that is generated during compilation.

.SH ICONS AND IMAGES

Fvwm can load
.B .xbm,
.B .xpm,
and
.B .png
images.
.B XBM
images are monochrome.  Fvwm can always display
.B XBM
files.
.B XPM
and
.B PNG
formats are color images.
Compile-time
options determine whether fvwm can display
.B XPM
or
.B PNG
icons and images.
See the
.I INSTALL.fvwm
file for more information.

The related
.BR SHAPE
compile-time option can make fvwm display spiffy
shaped icons.

.SH MODULES

A module is a separate program which runs as a separate Unix
process but transmits commands to fvwm to execute.  Users can
write their own modules to do any weird or bizarre manipulations
without bloating or affecting the integrity of fvwm itself.

Modules must be spawned by fvwm so that it can set up two pipes
for fvwm and the module to communicate with.  The pipes are
already open for the module when it starts and the file
descriptors for the pipes are provided as command line arguments.

Modules can be spawned during fvwm at any time during the X
session by use of the
.B Module
command.  Modules can exist for the duration of the X
session, or can perform a single task and exit.  If the module is
still active when fvwm is told to quit, then fvwm closes the
communication pipes and waits to receive a SIGCHLD from the
module, indicating that it has detected the pipe closure and has
exited.  If modules fail to detect the pipe closure fvwm exits
after approximately 30 seconds anyway.  The number of
simultaneously executing modules is limited by the operating
system's maximum number of simultaneously open files, usually
between 60 and 256.

Modules simply transmit commands to the fvwm command
engine.  Commands are formatted just as in the case of a
mouse binding in the
.I config
setup file.  Certain auxiliary information is also transmitted, as
in the sample module
.BR FvwmButtons .
The
.B FvwmButtons
module is documented in its own man page.

Please refer to the
.B "MODULE COMMANDS"
section for details.

.SH ICCCM COMPLIANCE

Fvwm attempts to be
.SM ICCCM
2.0 compliant.  In addition,
.SM ICCCM
states that it should be possible for applications to receive any
keystroke, which is not consistent with the keyboard shortcut
approach used in fvwm and most other window managers.  In
particular you cannot have the same keyboard shortcuts working
with your fvwm and another fvwm running within Xnest (a nested X
server running in a window).  The same problem exists with mouse
bindings.

The
.SM ICCCM
states that windows possessing the property
.EX
WM_HINTS(WM_HINTS):
    Client accepts input or input focus: False
.EE
should not be given the keyboard input focus by the window
manager. These windows can take the input focus by themselves,
however.  A number of applications set this property, and yet
expect the window manager to give them the keyboard focus anyway,
so fvwm provides a window style,
.IR Lenience ", "
which allows fvwm to overlook this
.SM ICCCM
rule.  Even with this window style it is not guaranteed that the
application accepts focus.

The differences between
.SM ICCCM
1.1 and 2.0 include the ability to take over from a running
.SM ICCCM
2.0 compliant window manager; thus
.EX
fvwm; vi ~/.fvwm/config; fvwm -replace
.EE
resembles the
.B Restart
command.  It is not exactly the same, since killing the previously
running wm may terminate your X session, if the wm was started as
the last client in your
.IR .Xclients " or " .Xsession
file.

Further additions are support for client-side colormap
installation (see the .SM ICCCM for details) and the urgency hint.
Clients can set this hint in the WM_HINTS property of their window
and expect the window manager to attract the users attention to
the window.  Fvwm has two re-definable functions for this purpose,
"UrgencyFunc" and "UrgencyDoneFunc", which are executed when the
flag is set/cleared.  Their default definitions are:
.EX
AddToFunc UrgencyFunc
 + I Iconify off
 + I FlipFocus
 + I Raise
 + I WarpToWindow 5p 5p
AddToFunc UrgencyDoneFunc
 + I Nop
.EE

.SH GNOME COMPLIANCE

Fvwm attempts to be
.SM GNOME
(version 1) compliant.  Check
.B http://www.gnome.org
for what that may mean. To disable GNOME hints for some or all
windows, the
.I GNOMEIgnoreHints
style can be used.

.SH EXTENDED WINDOW MANAGER HINTS

Fvwm attempts to respect the extended window manager hints (ewmh
or EWMH for short) specification:
.BR http://www.freedesktop.org/standards/wm-spec.html
and some extensions of this specification.  This allows fvwm to
work with
.SM KDE
version >= 2,
.SM GNOME
version 2 and other applications which respect this specification
(any application based on
.SM GTK+
version 2). Applications which respect this specification are
called ewmh compliant applications.

This support is configurable with styles and commands.
These styles and commands have
.SM EWMH
as the prefix (so you can find them easily in this man page).

There is a new Context 'D' for the
.BR Key ", " PointerKey ", " Mouse " and " Stroke
commands. This context is for desktop applications (such as
kdesktop and Nautilus desktop).

When a compliant taskbar asks fvwm to activate a window (typically
when you click on a button which represents a window in such a
taskbar), then fvwm calls the complex function
.B EWMHActivateWindowFunc
which by default is Iconify Off, Focus and Raise. You can redefine
this function.  For example:
.EX
DestroyFunc EWMHActivateWindowFunc
AddToFunc EWMHActivateWindowFunc I Iconify Off
+ I Focus
+ I Raise
+ I WarpToWindow 50 50
.EE
additionally warps the pointer to the center of the window.

The
.SM EWMH
specification introduces the notion of Working Area.  Without ewmh
support the Working Area is the full visible screen (or all your
screens if you have a multi head setup and you use Xinerama).
However, compliant applications (such as a panel) can ask to
reserve space at the edge of the screen.  If this is the case, the
Working Area is your full visible screen minus these reserved
spaces. If a panel can be hidden by clicking on a button the
Working Area does not change (as you can unhide the panel at any
time), but the Dynamic Working Area is updated: the space reserved
by the panel is removed (and added again if you pop up the
panel). The Dynamic Working Area may be used when fvwm places or
maximizes a window.  To know if an application reserves space you
can type "xprop | grep _NET_WM_STRUT" in a terminal and select the
application.  If four numbers appear then these numbers define the
reserved space as explained in the
.B EwmhBaseStruts
command.

.SH MWM COMPATIBILITY

Fvwm provides options to emulate Motif Window Manager (Mwm) as
well as possible.  Please refer to the
.B Emulate
command as well as to the Mwm specific options of the
.BR Style " and " MenuStyle
commands for details.

.SH OPEN LOOK and XVIEW COMPATIBILITY
Fvwm supports all the Open Look decoration hints (except
pushpins).  Should you use any such application, please add the
following line to your config:
.EX
Style * OLDecor
.EE
Most (perhaps all) Open Look applications have a strange notion of
keyboard focus handling.  Although a lot of work went into fvwm to
work well with these, you may still encounter problems.  It is
recommended to use the NeverFocus focus policy and the NoLenience
style for all such applications (the windows will still get the
focus):
.EX
Style <application name> NeverFocus, NoLenience
.EE
But in case you can not live with that focus policy, you can try
using one of the other focus policies in combination with the
Lenience style:
.EX
Style <application name> MouseFocus, Lenience
Style <application name> SloppyFocus, Lenience
Style <application name> ClickToFocus, Lenience
.EE

.SH M4 PREPROCESSING

.PP
M4 pre-processing is handled by a module in fvwm.  To get more
details, try man
.BR FvwmM4 .
In short, if you want fvwm to parse your files with m4, then
replace the command
.B Read
with
.B FvwmM4
in your
.I ~/.fvwm/config
file (if it appears at all), and start fvwm with the command
.EX
fvwm -cmd "FvwmM4 config"
.EE

.SH CPP PREPROCESSING

.PP
Cpp is the C-language pre-processor.  fvwm offers cpp processing
which mirrors the m4 pre-processing.  To find out about it,
re-read the M4 section above, but replace "m4" with "cpp".

.SH AUTO-RAISE

.PP
Windows can be automatically raised when it receives focus, or
some number of milliseconds after it receives focus, by using the
auto-raise module,
.BR FvwmAuto .

.SH CONFIGURATION FILES

The configuration file is used to describe mouse and button
bindings, colors, the virtual display size, and related items.
The initialization configuration file is typically called
.IR config " (or " .fvwm2rc ")."
By using the
.B Read
command, it is easy to read in new configuration files as you go.

Lines beginning with '#' are ignored by fvwm.  Lines starting with
\'*' are expected to contain module configuration commands (rather
than configuration commands for fvwm itself). Like in shell
scripts embedded newlines in a configuration file line can be
quoted by preceding them with a backslash.  All lines linked in
this fashion are treated as a single line.  The newline itself is
ignored.

Fvwm makes no distinction between configuration commands and
action commands, so anything mentioned in the fvwm commands
section can be placed on a line by itself for fvwm to execute as
it reads the configuration file, or it can be placed as an
executable command in a menu or bound to a mouse button or a
keyboard key.  It is left as an exercise for the user to decide
which function make sense for initialization and which ones make
sense for run-time.

.SH SUPPLIED CONFIGURATION

A sample configuration file,
.IR system.fvwm2rc ,
is supplied with the fvwm distribution.  It is well commented and
can be used as a source of examples for fvwm configuration.
It may be copied to /usr/local/share/fvwm/config file.

Alternativelly, the built-in menu (accessible when no
configuration file is found) has options to create an initial
config file for the user.

If you are new to
.IR fvwm ", try " fvwm-themes
package demonstrating the powerful fvwm functionality.
.\"
.\" .SH INTERNATIONALIZATION
.\" Internationalized fvwm enables to display not only LATIN-1
.\" characters but also multi byte characters such as Japanese,
.\" Korean, etc. You should set up your environment variable
.\" .IR LC_TYPE " or " LANG ,
.\" to enable this feature.  Also, you should specify proper
.\" .I FONTSET
.\" instead of
.\" .IR FONT .
.\" Note that no catalog-file or input-methods are implemented.

.SH FONT NAMES AND FONT LOADING

The fonts used for the text of a window title, icon titles, menus
and geometry window can be specified by using the Font and
IconFont Style, the Font MenuStyle and the DefaultFont
command. Also, all the Modules which use text have configuration
command(s) to specify font(s). All these styles and commands take
a font name as an argument. This section explains what is a font
name for fvwm and which fonts fvwm loads.

First, you can use what we can call a usual font name, for
example,
.EX
-adobe-courier-bold-r-normal--10-100-75-75-m-60-ISO8859-1
-adobe-courier-bold-r-normal--10-*
-*-fixed-medium-o-normal--14-*-ISO8859-15
.EE
That is, you can use an X Logical Font Description (XLFD for
short).  Then the "first" font which matches the description is
loaded and used. This "first" font depends of your font path and
also of your locale. Fonts which match the locale charset are
loaded in priority order. For example with
.EX
-adobe-courier-bold-r-normal--10-*
.EE
if the locale charset is ISO8859-1, then fvwm tries to load a
font which matches
.EX
-adobe-courier-bold-r-normal--10-*-ISO8859-1
.EE
with the locale charset ISO8859-15 fvwm tries to load
.EX
-adobe-courier-bold-r-normal--10-*-ISO8859-15.
.EE

A font name can be given as an extended XLFD. This
is a comma separated list of (simple) XLFD font names, for example:
.EX
-adobe-courier-bold-r-normal--14-*,-*-courier-medium-r-normal--14-*
.EE
Each simple font name is tried until a matching font with the
locale charset is found and if this fails each simple font name is
tried without constraint on the charset.

More details on the XLFD can be found in the X manual page, the X
Logical Font Description Conventions document (called xlfd) and
the XLoadFont and XCreateFontSet manual pages. Some useful font
utilities are: xlsfonts, xfontsel, xfd and xset.

If you have Xft support you can specify an Xft font name
(description) of a true type (or Type1) font prefixed by "xft:",
for example:
.EX
"xft:Luxi Mono"
"xft:Luxi Mono:Medium:Roman:size=14:encoding=iso8859-1"
.EE
The "first" font which matches the description is loaded.  This
first font depends on the XftConfig configuration file with Xft1
and on the /etc/fonts/fonts.conf file with Xft2.
One may read the Xft manual page and the fontconfig man page with
Xft2. The first string which follows "xft:" is always considered
as the family. With the second example Luxi Mono is the Family
(Other XFree TTF families: "Luxi Serif", "Luxi Sans"), Medium is
the Weight (other possible weights: Light, DemiBold, Bold, Black),
Roman is the slant or the style (other possibility: Regular,
Oblique, Italic) size specifies the point size (for a pixel size
use pixelsize=), encoding allows for enforce a charset (iso8859-1
or iso10646-1 only; if no encoding is given the locale charset is
assumed).
An important parameter is "minspace=bool" where bool is True or
False. If bool is False (the default?) Xft gives a greater font
height to fvwm than if bool is True. This may modify text
placement, icon and window title height, line spacing in menus and
FvwmIdent, button height in some fvwm modules ...etc.  With a LCD
monitor you may try to add "rgba=mode" where mode is either rgb,
bgr, vrgb or vbgr to enable subpixel rendering. The best mode
depends on the way your LCD cells are arranged. You can pass other
specifications in between ":", as "foundry=foundry_name",
"spacing=type" where type can be monospace, proportional or
charcell, "charwidth=integer", "charheight=integer" or
"antialias=bool" where bool is True or False. It seems that these
parameters are not always taken in account.
To determine which Xft fonts are really loaded you can export
XFT_DEBUG=1 before starting fvwm and take a look to the error
log. With Xft2 you may use fc-list to list the available
fonts. Anyway, Xft support is experimental (from the X and the
fvwm point of view) and the quality of the rendering depends on
number of parameters (the XFree and the freetype versions and your
video card(s)).

After an Xft font name you can add after a ";" an XLFD
font name (simple or extended) as:
.EX
xft:Verdana:pixelsize=14;-adobe-courier-bold-r-normal--14-*
.EE
then, if either loading the Xft font fails or fvwm has no Xft
support, fvwm loads the font
"-adobe-courier-bold-r-normal--14-*". This allows for writing
portable configuration files.

.SH FONT AND STRING ENCODING

Once a font is loaded, fvwm finds its encoding (or charset) using
its name (the last two fields of the name). fvwm assumes that the
strings which are displayed with this font use this encoding (an
exception is that if an iso10646-1 font is loaded, then UTF-8 is
assumed for string encoding).
In a normal situation,
(i) a font is loaded by giving a font name without specifying the
encoding,
(ii) the encoding of the loaded font is the locale encoding, and
then
(iii) the strings in the fvwm configuration files should use the
locale encoding as well as the window and icon name. With Xft the
situation is bit different as Xft supports only iso10646-1 and
iso8859-1. If you do not specify one of these encodings in the Xft
font name, then fvwm does strings conversion using (iii). Note
that with multibyte fonts (and in particular with "CJK" fonts) for
good text rendering, the locale encoding should be the charset of
the font.

To override the previous rules, it is possible to specify the
string encoding in the beginning of a font description as follow:
.EX
StringEncoding=enc:_full_font_name_
.EE
where
.B enc
is an encoding supported by fvwm (usually font name charset plus some
unicode encodings: UTF-8, USC-2, USC-4 and UTF-16).

For example, you may use an iso8859-1 locale charset and have an
FvwmForm in Russian using koi8-r encoding. In this case, you just
have to ask FvwmForm to load a koi8-r font by specifying the
encoding in the font name. With a multibyte language, (as
multibyte font works well only if the locale encoding is the
charset of the font), you should use an iso10646-1 font:
.EX
StringEncoding=jisx0208.1983-0:-*-fixed-medium-r-*-ja-*-iso10646-1
.EE
or
.EX
"StringEncoding=jisx0208.1983-0:xft:Bitstream Cyberbit"
.EE
if your
.B FvwmForm
configuration uses jisx0208.1983-0 encoding. Another possibility
is to use UTF-8 encoding for your FvwmForm configuration and use
an iso10646-1 font:
.EX
-*-fixed-medium-r-*-ja-*-iso10646-1
.EE
or
.EX
"StringEncoding=UTF-8:xft:Bitstream Cyberbit"
.EE
or equivalently
.EX
"xft:Bitstream Cyberbit:encoding=iso10646-1"
.EE
In general iso10646-1 fonts together with UTF-8 string encoding
allows the display of any characters in a given menu, FvwmForm
...etc.

More and more, unicode is used and text files use UTF-8
encoding. However, in practice the characters used range over your
locale charset (this is the case when you generate a menu with
fvwm-menu-desktop with recent versions of KDE and GNOME). For
saving memory (an iso10646-1 font may have a very large number of
characters) or because you have a pretty font without an
iso10646-1 charset, you can specify the string encoding to be
UTF-8 and use a font in the locale charset:
.EX
StringEncoding=UTF-8:-*-pretty_font-*-12-*
.EE

In most cases, fvwm correctly determines the encoding of the
font. However, some fonts don't end with valid encoding
names. When the font name isn't normal, for example:
.EX
-misc-fixed-*--20-*-my_utf8-36
.EE
you need to add the encoding after the font name using a slash as
a delimiter. For example:
.EX
MenuStyle * Font -misc-fixed-*--20-*-my_utf8-36/iso10646-1
.EE
If fvwm finds an encoding, fvwm uses the iconv system functions to
do conversion between encodings. Unfortunately, there are no
standards. For conversion between iso8859-1 and UTF-8: a GNU
system uses "ISO-8859-1" and other systems use "iso881" to define
the converters (these two names are supported by fvwm). Moreover,
in some cases it may be necessary to use machine specific
converters. So, if you experience problems you can try to get
information on your iconv implementation ("man iconv" may help)
and put the name which defines the converter between the font
encoding and UTF-8 at the end of the font name after the encoding
hint and a / (another possible solution is to use GNU
libiconv). For example use:
.EX
Style * Font -misc-fixed-*--14-*-iso8859-1/*/latin1
.EE
to use latin1 for defining the converter for the iso8859-1 encoding.
The "*" in between the "/" says to fvwm to determine the
encoding from the end of the font name. Use:
.EX
Style * Font -misc-fixed-*--14-*-local8859-6/iso8859-6/local_iso8859_6_iconv
.EE
to force fvwm to use the font with iso8859-6 as the encoding
(this is useful for bi-directionality)
and to use local_iso8859_6_iconv for defining the converters.

.SH FONT SHADOW EFFECTS

Fonts can be given 3d effects. At the beginning of the font name
(or just after a possible StringEncoding specification) add
.EX
Shadow=size [offset] [directions]:
.EE
.I size
is a positive integer which specifies the number of pixels of shadow.
.I offset
is an optional positive integer which defines the number of pixels
to offset the shadow from the edge of the character.  The default
offset is zero.
.I directions
is an optional set of directions the shadow emanates from the
character.  The
.I directions
are a space separated list of fvwm directions:

.IR N ", "  North ", "     Top ", "         t ", "  Up ", "        u ", " "-"

.IR E ", "  East ", "      Right ", "       r ", "  Right ", "     r ", " "]"

.IR S ", "  South ", "     Bottom ", "      b ", "  Down ", "      d ", " "_"

.IR W ", "  West ", "      Left ", "        l ", "  Left ", "      l ", " "["

.IR NE ", " NorthEast ", " TopRight ", "    tr ", " UpRight ", "   ur ", " "^"

.IR SE ", " SouthEast ", " BottomRight ", " br ", " DownRight ", " dr ", " ">"

.IR SW ", " SouthWest ", " BottomLeft ", "  bl ", " DownLeft ", "  dl ", " "v"

.IR NW ", " NorthWest ", " TopLeft ", "     tl ", " UpLeft ", "    ul ", " "<"

.IR C ", " Center ", "     Centre ", " .

A shadow is displayed in each given direction.
.I All
is equivalent to all the directions.  The default
.I direction
is
.IR BottomRight .
With the
.I Center
direction, the shadow surrounds the whole string.  Since this is a
super set of all other directions, it is a waste of time to
specify this along with any other directions.

The shadow effect only works with colorsets.  The color of the
shadow is defined by using the
.I fgsh
option of the
.I Colorset
command.  Please refer to the
.B COLORSETS
section for details about colorsets.

Note: It can be difficult to find the font,
.IR fg ", " fgsh " and " bg
colors to make this effect look good, but it can look quite good.

.SH BI-DIRECTIONAL TEXT

Arabic and Hebrew text require bi-directional text support to be
displayed correctly, this means that logical strings should be
converted before their visual presentation, so left-to-right and
right-to-left sub-strings are determined and reshuffled.
In fvwm this is done automatically in window titles, menus,
module labels and other places if the fonts used for displaying the
text are of one of the charsets that require
.I bidi
(bi-directional) support.  For example, this includes iso8859-6,
iso8859-8 and iso10646-1 (unicode), but not other iso8859-* fonts.

This bi-directional text support is done using the
.I fribidi
library compile time option, see
.IR INSTALL.fvwm .

.SH KEYBOARD SHORTCUTS

Almost all window manager operations can be performed from the
keyboard so mouse-less operation should be possible.  In addition
to scrolling around the virtual desktop by binding the
.B Scroll
command to appropriate keys,
.BR Popup ", " Move ", " Resize ", "
and any other command can be bound to keys.  Once a command
is started the pointer is moved by using the up, down,
left, and right arrows, and the action is terminated by pressing
return.  Holding down the
.SM Shift
key causes the pointer movement to go in larger steps and holding
down the
.SM control
key causes the pointer movement to go in smaller steps. Standard
emacs and vi cursor movement controls (
.SM n,
.SM p,
.SM f,
.SM b,
and
.SM j,
.SM k,
.SM h,
.SM l
) can be used instead of the arrow keys.

.SH SESSION MANAGEMENT

Fvwm supports session management according to the X Session
Management Protocol.  It saves and restores window position, size,
stacking order, desk, stickiness, shadedness, maximizedness,
iconifiedness for all windows. Furthermore, some global state is
saved.

Fvwm doesn't save any information regarding styles, decors,
functions or menus.  If you change any on these resources during a
session (e.g. by issuing
.B Style
commands or by using various modules), these changes are lost
after saving and restarting the session.  To become permanent,
such changes have to be added to the configuration file.

Note further that the current implementation has the following
anomaly when used on a multi-screen display: Starting fvwm for the
first time, fvwm manages all screens by forking a copy of itself
for each screen.  Every copy knows its parent and issuing a
.B Quit
command to any instance of fvwm kills the master and thus all
copies of fvwm.  When you save and restart the session, the
session manager brings up a copy of fvwm on each screen, but this
time they are started as individual instances managing one screen
only.  Thus a
.B Quit
kills only the copy it was sent to.  This is probably not a very
serious problem, since with session management, you are supposed
to quit a session through the session manager anyway. If it is
really needed,
.EX
Exec exec killall fvwm
.EE
still kills all copies of fvwm.  Your system must have the
.B killall
command though.

.SH BOOLEAN ARGUMENTS

A number of commands take one or several boolean arguments.  These
take a few equivalent inputs: "yes", "on", "true", "t" and "y" all
evaluate to true while "no", "off", "false", "f" and "n" evaluate
to false.  Some commands allow "toggle" too which means that the
feature is disabled if it is currently enabled and vice versa.

.SH CONDITIONAL COMMANDS AND RETURN CODES

Fvwm recognizes a number of commands that are executed only if
certain conditions are met.  For a complete description, please
refer to the section
.B CONDITIONAL COMMANDS
below.

.SH BUILT-IN KEY AND MOUSE BINDINGS

The following commands are built-in to fvwm:
.EX
Key Help R A Popup MenuFvwmRoot
Key F1 R A Popup MenuFvwmRoot
Key Tab A M WindowList Root c c NoDeskSort
Key Escape A MC EscapeFunc
Mouse 1 R A Menu MenuFvwmRoot
Mouse 1 T   A FuncFvwmRaiseLowerX Move
Mouse 1 FS  A FuncFvwmRaiseLowerX Resize
Mouse 2 FST A FuncFvwmRaiseLowerX Move
AddToFunc FuncFvwmRaiseLowerX
+ I Raise
+ M $0
+ D Lower
.EE
The
.SM Help
and
.SM F1
keys invoke a built-in menu that fvwm creates.  This is primarily
for new users that have not created their own configuration
file. Either key on the root (background) window pops up an menu
to help you get started.

The
.SM Tab
key pressed anywhere with the
.SM Meta
key (same as the
.SM Alt
key on PC keyboards) held down pop-ups a window list.

Mouse button 1 on the title-bar or side frame can move, raise or
lower a window.

Mouse button 1 on the window corners can resize, raise or lower a
window.

You can override or remove these bindings. To remove the window
list binding, use this:
.EX
Key Tab A M -
.EE

.SH MODULE AND FUNCTION COMMANDS

If fvwm encounters a command that it doesn't recognize,
it checks to see if the
specified command should have been
.EX
Function (rest of command)
.EE
or
.EX
Module (rest of command)
.EE
This allows complex functions or modules to be invoked in a manner
which is fairly transparent to the configuration file.

Example: the
.I config
file contains the line
.EX
HelpMe
.EE
Fvwm looks for an fvwm command called "HelpMe", and fails.
Next it looks for a user-defined complex function called "HelpMe".
If no such function exists, fvwm tries to execute a
module called "HelpMe".

.SH DELAYED EXECUTION OF COMMANDS

Note: There are many commands that affect look and feel of
specific, some or all windows, like
.BR Style ", " Mouse ", " Colorset ", " TitleStyle
and many others.  For performance reasons such changes are
not applied immediately but only when fvwm is idle, i.e. no user
interaction or module input is pending.  Specifically, new
.B Style
options that are set in a function are not applied until after the
function has completed.  This can sometimes lead to unwanted
effects.

To force that all pending changes are applied immediately, use the
.BR UpdateStyles ", " Refresh " or " RefreshWindow
commands.

.SH QUOTING

Quotes are required only when needed to make fvwm consider two or
more words to be a single argument.  Unnecessary quoting is
allowed.  If you want a quote character in your text, you must
escape it by using the backslash character.  For example, if you
have a pop-up menu called "Window-Ops", then you don't need
quotes:
.EX
Popup Window-Ops
.EE
but if you replace the dash with a space, then you need
quotes:
.EX
Popup "Window Ops"
.EE
The supported quoting characters are double quotes, single quotes
and reverse single quotes.  All three kinds of quotes are treated
in the same way.  Single characters can be quoted with a preceding
backslash.  Quoting single characters works even inside other
kinds of quotes.

.SH COMMAND EXPANSION

Whenever an fvwm command line is executed, fvwm performs parameter
expansion.  A parameter is a '$' followed by a word enclosed in
brackets ($[...]) or a single special character.  If fvwm
encounters an unquoted parameter on the command line it expands it
to a string indicated by the parameter name.  Unknown parameters
are left untouched.  Parameter expansion is performed before
quoting.  To get a literal '$' use "$$".

In the past, some single letter variables were supported.  It is
deprecated now, since they cause a number of problems.  You should
use the longer substitutes instead.

Example:

.EX
# Print the current desk number, horizontal page number
# and the window's class (unexpanded here, no window).
Echo $[desk.n] $[page.nx] $[w.class]
.EE

Note: If the command is called outside a window context, it will
print "$[w.class]" instead of the class name.  It is usually not
enough to have the pointer over a window to have a context window.
To force using the window with the focus, the
.B Current
command can be used:
.EX
Current Echo $[desk.n] $[page.nx] $[w.class]
.EE

The parameters known by fvwm are:

.in +.5i
$$
.in +.3i
A literal '$'.
.in -.3i
.in -.5i

.in +.5i
$.
.in +.3i
The absolute directory of the currently Read file.  Intended for
creating relative and relocatable configuration trees.  If used
outside of any read file, the returned value is '.'.
.in -.3i
.in -.5i

.in +.5i
$0 to $9
.in +.3i
The positional parameters given to a complex function (a function
that has been defined with the
.B AddToFunc
command).  "$0" is replaced with the first parameter, "$1" with
the second parameter and so on.  If the corresponding parameter is
undefined, the "$..." is deleted from the command line.
.in -.3i
.in -.5i

.in +.5i
$*
.in +.3i
All positional parameters given to a complex function.  This
includes parameters that follow after "$9".
.in -.3i
.in -.5i

.in +.5i
$[version.num]
.in +.3i
The version number, like "2.6.0".
.in -.3i
.in -.5i

.in +.5i
$[version.info]
.in +.3i
The version info, like " (from cvs)", empty for the official
releases.
.in -.3i
.in -.5i

.in +.5i
$[version.line]
.in +.3i
The first line printed by the --version command line option.
.in -.3i
.in -.5i

.in +.5i
$[vp.x]
$[vp.y]
$[vp.width]
$[vp.height]
.in +.3i
Either coordinate or the width or height of the current viewport.
.in -.3i
.in -.5i

.in +.5i
$[desk.n]
.in +.3i
The current desk number.
.in -.3i
.in -.5i

.in +.5i
$[desk.name<n>]
.in +.3i
These parameters are replaced with the name of the desktop
number <n> that is defined with the
.B DesktopName
command. If no name is defined, then the default name is returned.
.in -.3i
.in -.5i

.in +.5i
$[desk.width]
$[desk.height]
.in +.3i
The width or height of the whole desktop, i.e. the width or height
multiplied by the number of pages in x or y direction.
.in -.3i
.in -.5i

.in +.5i
$[desk.pagesx]
$[desk.pagesy]
.in +.3i
The number of total pages in a desk in x or y direction.
This is the same as the values set by
.BR DesktopSize .
.in -.3i
.in -.5i

.in +.5i
$[page.nx]
$[page.ny]
.in +.3i
The current page numbers, by X and Y axes, starting from 0.
.IR page " is equivalent to " area " in the GNOME terminology."
.in -.3i
.in -.5i

.in +.5i
$[w.id]
.in +.3i
The window-id (expressed in hex, e.g. 0x10023c) of the window the
command was called for or "$[w.id]" if no window is associated
with the command.
.in -.3i
.in -.5i

.in +.5i
$[w.name]
$[w.iconname]
$[w.iconfile]
$[w.miniiconfile]
$[w.class]
$[w.resource]
.in +.3i
The window's name, icon name, file name of its icon or mini icon
defined with the
.IR Icon " or " MiniIcon
style including the path information if the file was found on
disk, resource class or resource name respectivelly, or unexpanded
"$[w.<attribute>]" string if no window is associated with the
command.

.in -.3i
.in -.5i

.in +.5i
$[w.x]
$[w.y]
$[w.width]
$[w.height]
.in +.3i
Either coordinate or the width or height of the current window if
it is not iconified.  If no window is associated with the command
or the window is iconified, the string is left as is.
.in -.3i
.in -.5i

.in +.5i
$[w.desk]
.in +.3i
The number of the desk on which the window is shown.  If the
window is sticky the current desk number is used.
.in -.3i
.in -.5i

.in +.5i
$[w.layer]
.in +.3i
The layer of the window.
.in -.3i
.in -.5i

.in +.5i
$[cw.x]
$[cw.y]
$[cw.width]
$[cw.height]
.in +.3i
These work like $[w....] but return the geometry of the client
part of the window.  In other words: the border and title of the
window is not taken into account.
.in -.3i
.in -.5i

.in +.5i
$[i.x], $[it.x], $[ip.x]
$[i.y], $[it.y], $[ip.y]
$[i.width], $[it.width], $[ip.width]
$[i.height], $[it.height], $[ip.height]
.in +.3i
These work like $[w....] but return the geometry of the icon
($[i....]), the icon title ($[it....]) or the icon picture
($[ip....]).
.in -.3i
.in -.5i

.in +.5i
$[pointer.x]
$[pointer.y]
.in +.3i
These return the position of the pointer on the screen.  If the
pointer is not on the screen, these variables are not expanded.
.in -.3i
.in -.5i

.in +.5i
$[pointer.wx]
$[pointer.wy]
.in +.3i
These return the position of the pointer in the selected window.
If the pointer is not on the screen, the window is iconified  or
no window is selected, these variables are not expanded.
.in -.3i
.in -.5i

.in +.5i
$[pointer.cx]
$[pointer.cy]
.in +.3i
These return the position of the pointer in the client portion of
the selected window.  If the pointer is not on the screen, the
window is shaded or iconified or no window is selected, these
variables are not expanded.

.in -.3i
.in -.5i

.in +.5i
$[screen]
.in +.3i
The screen number fvwm is running on.  Useful for setups with
multiple screens.
.in -.3i
.in -.5i

.in +.5i
$[fg.cs<n>]
.in -.5i
.in +.5i
$[bg.cs<n>]
.in -.5i
.in +.5i
$[hilight.cs<n>]
.in -.5i
.in +.5i
$[shadow.cs<n>]
.in +.3i
These parameters are replaced with the name of the foreground
(fg), background (bg), hilight (hilight) or shadow (shadow) color
that is defined in colorset <n> (replace <n> with zero or a
positive integer).  For example "$[fg.cs3]" is expanded to the
name of the foreground color of colorset 3 (in rgb:rrrr/gggg/bbbb
form).  Please refer to the
.B COLORSETS
section for details about colorsets.
.in -.3i
.in -.5i

.in +.5i
$[schedule.last]
.in +.3i
This is replaced by the id of the last command that was scheduled
with the
.B Schedule
command, even if this command was already executed.
.in -.3i
.in -.5i

.in +.5i
$[schedule.next]
.in +.3i
This is replaced by the id the next command used with
.B Schedule
will get (unless a different id is specified explicitly).
.in -.3i
.in -.5i

.in +.5i
$[cond.rc]
.in +.3i
The return code of the last conditional command.  This variable is
only valid inside a function and can not be used in a conditional
command.  Please refer to the section
.B CONDITIONAL COMMANDS
in the command list.
.in -.3i
.in -.5i

.in +.5i
$[func.context]
.in +.3i
The context character of the running command as used in the
.BS Mouse ", " Key " or " PointerKey
command.  This is useful for example with:
.EX
Mouse 3 FS N WindowShade $$[func.context]
.EE
.in -.3i
.in -.5i

.in +.5i
$[gt.str]
.in +.3i
return the translation of
.I str
by looking in the current locale catalog(s). If no translation is
found
.I str
is returned as is. See the
.B LocalePath
command.
.in -.3i
.in -.5i

.in +.5i
$[...]
.in +.3i
If the string within the braces is neither of the above, fvwm
tries to find an environment variable with this name and replaces
its value if one is found (e.g. "$[PAGER]" could be replaced by
"more").  Otherwise the string is left as is.
.in -.3i
.in -.5i

Some examples can be found in the description of the
.B AddToFunc
command.

.SH SCRIPTING AND COMPLEX FUNCTIONS

To achieve the more complex effects, fvwm has a number of
commands that improve its scripting abilities.  Scripts can be
read from a file with
.BR Read ,
from the output of a command with
.B PipeRead
or written as a complex function with the
.B AddToFunc
command.  For the curious, section 7 of the fvwm FAQ shows some
real life applications of scripting.  Please refer to the sections
.B COMMANDS FOR USER FUNCTIONS AND SHELL COMMANDS
and
.B CONDITIONAL COMMANDS
for details.  A word of warning:  during execution of complex
functions, fvwm needs to take all input from the mouse pointer
(the pointer is "grabbed" in the slang of X).  No other programs
can receive any input from the pointer while a function is run.
This can confuse some programs.  For example, the xwd program
refuses to make screen shots when run from a complex function.  To
achieve the same functionality you can use the
.BR Read " or " PipeRead
command instead.

.SH THE LIST OF FVWM COMMANDS

The command descriptions below are grouped together in the
following sections.  The sections are hopefully sorted in order of
usefulness to the newcomer.
.EX
- Menu commands
- Miscellaneous commands
- Commands affecting window movement and placement
- Commands for focus and mouse movement
- Commands controlling window state
- Commands for mouse, key and stroke bindings
- The Style command (controlling window styles)
- Other commands controlling window styles
- Commands controlling the virtual desktop
- Commands for user functions and shell commands
- Conditional commands
- Module commands
- Quit, restart and session management commands
- Color gradients
.EE

.SS MENUS

Before a menu can be opened, it has to be populated with menu
items using the
.B AddToMenu
command and bound to a key or mouse button with the
.BR Key ", " PointerKey " or " Mouse
command (there are many other ways to invoke a menu too).  This is
usually done in the configuration file.

Fvwm menus are extremely configurable in look and feel.  Even the
slightest nuances can be changed to the user's liking, including
the menu item fonts, the background, delays before popping up sub
menus, generating menus dynamically and many other features.
Please refer to the
.B MenuStyle
command to learn more.

.TP
.B Types of Menus

In fvwm there are four slightly different types of menus:

.I Popup menus
can appear everywhere on the screen on their own or attached to a
part of a window.  The
.B Popup
command opens popup menus.  If the popup menu was invoked with a
mouse button held down, it is closed when the button is released.
THe item under the pointer is then activated and the associated
action is executed.

.B Menu
is a very similar command, but the menus it opens are slightly less
transient.  When invoked by clicking a mouse button, it stays open
and can be navigated with no button held.  But if it is invoked by
a button press followed by mouse motion, it behaves exactly like a
popup menu.

.IR "Tear off menus" " or " "Pin up menus"
are menus from either of the above two commands that have been
"torn off" their original context and pinned on the desktop like a
normal window.  They are created from other menus by certain key
presses or mouse sequences or with the
.B TearMenuOff
command from inside a menu.

.I Sub menus
are menus inside menus.  When a menu item that has the
.B Popup
command as its action is selected, the named menu is opened as an
inferior menu to the parent.  Any type of menu can have sub menus.

.TP
.B Menu Anatomy

Menus consist of any number of titles which are inactive menu
items that usually appear at the top of the menu, normal items
triggering various actions when selected, separator lines between
the items, tear off bars (a horizontal broken line) that tear off
the menu when selected, and sub menu items indicated with a
triangle pointing left or right, depending on the direction in
which the sub menu appears.  All the above menu items are
optional.

Additionally, if the menu is too long to fit on the screen, the
excess menu items are put in a continuation menu and a sub menu
with the string "More..." is placed at the bottom of the menu.
Finally, there may be a picture running up either side of the menu
(a "side bar").

.TP
.B Menu Navigation

Menus can be navigated either with the keyboard or with the
mouse.  Many people prefer to use the mouse, but it can be rather
tedious.  Once you get the hang of it, keyboard navigation can be
much faster.  While fvwm displays a menu, it can do nothing else.
For example, new windows do not appear before the menu is closed.
However, this is not exactly true for tear off menus.  See the
.B Tear Off Menus
section for details.

.TP
.B Mouse Navigation

Moving the pointer over a menu selects the item below it.
Normally this is indicated by a 3d border around the item, but not
all parts of a menu can be selected.  Pressing any mouse button
while a menu is open activates the item below it.  Items of a
popup menu are also activated by releasing a held mouse button.
In case of an item that hides a sub menu, the sub menu is
displayed if the pointer hovers over the item long enough or moves
close to the triangle indicating the sub menu.  This behaviour can
be tuned with menu styles.

Clicking on a selected item activates it - what happens exactly
depends on the type of the item.

Clicking on a title, a separator, the side bar, or outside the
menu closes the menu (exception:  tear off menus can not be closed
this way).  Pressing mouse button 2 over a menu title or
activating a tear off bar creates a tear off menu from the current
menu.  Clicking on a normal menu item invokes the command that is
bound to it, and clicking on a sub menu item either closes all
open menus and replaces them with the sub menu or posts the menu
(default).

Posting menus is meant to ease mouse navigation.  Once a sub menu
is posted, only items from that sub menu can be selected.  This
can be very useful to navigate the menu if the pointer tends to
stray off the menu.  To unpost the menu and revert back to normal
operation, either click on the same sub menu item or press any
key.

.TP
.B Keyboard Navigation

Just like with mouse navigation, the item below the pointer is
selected.  This is achieved by warping the pointer to the menu
items when necessary.  While a menu is open, all key presses are
intercepted by the menu.  No other application can get keyboard
input (although this is not the case for tear off menus).

Items can be selected directly by pressing a hotkey that can be
configured individually for each menu item.  The hotkey is
indicated by underlining it in the menu item label.  With the
.I AutomaticHotkeys
menu style fvwm automatically assigns hotkeys to all menu items.

The most basic keys to navigate through menus are the cursor keys
(move up or down one item, enter or leave a sub menu),
.SM Space
(activate item) and
.SM Escape
(close menu).  Numerous other keys can be used to navigate through
menus:

.SM \fIEnter\fP,
.SM \fIReturn\fP,
.SM \fISpace\fP
activate the current item.

.SM \fIEscape\fP,
.SM \fIDelete\fP,
.SM \fICtrl-G\fP
exit the current sequence of menus or destroy a tear off menu.

.SM \fIJ\fP,
.SM \fIN\fP,
.SM \fICursor-Down\fP,
.SM \fITab\fP,
.SM \fIMeta-Tab\fP,
.SM \fICtrl-F\fP,
move to the next item.

.SM \fIK\fP,
.SM \fIP\fP,
.SM \fICursor-Up\fP,
.SM \fIShift-Tab\fP,
.SM \fIShift-Meta-Tab\fP,
.SM \fICtrl-B\fP,
move to the prior item.

.SM \fIL\fP,
.SM \fICursor-Right\fP,
.SM \fIF\fP
enter a sub menu.

.SM \fIH\fP,
.SM \fICursor-Left\fP,
.SM \fIB\fP
return to the prior menu.

.SM \fICtrl-Cursor-Up\fP,
.SM \fICtrl-K\fP
.SM \fICtrl-P\fP,
.SM \fIShift-Ctrl-Meta-Tab\fP,
.SM \fIPage-Up\fP
move up five items.

.SM \fICtrl-Cursor-Down\fP,
.SM \fICtrl-J\fP
.SM \fICtrl-N\fP,
.SM \fICtrl-Meta-Tab\,P,
.SM \fIPage-Down\fP
move down five items.

.SM \fIHome\fP,
.SM \fIShift-Cursor-Up\fP,
.SM \fICtrl-A\fP
move to the first item.

.SM \fIEnd\fP,
.SM \fIShift-Cursor-Down\fP,
.SM \fICtrl-E\fP
move to the last item.

.SM \fIMeta-Cursor-Up\fP,
.SM \fICtrl-Cursor-Left\fP,
.SM \fIShift-Ctrl-Tab\fP
move up just below the next separator.

.SM \fIMeta-Cursor-Down\fP,
.SM \fICtrl-Cursor-Right\fP,
.SM \fICtrl-Tab\fP
move down just below the next separator.

.SM \fIInsert\fP
opens the "More..." sub menu if any.

.SM \fIBackspace\fP
tears off the menu.

.TP
.B Tear Off Menus

A tear off menu is any menu that has been "torn off" the window it
was attached to and pinned to the root window.  There are three
ways to tear off a menu:  click on the menu title with mouse
button 2, press
.SM Backspace
in the menu or activate its tear off bar (a horizontal bar with a
broken line).  Tear off bars must be added to the menu as any
other item by assigning them the command
.BR TearMenuOff .

The action taken with the backspace key cannot be overridden
but the action of mouse button 2 on the title can.
To remove the builtin mouse button 2 binding, use:

Mouse 2 M N -

("M" is for "Menu" context)

To assign some other button for tearoff, use:

Mouse 1 M N TearOff

Note that the Modifier, must be "N" (none) and that the
notation "Mouse 0" (for any mouse button cannot be used.)

The window containing the menu is placed as any other window would
be.  If you find it confusing to have your tear off menus appear
at random positions on the screen, put this line in your
configuration file:
.EX
Style fvwm_menu UsePPosition
.EE

A tear off menu is a cross breeding between a window and a menu.
The menu is swallowed by a window and its title is stripped off
and displayed in the window title.  The main advantage is that the
menu becomes permanent - activating an item does not close the
menu.  Therefore, it can be used multiple times without reopening
it.  To destroy such a menu, close its window or press the
.SM Escape
key.

Tear off menus behave somewhat differently than normal menus and
windows.  They do not take the keyboard focus, but while the
pointer is over one of them, all key presses are sent to the
menu.  Other fvwm key bindings are disabled as long as the pointer
is inside the tear off menu or one of its sub menus.  When the
pointer leaves this area, all sub menus are closed immediately.
Note that the window containing a tear off menu is never hilighted
as if it had the focus.

A tear off menu is an independent copy of the menu it originated
from.  As such, it is not affected by adding items to that menu or
changing its menu style.

To create a tear off menu without opening the normal menu first,
the option
.I TearOffImmediately
can be added to the
.BR Menu " or " Popup
command.

.TP
.BI "AddToMenu " menu-name " [" menu-label " " action "]"

Begins or adds to a menu definition.  Typically a menu definition
looks like this:
.EX
AddToMenu Utilities Utilities Title
 + Xterm           Exec  exec xterm -e tcsh
 + Rxvt            Exec  exec rxvt
 + "Remote Logins" Popup Remote-Logins
 + Top             Exec  exec rxvt -T Top -n \\
                   Top -e top
 + Calculator      Exec  exec xcalc
 + Xman            Exec  exec xman
 + Xmag            Exec  exec xmag
 + emacs           Exec  exec xemacs
 + Mail            MailFunction \\
                   xmh "-font fixed"
 + ""              Nop
 + Modules         Popup Module-Popup
 + ""              Nop
 + Exit Fvwm       Popup Quit-Verify
.EE
The menu could be invoked via
.EX
Mouse 1 R A Menu Utilities Nop
.EE
or
.EX
Mouse 1 R A Popup Utilities
.EE
There is no end-of-menu symbol.  Menus do not have to be defined
in a contiguous region of the
.I config
file.  The quoted (or first word)
portion in the above examples is the menu label,
which appears in the menu when the user pops it up.  The remaining
portion is an fvwm command which is executed if the user
selects that menu item.  An empty menu-label ("") and the
.B Nop
function are used to insert a separator into the menu.

The keywords
.IR DynamicPopUpAction " and " DynamicPopDownAction
have a special meaning when used as the name of a menu item.  The
action following the keyword is executed whenever the menu is
popped up or down.  This way you can implement dynamic menus.  It
is even possible to destroy itself with
.B DestroyMenu
and the rebuild from scratch.  When the menu has been destroyed
(unless you used the
.I recreate
option when destroying the menu), do not forget to add the dynamic
action again.

Note: Do not trigger actions that require user interaction. They
will probably fail and may screw up your menus.  See the
.B Silent
command.

Warning: Do not issue
.B MenuStyle
commands as dynamic menu actions.  Chances are good that this will
crash fvwm.

There are several configurable scripts installed together with fvwm
for automatical menu generation.  They have their own man pages.
Some of them, specifically
.BR fvwm-menu-directory " and " fvwm-menu-desktop ,
may be used with
.I DynamicPopupAction
to create a directory listing or GNOME/KDE application listing.

Example (File browser):
.EX
# You can find the shell script fvwm_make_browse_menu.sh
# in the utils/ directory of the distribution.
AddToMenu BrowseMenu
+ DynamicPopupAction Piperead \\
  'fvwm_make_browse_menu.sh BrowseMenu'
.EE
Example (Picture menu):
.EX
# Build a menu of all .jpg files in
# $HOME/Pictures
AddToMenu JpgMenu foo title
+ DynamicPopupAction Function MakeJpgMenu

AddToFunc MakeJpgMenu
+ I DestroyMenu recreate JpgMenu
+ I AddToMenu JpgMenu Pictures Title
+ I PipeRead 'for i in $HOME/Pictures/*.jpg; \\
  do echo AddToMenu JpgMenu "`basename $i`" Exec xv $i; done'
.EE
The keyword
.I MissingSubmenuFunction
has a similar meaning.  It is executed whenever you try to pop up
a sub menu that does not exist.  With this function you can define
and destroy menus on the fly.  You can use any command after the
keyword, but the name of an item (that is a submenu) defined with
.B AddToFunc
follows it, fvwm executes this command:
.EX
Function <function-name> <submenu-name>
.EE
I.e. the name is passed to the function as its first argument and
can be referred to with "$0".

The
.B fvwm-menu-directory
script mentioned above may be used with
.I MissingSubmenuFunction
to create an up to date recursive directory listing.

Example:
.EX
# There is another shell script fvwm_make_directory_menu.sh
# in the utils/ directory of the distribution. To use it,
# define this function in your configuration file:

DestroyFunc MakeMissingDirectoryMenu
AddToFunc MakeMissingDirectoryMenu
+ I PipeRead fvwm_make_directory_menu.sh $0

DestroyMenu SomeMenu
AddToMenu SomeMenu
+ MissingSubmenuFunction MakeMissingDirectoryMenu
+ "Root directory" Popup /
.EE
This is another implementation of the file browser that uses
sub menus for subdirectories.

Titles can be used within the menu. If you add the option
.I top
behind the keyword
.BR Title ,
the title is added to the top of the menu.  If there was a title
already, it is overwritten.
.EX
AddToMenu Utilities Tools Title top
.EE
All text up to the first
.SM Tab
in the menu label is aligned to the left side of the menu, all
text right of the first
.SM Tab
is aligned to the left in a second column and all text thereafter
is placed right aligned in the third column.  All other
.SM Tabs
are replaced by spaces.  Note that you can change this format with
the
.I ItemFormat
option of the
.B MenuStyle
command.

If the menu-label contains an ampersand ('&'), the next character
is taken as a hot-key for the menu item.  Hot-keys are underlined
in the label.  To get a literal '&', insert "&&".  Pressing the
hot-key moves through the list of menu items with this hot-key or
selects an item that is the only one with this hot-key.

If the menu-label contains a sub-string which is set off by stars,
then the text between the stars is expected to be the name of an
image file to insert in the menu.  To get a literal
\'*', insert "**".  For example
.EX
 + Calculator*xcalc.xpm* Exec exec xcalc
.EE
inserts a menu item labeled "Calculator" with a picture of a
calculator above it.  The following:
.EX
 + *xcalc.xpm*           Exec exec xcalc
.EE
Omits the "Calculator" label, but leaves the picture.

If the menu-label contains a sub-string which is set off by
percent signs, then the text between the percent signs is expected
to be the name of image file (a so called mini
icon to insert to the left of the menu label.  A second mini icon
that is drawn at the right side of the menu can be given in the
same way.  To get a literal '%', insert "%%". For example
.EX
 + Calculator%xcalc.xpm% Exec exec xcalc
.EE
inserts a menu item labeled "Calculator" with a picture of a
calculator to the left.  The following:
.EX
 + %xcalc.xpm%           Exec exec xcalc
.EE
Omits the "Calculator" label, but leaves the picture.  The
pictures used with this feature should be small (perhaps 16x16).
If the menu-name (not the label) contains a sub-string which is
set off by at signs ('@'), then the text between them is expected
to be the name of an xpm or bitmap file to draw along the left
side of the menu (a side pixmap).  You may want to use the
.I SidePic
option of the
.B MenuStyle
command instead.  To get a literal '@', insert "@@".  For example
.EX
AddToMenu StartMenu@linux-menu.xpm@
.EE
creates a menu with a picture in its bottom left corner.

If the menu-name also contains a sub-string surrounded by '^'s, then
the text between '^'s is expected to be the name of an X11 color
and the column containing the side picture is colored with that
color.  You can set this color for a menu style using the
.I SideColor
option of the
.B MenuStyle
command.  To get a literal '^', insert "^^".  Example:
.EX
AddToMenu StartMenu@linux-menu.xpm@^blue^
.EE
creates a menu with a picture in its bottom left corner and
colors with blue the region of the menu containing the picture.

In all the above cases, the name of the resulting menu is name
specified, stripped of the substrings between the various
delimiters.

.TP
.BI "ChangeMenuStyle " "menustyle menu ..."
Changes the menu style of
.IR menu " to " menustyle .
You may specified more than one menu in each call of
.BR ChangeMenuStyle .
.EX
ChangeMenuStyle pixmap1 \\
  ScreenSaverMenu ScreenLockMenu
.EE

.TP
.BI "CopyMenuStyle " "orig-menustyle dest-menustyle"
Copy
.IR orig-menustyle " to " dest-menustyle ,
where
.IR orig-menustyle
is an existing menu style.  If the menu style
.IR dest_menustyle
does not exist, then it is created.

.TP
.BI "DestroyMenu [" recreate "] " menu
Deletes a menu, so that subsequent references to it are no longer
valid.  You can use this to change the contents of a menu during
an fvwm session.  The menu can be rebuilt using
.BR AddToMenu .
The optional parameter
.I recreate
tells fvwm not to throw away the menu completely but to throw away
all the menu items (including the title).
.EX
DestroyMenu Utilities
.EE

.TP
.BI "DestroyMenuStyle " menustyle
Deletes the menu style named
.I menustyle
and changes all menus using this style to the default style, you
cannot destroy the default menu style.
.EX
DestroyMenuStyle pixamp1
.EE

.TP
.B "Menu \fImenu-name\fP \
[\fIposition\fP\
] [\fIdouble-click-action\fP\
]"
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
.I double-click-action
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).

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

The
.I position
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
.I context-rectangle
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
.I position
arguments consist of several parts:
.EX
.BI "[" context-rectangle "] " "x y" " [" special-options "]"
.EE
The
.I context-rectangle
can be one of:

.in +.5i
.BR Root
.in +.3i
the root window of the current screen.
.in -.3i
.BR XineramaRoot
.in +.3i
the root window of the whole Xinerama screen.  Equivalent to
"root" when Xinerama is not used.
.in -.3i
.BR Mouse
.in +.3i
a 1x1 rectangle at the mouse position.
.in -.3i
.BR Window
.in +.3i
the frame of the context window.
.in -.3i
.BR Interior
.in +.3i
the inside of the context window.
.in -.3i
.BR Title
.in +.3i
the title of the context window or icon.
.in -.3i
.BR Button<n>
.in +.3i
button #n of the context window.
.in -.3i
.BR Icon
.in +.3i
the icon of the context window.
.in -.3i
.BR Menu
.in +.3i
the current menu.
.in -.3i
.BR Item
.in +.3i
the current menu item.
.in -.3i
.BR Context
.in +.3i
the current window, menu or icon.
.in -.3i
.BR This
.in +.3i
whatever widget the pointer is on (e.g. a corner of a window or
the root window).
.in -.3i
.BI "Rectangle <" geometry ">"
.in +.3i
the rectangle defined by
.RI < geometry >
in X geometry format.  Width and height default to 1 if omitted.
.in -.3i
.in -.5i

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).

The offset values
.I x
and
.I y
specify how far the menu is moved from it's default position.  By
default, the numeric value given is interpreted as a percentage of
the context rectangle's width (height), but with a trailing
.RI ' m '
the menu's width (height) is used instead.  Furthermore a trailing
.RI ' p '
changes the interpretation to mean pixels.

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.

If
.IR x " or " y
are prefixed with "o<number>" where <number> 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 <number> percent of the
rectangle's width/height is right over the pixel at <number>
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<number>" is an abbreviation for "+<number>-<number>m".

A prefix of
.RI ' c '
is equivalent to "o50".  Examples:
.EX
# window list in the middle of the screen
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
Popup name mouse c -100m-8p

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

# centered vertically around a menu item
AddToMenu foobar-menu
 + "first item" Nop
 + "special item" Popup "another menu" item \\
                  +100 c
 + "last item" Nop

# above the first menu item
AddToMenu foobar-menu
 + "first item" Popup "another menu" item \\
                +0 -100m
.EE
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.

The
.IR special-options :

.in +.5i
To create a tear off menu without opening the normal menu, add the
option
.IR 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:
.EX
# Forbid fvwm to place the menu window
Style <name of menu> UsePPosition
# Menu at top left corner of screen
Menu Root 0p 0p TearOffImmediately
.EE

The
.IR animated " and " Mwm " or " Win
menu styles may move a menu somewhere else on the screen.  If you
do not want this you can add
.I Fixed
as an option.  This might happen for example if you want the menu
always in the top right corner of the screen.

Where do you want a menu to appear when you click on it's menu
item? The default is to place the title under the cursor, but if
you want it where the position arguments say, use the
.I SelectInPlace
option.  If you want the pointer on the title of the menu, use
.I SelectWarp
too.  Note that these options apply only if the
.IB "PopupAsRootMenu " MenuStyle
option is used.

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
.RI ( fvwm
menu style) or never warped to the title at all
.RI ( Mwm " or " Win
menu styles).  You can force (forbid) warping whenever the
sub menu is opened with the
.IR WarpTitle " (" NoWarp ") option."

Note that the
.I special-options
do work with a normal menu that has no other position arguments.
.in -.5i

.TP
.BI "MenuStyle " "stylename options"
Sets a new menu style or changes a previously defined style.  The
.I stylename
is the style name; if it contains spaces or tabs it has to be
quoted.  The name "*" is reserved for the default menu style. The
default menu style is used for every menu-like object (e.g. the
window created by the
.B WindowList
command) that had not be assigned a style using the
.BR ChangeMenuStyle .
See also
.BR DestroyMenuStyle .
When using monochrome color options are ignored.

.I options
is a comma separated list containing some of the keywords
Fvwm / Mwm / Win,
BorderWidth,
Foreground,
Background,
Greyed,
HilightBack / HilightBackOff,
ActiveFore / ActiveForeOff,
MenuColorset,
ActiveColorset,
GreyedColorset,
Hilight3DThick / Hilight3DThin / Hilight3DOff,
Hilight3DThickness,
Animation / AnimationOff,
Font,
MenuFace,
PopupDelay,
PopupOffset,
TitleWarp / TitleWarpOff,
TitleUnderlines0 / TitleUnderlines1 / TitleUnderlines2,
SeparatorsLong / SeparatorsShort,
TrianglesSolid / TrianglesRelief,
PopupImmediately / PopupDelayed,
PopdownImmediately / PopdownDelayed,
PopupActiveArea,
DoubleClickTime,
SidePic,
SideColor,
PopupAsRootMenu / PopupAsSubmenu / PopupIgnore / PopupClose,
RemoveSubmenus / HoldSubmenus,
SubmenusRight / SubmenusLeft,
SelectOnRelease,
ItemFormat,
VerticalItemSpacing,
VerticalTitleSpacing,
AutomaticHotkeys / AutomaticHotkeysOff.

In the above list some options are listed as option pairs or
triples with a '/' in between.  These options exclude each other.

.IR Fvwm ", " Mwm ", " Win
reset all options to the style with the same name in former
versions of fvwm.  The default for new menu styles is
.I Fvwm
style.  These options override all others except
.IR Foreground ", " Background ", " Greyed ", " HilightBack ", "
.IR ActiveFore " and " PopupDelay ,
so they should be used only as the first option specified for a
menu style or to reset the style to defined behavior.  The same
effect can be created by setting all the other options one by one.

.IR Mwm " and " Win
style menus popup sub menus automatically.
.I Win
menus indicate the current menu item by changing the background to
dark.
.I Fvwm
sub menus overlap the parent menu,
.IR Mwm " and " Win
style menus never overlap the parent menu.

.I Fvwm
style is equivalent to HilightBackOff, Hilight3DThin,
ActiveForeOff, ActiveBackOff,
AnimationOff, Font, MenuFace, PopupOffset 0 67,
TitleWarp, TitleUnderlines1, SeparatorsShort, TrianglesRelief,
PopupDelayed, PopdownDelayed, PopupDelay 150, PopdownDelay 150,
PopupAsSubmenu, HoldSubmenus,
SubmenusRight, BorderWidth 2, AutomaticHotkeysOff,
PopupActiveArea 75.

.I Mwm
style is equivalent to HilightBackOff, Hilight3DThick,
ActiveForeOff, ActiveBackOff,
AnimationOff, Font, MenuFace, PopupOffset -3 100,
TitleWarpOff, TitleUnderlines2, SeparatorsLong, TrianglesRelief,
PopupImmediately, PopdownDelayed, PopdownDelay 150,
PopupAsSubmenu, HoldSubmenus, SubmenusRight, BorderWidth 2,
AutomaticHotkeysOff, PopupActiveArea 75.

.I Win
style is equivalent to HilightBack, Hilight3DOff, ActiveFore,
ActiveBack,
AnimationOff, Font, MenuFace, PopupOffset -5 100, TitleWarpOff,
TitleUnderlines1, SeparatorsShort, TrianglesSolid,
PopupImmediately, PopdownDelayed, PopdownDelay 150,
PopupAsSubmenu, RemoveSubmenus, SubmenusRight, BorderWidth 2,
AutomaticHotkeysOff, PopupActiveArea 75.

.I BorderWidth
takes the thickness of the border around the menus in pixels. It
may be zero to 50 pixels.  The default is 2.  Using an illegal
value reverts the border width to the default.

.IR Foreground " and " Background
may have a color name as an argument.  This color is used for menu
text or the menu's background.  You can omit the color name to
reset these colors to the built-in default.

.I Greyed
may have a color name as an argument.  This color is the one used
to draw a menu-selection which is prohibited (or not recommended)
by the Mwm hints which an application has specified. If the color
is omitted the color of greyed menu entries is based on the
background color of the menu.

.IR HilightBack " and " HilightBackOff
switch hilighting the background of the selected menu item on and
off.  A specific background color may be used by providing the
color name as an argument to
.IR HilightBack .
If you use this option without an argument the color is based on
the menu's background color.  The
.I ActiveColorset
option overrides the specified color.

.I ActiveFore " and " ActiveForeOff
switch hilighting the foreground of the selected menu item on and
off.  A specific foreground color may be used by providing the
color name as an argument to
.IR ActiveFore .
Omitting the color turns hilighting on when an
.I ActiveColorset
is used.
.I ActiveForeOff
turns off hilighting the foreground completely.  The
.I ActiveColorset
option overrides the specified color.

.I MenuColorset
controls if a colorset is used instead of the
.IR Foreground ", " Background " and " MenuFace
menu styles.  If the
.I MenuColorset
keyword is followed by a number equal to zero or greater, this
number is taken as the number of the colorset to use.  If the
number is omitted, the colorset is switched off and the regular
menu styles are used again.  The foreground and background colors
of the menu items are replaced by the colors from the colorset. If
the colorset has a pixmap defined, this pixmap is used as the
background of the menu.  Note that the
.I MenuFace
menu style has been optimized for memory consumption and may use
less memory than the background from a colorset.  The shape mask
from the colorset is used to shape the menu.  Please refer to the
.B COLORSETS
section for details about colorsets.

.I ActiveColorset
works exactly like
.IR MenuColorset ,
but the foreground from the colorset replaces the color given with
the
.I ActiveFore
menu style and the colorset's background color replaces the color
given with the
.I HilightBack
command (to turn on background hilighting you have to use the
.I HilightBack
menu style too).  If specified, the hilight and shadow colors
from the colorset are used too.  The pixmap and shape mask from
the colorset are not used.  Hilighting the background or
foreground can be turned off individually with the
.IR ActiveForeOff " or " HilightBackOff
menu styles.

.I GreyedColorset
works exactly like
.IR MenuColorset ,
but the foreground from the colorset replaces the color given with
the
.I Greyed
menu style.  No other parts of the colorset are used.

.IR Hilight3DThick ", " Hilight3DThin " and " Hilight3DOff
determine if the selected menu item is hilighted with a 3D
relief. Thick reliefs are two pixels wide, thin reliefs are one
pixel wide.

.I Hilight3DThickness
takes one numeric argument that may be between -50 and +50
pixels. With negative values the menu item gets a pressed in look.
The above three commands are equivalent to a thickness of 2, 1 and
0.

.IR Animation " and " AnimationOff
turn menu animation on or off.  When animation is on, sub menus
that don't fit on the screen cause the parent menu to be shifted
to the left so the sub menu can be seen.

.I Font
takes a font name as an argument.  If a font by this name exists
it is used for the text of all menu items.  If it does not exist
or if the name is left blank the built-in default is used.

.I MenuFace
enforces a fancy background upon the menus.  You can use the same
options for
.I MenuFace
as for the
.BR ButtonStyle .
See description of
.B ButtonStyle
command and the
.B COLOR GRADIENTS
sections for more information.  If you use
.I MenuFace
without arguments the style is reverted back to normal.

Some examples of MenuFaces are:
.EX
MenuFace DGradient 128 2 lightgrey 50 blue 50 \\
  white
MenuFace TiledPixmap texture10.xpm
MenuFace HGradient 128 2 Red 40 Maroon 60 \\
  White
MenuFace Solid Maroon
.EE
Note: The gradient styles H, V, B and D are optimized for high
speed and low memory consumption in menus.  This is not the case
for all the other gradient styles.  They may be slow and consume
huge amounts of memory, so if you encounter performance problems
with them you may be better off by not using them.  To improve
performance you can try one or all of the following:

Turn hilighting of the active menu item other than foreground
color off:
.EX
MenuStyle <style> Hilight3DOff, HilightBackOff
MenuStyle <style> ActiveFore <preferred color>
.EE
Make sure sub menus do not overlap the parent menu. This can
prevent menus being redrawn every time a sub menu pops up or down.
.EX
MenuStyle <style> PopupOffset 1 100
.EE
Run your X server with backing storage.  If your X Server is
started with the -bs option, turn it off.  If not try the -wm
and +bs options:
.EX
startx -- -wm +bs
.EE
You may have to adapt this example to your system (e.g. if you use
xinit to start X).

.I PopupDelay
requires one numeric argument.  This value is the delay in
milliseconds before a sub menu is popped up when the pointer moves
over a menu item that has a sub menu.  If the value is zero no
automatic pop up is done.  If the argument is omitted the built-in
default is used. Note that the popup delay has no effect if the
.I PopupImmediately
option is used since sub menus pop up immediately then.

.I PopupImmediately
makes menu items with sub menus pop up it up as soon as the
pointer enters the item.  The
.I PopupDelay option
is ignored then.  If
.I PopupDelayed
is used fvwm looks at the
.I PopupDelay
option if or when this automatic popup happens.

.I PopdownDelay
works exactly like
.I PopupDelay
but determines the timeout of the
.I PopupDelayed
style.

.I PopdownImmediately
makes sub menus vanish as soon as the pointer leaves the sub menu
and the correspondent item in the parent menu.  With the opposite
option
.I PopdownDelayed
the sub menu only pops down after the time specified with the
.I PopdownDelay
option.  This comes handy when the pointer often strays off the
menu item when trying to move into the sub menu.  Whenever there
is a conflict between the
.IR PopupImmediately ", " PopupDelayed ", " PopupDelay
styles and the
.IR PopdownImmediately ", " PopdownDelayed ", " PopdownDelay
styles, the
.I Popup...
styles win when using mouse navigation and the
.I Popdown...
styles win when navigating with the keyboard.

.I PopupOffset
requires two integer arguments.  Both values affect where sub
menus are placed relative to the parent menu.  If both values are
zero, the left edge of the sub menu overlaps the left edge of the
parent menu.  If the first value is non-zero the sub menu is
shifted that many pixels to the right (or left if negative).  If
the second value is non-zero the menu is moved by that many
percent of the parent menu's width to the right or left.

.I PopupActiveArea
requires an integer value between 51 and 100.  Normally, when the
pointer is over a menu item with a sub menu and the pointer enters
the area that starts at 75% of the menu width, the sub menu is
shown immediately.  This percentage can be changed with
.IR PopupActiveArea .
Setting this value to 100 disables this kind of automatic popups
altogether.  The default value is restored if no or an illegal
value is given.

.IR TitleWarp " and " TitleWarpOff
affect if the pointer warps to the menu title when a sub menu is
opened or not. Note that regardless of this setting the pointer is
not warped if the menu does not pop up under the pointer.

.IR TitleUnderlines0 ", " TitleUnderlines1 " and " TitleUnderlines2
specify how many lines are drawn below a menu title.

.IR SeparatorsLong " and " SeparatorsShort
set the length of menu separators.  Long separators run from the
left edge all the way to the right edge.  Short separators leave a
few pixels to the edges of the menu.

.IR TrianglesSolid " and " TrianglesRelief
affect how the small triangles for sub menus is drawn.  Solid
triangles are filled with a color while relief triangles are
hollow.

.I DoubleClickTime
requires one numeric argument.  This value is the time in
milliseconds between two mouse clicks in a menu to be considered
as a double click.  The default is 450 milliseconds.  If the
argument is omitted the double click time is reset to this
default.

.I SidePic
takes the name of an image file as an argument. The
picture is drawn along the left side of the menu.  The
.I SidePic
option can be overridden by a menu specific side pixmap (see
.BR AddToMenu ).
If the file name is omitted an existing side pixmap is remove from
the menu style.

.I SideColor
takes the name of an X11 color as an argument. This color is used
to color the column containing the side picture (see
above). The SideColor option can be overridden by a menu specific
side color (see
.BR AddToMenu ).
If the color name is omitted the side color option is switched off.

.IR PopupAsRootMenu ", " PopupAsSubmenu ", " PopupIgnore " and " PopupClose
change the behavior when you click on a menu item that opens a
sub menu. With
.I PopupAsRootMenu
the original menu is closed before the sub menu appears, with
.I PopupAsSubmenu
it is not, so you can navigate back into the
parent menu.  Furthermore, with
.I PopupAsSubmenu
the sub menu is held open (posted) regardless of where you move
the mouse.  Depending on your menu style this may simplify
navigating through the menu.  Any keystroke while a menu is posted
reverts the menu back to the normal behavior.  With
.I PopupClose
the menu is cloed when a sub menu item is activated, and the menu
stays open if
.I PopupIgnore
is used (even if the menu was invoked with the
.B Popup
command).
.I PopupAsSubmenu
is the default.

.I RemoveSubmenus
instructs fvwm to remove sub menus when you move back into the
parent menu.  With
.I HoldSubmenus
the sub menu remains visible.  You probably want to use
.I HoldSubmenus
if you are using the
.I PopupDelayed
style.
.I RemoveSubmenus
affects menu navigation with the keyboard.

.I SelectOnRelease
takes an optional key name as an argument.  If the given key is
release in a menu using this style, the current menu item is
selected.  This is intended for
.SM Alt-Tab
.B WindowList
navigation.
The key name is a standard X11 key name as defined in
.IR /usr/include/X11/keysymdef.h ,
(without the 
.I XK_
prefix), or the keysym database
.IR /usr/X11R6/lib/X11/XKeysymDB .
To disable this behavior, omit
the key name.

Note: Some X servers do not support KeyRelease events.
.I SelectOnRelease
does not work on such a machine.

.I ItemFormat
takes a special string as its argument that determines the layout
of the menu items.  Think of the format string as if it were a
menu item.  All you have to do is tell fvwm where to place the
different parts of the menu item (i.e. the labels, the triangle
denoting a sub menu, the mini icons and the side pic) in the blank
area.  The string consists of spaces,
.SM Tab
characters and formatting directives beginning with '%'. Any
illegal characters and formatting directives are silently ignored:

.in +.5i
.BR %l ", " %c " and " %r
.in +.3i
Insert the next item label.  Up to three labels can be used. The
item column is left-aligned
.RB ( %l ),
centered
.RB ( %c )
or right-aligned
.RB ( %r ).
.in -.3i
.B %i
.in +.3i
Inserts the mini icon.
.in -.3i
.BR %> " and " %<
.in +.3i
Insert the sub menu triangle pointing either to the right
.RB ( %> )
or to the left
.RB ( %< )
.in -.3i
.B %|
.in +.3i
The first
.B %|
denotes the beginning of the area that is highlighted either with
a background color or a relief (or both).  The second
.B %|
marks the end of this area.
.B %|
can be used up to twice in the string.  If you don't add one or
both of them, fvwm sets the margins to the margins of the whole
item (not counting the side picture).
.in -.3i
.B %s
.in +.3i
Places the side picture either at the beginning or the end of the
menu. This directive may be used only once and only as the first
or last in the format string. If the
.B %s
is not at the beginning of the string, all characters to the right
of it are silently ignored.
.in -.3i
.BR Space ", " Tab ", " %Space " and " %Tab
.in +.3i
Add gap of one space, or a tab, using the width of the menu font.
When using a tab, the size of the gap can be one to 8 spaces
since the tab position is a multiple of 8 from the edge of the menu.
The whole string must be quoted if spaces or tabs are used.
.in -.3i
.B %p
.in +.3i
Like
.SM Space
and
.SM Tab
.B %p
inserts an empty area into the item, but with better control of
its size (see below).
.in -.3i
.in -.5i

You can define an additional space before and after each of the
objects like this:
.EX
.BI % left . right p
.EE
This means: if the object is defined in the menu (e.g. if it is
.B %s
and you use a side picture, or it is
.B %l
for the third column and there are items defined that actually
have a third column), then add
.I left
pixels before the object and
.I right
pixels after it.  You may leave out the
.I left
or the
.I .right
parts if you don't need them.  All values up to the screen width
are allowed.  Even negative values can be used with care.  The
.B p
may be replaced with any other formatting directives described
above.

Note: Only items defined in the format string are visible in the
menus. So if you do not put a
.B %s
in there you do not see a side picture, even if one is specified.

Note: The
.I SubmenusLeft
style changes the default
.I ItemFormat
string, but if it was set manually it is not modified.

Note: If any unformatted title of the menu is wider than the
widest menu item, the spaces between the different parts of the
menu items are enlarged to match the width of the title.  Leading
left aligned objects in the format string
.RB ( %l ", " %i ", "%< ", first " %| )
stick to the left edge of the menu and trailing right aligned
objects
.RB ( %r ", " %i ", "%> ", second " %| )
stick to the right edge.  The gaps between the remaining items are
enlarged equally.

Examples:
.EX
MenuStyle * ItemFormat \\
  "%.4s%.1|%.5i%.5l%.5l%.5r%.5i%2.3>%1|"
.EE
Is the default string used by fvwm: (side picture + 4 pixels gap)
(beginning of the hilighted area + 1 pixel gap) (mini icon + 5p)
(first column left aligned + 5p) (second column left aligned + 5p)
(third column right aligned + 5p) (second mini icon + 5p) (2p +
sub menu triangle + 3p) (1p + end of hilighted area).
.EX
MenuStyle * ItemFormat \\
  "%.1|%3.2<%5i%5l%5l%5r%5i%1|%4s"
.EE
Is used by fvwm with the
.I SubmenusLeft
option below.

.IR VerticalItemSpacing " and " VerticalTitleSpacing
control the vertical spacing of menu items and titles like
.I ItemFormat
controls the horizontal spacing.  Both take two numeric arguments
that may range from -100 to +100.  The first is the gap in pixels
above a normal menu item (or a menu title), the second is the gap
in pixels below it.  Negative numbers do not make much sense and
may screw up the menu completely.  If no arguments are given or
the given arguments are invalid, the built-in defaults are used:
one pixel above the item or title and two below.

.I SubmenusLeft
mirrors the menu layout and behavior.  Sub menus pop up to the
left, the sub menu triangle is drawn left and the mini icon and
side picture are drawn at the right side of the menu.  The default
is
.IR SubmenusRight .
The position hints of a menu are also affected by this setting,
i.e. position hints using
.IR item " or " menu
as context rectangle and position hints using
.I m
offsets.

.IR AutomaticHotkeys " and " AutomaticHotkeysOff
control the menu's ability to automatically provide hot-keys on
the first character of each menu item's label.  This behavior is
always overridden if an explicit hot-key is assigned in the
.B AddToMenu
command.

Examples:
.EX
MenuStyle * Mwm
MenuStyle * Foreground Black, Background gray40
MenuStyle * Greyed gray70, ActiveFore White
MenuStyle * HilightBackOff, Hilight3DOff
MenuStyle * Font lucidasanstypewriter-14
MenuStyle * MenuFace DGradient 64 darkgray \\
  MidnightBlue

MenuStyle red Mwm
MenuStyle red Foreground Yellow
MenuStyle red Background Maroon
MenuStyle red Greyed Red, ActiveFore Red
MenuStyle red HilightBackOff, Hilight3DOff
MenuStyle red Font lucidasanstypewriter-12
MenuStyle red MenuFace DGradient 64 Red Black
.EE
Note that all style options could be placed on a single line for
each style name.

.TP
.BI "MenuStyle " "forecolor backcolor shadecolor font style" " [" anim "]"
This is the old syntax of the
.B MenuStyle
command.  It is obsolete and may be removed in the future.  Please
use the new syntax as described above.

Sets the menu style.  When using monochrome the colors are
ignored.  The
.I shadecolor
is the one used to draw a menu-selection which is prohibited (or
not recommended) by the Mwm hints which an application has
specified.  The style option is either
.IR Fvwm ", " Mwm " or " Win ,
which changes the appearance and operation of the menus.

.IR Mwm " and " Win
style menus popup sub menus automatically.
.I win
menus indicate the current menu item by changing the background to
black.
.I fvwm
sub menus overlap the parent menu,
.IR Mwm " and " win
style menus never overlap the parent menu.

When the
.I anim
option is given, sub menus that don't fit on the screen cause the
parent menu to be shifted to the left so the sub menu can be
seen. See also
.B SetAnimation
command.

.TP
.BI "Popup " PopupName " [" position "] [" default-action "]"
This command has two purposes: to bind a menu to a key or mouse
button, and to bind a sub menu into a menu.  The formats for the
two purposes differ slightly.  The
.I position
arguments are the same as for
.BR Menu .
The command
.I default-action
is invoked if the user clicks a button to invoke the menu and
releases it immediately again (or hits the key rapidly twice if
the menu is bound to a key).  If the default 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 default action is not given, double clicking
invokes the first item of the menu (but only if the pointer really
was over the item).

To bind a previously defined pop-up menu to a key or mouse button:
.sp
.in +.25i
The following example binds mouse buttons 2 and 3 to a pop-up
called "Window Ops".  The menu pops up if the buttons 2 or 3 are
pressed in the window frame, side-bar, or title-bar, with no
modifiers (none of shift, control, or meta).
.EX
Mouse 2 FST N Popup "Window Ops"
Mouse 3 FST N Popup "Window Ops"
.EE
Pop-ups can be bound to keys through the use of the
.B Key
command.  Pop-ups can be operated without using the mouse by
binding to keys and operating via the up arrow, down arrow, and
enter keys.
.in -.25i
.sp
To bind a previously defined pop-up menu to another menu, for use
as a sub menu:
.sp
.in +.25i
The following example defines a sub menu "Quit-Verify" and binds
it into a main menu, called "RootMenu":
.EX
AddToMenu Quit-Verify
 + "Really Quit Fvwm?" Title
 + "Yes, Really Quit"  Quit
 + "Restart Fvwm"      Restart
 + "Restart Fvwm 1.xx" Restart fvwm1 -s
 + ""                  Nop
 + "No, Don't Quit"    Nop

AddToMenu RootMenu "Root Menu" Title
 + "Open XTerm Window" Popup NewWindowMenu
 + "Login as Root"     Exec exec xterm \\
                         -fg green -T Root \\
                         -n Root -e su -
 + "Login as Anyone"   Popup AnyoneMenu
 + "Remote Hosts"      Popup HostMenu
 + ""                  Nop
 + "X utilities"       Popup Xutils
 + ""                  Nop
 + "Fvwm Modules"      Popup Module-Popup
 + "Fvwm Window Ops"   Popup Window-Ops
 + ""                  Nop
 + "Previous Focus"    Prev (AcceptsFocus) Focus
 + "Next Focus"        Next (AcceptsFocus) Focus
 + ""                  Nop
 + "Refresh screen"    Refresh
 + ""                  Nop
 + "Reset X defaults"  Exec xrdb -load \\
                       $HOME/.Xdefaults
 + ""                  Nop
 + ""                  Nop
 + Quit                Popup Quit-Verify
.EE
.in -.25i
.sp
.B Popup
differs from
.B Menu
in that pop-ups do not stay up if the user simply clicks.  These
are popup-menus, which are a little hard on the wrist.
.B Menu
menus stay up on a click action.  See the
.B Menu
command for an explanation of the interactive behavior of menus. A
menu can be open up to ten times at once, so a menu may even use
itself or any of its predecessors as a sub menu.

.TP
.BI "TearMenuOff"
When assigned to a menu item, it inserts a tear off bar into the
menu (a horizontal broken line).  Activating that item tears off
the menu.  If the menu item has a label, it is shown instead of
the broken line.  If used outside menus, this command does
nothing.  Examples:
.EX
AddToMenu WindowMenu
+ I "" TearMenuOff

AddToMenu RootMenu
+ I "click here to tear me off" TearMenuOff
.EE

.TP
.BI "Title"
Does nothing.  This is used to insert a title line in a popup or
menu.

.SS MISCELLANEOUS COMMANDS

.TP
.BI "BugOpts [" option " [" bool "]], " ...
This command controls several workarounds for bugs in third party
programs.  The individual options are separated by commas.  The
optional argument
.I bool
is a boolean argument and controls if the bug workaround is
enabled or not.  It can either be "True" or "False" to turn the
option on or off, or "toggle" to switch is back and forth.  If
.I bool
is omitted, the default setting is restored.

.I FlickeringMoveWorkaround
disables ConfigureNotify events that are usually sent to an
application while it is moved.  If some windows flicker annoyingly
while being moved, this option may help you.  Note that if this
problem occurs it is not an fvwm bug, it is a problem of the
application.

.I MixedVisualWorkaround
makes fvwm install the root colormap before it does some
operations using the root window visuals.  This is only useful
when the
.B -visual
option is used to start fvwm and then only with some
configurations of some servers (e.g. Exceed 6.0 with an 8 bit
PseudoColor root and fvwm using a 24 bit TrueColor visual).

The
.I ModalityIsEvil
option controls whether Motif applications have the ability to
have modal dialogs (dialogs that force you to close them first
before you can do anything else).  The default is to not allow
applications to have modal dialogs.  Use this option with
care. Once this option is turned on, you have to restart fvwm to
turn it off.

.I RaiseOverNativeWindows
makes fvwm try to raise the windows it manages over native windows
of the X servers host system.  This is needed for some X servers
running under Windows or Windows NT.  Fvwm tries to detect if it
is running under such an X server and initializes the flag
accordingly.

.I RaiseOverUnmanaged
makes fvwm try to raise the windows it manages over
override_redirect windows.  This is used to cope with ill-mannered
applications that use long-lived windows of this sort, contrary to
.SM ICCCM
conventions.  It is usefull with the
.I Unmanaged
style option too.

.I FlickeringQtDialogsWorkaround
suppresses flickering of the focused window in some modules when
using KDE or Qt applications with application modal dialog
windows.  By default this option is turned on.  This option may be
visually disturbing for other applications using windows not
managed by fvwm.  Since these applications are rare it is most
likely safe to leave this option at its default.

.I EWMHIconicStateWorkaround
is needed by EWMH compliant pagers or taskbars which represent
windows which are on a different desktops as iconified. These
pagers and taskbars use a version of the EWMH specification before
version 1.2 (the current KDE2 & 3 versions).  These pagers and
taskbars use the IconicState WM_STATE state to determine if an
application is iconified.  This state, according to the
.SM ICCCM ,
does not imply that a window is iconified (in the usual sense).
Turning on this option forces fvwm to establish an equivalence
between the IconicState WM_STATE state and the iconified window.
This violates
.SM ICCCM
compliance but should not cause big problems.
By default this option is off.

With the
.I DisplayNewWindowNames
enabled, fvwm prints the name, icon name (if available), resource
and class of new windows to the console.  This can help in finding
the correct strings to use in the
.B Style
command.

When the
.I ExplainWindowPlacement
option is enabled, fvwm prints a message to the console whenever a
new window is placed or one of the commands
.BR PlaceAgain ", " Recapture " or " RecaptureWindow
is used.  The message explains on which desk, page, Xinerama
screen and position it was placed and why.  This option can be
used to figure out why a specific window does not appear where you
think it should.

The
.I DebugCRMotionMethod
option enables some debugging code in the ConfigureRequest
handling routines of fvwm.  It is not helpful for the user, but if
you report a bug to the fvwm team we may ask you to enable this
option.

.TP
.BI "BusyCursor [" "Option bool" "], " ...
This command controls the cursor during the execution of certain
commands.
.I Option
can be
.IR DynamicMenu ", " ModuleSynchronous ", " Read ", " Wait ", " * .
An option must be followed by a boolean argument
.IR bool .
You can use commas to separate individual options.  If you set an
option to "True", then when the corresponding command is run, fvwm
displays the cursor of the
.I WAIT
context of the
.B CursorStyle
command.  "False" forces to not display the cursor.  The default is:
.EX
BusyCursor DynamicMenu False, \\
  ModuleSynchronous False, Read False, \\
  Recapture True, Wait False
.EE
The option
.I *
refers to all available options.

The
.I Read
option also controls the
.B PipeRead
command.

The
.I DynamicMenu
option affects the
.I DynamicPopupAction
and
.I MissingSubmenuFunction
options of the
.B AddToMenu
command.  If this option is set to "False", then the busy cursor
is not displayed during a dynamic menu command even if this
command is a
.BR Read " or " PipeRead
command and the
.I Read
option is set to "True".

The
.I Wait
option affects only the root cursor.  During a wait pause the root
cursor is replaced by the busy cursor and fvwm is still fully
functional (you can escape from the pause, see the
.B EscapeFunc
command).  If you want to use this option and if you do not use
the default root cursor, you must set your root cursor with the
.B CursorStyle
command.

.TP
.BI "ClickTime [" delay "]"
Specifies the maximum delay in milliseconds between a button press
and a button release for the
.B Function
command to consider the action a mouse click.  The default delay
is 150 milliseconds.  Omitting the delay value resets the
.B ClickTime
to the default.

.TP
.BI "ColorLimit " limit
This command is obsolete. See the
.I --color-limit
option to fvwm.
.\"Specifies a
.\".I limit
.\"on the colors used in pixmaps used by fvwm. Zero (the default)
.\"sets no limit.  Fvwm uses pixmaps for icons, mini-icons, and
.\"pixmap borders, menu backgrounds and titles. This command limits
.\"pixmap colors to a set of colors that starts out with common
.\"colors.  The current list contains about 60 colors and starts with
.\"white, black, grey, green, blue, red, cyan, yellow, and magenta.
.\"The command
.\".EX
.\"ColorLimit 9
.\".EE
.\"would limit pixmaps to these 9 colors.
.\"
.\"It makes the most sense to put this command at the front of the
.\".I config
.\"file.  This command should occur before any menu definitions that
.\"contain mini-icons.
.\"
.\"Solid frame and title colors (including shadows and gradients) are
.\"not controlled by this command.
.\"
.\"This command only makes sense on screens that display a limited
.\"number of colors at once.  If your  display can display more than
.\"2 million colors at once, this command is ignored.  Screens that
.\"only display 256 colors at once are known as 8 bit displays. The 2
.\"million color cutoff point corresponds to 21 bit color, the most
.\"common screen that exceeds this limit would be 24 bit.
.\"
.\"On 8 bit displays, the default color limit is set to the size of
.\"the built-in table (about 60).  We recommend that you start with
.\"the default value, and not include this command in your
.\".IR config " file."

.TP
.BI "ColormapFocus " FollowsMouse | FollowsFocus
By default, fvwm installs the colormap of the window that the
cursor is in.  If you use
.EX
ColormapFocus FollowsFocus
.EE
then the installed colormap is the one for the window that
currently has the keyboard focus.

.TP
.B "CursorStyle \fIcontext\fP [\fInumber\fP\
| \fIname\fP \
| \fIxpm\fP \
| \fINone\fP \
| \fITiny\fP \
[\fIfore back\fP\
]]"
Defines a new cursor for the specified context.  Note that this
command can not control the shapes an applications uses, for
example, to indicate that it is busy.  The various contexts are:

.in +.5i
.BR "POSITION " (top_left_corner)
.in +.3i
used when initially placing windows
.in -.3i

.BR "TITLE " (top_left_arrow)
.in +.3i
used in a window title-bar
.in -.3i

.BR "DEFAULT " (top_left_arrow)
.in +.3i
used in windows that don't set their cursor
.in -.3i

.BR "SYS " (hand2)
.in +.3i
used in one of the title-bar buttons
.in -.3i

.BR "MOVE " (fleur)
.in +.3i
used when moving or resizing windows
.in -.3i

.BR "RESIZE " (sizing)
.in +.3i
used when moving or resizing windows
.in -.3i

.BR "WAIT " (watch)
.in +.3i
used during certain fvwm commands (see
.B BusyCursor
for details).
.in -.3i

.BR "MENU " (top_left_arrow)
.in +.3i
used in menus
.in -.3i

.BR "SELECT " (crosshair)
.in +.3i
used when the user is required to select a window
.in -.3i

.BR "DESTROY " (pirate)
.in +.3i
used for DESTROY, CLOSE, and DELETE commands
.in -.3i

.BR "TOP " (top_side)
.in +.3i
used in the top side-bar of a window
.in -.3i

.BR "RIGHT " (right_side)
.in +.3i
used in the right side-bar of a window
.in -.3i

.BR "BOTTOM " (bottom_side)
.in +.3i
used in the bottom side-bar of a window
.in -.3i

.BR "LEFT " (left_side)
.in +.3i
used in the left side-bar of a window
.in -.3i

.BR "TOP_LEFT " (top_left_corner)
.in +.3i
used in the top left corner of a window
.in -.3i

.BR "TOP_RIGHT " (top_right_corner)
.in +.3i
used in the top right corner of a window
.in -.3i

.BR "BOTTOM_LEFT " (bottom_left_corner)
.in +.3i
used in the bottom left corner of a window
.in -.3i

.BR "BOTTOM_RIGHT " (bottom_right_corner)
.in +.3i
used in the bottom right corner of a window
.in -.3i

.BR "TOP_EDGE " (top_side)
.in +.3i
used at the top edge of the screen.
.in -.3i

.BR "RIGHT_EDGE " (right_side)
.in +.3i
used at the right edge of the screen.
.in -.3i

.BR "BOTTOM_EDGE " (bottom_side)
.in +.3i
used at the bottom edge of the screen.
.in -.3i

.BR "LEFT_EDGE " (left_side)
.in +.3i
used at the left edge of the screen.
.in -.3i

.BR "ROOT " (left_ptr)
.in +.3i
used as the root cursor.
.in -.3i

.BR "STROKE " (plus)
.in +.3i
used during a
.B StrokeFunc
command.
.in -.3i
.in -.5i

The defaults are shown in parentheses above.  If you ever want to
restore the default cursor for a specific context you can omit the
second argument.

The second is either the numeric value of the cursor as defined in
the include file
.I X11/cursorfont.h
or its name (without the XC_ prefix). Alternativelly the xpm file
name may be specified.  This xpm file should contain a pixmap
using 3 colors (None, black, white) and an optional hot-spot.  If
no hot-spot is defined, the hot-spot is placed in the center of
the image.  Furthermore the name can be
.I None
(no cursor) or
.I Tiny
(a single pixel as the cursor).  For example:
.EX
# make the kill cursor be XC_gumby (both forms work):
CursorStyle DESTROY 56
CursorStyle DESTROY gumby

CursorStyle TOP_LEFT topl.xpm
CursorStyle ROOT nice_arrow.xpm yellow black
.EE
The optional
.IR fg " and " bg
arguments specify the foreground and background colors for the
cursor, defaulting to black and white.

Here is an example pixmap file
.IR nice_arrow.xpm :
.EX
/* XPM */
static char *nice_arrow_xpm[] = {
/* width height num_colors chars_per_pixel hot-spot */
"    14    14        3            1          1 1",
/* colors */
"  c None",
". c black",
"# c white",
/* pixels */
"...           ",
".##..         ",
".####..       ",
" .#####..     ",
" .#######..   ",
"  .########.. ",
"  .##########.",
"   .#######.. ",
"   .######.   ",
"    .######.  ",
"    .###.###. ",
"     .#. .###.",
"     .#.  .#. ",
"      .    .  ",
};
.EE
The hot-spot coordinates are relative to zero, in the above
example, the hot-spot is in the second row, and second column.

.TP
.BI "DefaultColors [" "foreground background" "]"
.B DefaultColors
sets the default foreground and background colors used in
miscellaneous windows created by fvwm, for example in the geometry
feedback windows during a move or resize operation. If you don't
want to change one color or the other, use - as its color name. To
revert to the built-in default colors omit both color names. Note
that the default colors are not used in menus, window titles or
icon titles.

.TP
.BI "DefaultColorset [" num "]"
.B DefaultColorset
sets the colorset used by the windows controlled by the
.B DefaultColors
command.  To revert back to the
.B DefaultColors
colors use
.EX
DefaultColorset -1
.EE
or any variant of the
.B DefaultColors
command.

.TP
.BI "DefaultFont [" fontname "]"
.B DefaultFont
sets the default font to font
.IR fontname .
The default font is used by fvwm whenever no other font has been
specified.  To reset the default font to the built-in default,
omit the argument.  The default font is used for menus, window
titles, icon titles as well as the geometry feedback windows
during a move or resize operation.  To override the default font
in a specific context, use the
.BR "Style * Font" ", " "Style * IconFont" ", or " MenuStyle
commands.

.TP
.BI "DefaultIcon " filename
sets the default icon which is used if a window has neither an
client-supplied icon nor an icon supplied via the
.I Icon
option of the
.B Style
command.

.TP
.BI "DefaultLayers " "bottom put top"
changes the layers that are used for the
.IR StaysOnBottom ", " StaysPut ", " StaysOnTop
.B Style
options.  Initially, the layers 2, 4 and 6 are used.

.TP
.BI "Deschedule " "[command_id]"
Removes all commands that were scheduled with the id
.I command_id
with the
.B Schedule
command from the list of commands to be executed unless they were
already executed.  If the
.I command_id
is omitted, the value of the variable $[schedule.last] is used as
the id.

.TP
.BI "Emulate " Fvwm | Mwm | Win
This command is a catch all for how miscellaneous things are done
by fvwm. Right now this command affects where the move/resize
feedback window appears and how window placement is aborted. To
have more Mwm- or Win-like behavior you can call
.BI Emulate
with
.IR Mwm " or " Win
as its argument.  With
.I Mwm
resize and move feedback windows are in the center of the screen,
instead of the upper left corner.
This also affects how manual placement is aborted.
See the ManualPlacement description.

.TP
.BI "EscapeFunc"
By default the key sequence
.SM Ctrl-Alt-Escape
allows for escaping from a
.B Wait
pause and from a locked
.B ModuleSynchronous
command.  The
.B EscapeFunc
command used with the
.B Key
command allows for configuring this key sequence.  An example:
.EX
Key Escape A MC -
Key Escape A  S EscapeFunc
.EE
replaces the
.SM Ctrl-Alt-Escape
key sequence with
.SM Shift-Escape
for aborting a
.B Wait
pause and
.B ModuleSynchronous
command.
.B EscapeFunc
used outside the
.B Key
command does nothing.

.TP
.BI "FakeClick [" "command value" "] ..."
This command is mainly intended for debugging fvwm and no
guarantees are made that it works for you.
.B FakeClick
can simulate mouse button press and release events and pass them
to fvwm or the applications.  The parameters are a list of
commands which consist of pairs of
.I command
tokens and integer
.IR values ,
The
.IR press " and " release
commands are followed by the appropriate mouse button number and
generate a button press or release event on the window below the
pointer.  The
.I wait
commands pauses fvwm for the given number of milliseconds.  The
.I modifiers
command simulates pressing or releasing modifier keys.  The values
1 to 5 are mapped to
.SM Mod1
to
.SM Mod5
while 6, 7 and 8 are mapped to
.SM Shift,
.SM Lock
and
.SM Control.
The modifier is set for any further button events.  To release a
modifier key, use the corresponding negative number.  The
.I depth
command determines to which window the button events are
sent. With a depth of 1, all events go to the root window,
regardless of the pointer's position.  With 2, the event is passed
to the top level window under the pointer which is usually the
frame window. With 3, events go to the client window. Higher
numbers go to successive sub windows.  Zero (0) goes to the
smallest window that contains the pointer.  Note that events
propagate upward.
.EX
 FakeClick depth 2 press 1 wait 250 release 1
.EE
This simulates a click with button 1 in the parent window (depth
2) with a delay of 250 milliseconds between the press and the
release.
Note: all command names can be abbreviated with their first letter.


.TP
.BI "FakeKeypress [" "command value" "] ..."
This command is mainly intended for debugging fvwm and no
guarantees are made that it works for you.
.B FakeKeypress
can simulate key press and release events and pass them
to fvwm or applications.  The parameters are a list of
commands which consist of pairs of command tokens and values.
The
.IR press " and " release
commands are followed by a key name.  
The key name is a standard X11 key name as defined in
.IR /usr/include/X11/keysymdef.h ,
(without the 
.I XK_
prefix), or the keysym database
.IR /usr/X11R6/lib/X11/XKeysymDB .
The
.IR wait ", " modifiers " and " depth
commands are the same as those used by
.BR FakeClick .

Save all GVim sessions with: "Esc:w\\n"
.EX
All (gvim) FakeKeypress press Escape \\
                        press colon \\
                        press w \\
                        press Return
.EE
Save & exit all GVim sessions with: "Esc:wq\\n"
.EX
All (gvim) FakeKeypress press Escape \\
                        press colon \\
                        press w \\
                        press q \\
                        press Return
.EE
Send A to a specific window:
.EX
WindowId 0x3800002 FakeKeypress press A
.EE
Note: all command names can be abbreviated with their first letter.


.TP
.BI "GlobalOpts [" options "]"
As announced in the past, this command has been removed.  Please
replace the global options in your configuration file according to
the following table:
.EX
GlobalOpts WindowShadeShrinks
  -->
Style * WindowShadeShrinks

GlobalOpts WindowShadeScrolls
  -->
Style * WindowShadeScrolls

GlobalOpts SmartPlacementIsReallySmart
  -->
Style * MinOverlapPlacement

GlobalOpts SmartPlacementIsNormal
  -->
Style * TileCascadePlacement

GlobalOpts ClickToFocusDoesntPassClick
  -->
Style * ClickToFocusPassesClickOff

GlobalOpts ClickToFocusPassesClick
  -->
Style * ClickToFocusPassesClick

GlobalOpts ClickToFocusDoesntRaise
  -->
Style * ClickToFocusRaisesOff

GlobalOpts ClickToFocusRaises
  -->
Style * ClickToFocusRaises

GlobalOpts MouseFocusClickDoesntRaise
  -->
Style * MouseFocusClickRaisesOff

GlobalOpts MouseFocusClickRaises
  -->
Style * MouseFocusClickRaises

GlobalOpts NoStipledTitles
  -->
Style * StippledTitleOff

GlobalOpts StipledTitles
  -->
Style * StippledTitle

GlobalOpts CaptureHonorsStartsOnPage
  -->
Style * CaptureHonorsStartsOnPage

GlobalOpts CaptureIgnoresStartsOnPage
  -->
Style * CaptureIgnoresStartsOnPage

GlobalOpts RecaptureHonorsStartsOnPage
  -->
Style * RecaptureHonorsStartsOnPage

GlobalOpts RecaptureIgnoresStartsOnPage
  -->
Style * RecaptureIgnoresStartsOnPage

GlobalOpts ActivePlacementHonorsStartsOnPage
  -->
Style * ManualPlacementHonorsStartsOnPage

GlobalOpts ActivePlacementIgnoresStartsOnPage
  -->
Style * ManualPlacementIgnoresStartsOnPage

GlobalOpts RaiseOverNativeWindows
  -->
BugOpts RaiseOverNativeWindows on

GlobalOpts IgnoreNativeWindows
  -->
BugOpts RaiseOverNativeWindows off

.EE

.TP
.BI "HilightColor " "textcolor backgroundcolor"
This command is obsoleted by the
.B Style
options
.IR HilightFore " and " HilightBack .
Please use
.EX
Style * HilightFore textcolor, \\
        HilightBack backgroundcolor
.EE
instead.

.TP
.BI "HilightColorset [" num "]"
This command is obsoleted by the
.B Style
option
.IR HilightColorset .
Please use
.EX
Style * HilightColorset num
.EE
instead.

.TP
.BI "IconFont [" fontname "]"
This command is obsoleted by the
.B Style
option
.IR IconFont .
Please use
.EX
Style * IconFont fontname
.EE
instead.

.TP
.BI "IconPath " path
This command is obsolete.  Please use
.B ImagePath
instead.

.TP
.BI "ImagePath " path
Specifies a colon separated list of directories in which to search
for images (both monochrome and pixmap).  To find an image given
by a relative pathname, fvwm looks into each directory listed in
turn, and uses the first file found.

If a directory is given in the form "/some/dir;.ext", this means
all images in this directory have the extension ".ext" that should
be forced.  The original image name (that may contain another
extension or no extension at all) is not probed, instead ".ext" is
added or replaces the original extension.  This is useful, for
example, if a user has some image directories with ".xpm" images
and other image directories with the same names, but ".png"
images.

The
.I path
may contain environment variables such as
.IR $HOME " (or " ${HOME} ).
Further, a '+' in the
.I path
is expanded to the previous value of the path, allowing appending
or prepending to the path easily.

For example:
.EX
ImagePath $HOME/icons:+:/usr/include/X11/bitmaps
.EE
Note: if the
.B FvwmM4
module is used to parse your
.I config
files, then m4 may want to mangle the word "include" which
frequently shows up in the
.B ImagePath
command.  To fix this one may add
.EX
undefine(`include')
.EE
prior to the
.B ImagePath
command, or better: use the
.I -m4-prefix
option to force all
.B m4
directives to have a prefix of "m4_" (see the
.B FvwmM4
man page).

.TP
.BI "LocalePath " path
Specifies a colon separated list of "locale path" in which to
search for string translations. A locale path is constituted by a
directory path and a text domain separated by a semicolon
(';'). As an example the default locale path is:
.EX
/install_prefix/share/locale;fvwm
.EE
where install_prefix is the fvwm installation directory. With such
a locale path translations are searched for in
.EX
/install_prefix/share/locale/lang/LC_MESSAGES/fvwm.mo
.EE
where
.I lang
depends on the locale. If no directory is given the default
directory path is assumed. If no text domain is given,
.I fvwm
is assumed. Without argument the default locale path is restored.

As for the
.B ImagePath
command,
.I path
may contain environment variables and a '+' to append or prepend
the locale path easily.

For example, the fvwm-themes package uses
.EX
LocalePath ";fvwm-themes:+"
.EE
to add locale catalogs.

The default fvwm catalog contains a few strings used by the fvwm
executable itself (Desk and Geometry) and strings used in some
default configuration files and
.B FvwmForm
configuration. You can take a look at the po/ subdirectory of the
fvwm source to get the list of the strings with a possible
translation in various languages. At present, very few languages
are supported.

The main use of locale catalogs is via the "$[gt.string]"
parameter:
.EX
DestroyMenu MenuFvwmWindowOps
AddToMenu   MenuFvwmWindowOps "$[gt.Window Ops]" Title
+ "$[gt.&Move]"              Move
+ "$[gt.&Resize]"            Resize
+ "$[gt.R&aise]"             Raise
+ "$[gt.&Lower]"             Lower
+ "$[gt.(De)&Iconify]"       Iconify
+ "$[gt.(Un)&Stick]"         Stick
+ "$[gt.(Un)Ma&ximize]"      Maximize
+ "" Nop
+ "$[gt.&Close]"             Close
+ "$[gt.&Destroy]"            Destroy
.EE
gives a menu in the locale languages if translations are
available.

Note that the
.B FvwmTaskBar
module has its own catalog and that the
.B FvwmScript
module has a set of special instructions for string
translation. It is out of the scope of this discussion to explain
how to build locale catalogs. Please refer to the GNU gettext
documentation.

.TP
.BI "PixmapPath " path
This command is obsolete. Please use
.B ImagePath
instead.

.TP
.BI "PrintInfo " "subject [verbose]"
Print information on
.I subject
on stderr.  An optional integer argument
.I verbose
defines the level of information which is given.
The current valid subjects are:

.IR Colors
which prints information about the colors used by fvwm. This useful
on screens which can only display 256 (or less) colors at once.
If
.I verbose
is one or greater the palette used by fvwm is printed.
If you have a limited color palette, and you run out of colors,
this command might be helpful.

.IR Locale
which prints information on your locale and the fonts that fvwm
used.
.I verbose
can be 1 or 2.

.IR nls
which prints information on the locale catalogs that fvwm used

.IR style
which prints information on fvwm styles.
.I verbose
can be 1.

.TP
.BI "Repeat"
When the
.B Repeat
command is invoked, the last command that was executed by fvwm is
executed again.  This happens regardless of whether it was
triggered by user interaction, a module or by an X event.
Commands that are executed from a function defined with the
.B Function
command, from the
.BR Read " or " PipeRead
commands or by a menu are not repeated.  Instead, the function,
menu  or the
.B Read " or " PipeRead
command is executed again.

.TP
.BI "Schedule " "delay_ms [command_id] command"
The
.I command
is executed after about
.I delay_ms
milliseconds.  This may be useful in some tricky setups.  The
.I command
is executed in the same context window as the
.B Schedule
command.  An optional integer argument
.I command_id
may be given in decimal, hexadecimal or octal format.  This id can
be used with the
.B Deschedule
command to remove the scheduled command before it is executed.  If
no id is given, fvwm uses negative id numbers, starting with -1
and decreasing by one with each use of the
.B Schedule
command.
Note that the
.B Schedule
command and its arguments undergo the usual command line
expansion, and, when
.I command
is finally executed, it is expanded again.  It may therefore be
necessary to quote the parts of the command that must not be
expanded twice.

Note:  A window's id as it is returned with $[w.id] can be used as
the
.IR command_id .
Example:
.EX
Current Schedule 1000 $[w.id] WindowShade
.EE

.TP
.BI "State " state " [" bool "]"
Sets, clears or toggles one of the 32 user defined states which
are associated with each window.  The
.I state
is a number ranging from 0 to 31.  The states have no meaning in
fvwm, but they can be checked in conditional commands like
.B Next
with the
.I State
condition.  The optional argument
.I bool
is a boolean argument.  "True" sets the given state, while "False"
clears it.  Using "toggle" switches to the opposite state.  If the
.I bool
argument is not given, the state is toggled.

.TP
.BI "WindowFont [" fontname "]"
This command is obsoleted by the
.B Style
option
.IR Font .
Please use
.EX
Style * Font fontname
.EE
instead.

.TP
.B "WindowList [(\fIconditions\fP\
)] [\fIposition\fP\
] [\fIoptions\fP\
] [\fIdouble-click-action\fP\
]"
Generates a pop-up menu (and pops it up) in which the title and
geometry of each of the windows currently on the desktop are
shown.

The format of the geometry part is:
. IR desk "(" layer "): " "x-geometry sticky" ,
where
.IR desk " and " layer
are the corresponding numbers and
.I sticky
is empty or a capital S.  The geometry of iconified windows is
shown in parentheses.  Selecting an item from the window list
pop-up menu causes the interpreted function "WindowListFunc" to be
run with the window id of that window passed in as $0. The default
"WindowListFunc" looks like this:
.EX
AddToFunc WindowListFunc
+ I Iconify off
+ I FlipFocus
+ I Raise
+ I WarpToWindow 5p 5p
.EE
You can destroy the built-in "WindowListFunc" and create your own
if these defaults do not suit you.

The window list menu uses the "WindowList" menu style if it is
defined (see
.B MenuStyle
command).  Otherwise the default menu style is used.  To switch
back to the default menu style, issue the command
.EX
DestroyMenuStyle WindowList
.EE
Example:
.EX
MenuStyle WindowList SelectOnRelease Meta_L
.EE
The
.I conditions
can be used to exclude certain windows from the window
list. Please refer to the
.B Current
command for details.  Only windows that match the given conditions
are displayed in the window list.  The
.I options
below work vice versa: windows that would otherwise not be
included in the window list can be selected with them.  The
.I conditions
always override the
.IR options .


The
.I position
arguments are the same as for
.BR Menu .
The command
.I double-click-action
is invoked if the user double-clicks (or hits the key rapidly
twice if the menu is bound to a key) when bringing the window
list.  The
.I double-click-action
must be quoted if it consists of more than one word.

The
.I double-click-action
is useful to define a default window if you have bound the window
list to a key (or button) like this:
.EX
# Here we call an existing function, but
# it may be different.  See the default
# WindowListFunc definition earlier in this
# man page.
AddToFunc SwitchToWindow
+ I WindowListFunc

Key Tab A M WindowList "Prev SwitchToWindow"
.EE
Hitting
.SM Alt-Tab
once it brings up the window list, if you hit it twice the focus
is flipped between the current and the last focused window.  With
the proper
.I SelectOnRelease
menu style (see example above) a window is selected as soon as you
release the
.SM Alt
key.

The
.I options
passed to WindowList are separated by commas and can be
.IR Geometry " / " NoGeometry " / " NoGeometryWithInfo ,
.IR NoDeskNum,
.IR NoNumInDeskTitle ,
.IR NoCurrentDeskTitle ,
.IR "MaxLabelWidth width",
.IR TitleForAllDesks ,
.IR "Function funcname" ,
.IR "Desk desknum" ,
.IR CurrentDesk ,
.IR NoIcons " / " Icons " / " OnlyIcons ,
.IR NoNormal " / " Normal " / " OnlyNormal ,
.IR NoSticky " / " Sticky " / " OnlySticky ,
.IR NoStickyAcrossPages " / " StickyAcrossPages " / " OnlyStickyAcrossPages ,
.IR NoStickyAcrossDesks " / " StickyAcrossDesks " / " OnlyStickyAcrossDesks ,
.IR NoOnTop " / " OnTop " / " OnlyOnTop ,
.IR NoOnBottom " / " OnBottom " / " OnlyOnBottom ,
.IR "Layer m [n]" ,
.IR UseListSkip " / " OnlyListSkip ,
.IR NoDeskSort ,
.IR ReverseOrder ,
.IR CurrentAtEnd ,
.IR IconifiedAtEnd ,
.IR UseIconName ,
.IR Alphabetic " / " NotAlphabetic ,
.IR SortByResource ,
.IR SortByClass ,
.IR NoHotkeys ,
.IR SelectOnRelease .

(Note - normal means not iconic, sticky, or on top)

With the
.I SortByResource
option windows are alphabetically sorted first by resource class,
then by resource name and then by window name (or icon name if
.I UseIconName
is specified).
.I ReverseOrder
also works in the expected manner.

With the
.I SortByClass
option windows are sorted just like with
.IR SortByResource ,
but the resource name is not taken into account, only the resource
class.

The
.I SelectOnRelease
option works exactly like the
.B MenuStyle
option with the same name, but overrides the option given in a
menu style.  By default, this option is set to the left
.SM Alt
key.  To switch it off, use
.I SelectOnRelease
without a key name.

If you pass in a function via
.IR "Function funcname" ,
it is called within a window context of the selected window:
.EX
AddToFunc IFunc I Iconify toggle
WindowList Function IFunc, NoSticky, \\
  CurrentDesk, NoIcons
.EE
If you use the
.IB "Layer m " [ "n" ]
option, only windows in layers between m and n are displayed. n
defaults to m.  With the
.I ReverseOrder
option the order of the windows in the list is reversed.

With the
.I CurrentAtEnd
option the currently focused window (if any) is shown at the
bottom of the list.  This is mostly intended for simulating the
Alt-Tab behavior in another GUI.

.I IconifiedAtEnd
makes iconified windows be moved to the end of the list.  This is
also from another GUI.

The
.I NoGeometry
option causes fvwm to not display the geometries as well as
the separators which indicate the different desktops.
.I NoGeometryWithInfo
removes the geometries, but keep the desktop information
and indicates iconic windows.
.I NoDeskNum
causes fvwm to not display the desktop number in the geometry
or before the window title with the
.I NoGeometryWithInfo
option.
.I NoNumInDeskTitle
is only useful if a desktop name is defined with the
.B DesktopName
command. It causes fvwm to not display the desktop number before
the desktop name.  By default, the WindowList menu have a title
which indicates the current desk or the selected desktop if the .I
Desk condition is used. The
.I NoCurrentDeskTitle
option removes this title.
.I TitleForAllDesks
causes fvwm to add a menu title with the desk name and/or number
before each group of windows on the same desk.
With
.IR NoLayer ,
the layer of the window is not diplayed.  The options
.IR ShowPage ", " ShowPageX " and " ShowPageY
enable displaying the page of the window rounded multiples of the
display size.
With
.IR ShowScreen ,
the window's Xinerama screen number is displayed.

The
.I MaxLabelWidth
option takes the number of characters to print as its argument.
No more than that many characters of the window name are visible.

If you wanted to use the
.B WindowList
as an icon manager, you could invoke the following:
.EX
WindowList OnlyIcons, Sticky, OnTop, Geometry
.EE
(Note - the
.I Only
options essentially wipe out all other ones... but the
.I OnlyListSkip
option which just causes
.B WindowList
to only consider the windows with
.I WindowListSkip
style.)

.TP
.BI "XSync "
When
.B XSync
is called, the X function with the same name is used to send all
pending X requests to the server.  This command is intended for
debugging only.

.TP
.BI "XSynchronize [" bool "]"
The
.B XSynchronize
command controls wether X requests are sent to the X server
immediately or not.  Normally, requests are sent in larger batches
to save unnecessary communication.  To send requests immediately,
use "True" as the argument, to disable this use "False" or to
toggle between both methods use "Toggle" or omit the
.B bool
argument.  Fvwm defaults to synchronized requests when started
with the
.B \-debug
option.  This command is intended for debugging only.

.TP
.BI "+"
Used to continue adding to the last specified decor, function or
menu. See the discussion for
.BR AddToDecor ", " AddToFunc ", and " AddToMenu .


.SS COMMANDS AFFECTING WINDOW MOVEMENT AND PLACEMENT

.TP
.BI "AnimatedMove " "x y" " [" Warp "]"
Move a window in an animated fashion.  Similar to
.B Move
command below. The options are the same, except they are required,
since it doesn't make sense to have a user move the window
interactively and animatedly.  If the optional argument
.I Warp
is specified the pointer is warped with the window.

.TP
.BI "HideGeometryWindow [" Never " | " Move " | " Resize "]"
Hides the position or size window that is usually shown when a
window is moved or resized interactively.  To switch it off only
for move or resize operations the optional parameters
.IR Move " and " Resize
can be used respectively.  To switch both on again use the
.I Never
option.

.TP
.BI "Layer [" "arg1 arg2" "] | [" default "]"
Puts the current window in a new layer.  If
.I arg1
is non zero then the next layer is the current layer number plus
.IR arg1 .
If
.I arg1
is zero then the new layer is
.IR arg2 .

As a special case,
.I default
puts the window in its default layer, i.e. the layer it was
initially in.  The same happens if no or invalid arguments are
specified.

.TP
.BI "Lower"
Allows the user to lower a window.  Note that this lowers a window
only in its layer.  To bring a window to the absolute bottom, use
.EX
AddToFunc lower-to-bottom
 + I Layer 0 0
 + I Lower
.EE

.TP
.B "Move [[\fIw\fP\
 | \fIm\fP\
]\fIx\fP\
[\fIp\fP\
] [\fIw\fP\
 | \fIm\fP\
]\fIy\fP\
[\fIp\fP\
] [\fIWarp\fP\
]] | [\fIpointer\fP\
]"
Allows the user to move a window.  If called from somewhere in a
window or its border, then that window is moved.  If called from
the root window then the user is allowed to select the target
window.  If the optional argument
.I Warp
is specified the pointer is warped with the window.  If the single
argument
.I pointer
is given, the top left corner of the window window is moved to the
pointer position before starting the operation; this is mainly
intended for internal use by modules like
.BR FvwmPager .

The operation can be aborted with Escape or by pressing mouse
button 2. Pressing button 3 sets the
.I PlacedByButton3
condition (see
.B Current
command).

If the optional arguments
.IR x " and " y
are provided, then the window is moved immediately without user
interaction.  Each argument can specify an absolute or relative
position from either the left/top or right/bottom of the screen.
By default, the numeric value given is interpreted as a percentage
of the screen width/height, but a trailing
.RI ' p '
changes the interpretation to mean pixels.  To move the window
relative to its current position, add the
.RI ' w '
(for "window") prefix before the
. IR x " and/or " y
value.  To move the window to a position relative to the current
location of the pointer, add the
.RI ' m '
(for "mouse") prefix.  To leave either coordinate unchanged,
"keep" can be specified in place of
.IR x " or " y .

Simple Examples:
.EX
# Interactive move
Mouse 1 T A Move
# Move window to top left is at (10%,10%)
Mouse 2 T A Move 10 10
# Move top left to (10pixels,10pixels)
Mouse 3 T A Move 10p 10p
.EE
More complex examples (these can be bound as actions to
keystrokes, etc.; only the command is shown, though):
.EX
# Move window so bottom right is at bottom
# right of screen
Move -0 -0

# Move window so top left corner is 10 pixels
# off the top left screen edge
Move +-10 +-10

# Move window 5% to the right, and to the
# middle vertically
Move w+5 50

# Move window up 10 pixels, and so left edge
# is at x=40 pixels
Move 40p w-10p

# Move window to the mouse pointer location
Move m+0 m+0
.EE
See also the
.B AnimatedMove
command above.

.TP
.BI "MoveToDesk [" prev " | " arg1 " [" arg2 "] [" "min max" "]]"
Moves the selected window to another desktop.  The arguments are
the same as for the
.B GotoDesk
command.  Without any arguments, the window is moved to the
current desk.
.B MoveToDesk
is a replacement for the old
.B WindowsDesk
command, which can no longer be used.

.TP
.BI "MoveThreshold [" pixels "]"
When the user presses a mouse button upon an object fvwm waits to
see if the action is a click or a drag.  If the mouse moves by
more than
.I pixels
pixels it is assumed to be a drag.

Previous versions of fvwm hardwired
.I pixels
to 3, which is now the default value.  If
.I pixels
is negative or omitted the default value (which might be increased
when 16000x9000 pixel displays become affordable) is restored.

.TP
.B "MoveToPage [\fIoptions\fP
] [\fIx\fP\
[\fIp\fP|\fIw\fP\
] \fIy\fP\
[\fIp\fP|\fIw\fP\
]] | [\fIprev\
]"
Moves the selected window to another page (x,y).  The upper left
page is (0,0), the upper right is (M,0), where M is one less than
the current number of horizontal pages specified in the
.B DeskTopSize
command.  Similarly the lower left page is (0,N), and the lower
right page is (M,N).  Negative page numbers refer to pages from
the rightmost/lowest page.  If
.IR x " and " y
are not given, the window is moved to the current page (a window
that has the focus but is off-screen can be retrieved with this).
Moving windows to a page relative to the current page can be
achieved by adding a trailing
.RI ' p '
after any or both numerical arguments.  To move the window
relative to its current location, add a trailing
.RI ' w '.
To move a window to the previous page use
.I prev
as the single argument.

Windows are usually not moved beyond desk boundaries.

Possible
.I options
are
.IR wrapx " and " wrapy
to wrap around the x or y coordinate when the window is moved
beyond the border of the desktop. For example, with
.IR wrapx ,
when the window moves past the right edge of the desktop, it
reappears on the left edge.  The options
.IR nodesklimitx " and " nodesklimit
allow moving windows beyond the desk boundaries in x and y
direction (disabling the
.IR wrapx " and " wrapy
options).

Examples:
.EX
# Move window to page (2,3)
MoveToPage 2 3

# Move window to lowest and rightmost page
MoveToPage -1 -1

# Move window to last page visited
MoveToPage prev

# Move window two pages to the right and one
# page up, wrap at desk boundaries
MoveToPage wrapx wrapy +2p -1p
.EE

.TP
.BI "MoveToScreen [" screen "]"
Moves the selected window to another Xinerama screen.  The
.I screen
argument can be 'p' for the primary screen, 'c' for the current
screen (containing the mouse pointer), 'g' for the global screen
or the screen number itself (counting from zero).

.TP
.BI "OpaqueMoveSize [" percentage "]"
Tells fvwm the maximum size window with which opaque window
movement should be used.  The percentage is percent of the total
screen area (may be greater than 100).  With
.EX
OpaqueMoveSize 0
.EE
all windows are moved using the traditional rubber-band
outline. With
.EX
OpaqueMoveSize unlimited
.EE
or if a negative percentage is given
all windows are moved as solid windows.  The default is
.EX
OpaqueMoveSize 5
.EE
which allows small windows to be moved in an opaque manner but
large windows are moved as rubber-bands.  If
.I percentage
is omitted or invalid the default value is set.  To resize windows
in an opaque manner you can use the
.I ResizeOpaque
style.  See
.B Style
command.

.TP
.BI "PlaceAgain [" Anim "] [" "Icon" "]"
Causes the current window's position to be re-computed using the
initial window placement logic.  The window is moved to where it
would have been if it were a new window that had just appeared.
Most useful with
.IR Smart " or " Clever " (" ReallySmart ")"
placement.  With the optional argument
.I Anim
an animated move is used to place the window in its new position.
With the additional option
.IR Icon ,
the icon is placed again instead.

.TP
.BI "Raise"
Allows the user to raise a window. Note that this raises a window
only in its layer. To bring a window to the absolute top, use
.EX
AddToFunc raise-to-top
 + I Layer 0 ontop
 + I Raise
.EE
where ontop is the highest layer used in your setup.

.TP
.BI "RaiseLower"
Alternately raises and lowers a window.  The window is raised if
it is obscured by any window (except for its own transients when
.I RaiseTransient
style is used; see
.B Style
command) otherwise it is lowered.

.TP
.B "Resize [[\fIframe\fP] [direction \fIdir\fP [\fIwarptoborder\fP]] \
[\fIfixeddirection\fP] \
\fIwidth\fP \
[\fIp\fP \
| \fIc\fP\
] \fIheight\fP \
[\fIp\fP \
| \fIc\fP\
]] | [\fIbottomright\fP \
| \fIbr x y\fP\
]"
Allows for resizing a window.  If called from somewhere in a window
or its border, then that window is resized.  If called from the
root window then the user is allowed to select the target window.

The operation can be aborted with Escape or by pressing any mouse
button (except button 1 which confirms it).

If the optional arguments
.IR width " and " height
are provided, then the window is resized so that its dimensions
are
.IR width " by " height .
The units of
.IR width " and " height
are percent-of-screen, unless a letter
.RI ' p '
is appended to one or both coordinates, in which case the location
is specified in pixels.  With a
.RI ' c '
suffix the unit defined by the client application (hence the c) is
used.  So you can say
.EX
Resize 80c 24c
.EE
to make a terminal window just big enough for 80x24
characters. Both,
.IR width " and " height
can be negative.  In this case the new size is the screen size
minus the given value.  If either value is "keep", the
corresponding dimension of the window is left untouched.  The new
size is the size of the client window, thus
.EX
Resize 100 100
.EE
may make the window bigger than the screen.  To base the new size
on the size of the whole fvwm window, add the
.I frame
option after the command.  The options
.IR fixeddirection ", " direction " and " warptoborder
are only used in interactive move operations.  With
.I fixeddirection
the same border is moved even if the pointer moves past the
opposite border.  The
.I direction
option must be followed by a direction name such as "NorthWest",
"South" or "East" (you get the idea).  Resizing is started
immediately, even if the pointer is not on a border.  The
.I warptoborder
option changes the behaviour of the
.I direction
option so that the pointer is automatically warped to the border
in the given direction before starting to resize.  Also, if
resizing is started by clicking on the window border, the pointer
is warped to the outer edge of the border.
.EX
AddToFunc ResizeSE I Resize Direction SE
Mouse 3 A M ResizeSE
.EE

An alternate syntax is used if the keyword
.IR bottomright " or in short " br
follows the command name.  In this case, the arguments
.IR x " and " y
specify the desired position of the bottom right corner of the
window.  They are interpreted exactly like the
.IR x " and " y
arguments of the
.B Move
command.

.TP
.BI "ResizeMaximize [" resize-arguments "]"
Combines the effects of
.BR Resize " and " Maximize
in a single command.  When used on a maximized window, the window
is resized and is still in the maximized state afterwards.  When
used on an unmaximized window, the window is resized and put into
the maximized state afterwards.  This is useful if the user wants
to resize the window temporarily and then return to the original
geometry.  The
.I resize-arguments
are the same as for the
.B Resize
command.

.TP
.BI "ResizeMove " "resize-arguments move-arguments"
This command does the same as the
.BR Resize " and " Move
commands, but in a single call which is less visually
disturbing. The
.I resize-arguments
are exactly the same arguments as for the
.B Resize
command and the
.I move-arguments
are exactly the same arguments as for the
.B Move
command except the
.I pointer
option which is not supported by the
.B ResizeMove
command.

Example:
.EX
# Move the window to the top left corner
ResizeMove w+0 -10p 0 -20p
.EE

.TP
.BI "ResizeMoveMaximize " "resize-arguments move-arguments"
Combines the effects of
.BR ResizeMove " and " Maximize
in a single command.  When used on a maximized window, the window
is resized and moved and is still in the maximized state
afterwards.  When used on an unmaximized window, the window is
resized and put into the maximized state afterwards.  This is
useful if the user wants to resize the window temporarily and then
return to the original geometry.  The
.IR resize-arguments " and " move-arguments
are the same as for the
.B ResizeMove
command.

.TP
.BI "RestackTransients"
This command regroups the transients of a window close to it in
the stacking order as if the window had just been lowered and then
raised.  The position of the window itself is not altered.  Only
windows that use either the
.I RaiseTransient " or " LowerTransient
style are affected at all.  When
.B RestackTransients
is used on a transient window with the
.I StackTransientParent
style set, it is redirected to the parent window.

.TP
.BI "SetAnimation " milliseconds-delay " [" fractions-to-move-list "]"
Sets the time between frames and the list of fractional offsets to
customize the animated moves of the
.B AnimatedMove
command and the animation of menus (if the menu style is set to
animated; see
.B MenuStyle
command).  If the
.I fractions-to-move-list
is omitted, only the time between frames is altered.  The
.I fractions-to-move-list
specifies how far the window should be offset at each successive
frame as a fraction of the difference between the starting
location and the ending location.  e.g.:
.EX
SetAnimation 10 -.01 0 .01 .03 .08 .18 .3 \\
  .45 .6 .75 .85 .90 .94 .97 .99 1.0
.EE
Sets the delay between frames to 10 milliseconds, and sets the
positions of the 16 frames of the animation motion.  Negative
values are allowed, and in particular can be used to make the
motion appear more cartoonish, by briefly moving slightly in the
opposite direction of the main motion.  The above settings are the
default.

.TP
.B "SnapAttraction [\fIproximity\fP \
[\fIbehavior\fP\
] [\fIScreen\fP\
]]"
If during an interactive move the window or icon comes within
.I proximity
pixels of another the window or icon, it is moved to make the
borders adjoin.  The default of 0 means that no snapping happens.
Calling this command without arguments turns off snap attraction
and restores the default behavior.  Please refer also to the
.B SnapGrid
command.

The
.I behavior
argument is optional and may be set to one of the four following
values:  With
.I All
both icons and windows snap to other windows and other icons.
.I SameType
lets snap windows only to other windows and icons only to other
icons. With
.I Windows
windows snap only to other windows.  Icons do not snap. Similarly
with
.I Icons
icons snap to only other icons and windows do not snap.

If the
.I behavior
option is not given, the snapping behavior is not changed.  The
default behavior is
.IR All .

If the
.I Screen
option is present windows and or icons are snapped to the screen
edges too.

.TP
.BI "SnapGrid [" "x-grid-size y-grid-size" "]"
During an interactive move a window or icon is positioned such
that its location (top left corner) is coincident with the nearest
grid point. The default
.IR x-grid-size " and " y-grid-size
setting are both 1, which is effectively no grid all.  An
interactive move with both
.BR SnapGrid " and " SnapAttraction
results in the window being moved to be adjacent to the nearest
window border (if within snap proximity) or grid position.  In
other words, the window moves the shortest distance possible to
satisfy both
.BR SnapGrid " and " SnapAttraction .
Note that the x and y coordinates are not coupled.  For example, a
window may snap to another window on the x axis while snapping to
a grid point on the y axis.  Calling this command without
arguments reinstates the default settings.

.TP
.BI "WindowsDesk " arg1 " [" arg2 "]"
Moves the selected window to another desktop.

This command has been removed and must be replaced by
.BR MoveToDesk ,
the arguments for which are the same as for the
.B GotoDesk
command.
.B Important note:
You cannot simply change the name of the command: the syntax has
changed.  If you used
.EX
WindowsDesk n
.EE
to move a window to desk n, you have to change it to
.EX
MoveToDesk 0 n
.EE

.TP
.BI "XorPixmap [" pixmap "]"
Selects the pixmap with which bits are xor'ed when doing
rubber-band window moving or resizing.  This has a better chance
of making the rubber-band visible if
.B XorValue
does not give good results.  An example pixmap
.I resize.rainbow.xpm
is provided with the icon distribution.  To turn the
.B XorPixmap
off again use the
.B XorValue
command or omit the
.I pixmap
argument.

.TP
.BI "XorValue [" number "]"
Changes the value with which bits are xor'ed when doing
rubber-band window moving or resizing.
Valid values range from zero to the maximum value of an
unsigned long integer on your system.
Setting this value is a trial-and-error process.
The default value 0 tries to find a
value that gives a good contrast to black and white.
The default value is used if the given
.I number
is omitted or invalid.


.SS COMMANDS FOR FOCUS AND MOUSE MOVEMENT

.TP
.BI "CursorMove " horizontal "[" p "] " vertical "[" p "]"
Moves the mouse pointer by
.I horizontal
pages in the X direction and
.I vertical
pages in the Y direction.  Either or both entries may be
negative. Both horizontal and vertical values are expressed in
percent of pages, so
.EX
CursorMove 100 100
.EE
means to move down and right by one full page.
.EX
CursorMove 50 25
.EE
means to move right half a page and down a quarter of a
page. Alternatively, the distance can be specified in pixels by
appending a
.RI ' p '
to the horizontal and/or vertical specification.  For example
.EX
CursorMove -10p -10p
.EE
means move ten pixels up and ten pixels left.  The CursorMove
function should not be called from pop-up menus.

.TP
.BI "FlipFocus  [" NoWarp "]"
Executes a
.B Focus
command as if the user had used the pointer to select the
window. This command alters the order of the WindowList in the
same way as clicking in a window to focus, i.e. the target window
is removed from the
.B WindowList
and placed at the start. This command is recommended for use with
the
.B Direction
command and in the function invoked from
.BR WindowList .

.TP
.BI "Focus  [" NoWarp "]"
Sets the keyboard focus to the selected window.  If the
.I NoWarp
argument is given, this is all it does.  Otherwise it also moves
the viewport or window as needed to make the selected window
visible. This command does not automatically raise the
window. Does not warp the pointer into the selected window (see
.B WarpToWindow
function).  Does not de-iconify.  This command does not alter the
order of the
.BR WindowList ,
it rotates the
.B WindowList
around so that the target window is at the start.

When the
.I NoWarp
argument is given, Focus cannot transfer the keyboard focus to
windows on other desks.

To raise and/or warp a pointer to a window together with
.BR Focus " or " FlipFocus ,
use a function, like:
.EX
AddToFunc SelectWindow
+ I Focus
+ I Iconify false
+ I Raise
+ I WarpToWindow 50 8p
.EE

.TP
.BI "WarpToWindow " x "[" p "] " y "[" p "]"
Warps the cursor to the associated window.  The parameters
.IR x " and " y
default to percentage of window down and in from the upper left
hand corner (or number of pixels down and in if
.RI ' p '
is appended to the numbers).  If a number is negative the opposite
edge is used and the direction reversed.  This command works also
with windows that are not managed by fvwm.  In this case fvwm does
not bring the window onto the screen if it is not visible.  For
example it is possible to warp the pointer to the center of the
root window on screen 1:
.EX
WindowId root 1 WarpToWindow 50 50
.EE


.SS COMMANDS CONTROLLING WINDOW STATE

.TP
.BI "Close"
If the window accepts the delete window protocol a message is sent
to the window asking it to gracefully remove itself.  If the
window does not understand the delete window protocol then the
window is destroyed as with the
.B Destroy
command.  Note: if the window accepts the delete window protocol
but does not close itself in response, the window is not deleted.

.TP
.BI "Delete"
Sends a message to a window asking that it remove itself,
frequently causing the application to exit.

.TP
.BI "Destroy"
Destroys an application window, which usually causes the
application to crash and burn.

.TP
.BI "Iconify [" bool "]"
Iconifies a window if it is not already iconified or de-iconifies
it if it is already iconified.  The optional argument
.I bool
is a boolean argument.  "True" means only iconification is
allowed, while "False" forces de-iconification.  Using "toggle"
switches between iconified and de-iconified states.

There are a number of
.B Style
options which influence the appearance and behavior of icons (e.g.
.IR StickyIcon ", " NoIcon ).

For backward compatibility, the optional argument may also be a
positive number instead of "True", or a negative number instead
of "False".  Note that this syntax is obsolete, and will be removed
in the future.

.TP
.B "Maximize [\fIflags\fP\
] [\fIbool\fP\
] [\fIhorizontal\fP\
[\fIp\fP\
]] [\fIvertical\fP \
[\fIp\fP\
]]"
Without its optional arguments (or if the
.I bool
bit has the value "toggle")
.B Maximize
causes the window to alternately switch from a full-screen size to
its normal size.  To force a window into maximized (normal) state
you can use a "True" or "False" value for the
.I bool
argument.

With the optional arguments
.IR horizontal " and " vertical ,
which are expressed as percentage of a full screen, the user can
control the new size of the window.  An optional suffix
.RI ' p '
can be used to indicate pixels instead of percents of the screen
size.  If horizontal is greater than 0 then the horizontal
dimension of the window is set to
.IR horizontal *screen_width/100.
If the value is smaller than 0 the size is subtracted from the
screen width, i.e. -25 is the same as 75.  If
.I horizontal
is "grow", it is maximized to current available space until
finding any obstacle.  The vertical resizing is similar.  If both
horizontal and vertical values are "grow", it expands vertically
first, then horizontally to find space.  Instead of the horizontal
"grow" argument, "growleft" or "growright" can be used
respectively "growup" and "growdown".
The optional
.I flags
argument is a space separated list containing the following
key words:
.IR ewmhiwa ", " growonwindowlayer ", " growonlayers " and " screen .
.I ewmhiwa
causes fvwm to ignore the EWMH working area.
.I Growonwindowlayer
causes the various grow methods to ignore windows with a layer
other than the current layer of the window which is maximized.
The
.I growonlayers
option must have two integer arguments.  The first one is the
minimum layer and the second one the maximum layer to use.
Windows that are outside of this range of layers are ignored by
the grow methods.  A negative value as the first or second
argument means to assume no minimum or maximum layer.
.I Screen
must have an argument which specifies the Xinerama screen on which
to operate.
It can be 'p' for the primary screen, 'c' for the current
screen (containing the mouse pointer), 'g' for the global screen
or the screen number itself (counting from zero).  This option is
only useful with multiple Xinerama screens.

Here are some examples.  The following adds a title-bar button to
switch a window to the full vertical size of the screen:
.EX
Mouse 0 4 A Maximize 0 100
.EE
The following causes windows to be stretched to the full width:
.EX
Mouse 0 4 A Maximize 100 0
.EE
This makes a window that is half the screen size in each
direction:
.EX
Mouse 0 4 A Maximize 50 50
.EE
To expand a window horizontally until any other window is found:
.EX
Mouse 0 4 A Maximize 0 grow
.EE
To expand a window until any other window on the same or a higher
layer is hit.
.EX
Mouse 0 4 A Maximize growonlayers $[w.layer] -1 grow grow
.EE
To expand a window but leave the lower 60 pixels of the screen
unoccupied:
.EX
Mouse 0 4 A Maximize 100 -60p
.EE
Values larger than 100 can be used with caution.

.TP
.BI "Recapture"
This command is obsolete and should not be used anymore.  Should
you want to do something specific that you cannot do without it,
please report this to the fvwm-workers mailing list
(@FVWMWORKERSLIST@).  This command will be removed at some point
in the future.  Please read the note at the end of the section
.B "DELAYED EXECUTION OF COMMANDS"
to learn about how to avoid the
.B Recapture
command.

Causes fvwm to recapture all of its windows.  This ensures that
the latest style parameters are used.  The recapture operation is
visually disturbing.

Since fvwm version 2.4 only a very few
.B Style
options need a
.B Recapture
to take effect (e.g.
.IR UseStyle ).

.TP
.BI "RecaptureWindow"
This command is obsolete and should not be used anymore.  See
.B Recapture
For details.

Causes fvwm to recapture the chosen window.

.TP
.BI "Refresh"
Causes all windows on the screen to redraw themselves. All pending
updates of all windows' styles and looks are applied immediately.
E.g. if
.BR Style " or " TitleStyle
commands were issued inside a fvwm function.

.TP
.BI "RefreshWindow"
Causes the chosen window to redraw itself. All pending updates of
the window's style and looks are applied immediately.  E.g. if
.BR Style " or " TitleStyle
commands were issued inside a fvwm function.

.TP
.BI "Stick [" bool "]"
If the
.I bool
argument is empty or "toggle", the
.B Stick
command makes a window sticky if it is not already sticky, or
non-sticky if it is already sticky.  To make a window sticky
regardless of its current state the
.I bool
argument must be "True".  To make it non-sticky use "False".

.TP
.BI "StickAcrossPages [" bool "]"
Works like
.B Stick
but only sticks a window across pages, not across desks.

.TP
.BI "StickAcrossDesks [" bool "]"
Works like
.B Stick
but only sticks a window across desks, not across pages.

.TP
.BI "WindowShade [" bool "] | [[" ShadeAgain "] " direction "]"
Toggles the window shade feature for titled windows.  Windows in
the shaded state only display a title-bar.  If
.I bool
is not given or "toggle", the window shade state is toggled.  If
.I bool
is "True", the window is forced to the shaded state.  If
.I bool
is "False", then the window is forced to the non-shaded
state.  To force shading in a certain direction, the
.I direction
argument can be used.  Any of the strings "North", "South",
"West", "East", "NorthWest", "NorthEast", "SouthWest" or
"SouthEast" can be given.  The direction can be abbreviated with
the usual one or two letters "N", "NW", etc.  Using a direction on
a window that was already shaded unshades the window.  To shade it
in a different direction, use the
.I ShadeAgain
option.  Windows without titles can be shaded too.  Please refer
also to the options
.IR WindowShadeSteps ", " WindowShadeShrinks ,
.IR WindowShadeScrolls ", " WindowShadeLazy ,
.IR WindowShadeAlwaysLazy " and " WindowShadeBusy .
option of the
.B Style
command.  Examples:
.EX
Style * WindowShadeShrinks, \\
WindowShadeSteps 20, WindowShadeLazy
Mouse 1 S - WindowShade North
Mouse 1 S [ WindowShade West
Mouse 1 S ] WindowShade E
Mouse 1 S _ WindowShade S
.EE

Note: When a window that has been shaded with a
.I direction
argument changes the direction of the window title (see
.I TitleAtTop
.B Style
option), the shading direction does not change.  This may look
very strange.  Windows that were shaded without a
.I direction
argument stay shaded in the direction of the title bar.

For backward compatibility, the optional argument may also be 1 to
signify "on", and 2 to signify "off". Note that this syntax is
obsolete, and will be removed in the future.

.TP
.BI "WindowShadeAnimate  [" steps "[" p "]]"
This command is obsolete.  Please use the
.I WindowShadeSteps
option of the
.B Style
command instead.


.SS COMMANDS FOR MOUSE, KEY AND STROKE BINDINGS

.TP
.BI "IgnoreModifiers [" Modifiers "]"
Tells fvwm which modifiers to ignore when matching Mouse or Key
bindings.
.B IgnoreModifiers
affects the
.I ClickToFocus
style too.  This command belongs into your
.IR config .
If you issue it when your fvwm session is already up and running
the results are unpredictable.  The should appear before any
applications or modules are started in your
.I config
file (e.g. with the
.B Exec
command).

.I Modifiers
has the same syntax as in the
.BR Mouse " or " Key
bindings, with the addition of 'L' meaning the
.SM caps lock
key.  The default is "L".
.I Modifiers
can be omitted, meaning no modifiers are ignored.  This command
comes in handy if the
.SM num-lock
and
.SM scroll-lock
keys interfere with your shortcuts.  With XFree86 '2' usually is
the
.SM num-lock
modifier and '5' refers to the
.SM scroll-lock
key. To turn all these pesky modifiers off you can use this
command:
.EX
IgnoreModifiers L25
.EE
If the
.I Modifiers
argument is the string "default", fvwm reverts back to the
default value "L".

.I Important Note:
This command creates a lot of extra network traffic, depending on
your CPU, network connection, the number of
.BR Key " or " Mouse
commands in your configuration file and the number of modifiers
you want to ignore.  If you do not have a lightning fast machine
or very few bindings you should not ignore more than two
modifiers. I.e. do not ignore
.SM scroll-lock
if you have no problem with it.  In the
.I FAQ
you can find a better solution of this problem.

.TP
.BI "EdgeCommand [" direction " [" Function "]]"
Binds a specified fvwm command
.I Function
to an edge of the screen. Direction may be one of
"North", "Top", "West", "Left", "South", "Bottom", "Right"
and "East". If
.I Function
is omitted the binding for this edge is removed. If EdgeCommand is
called without any arguments all edge bindings are removed.

.I Function
is executed when the mouse pointer
enters the invisible pan frames that surround the visible screen.
The binding works only if
.I EdgeThickness
is set to a value greater than 0.
If a function is bound to an edge, scrolling specified by
.I EdgeScroll
is disabled for this edge.
It is possible to bind a function only to some edges
and use the other edges for scrolling.
This command is intended to raise or lower certain windows
when the mouse pointer enters an edge.
.I FvwmAuto
can be used get a delay when raising or lowering windows.
The following example raises
.I FvwmButtons
if the mouse pointer enters the top edge of the screen.
.EX
# Disable EdgeScrolling but make it possible
# to move windows over the screen edge
EdgeResistance 10000 20

# Set thickness of the edge of the screen to 1
EdgeThickness 1

# Give focus to FvwmButtons if the mouse
# hits top edge
EdgeCommand Top Next (FvwmButtons) Focus
# Make sure the Next command matches the window
Style FvwmButtons CirculateHit

Module FvwmButtons
Module FvwmAuto 100 \\
        "Silent AutoRaiseFunction" \\
        "Silent AutoLowerFunction"

# If any window except FvwmButtons has
# focus when calling this function
# FvwmButtons are lowered
DestroyFunc AutoLowerFunction
AddToFunc AutoLowerFunction
+ I Current (!FvwmButtons) \\
        All (FvwmButtons) Lower

# If FvwmButtons has focus when calling \\
# this function raise it
DestroyFunc AutoRaiseFunction
AddToFunc AutoRaiseFunction
+ I Current (FvwmButtons) Raise
.EE
Normally, the invisible pan frames are only on the screen edges
that border virtual pages.  If a screen edge has a command bound
to it, the pan frame is always created on that edge.

.TP
.BI "EdgeLeaveCommand [" direction " [" Function "]]"
Binds a specified fvwm command
.I Function
to an edge of the screen. Direction may be one of
"North", "Top", "West", "Left", "South", "Bottom", "Right"
and "East". If
.I Function
is omitted the binding for this edge is removed. If
EdgeLeaveCommand is called without any arguments all edge bindings
are removed.

.I Function
is executed when the mouse pointer
leaves the invisible pan frames that surround the visible screen.
The binding works only if
.I EdgeThickness
is set to a value greater than 0.
If a function is bound to an edge, scrolling specified by
.I EdgeScroll
is disabled for this edge.
It is possible to bind a function only to some edges
and use the other edges for scrolling.
This command is intended to raise or lower certain windows
when the mouse pointer leaves an edge.
.I FvwmAuto
can be used get a delay when raising or lowering windows.
See example for
.I EdgeCommand
.EE
Normally, the invisible pan frames are only on the screen edges
that border virtual pages.  If a screen edge has a command bound
to it, the pan frame is always created on that edge.

.TP
.BI "GnomeButton"
Used in conjunction with
.B Mouse
to pass mouse button presses on the root window to a
.SM GNOME
program (such as GMC).  The following example passes presses of
mouse buttons 1 and 3 to such a program.
.EX
Mouse 1 R A GnomeButton
Mouse 3 R A GnomeButton
.EE

.TP
.BI "Key [(" window ")] " "Keyname Context Modifiers Function"
Binds a keyboard key to a specified fvwm command, or
removes the binding if
.I Function
is '-'.  The syntax is the same as for a
.B Mouse
binding except that the mouse button number is replaced with a
.IR Keyname .
Normally, the key binding is activated when the key is pressed.
.I Keyname
is a standard X11 key name as defined in
.IR /usr/include/X11/keysymdef.h ,
(without the 
.I XK_
prefix), or the keysym database
.IR /usr/X11R6/lib/X11/XKeysymDB .
Only key names that are
generated with no modifier keys or with just the
.SM Shift
key held are guaranteed to work.  The
.IR Context " and " Modifiers
fields are defined as in the
.B Mouse
binding.  However, when you press a key the context window is the
window that has the keyboard focus.  That is not necessarily the
same as the window the pointer is over (with
.IR SloppyFocus " or " ClickToFocus ).
Note that key bindings with the 'R' (root window) context do not
work properly with
.IR SloppyFocus " and " ClickToFocus .
If you encounter problems, use the
.B PointerKey
command instead.  If you want to bind keys to a window with
.IR SloppyFocus " or " ClickToFocus
that are supposed to work when the pointer is not over the window,
fvwm assumes the pointer is over the client window (i.e. you have
to use the 'W' modifier).

The following example binds the built-in window list to pop up
when
.SM Alt-Ctrl-Shift-F11
is hit, no matter where the mouse pointer is:
.EX
Key F11 A SCM WindowList
.EE
Binding a key to a title-bar button causes that button to appear.
Please refer to the
.B Mouse
command for details.

.TP
.BI "Mouse [(" window ")] " "Button Context Modifiers Function"
Defines a mouse binding, or removes the binding if
.I Function
is '-'.
.I Button
is the mouse button number.  If
.I Button
is zero then any button performs the specified function.  Note
that only mouse buttons 1 to 5 are fully supported by X11.  Any
number above this works only partially.  Complex functions can not
be used with these buttons and neither any operation that requires
dragging the pointer with the button held.  This is due to
limitations of X11.  By default, the highest allowed button number
is 9.

.I Context
describes where the binding applies.  Valid contexts are 'R' for
the root window, 'W' for an application window, 'D' for a desktop
application (as kdesktop or Nautilus desktop), 'T' for a window
title-bar, 'S' for a window side, top, or bottom bar, '[', ']',
\'-' and '_' for the left, right, top or bottom side only, 'F' for
a window frame (the corners), '<', '^', '>' and 'v' for the top
left, top right, bottom right or bottom left corner, 'I' for an
icon window, or '0' through '9' for title-bar buttons, or any
combination of these letters.  'A' is for any context.  For
instance, a context of "FST" applies when the mouse is anywhere in
a window's border except the title-bar buttons.  Only 'S' and 'W'
are valid for an undecorated window.

The special context 'M' for menus can only be used to control
which mouse button is used to tear off menus.  See the section
"Tear Off Menus" for details.

By default, the binding applies to all windows. You can specify
that a binding only applies to specific windows by specifying the
window name in brackets. The window name is a wildcard pattern
specifying the class, resource or name of the window you want the
binding to apply to.

The following example shows how the same key-binding can be used to
perform different functions depending on the window that is focussed:
.EX
Key (rxvt)  V A C Echo ctrl-V-in-RXVT
Key (*term) V A C Echo ctrl-V-in-Term
Key (*vim)  V A C --
Key         V A C Echo ctrl-V-elsewhere
.EE

A '--' action indicates that the event should be propagated to the specified
window to handle. This is only a valid action for window-specific bindings.

This example shows how to display the WindowList when Button 3 is
pressed on an rxvt window:
.EX
Mouse (rxvt) 3 A A WindowList
.EE

Note that Fvwm actually intercepts all events for a window-specific
binding and (if the focussed window doesn't match any of the bindings)
sends a synthetic copy of the event to the window. This should be
transparent to most applications, however (for security reasons) some programs
ignore these synthetic events by default - xterm is one of them. To enable
handling of these events, add the following line to your ~/.Xdefaults file:

.EX
XTerm*allowSendEvents:  true
.EE

.I Modifiers
is any combination of 'N' for no modifiers, 'C' for control, 'S'
for shift, 'M' for Meta, 'L' for Caps-Lock or 'A' for any
modifier. For example, a modifier of "SM" applies when both the
.SM Meta
and
.SM Shift
keys are down.  X11 modifiers mod1 through mod5 are represented as
the digits '1' through '5'.  The modifier 'L' is ignored by
default.  To turn it on, use the
.B IgnoreModifiers
command.

.I Function
is one of fvwm's commands.

The title-bar buttons are numbered with odd numbered buttons on
the left side of the title-bar and even numbers on the
right. Smaller-numbered buttons are displayed toward the outside
of the window while larger-numbered buttons appear toward the
middle of the window (0 is short for 10).  In summary, the buttons
are numbered:
.EX
1 3 5 7 9    0 8 6 4 2
.EE
The highest odd numbered button which has an action bound to it
determines the number of buttons drawn on the left side of the
title bar.  The highest even number determines the number or right
side buttons which are drawn.  Actions can be bound to either
mouse buttons or keyboard keys.

.TP
.BI "PointerKey [(" window ")] " "Keyname Context Modifiers Function"
This command works exactly like the
.B Key
command.  The only difference is that the binding operates on the
window under the pointer.  Normal key bindings operate on the
focused window instead.  The
.B PointerKey
command can for example be used to bind keys to the root window if
you are using
.IR SloppyFocus " or " ClickToFocus .
However, some applications (xterm is one example) are unable to
handle this key anymore, even if the pointer is over the xterm
window.  It is recommended to use the
.B PointerKey
command only for key combinations that are not needed in any
application window.

Example:
.EX
Style * SloppyFocus
PointerKey f1 a m Menu MainMenu
.EE

.TP
.BI "Stroke [(" window ")] " "Sequence Button Context Modifiers Function"
Binds a mouse stroke sequence to a specified fvwm command,
or removes the binding if
.I Function
is '-'.  The syntax is the same as for a
.B Mouse
binding except that
.I Sequence
is inserted in front of the button number and a value of 0 for
.I Button
concerns the
.B StrokeFunc
command.  The
.IR Context " and " Modifiers
fields are defined as in the
.B Mouse
binding.  However, only the 'R' Context really works (if you want
to use other contexts you need to use the
.B StrokeFunc
below).

Strokes sequences are defined in a telephone grid like this:
.EX
 1  2  3

 4  5  6

 7  8  9
.EE
or in a numeric pad grid like this:
.EX
 7  8  9

 4  5  6

 1  2  3
.EE
The telephone grid is used by default, to use the numeric pad grid
you should begin the sequence with a 'N'.  Note that a complex
motion may gives several different sequences (see the "netscape"
example below to handle such motion).  Moreover, sequence are
limited to 20 elements (with the present version of
.BR libstroke ),
however, in practice it is preferable to use sequence with less
than 12 elements.

Because of the default button menu in fvwm, you may need to remove
a mouse button binding (using an empty action) before using the
stroke
.EX
Mouse 3 R N
.EE
Also, you can still use the stroke "sequence 0" to simulate a
click:
.EX
Stroke 0 3 R N Menu WindowList Nop
.EE
The following example starts xterm when the mouse drags an 'I' on
the root window with button 3 pressed down:
.EX
Stroke 258  3  R  N  Exec exec xterm
.EE
An example for Netscape:
.EX
Stroke 7415963    3  R  N  Exec exec netscape
Stroke 74148963   3  R  N  Exec exec netscape
Stroke 74158963   3  R  N  Exec exec netscape
Stroke 7418963    3  R  N  Exec exec netscape
Stroke 415963     3  R  N  Exec exec netscape
.EE
You may prefer to use the numeric pad grid since you have such a
grid on your machine. Here an example:
.EX
Stroke N78963214   3  R  N  FvwmForm FvwmForm-QuitVerify
Stroke N789632147  3  R  N  FvwmForm FvwmForm-QuitVerify
.EE
This example starts the "QuitVerify" form if you draw a box that
begins in the top left corner.

Note: You need
.B libstroke
installed and fvwm compiled with stroke support.
.B libstroke
can be obtained at
.EX
.B http://www.etla.net/~willey/projects/libstroke/
.EE

.TP
.BI "StrokeFunc [" Options "]"
Causes fvwm to record a mouse stroke sequence and to execute the
corresponding action as defined in a
.B Stroke
command.  The cursor is modified to the
.I STROKE
context of the
.B CursorStyle
command during recording.  When the stroke is finished
.B StrokeFunc
looks for a stroke binding of the form
.EX
Stroke sequence 0 Context Modifiers action
.EE
and executes the corresponding action (Note the 0).  Normal use of
this function is via a
.BR Mouse " or " Key
command.  Examples:
.EX
Mouse 3 A M StrokeFunc
Key x R N StrokeFunc
.EE
If you press mouse button 3 and
.SM Alt
anywhere (respectively, press the key x when the cursor is on the
root window), then fvwm records the mouse motions until the mouse
button 3 (respectively, the x key) is released and then check if
the recorded
.I sequence
corresponds to a stroke binding of the form
.EX
.RI """Stroke " sequence " 0 A M " action """ \""
.RI """Stroke " sequence " 0 R N " action """ \""
.EE
Note that the
.IR Context " and " Modifiers
are taken at the beginning of the execution of the
.B StrokeFunc
command (so you can release the modifiers before the end of the
stroke recording in the case of a mouse binding and if you used,
say, a title-bar context the mouse motion can go through an
application window).  The keys
.SM Escape
and
.SM Delete
allow you to abort the command.

The
.B StrokeFunc
command has five options:
.IR NotStayPressed ", " EchoSequence ", " DrawMotion ", "
.IR FeedBack " and " StrokeWidth .
These options are disabled by default.
.I EchoSequence
causes fvwm to Echo the recorded stroke sequence.
.I DrawMotion
causes fvwm to draw the mouse motion on the screen.
.I FeedBack
causes fvwm to display during a fraction of second the cursor of
the
.I WAIT
context of the
.B CursorStyle
command if the recorded stroke sequence corresponds to a stroke
binding.
.I StrokeWidth
takes an integer argument, which must be >= 0 and <= 100 and which
defines the width of the line for the
.I DrawMotion option.

.I NotStayPressed
works only if
.B StrokeFunc
is used via a
.BR Mouse
or a
.B Key
command.  This option removes the need to have a button or the key
pressed during the stroke, but you have to do a mouse click or
press the
.SM Return
or
.SM Space
key to finish the mouse motion recording (these keys also work
without the
.I NotStayPressed
option).

You can use the
.B StrokeFunc
"alone".  In this case it works as above with the
.I NotStayPressed
option enabled.  However,
.I Modifiers,
in general, may not work as expected (i.e., in this case use 'A'
or 'N' as
.I Modifiers
in the stroke bindings).

Note that some computers do not support key release events. If
that is the case the
.B StrokeFunc
used via a
.B Key
command works as if the
.I NotStayPressed
option is enabled.


.SS THE STYLE COMMAND (CONTROLLING WINDOW STYLES)

For readability, the commands in this section are not sorted
alphabetically.  The description of the
.B Style
command can be found at the end of this section.

.TP
.BI "FocusStyle " "stylename options"
works exactly like the
.B Style
command, but accepts only the focus policy related styles
beginning with "FP".  The prefix can be removed, but at the cost
of a little bit of time.
.B FocusStyle
is meant to make the configuration file more readable.  Example:
.EX
FocusStyle * EnterToFocus, !LeaveToUnfocus
.EE
is equivalent to
.EX
Style * FPEnterToFocus, !FPLeaveToUnfocus
.EE

.TP
.BI "DestroyStyle " style
deletes the style named
.IR style .
The changes take effect immediately.  Note that
.I style
is not a wild-carded search string, but rather a case-sensitive
string that should exactly match the original
.B Style
command.

Destroying style "*" can be done, but isn't really to be
recommended. For example:
.EX
DestroyStyle Application*
.EE
This removes all settings for the style named "Application*", NOT
all styles starting with "Application".

.TP
.B "DestroyWindowStyle"
deletes the styles set by the
.B WindowStyle
command on the selected window. The changes take effect immediately.

.TP
.BI "UpdateStyles"
All pending updates of all windows' styles and looks are applied
immediately.  E.g. if
.BR Style ", " WindowStyle " or " TitleStyle
commands were issued inside a fvwm function.

.TP
.BI "Style " "stylename options"
This command is intended to replace the old fvwm 1.xx global
commands NoBorder, NoTitle, StartsOnDesk, Sticky, StaysOnTop,
Icon, WindowListSkip, CirculateSkip, SuppressIcons, BoundaryWidth,
NoBoundaryWidth, StdForeColor, and StdBackColor with a single
flexible and comprehensive window specific command.  This command
is used to set attributes of a window to values other than the
default or to set the window manager default styles.

.I stylename
can be a window's name, class, or resource string.  It may contain
the wildcards '*' and '?', which are matched in the usual Unix
filename manner.  They are searched in the reverse order stated.
When two conflicting styles apply to the same window, the style
that was changed last wins.

Note: windows that have no name (WM_NAME) are given a name of
"Untitled", and windows that don't have a class (WM_CLASS,
res_class) are given class "NoClass" and those that don't have a
resource (WM_CLASS, res_name) are given resource "NoResource".

.I options is a comma separated list containing one or more of the
following keywords.  Each group of style names is separated by
slashes ('/').  The last style in these groups is the default.
.IR BorderWidth ", " HandleWidth ,
.IR NoIcon " / " Icon ", " MiniIcon ,
.IR IconBox ", " IconGrid ", " IconFill ", " IconSize ,
.IR NoTitle " / " Title ,
.IR TitleAtBottom " / " TitleAtLeft " / " TitleAtRight " / " TitleAtTop ,
.IR LeftTitleRotatedCW " / " LeftTitleRotatedCCW,
.IR RightTitleRotatedCCW " / " RightTitleRotatedCW,
.IR TopTitleRotated " / " TopTitleNotRotated,
.IR BottomTitleRotated " / " BottomTitleNotRotated,
.IR !UseTitleDecorRotation " / " UseTitleDecorRotation,
.IR StippledTitle " / " StippledTitleOff ,
.IR IndexedWindowName " / " ExactWindowName ,
.IR IndexedIconName " / " ExactIconName ,
.IR !Borders " / " Borders ,
.IR NoHandles " / " Handles ,
.IR WindowListSkip " / " WindowListHit ,
.IR CirculateSkip " / " CirculateHit ,
.IR CirculateSkipShaded " / " CirculateHitShaded ,
.IR Layer ,
.IR StaysOnTop " / " StaysOnBottom " / " StaysPut ,
.IR Sticky " / " Slippery ,
.IR StickyAcrossPages " / " !StickyAcrossPages ,
.IR StickyAcrossDesks " / " !StickyAcrossDesks ,
.IR StartIconic " / " StartNormal ,
.IR Color ", " ForeColor ", " BackColor ", " Colorset ,
.IR HilightFore ", " HilightBack ", " HilightColorset ,
.IR BorderColorset ", " HilightBorderColorset ,
.IR IconTitleColorset ", " HilightIconTitleColorset ,
.IR IconBackgroundColorset ,
.IR IconTitleRelief ", " IconBackgroundRelief ", " IconBackgroundPadding ,
.IR Font ,
.IR IconFont ,
.IR StartsOnDesk " / " StartsOnPage " / " StartsAnyWhere ,
.IR StartsOnScreen ,
.IR ManualPlacementHonorsStartsOnPage " / " ManualPlacementIgnoresStartsOnPage ,
.IR CaptureHonorsStartsOnPage " / " CaptureIgnoresStartsOnPage ,
.IR RecaptureHonorsStartsOnPage " / " RecaptureIgnoresStartsOnPage ,
.IR StartsOnPageIncludesTransients " / " StartsOnPageIgnoresTransients ,
.IR IconTitle " / " NoIconTitle ,
.IR MwmButtons " / " FvwmButtons ,
.IR MwmBorder " / " FvwmBorder ,
.IR MwmDecor " / " NoDecorHint ,
.IR MwmFunctions " / " NoFuncHint ,
.IR HintOverride " / " NoOverride ,
.IR NoButton " / " Button ,
.IR ResizeHintOverride " / " NoResizeOverride ,
.IR OLDecor " / " NoOLDecor ,
.IR GNOMEUseHints " / " GNOMEIgnoreHints ,
.IR StickyIcon " / " SlipperyIcon ,
.IR StickyAcrossPagesIcon " / " !StickyAcrossPagesIcon ,
.IR StickyAcrossDesksIcon " / " !StickyAcrossDesksIcon ,
.IR ManualPlacement " / " CascadePlacement " / " MinOverlapPlacement " / "
.IR MinOverlapPercentPlacement " / " TileManualPlacement " / "
.IR TileCascadePlacement , " / " CenterPlacement ,
.IR MinOverlapPlacementPenalties ,
.IR MinOverlapPercentPlacementPenalties ,
.IR DecorateTransient " / " NakedTransient ,
.IR DontRaiseTransient " / " RaiseTransient ,
.IR DontLowerTransient " / " LowerTransient ,
.IR DontStackTransientParent " / " StackTransientParent ,
.IR SkipMapping " / " ShowMapping ,
.IR ScatterWindowGroups " / " KeepWindowGroupsOnDesk ,
.IR UseDecor ,
.IR UseStyle ,
.IR NoPPosition " / " UsePPosition ,
.IR NoUSPosition " / " UseUSPosition ,
.IR NoTransientPPosition " / " UseTransientPPosition ,
.IR NoTransientUSPosition " / " UseTransientUSPosition ,
.IR NoIconPosition " / " UseIconPosition ,
.IR Lenience " / " NoLenience ,
.IR ClickToFocus " / " SloppyFocus " /"
.IR MouseFocus | FocusFollowsMouse " / " NeverFocus ,
.IR ClickToFocusPassesClickOff " / " ClickToFocusPassesClick ,
.IR ClickToFocusRaisesOff " / " ClickToFocusRaises ,
.IR MouseFocusClickRaises " / " MouseFocusClickRaisesOff ,
.IR GrabFocus " / " GrabFocusOff ,
.IR GrabFocusTransientOff " / " GrabFocusTransient ,
.IR FPFocusClickButtons ,
.IR FPFocusClickModifiers ,
.IR !FPSortWindowlistByFocus " / " FPSortWindowlistByFocus,
.IR FPClickRaisesFocused " / " !FPClickRaisesFocused,
.IR FPClickDecorRaisesFocused " / " !FPClickDecorRaisesFocused,
.IR FPClickIconRaisesFocused " / " !FPClickIconRaisesFocused,
.IR !FPClickRaisesUnfocused " / " FPClickRaisesUnfocused,
.IR FPClickDecorRaisesUnfocused " / " !FPClickDecorRaisesUnfocused,
.IR FPClickIconRaisesUnfocused " / " !FPClickIconRaisesUnfocused,
.IR FPClickToFocus " / " !FPClickToFocus,
.IR FPClickDecorToFocus " / " !FPClickDecorToFocus,
.IR FPClickIconToFocus " / " !FPClickIconToFocus,
.IR !FPEnterToFocus " / " FPEnterToFocus,
.IR !FPLeaveToUnfocus " / " FPLeaveToUnfocus,
.IR !FPFocusByProgram " / " FPFocusByProgram,
.IR !FPFocusByFunction " / " FPFocusByFunction,
.IR FPFocusByFunctionWarpPointer " / " !FPFocusByFunctionWarpPointer,
.IR FPLenient " / " !FPLenient,
.IR !FPPassFocusClick " / " FPPassFocusClick,
.IR !FPPassRaiseClick " / " FPPassRaiseClick,
.IR FPIgnoreFocusClickMotion " / " !FPIgnoreFocusClickMotion,
.IR FPIgnoreRaiseClickMotion " / " !FPIgnoreRaiseClickMotion,
.IR !FPAllowFocusClickFunction " / " FPAllowFocusClickFunction,
.IR !FPAllowRaiseClickFunction " / " FPAllowRaiseClickFunction,
.IR FPGrabFocus " / " !FPGrabFocus,
.IR !FPGrabFocusTransient " / " FPGrabFocusTransient,
.IR FPOverrideGrabFocus " / " !FPOverrideGrabFocus,
.IR FPReleaseFocus " / " !FPReleaseFocus,
.IR !FPReleaseFocusTransient " / " FPReleaseFocusTransient,
.IR FPOverrideReleaseFocus " / " !FPOverrideReleaseFocus,
.IR StartsLowered " / " StartsRaised ,
.IR IgnoreRestack " / " AllowRestack ,
.IR FixedPosition " / " VariablePosition ,
.IR FixedUSPosition " / " VariableUSPosition ,
.IR FixedPPosition " / " VariablePPosition ,
.IR FixedSize " / " VariableSize ,
.IR FixedUSSize " / " VariableUSSize ,
.IR FixedPSize " / " VariablePSize ,
.IR !Closable " / " Closable ,
.IR !Iconifiable " / " Iconifiable ,
.IR !Maximizable " / " Maximizable ,
.IR !AllowMaximizeFixedSize " / " AllowMaximizeFixedSize ,
.IR IconOverride " / " NoIconOverride " / " NoActiveIconOverride ,
.IR DepressableBorder " / " FirmBorder ,
.IR MaxWindowSize ,
.IR IconifyWindowGroups " / " IconifyWindowGroupsOff ,
.IR ResizeOpaque " / " ResizeOutline ,
.IR BackingStore " / " BackingStoreOff " / " BackingStoreWindowDefault ,
.IR Opacity " / " ParentalRelativity ,
.IR SaveUnder " / " SaveUnderOff ,
.IR WindowShadeShrinks " / " WindowShadeScrolls ,
.IR WindowShadeSteps ,
.IR WindowShadeAlwaysLazy " / " WindowShadeBusy " / " WindowShadeLazy,
.IR EWMHDonateIcon " / " EWMHDontDonateIcon ,
.IR EWMHDonateMiniIcon " / " EWMHDontDonateMiniIcon ,
.IR EWMHMiniIconOverride " / " EWMHNoMiniIconOverride ,
.IR EWMHUseStackingOrderHints " / " EWMHIgnoreStackingOrderHints ,
.IR EWMHIgnoreStateHints " / " EWMHUseStateHints ,
.IR EWMHIgnoreStrutHints " / " EWMHUseStrutHints ,
.IR EWMHMaximizeIgnoreWorkingArea " / " EWMHMaximizeUseWorkingArea " / "
.IR EWMHMaximizeUseDynamicWorkingArea ,
.IR EWMHPlacementIgnoreWorkingArea " / " EWMHPlacementUseWorkingArea
.IR EWMHPlacementUseDynamicWorkingArea ,
.IR MoveByProgramMethod ,
.IR Unmanaged ,
.IR State .

.\" +++++++++++++++ general notes
In the above list some options are listed as
style-option/opposite-style-option.  The opposite-style-option for
entries that have them describes the fvwm default behavior and can
be used if you want to change the fvwm default behavior.

.\" +++++++++++++++ focus policy
.TP
.B Focus policy
.I ClickToFocus
instructs fvwm to give the focus to a window when it is clicked
in.  The default
.I MouseFocus
(or its alias
.IR FocusFollowsMouse )
tells fvwm to give a window the focus as soon as the pointer
enters the window, and take it away when the pointer leaves the
window.
.I SloppyFocus
is similar, but doesn't give up the focus if the pointer leaves
the window to pass over the root window or a ClickToFocus window
(unless you click on it, that is), which makes it possible to move
the mouse out of the way without losing focus.  A window with the
style
.I NeverFocus
never receives the focus.  This is useful for modules like
.BR FvwmButtons ,
for example.
Note:  Once any of the "FP..." styles has been used, the defaults
that come with the basic focus policies are not restored when the
latter are used again.  For example, once !FPGrabFocus has been
used, using ClickToFocus does not restore FPGrabFocus.

The focus model can be augmented with several additional options.
In fvwm-2.5.3 and later, there are a large number of advanced
options beginning with "FP" or "!FP".  These options shall replace
the older options one day and are described first.  Using any of
these new options may limit compatibility with older releases.  In
general, options beginning with "FP" turn a feature on, while
those beginning with "!FP" turn it off.

.B Focusing the window

With
.IR FPEnterToFocus ,
when the pointer enters a window it receives focus.

With
.IR FPLeaveToUnfocus
a window loses focus when the pointer leaves it.

With
.IR FPClickToFocus ", " FPClickDecorToFocus " or "
.IR FPClickIconToFocus ,
a window receives focus when the inside of the window or the
decorations or its icon is clicked.

The
.IR FPFocusByProgram
style allows windows to take the focus themselves.

The
.IR !FPFocusByFunction
style forbids that a window receives the focus via the
.BR Focus " and " FlipFocus
commands.

The
.IR FPFocusByFunctionWarpPointer
style controls if the pointer is warped to a selected window
when the
.B Focus
command is used.

.I FPLenient
allows focus on windows that do not want it, like
.BR FvwmPager
or xclock.

The
.IR FPFocusClickButtons
style takes a list of mouse buttons that can be clicked to focus
or raise a window when the appropriate style is used.  The default
is to use the first three buttons ("123").

The
.IR FPFocusClickModifiers
style takes a list of modifier keys just like the
.B Key
command.  The exact combination of modifier keys must be pressed
for the click to focus or raise a window to work.  The default is
to use no modifiers ("N").

With the
.IR FPPassFocusClick
style, the click that was used to focus a window is passed to
the application.

With the
.IR FPAllowFocusClickFunction
style, the click that was used to focus a window can also
trigger a normal action that was bound to the window with the
.B Mouse
command).

If the
.IR FPIgnoreFocusClickMotion
style is used, clicking in a window and then dragging the pointer
with the button held down does not count as the click to focus the
window.  Instead, the application processes these events
normally.  This is useful to select text in a terminal window with
the mouse without raising the window.  However, mouse bindings on
the client window are not guaranteed to work anymore (see
.B Mouse
command).  This style forces the initial click to be
passed to the application.  The distance that the pointer must be
moved to trigger this is controlled by the
.B MoveThreshold
command.

The
.IR FPSortWindowlistByFocus " and " !FPSortWindowlistByFocus
styles control whether the internal window list is sorted in the
order the windows were focused or in the order they were created.
The latter is the default for
.IR ClickToFocus " and " SloppyFocus .


.B Clicking the window to raise

The styles
.IR FPClickRaisesFocused ", " FPClickDecorRaisesFocused " and "
.IR FPClickIconRaisesFocused
allow to raise the window when the interior or the decorations or
the icon of the window is clicked while the window is already
focused.

The styles
.IR FPClickRaisesUnfocused ", " FPClickDecorRaisesUnfocused " and "
.IR FPClickIconRaisesUnfocused
allow to raise the window when the interior or the decorations or
the icon of the window is clicked while the window is not yet
focused.

With the
.IR FPPassRaiseClick
style, the click that was used to raise the window is passed to
the application.

With the
.IR FPAllowRaiseClickFunction
style, the click that was used to raise the window can also
trigger a normal action that was bound to the window with the
.B Mouse
command.

.IR FPIgnoreRaiseClickMotion
style is used, clicking in a window and then dragging the pointer
with the button held down does not count as the click to raise the
window.  Instead, the application processes these events
normally.  This is useful to select text in a terminal window with
the mouse without raising the window.  However, mouse bindings on
the client window are not guaranteed to work anymore (see
.B Mouse
command.  Note that this style forces that the initial click is
passed to the application.  The distance that the pointer must be
moved to trigger this is controlled by the
.B MoveThreshold
command.

.B Grabbing the focus when a new window is created

New normal or transient windows with the
.IR FPGrabFocus " or " FPGrabFocusTransient
style automatically receive the focus when they are created.
.I FPGrabFocus
is the default for windows with the
.I ClickToFocus
style.

The
.I OverrideGrabFocus
style instructs fvwm to never take away the focus from such a
window via the
.IR GrabFocus " or " GrabFocusTransient
styles.  This can be useful if you like to have transient windows
receive the focus immediately, for example in a web browser, but
not while you are working in a terminal window or a text
processor.

The above three styles are accompanied by
.IR FPReleaseFocus ", " FPReleaseFocusTransient " and "
.IR FPOverrideReleaseFocus .
These control if the focus is returned to another window when the
window is closed.  Otherwise no window or the window under the
pointer will receive the focus.

.IR ClickToFocusPassesClickOff " and " ClickToFocusPassesClick
controls whether a mouse click to focus a window is sent to the
application or not.  Similarly,
.I ClickToFocusRaisesOff/MouseFocusClickRaisesOff
and
.I ClickToFocusRaises/MouseFocusClickRaises
control if the window is raised (but depending on the focus
model).

Note: in fvwm versions prior to
2.5.3, the "Click..." options applied only to windows with
.I ClickToFocus
while the "Mouse..." options applied to windows with a different
focus policy.  This is no longer the case.

The old
.I GrabFocus
style is equivalent to using
.IR FPGrabFocus " + " FPReleaseFocus .

The old
.I GrabFocusTransient
style is equivalent to using
.IR FPGrabFocusTransient " + " FPReleaseFocusTransient .

.I Lenience
is equivalent to the new style
.IR FPLenient .

.\" +++++++++++++++ styles affecting the window title
.TP
.B Window title
The
.IR Title " and " NoTitle
options determine if the window has a title-bar or not.  By
default all windows have a title-bar.

Windows with the
.IR TitleAtBottom ", " TitleAtLeft " or " TitleAtRight
style have a title-bar below, to the left or to the right of the
window instead of above as usual.  The
.I TitleAtTop
style restores the default placement.  Even if the window has the
.I NoTitle
style set, this affects the
.I WindowShade
command.  Please check the
.B WindowShade
command for interactions between that command and these styles.
Titles on the left or right side of the windows are augmented by
the following styles:

Normally, the text in titles on the left side of a window is
rotated counterclockwise by 90 degrees from the normal upright
position and 90 degrees clockwise for titles on the right side.
It can also be rotated in the opposite directions with
.IR LeftTitleRotatedCW " if " TitleAtLeft
is used, and with
.IR RightTitleRotatedCCW " if " TitleAtRight
is used.  The defaults can be restored with
.IR LeftTitleRotatedCCW " and " RightTitleRotatedCW .
A normal horizontal text may be rotated as well with
.IR TopTitleRotated " if " TitleAtTop
is used, and with
.IR BottomTitleRotated " if " TitleAtBottom
is used.  The defaults can be restored with
.IR TopTitleNotRotated " and " BottomTitleNotRotated .

By default the title bar decoration defined using the
.B TitleStyle
command is rotated following the title text rotation (see the
previous paragraph). This can be disabled by using the
.I !UseTitleDecorRotation
style.
.I UseTitleDecorRotation
reverts back to the default.

With the
.I StippledTitle
style, titles are drawn with the same effect that is usually
reserved for windows with the
.IR Sticky ", " StickyAcrossPages " or " StickyAcrossDesks
style.
.I StippledTitleOff
reverts back to normal titles.

.I Color
takes two arguments.  The first is the window-label text color and
the second is the window decorations normal background color. The
two colors are separated with a slash.  If the use of a slash
causes problems then the separate
.IR ForeColor " and " BackColor
options can be used.

.I Colorset
takes the colorset number as its sole argument and overrides the
colors set by
.IR Color .
Instead, the corresponding colors from the given colorset are
used.  Note that all other features of a colorset are not used.
Use the
.I Colorset
decoration style in the
.BR TitleStyle " and " ButtonStyle
command for that.
To stop using the colorset, the colorset number is omitted.

The
.IR HilightFore ", " HilightBack " and " HilightColorset
style options work exactly like
.IR ForeColor ", " BackColor " and " Colorset
but are used only if the window has the focus.  These styles
replace the old commands
.BR HilightColor " and " HilightColorset .

.IR BorderColorset
takes the colorset number as its sole argument and overrides the
colors set by
.IR Color " or " Colorset .
for the window border.  To stop using a colorset, the argument is
omitted.

The
.IR HilightBorderColorset
style option works similarly to
.IR BorderColorset
but is used when the window has the focus.

.I NoIconTitle
disables displaying icon labels while the opposite style
.I IconTitle
enables icon labels (default behaviour).

.IR IconTitleColorset
takes the colorset number as its sole argument and overrides the
colors set by
.IR Color " or " Colorset .
To stop using this colorset, the argument is omitted.

.IR HilightIconTitleColorset
takes the colorset number as its sole argument and overrides the
colors set by
.IR HilightColor " or " HilightColorset .
To stop using this colorset, the argument is omitted.

.IR IconBackgroundColorset
takes the colorset number as its sole argument and uses it to set
a background for the icon picture. By default the icon picture is
not drawn onto a background image. To restore the default, the
argument is omitted.

.IR IconTitleRelief
takes one numeric argument that may be between -50 and +50 pixels
and defines the thickness of the 3D relief drawn around the icon
title. With negative values the icon title gets a pressed in
look. The default is 2 and it is restored if the argument is
omitted.

.IR IconBackgroundRelief
takes one numeric argument that may be between -50 and +50 pixels
and defines the thickness of the 3D relief drawn around the icon
picture background (if any). With negative values the icon
background gets a pressed in look.  The default is 2 and it is
restored if the argument is omitted.

.IR IconBackgroundPadding
takes one numeric argument that may be between 0 and 50 pixels and
defines the amount of free space between the relief of the icon
background picture (if any) and the icon picture. The default is 2
and it is restored if the argument is omitted.

The
.IR Font " and " IconFont
options take the name of a font as their sole argument. This font
is used in the window or icon title.  By default the font given in
the
.B DefaultFont
command is used.  To revert back to the default, use the style
without the name argument.  These styles replace the older
.BR WindowFont " and " IconFont
commands.

The
.I IndexedWindowName
style causes fvwm to use window titles in the form
.EX
.IR name " (" i ") "
.EE
where
.I name
is the exact window name and
.I i
is an integer which represents the
.I i "th"
window with
.I name
as window name.
.I ExactWindowName
restores the default which is to use the exact window name.
.I IndexedIconName
and
.I ExactIconName
work the same as
.I IndexedWindowName
and
.I ExactWindowName
styles but for the icon titles.

.\" +++++++++++++++ styles affecting title buttons
.TP
.B Title buttons
.IR Button " and " NoButton
take a numeric argument which is the number of the title-bar
button which is to be included/omitted.

.I MwmButtons
makes the
.B Maximize
button look pressed-in when the window is maximized.  See the
.I MwmDecorMax
flag in
.B ButtonStyle
for more information.  To switch this style off again, use the
.I FvwmButtons
style.

.\" +++++++++++++++ styles affecting borders
.TP
.B Borders

.I !Borders
suppresses the window border (but not the title) completely.  The
.I Borders
style enables them again.  Without borders, all other styles
affecting window borders are meaningless.

.I MwmBorder
makes the 3-D bevel more closely match Mwm's.
.I FvwmBorder
turns off the previous option.

With the
.I NoHandles
style, the window does not get the handles in the window corners
that are commonly used to resize it.  With
.IR NoHandles ,
the width from the
.I BorderWidth
style is used.  By default, or if
.I Handles
is is specified, the width from the
.I HandleWidth
style is used.

.I HandleWidth
takes a numeric argument which is the width of the border to place
the window if it does have resize-handles.

.I BorderWidth
takes a numeric argument which is the width of the border to place
the window if it does not have resize-handles.  It is used only if
the
.I NoHandles
style is specified too.

.I DepressableBorder
makes the border parts of the window decoration look sunken in
when a button is pressed over them.  This can be disabled again
with the
.I FirmBorder
style.

.\" +++++++++++++++ icons, shading, maximizing, movement, resizing
.TP
.B Icons, shading, maximizing, movement, resizing
.I Icon
takes an (optional) unquoted string argument which is the icon
bitmap or pixmap to use. Icons specified this way override pixmap
icons, but not icon windows or the ewmh icon, provided by the
client in the application (with the WM_HINTS property or with the
ewmh _NET_WM_ICON property).  The
.I IconOverride
style changes the behavior to override any client-provided icons;
the
.I NoIconOverride
style changes the behavior to not override any client-provided
icons; the default overriding behavior can be activated with the
.I NoActiveIconOverride
style.  With this style, fvwm uses application provided icons if
the icon is changed but uses the icon provided in the
configuration file until then.

There is one exception to these rules, namely
.EX
Style * Icon unknown.xpm
.EE
doesn't force the unknown.xpm icon on every window, it just sets
the default icon like the DefaultIcon command. If you really want
all windows to have the same icon, you can use
.EX
Style ** Icon unknown.xpm
.EE
If the
.I NoIcon
attribute is set then the specified window simply disappears when
it is iconified.  The window can be recovered through the
window-list.  If
.I Icon
is set without an argument then the
.I NoIcon
attribute is cleared but no icon is specified.  An example which
allows only the
.B FvwmPager
module icon to exist:
.EX
Style * NoIcon
Style FvwmPager Icon
.EE

.I IconBox
takes no argument, four numeric arguments (plus optionally a
screen specification), an X11 geometry string or the string
"none":
.EX
.RI IconBox " [" "screen scr-spec" "] " "l t r b"
.EE
or
.EX
IconBox geometry
.EE
Where
.I l
is the left coordinate,
.I t
is the top,
.I r
is right and
.I b
is bottom.  Negative coordinates indicate distance from the right
or bottom of the screen.
If the first argument is the word
.IR screen ,
the
.I scr-spec
argument specifies the Xinerama screen on which the IconBox is
defined.  It can be the usual screen Xinerama specification, 'p',
\'c', 'g', a screen number or the additional 'w' for the screen
where the window center is located.  This is only useful with
multiple Xinerama screens.
The "l t r b" specification is more flexible than an X11 geometry.
For example:
.EX
IconBox -80 240 -1 -1
.EE
defines a box that is 80 pixels wide from the right edge,
240 pixels down from the top, and continues to the bottom of
the screen.

Perhaps it is easier to use is an X11
geometry string though:
.EX
IconBox 1000x70-1-1
.EE
places an 1000 by 70 pixel icon box on the bottom of the screen
starting in the lower right  hand corner of the screen.
One way to figure out a geometry like this is to use a window
that resizes in pixel increments, for example, xv.
Then resize and place the xv window where you want the iconbox.
Then use FvwmIdent to read the windows geometry.
The icon box is a region of the screen
where fvwm attempts to put icons for any matching window, as long
as they do not overlap other icons.
Multiple icon boxes can be
defined as overflow areas.  When the first icon box is full, the
second one is filled.  All the icon boxes for one style must be
defined in one
.B Style
command.  For example:
.EX
Style * IconBox -80 240 -1 -1, \\
        IconBox 1000x70-1-1
.EE
A Style command with the IconBox option replaces any icon box
defined previously by another Style command for the same style.
Thats why the backslash in the previous example is required.

Note: The geometry for the icon box command takes the additional
screen specifier "@w" in case a Xinerama setup is used.  This
designates the screen where the window center is located.  The
additional screen specifier is not allowed anywhere else.

If you never define an icon box, or you fill all the icon boxes,
fvwm has a default icon box that covers the screen, it fills top
to bottom, then left to right, and has an 80x80 pixel grid.  To
disable all but the default icon box you can use IconBox without
arguments in a separate
.B Style
command.  To disable all icon boxes including the default icon
box, the argument "none" can be specified.

Hint: You can auto arrange your icons in the icon box with a
simple fvwm function.  Put the "DeiconifyAndRearrange" function
below in your configuration file:
.EX
AddToFunc DeiconifyAndRearrange
 + C Iconify off
 + C All (CurrentPage, Iconic) PlaceAgain Icon
.EE
And then replace all places where you call the
.B Iconify
command to de-iconify an icon with a call to the new
function.  For example replace
.EX
AddToFunc IconFunc
 + C Iconify off
 + M Raise
 + M Move
 + D Iconify off

Mouse 1 I A Iconify off
.EE
with
.EX
AddToFunc IconFunc
 + C DeiconifyAndRearrange
 + M Raise
 + M Move
 + D DeiconifyAndRearrange

Mouse 1 I A DeiconifyAndRearrange
.EE
.I IconGrid
takes 2 numeric arguments greater than zero.
.EX
.I IconGrid x y
.EE
Icons are placed in an icon box by stepping through the icon box
using the
.IR x " and " y
values for the icon grid, looking for a free space. The default
grid is 3 by 3 pixels which gives a tightly packed appearance. To
get a more regular appearance use a grid larger than your largest
icon. Use the
.I IconSize
definition to clip an icon to a maximum size. An
.I IconGrid
definition must follow the
.B IconBox
definition that it applies to:
.EX
Style * IconBox -80x240-1-1, IconGrid 90 90
.EE
.I IconFill
takes 2 arguments.
.EX
.RI "IconFill " "Bottom Right"
.EE
Icons are placed in an icon box by stepping through the icon box
using these arguments to control the direction the box is filled
in. By default the direction is left to right, then top to bottom.
This would be expressed as:
.EX
IconFill left top
.EE
To fill an icon box in columns instead of rows, specify the
vertical direction (top or bottom) first. The directions can be
abbreviated or spelled out as follows: "t", "top", "b", "bot",
"bottom", "l", "lft", "left", "r", "rgt", "right". An
.B IconFill
definition must follow the
.B IconBox
definition that it applies to:
.EX
Style * IconBox -80x240-1-1, IconFill b r
.EE
.I IconSize
sets limits on the size of an icon image.  Both user-provided
and application-provided icon images are affected.
.EX
.RI IconSize " [ " width " " height " [ " maxwidth " " maxheight " ] ]"
.EE
All arguments are measured in pixels.  When all four arguments are
passed to
.I IconSize,
.I width
and
.I height
represent the minimum size of an icon, and
.I maxwidth
and
.I maxheight
represent the maximum size of an icon.  Icon images that are smaller
than the minimum size are padded.  Icon images that are bigger than
the maximum size are clipped.

If only two arguments are passed to
.I IconSize,
.I width
and
.I height
represent the absolute size of an icon.  Icons covered by this style
will be padded or clipped to achieve the given size.

If no arguments are specified, the default values are used for each
dimension.  This effectively places no limits on the size of an icon.

The value of "-1" can be used in place of any of the arguments to
specify the default value for that dimension.

Note that application-provided icon windows are not affected.

.I MiniIcon
specifies a pixmap to use as the miniature icon for the
window. This miniature icon can be drawn in a title-bar button
(see
.BR ButtonStyle ),
and can be used by various fvwm modules
.RB ( FvwmWinList ", " FvwmIconMan " and " FvwmTaskBar ).
It takes the name of a pixmap as an argument.

.IR WindowShadeShrinks " and " WindowShadeScrolls
control if the contents of a window that is being shaded with the
.B WindowShade
command are scrolled (default) or if they stay in place.  The
shrinking mode is a bit faster

The
.I WindowShadeSteps
option selects the number of steps for animation when shading a
window with
.BR WindowShade .
It takes one number as its argument.  If the number has a trailing
.RI ' p '
it sets the number of pixels to use as the step size instead of
a fixed number of steps.  0 disables the animation.  This happens
too if the argument is omitted or invalid.

The
.B WindowShade
command has two modes of operation: busy and lazy shading.  Busy
shading can be 50% slower than lazy shading, but the latter can
look strange under some conditions, for example, if the window
borders, buttons or the title are filled with a tiled pixmap.
Also, the window handles are not drawn in lazy mode and the border
relief may only be draw partially right before the window reaches
the shaded state or tight after leaves the unshaded state. By
default, fvwm uses lazy mode if there are no bad visual effects
(not counting the window handles) and busy mode otherwise.  Use
the
.I WindowShadeAlwaysLazy " or " WindowShadeBusy
to force using the lazy or busy mode.  The default setting is
restored with
.IR WindowShadeLazy .

.I ResizeOpaque
instructs fvwm to resize the corresponding windows with their
contents visible instead of using an outline.  Since this causes
the application to redraw frequently it can be quite slow and make
the window flicker excessively, depending on the amount of
graphics the application redraws.  The
.I ResizeOutline
style (default) negates the
.I ResizeOpaque
style.  Many applications do not like their windows being resized
opaque, e.g. XEmacs, Netscape or terminals with a pixmap
background. If you do not like the result, don't use the
.I ResizeOpaque
style for these windows.  To exempt certain windows from opaque
resizing you could use these lines in your configuration file:
.EX
Style * ResizeOpaque
Style rxvt ResizeOutline
Style emacs ResizeOutline
.EE
.I Sticky
makes the window sticky, i.e. it is always visible on each page
and each desk.  The opposite style,
.I Slippery
reverts back to the default.

.IR StickyAcrossPages " and " StickyAcrossPagesIcon
work like
.IR Sticky " and " StickyIcon ,
but stick the window only across pages, not desks while
.I StickyAcrossDesks " and " StickyAcrossDesksIcon
works the other way round.

Windows with the
.I StartIconic
style are shown as icons initially.  Note that some applications
counteract that by deiconifying themselves.  The default is to not
iconify windows and can be set with the
.I StartNormal
style.

.I StickyIcon
makes the window sticky when its iconified.  It de-iconifies on
top the active desktop.
.I SlipperIcon
reverts back to the default.

.I StickyIconPage
works like
.IR StickyIcon ,
but sticks the icon only across pages, not desks while
.I StickyIconDesk
works the other way round.

.I IgnoreRestack
makes fvwm ignore attempts of clients to raise or lower their own
windows.  By default, the opposite style,
.I AllowRestack
is active.

.IR FixedPosition " and " FixedUSPosition
make fvwm ignore attempts of the user to move the window.  It is
still possible to move the window by resizing is.  To allow the
user to move windows, use the
.IR VariablePosition or VariableUSPosition
style.

.IR FixedSize " and " FixedUSSize
make fvwm ignore attempts of the user to resize the window.  To
allow the user to resize windows, use the
.IR VariableSize " or " VariableUSSize
style.

.IR FixedPPosition " and " FixedPSize
make fvwm ignore attempts of the program to move or resize its
windows.  To allow this kind of actions, use the
.IR VariablePPosition " or " VariablePSize
style.  These styles may sometimes affect the initial placement
and dimensions of new windows (depending on the application).  If
windows are created at strange places, try either the
.IR VariablePPosition " or " NoPPosition
styles.  The
.I FixedPSize
style may screw up window dimensions for some applications.  Don't
use this style in this case.

.IR MoveByProgramMethod
affects how fvwm reacts to requests by the application to move its
windows.  By default, fvwm tries to detect which method to use,
but it sometimes detects the wrong method.  You may come across a
window that travels across the screen by a few pixels when the
application resizes it, moves to a screen border with the frame
decorations off screen, that remembers its position for the next
time it starts but appears in a slighly shifted position, or that
attepmts to become full screen but has the.  Try out both options,
.IR UseGravity " and " IgnoreGravity
on the window (and that window only) and see if that helps.  By
default, fvwm uses the
.I AutoDetect
method.  Once the method was detected, it is never changed again.
As long as fvwm can not detect the proper method, it uses
.IR IgnoreGravity .
To force fvwm to retry the detection, use one of the other two
options first and then use
.I AutoDetect
again.

Note:  This option was introduced to alleviate a problem with the
ICCCM2 specification.  The ICCCM2 clearly states that the
.I UseGravity
option should be used, but traditionally applications ignored this
rule.

.IR Closable
enables the functions
.I Close,
.I Delete
and
.I Destroy
to be performed on the windows. This is on by default.
The opposite,
.IR !Closable ,
inhibits the window to be closed.

.IR Iconifiable
enables the function
.I Iconify
to be performed on the windows.
This is on by default.
The opposite,
.IR !Iconifiable ,
inhibits the window from being iconified.

.IR Maximizable
enables the function
.I Maximize
to be performed on the windows.
This is on by default.
The opposite,
.IR !Maximizable ,
inhibits the window from being maximized.

.IR AllowMaximizeFixedSize
enables the function
.I Maximize
to be performed on windows that are not resizable, unless maximisation
has been disabled either using the style
.I Unmaximizable
or throuth WM hints,
This on by default.
The opposite,
.IR !AllowMaximizeFixedSize ,
inibits all windows that are not resizable from being maximized.

.I ResizeHintOverride
instructs fvwm to ignore the program supplied minimum and maximum
size.  This can be handy for broken applications that refuse to be
resized.  Don't use it if you don't need it.  The default
(opposite) style is
.I NoResizeOverride.

.I MaxWindowSize " [ width [ p ]  height [ p ] ]"
Tells fvwm the maximum width and height of a window.  The values
are the percentage of the total screen area.  If the letter
.RI ' p '
is appended to either of the values, the numbers are interpreted
as pixels. This command is useful to force large application
windows to be fully visible.  Neither
.IR height " nor " width
may be less than 100 pixels.  If you omit the parameters or their
values are invalid, both limits are set to 32767 pixels (which is
the default).

With
.I IconifyWindowGroups
all windows in the same window group are iconified at once when
group leader is iconified.  The default is
.IR IconifyWindowGroupsOff ,
which disables this behavior.  Although a number of applications
use the window group hint, it is rarely used in a proper way, so
it is probably best to use
.I IconifyWindowGroups
only for selected applications.

.\" +++++++++++++++ Window Manager placement
.TP
.B Window Manager placement
Applications can place windows at a particular spot on the screen
either by window manager hints or a geometry specification.  When
they do neither, then the window manager steps in to find a place
for the window.  Fvwm knows six ways to deal with this
situation. The default is
.IR TileCascadePlacement .

.I CenterPlacement
automatically places new windows in the center of the display.

.I CascadePlacement
automatically place new windows in a cascading fashion.

.I TileCascadePlacement
automatically places new windows in a smart location - a location
in which they do not overlap any other windows on the screen.  If
no such position can be found
.IR CascadePlacement
is used as a fall-back method.

.I TileManualPlacement
This is the same as
.IR TileCascadePlacement ,
but uses
.IR ManualPlacement
as the fall-back method.

.I MinOverlapPlacement
automatically places new windows in a location in which the
overlapping area in pixels of other windows is minimized.
By default this placement policy tries to avoid
overlapping icons and windows on higher layers.
This can be configured with the
.IR MinOverlapPlacementPenalties
style.

.I MinOverlapPercentPlacement
is similar to
.IR MinOverlapPlacement
but tries to minimize the overlapped percentages of other windows
instead of the overlapped area in pixels.  This placement policy
tries to avoid covering other windows completely and tries even
harder not to cover small windows.
This can be configured with the
.I MinOverlapPlacementPenalties
and
.I MinOverlapPercentPlacementPenalties
styles.

.I MinOverlapPlacementPenalties
takes at most 6 positive or null decimal arguments:
.EX
.I normal ontop icon sticky below strut
.EE
if trailing arguments are missing
the default is used which is:
.EX
1 5 10 1 0.05 50
.EE
This style configures the
.IR MinOverlapPlacement " and " MinOverlapPercentPlacement
placement policy.
The
.I normal
factor affects normal windows, the
.I ontop
factor affects windows with a greater layer than the window being
placed, the
.I icon
factor affects icons, the
.I sticky
factor affects sticky windows, the
.I below
factor affects windows with a smaller layer than the window being
placed, the
.I strut
factor affects the complement of the EWMH working area if the
window being placed has the
.I EWMHPlacementUseWorkingArea
style and windows with an EWMH strut hint (i.e., a "please don't
not cover me" hint) if the window being placed has the
.I EWMHPlacementUseDynamicWorkingArea
style.  These factors represent the amount of area that these
types of windows (or area) are counted as, when a new window is
placed.  For example, by default the area of ontop windows is
counted 5 times as much as normal windows.  So
.IR MinOverlapPlacement " and "  MinOverlapPercentPlacement
will cover 5 times as much area of another window before it will
cover an ontop window.  To treat ontop windows the same as other
windows, set this to 1.  To really, really avoid putting windows
under ontop windows, set this to a high value, say 1000. This
style affects the window already mapped and not the window which
is currently placed. There is one exception to this rule: in the
case of the window being placed has the
.I EWMHPlacementUseWorkingArea
style the
.I strut
factor affects the placed window.

.I MinOverlapPercentPlacementPenalties
takes at most 4 positive or null integer arguments:
.EX
.I cover_100 cover_95 cover_85 cover_75
.EE
if trailing arguments are missing the defaults are used
which are:
.EX
12 6 4 1
.EE
This style affects the
.I MinOverlapPercentPlacement
placement policy and is similar to the
.I MinOverlapPlacementPenalties
style. The
.I cover_xx
factor is used when the window being placed covers at least
.I xx
percent of the window. This factor is added to the factor
determined by the
.IR MinOverlapPlacementPenalties
style.

.I ManualPlacement
(aka active placement). The user is required to place every new
window manually.  The window only shows as a rubber band until a
place is selected manually. The window is placed when a mouse
button or any key except
.SM Escape
is pressed.  Escape aborts manual placement which places the
window in the top left corner of the screen. If mouse button 2 is
pressed during the initial placement of a window (respectively
.SM Shift
and mouse button 1 in case Mwm emulation has been enabled with the
.B Emulate
command), the user is asked to resize the window too.  Pressing
button 3 sets the
.I PlacedByButton3
condition (see
.B Current
command).

Example:
.EX
Style * ManualPlacement

*FvwmEvent: PassID
*FvwmEvent: add_window GrowDownFunc
AddToFunc StartFunction
+ I FvwmEvent

AddToFunc GrowDownFunc
+ I windowid $0 (PlacedByButton3) \\
  Resize bottomright keep -0p
.EE

Now, whenever a window is created and the user presses button 3 to
finish initial placement, the window is automatically enlarged
until it hits the bottom screen border.

.I Old placement styles
DumbPlacement / SmartPlacement / SmartPlacementOff,
ActivePlacement / RandomPlacement,
ActivePlacementsHonorsStartsOnPage /
ActivePlacementsHonorsStartsOnPageOff, GlobalOpts
SmartPlacementIsReallySmart / GlobalOpts SmartPlacementIsNormal
are still supported but will be removed in the future. The old and
new styles can be translated according to the following table:
.EX
GlobalOpts SmartPlacementIsReallySmart
Style * SmartPlacement
  -->
Style * SmartPlacement, CleverPlacement

GlobalOpts SmartPlacementIsNormal
Style * SmartPlacement
  -->
Style * SmartPlacement, CleverPlacementOff

Style * DumbPlacement, RandomPlacement
  -->
Style * CascadePlacement

Style * DumbPlacement, ActivePlacement
  -->
Style * ManualPlacement

Style * SmartPlacement, \\
RandomPlacement, CleverPlacementOff
  -->
Style * TileCascadePlacement

Style * SmartPlacement, \\
ActivePlacement, CleverPlacementOff
  -->
Style * TileManualPlacement

Style * SmartPlacement, CleverPlacement
  -->
Style * MinOverlapPlacement

Style * SmartPlacement, \\
ActivePlacement, CleverPlacement
  -->
Style * MinOverlapPercentPlacement

Style * ActivePlacementsHonorsStartsOnPage
  -->
Style * ManualPlacementsHonorsStartsOnPage

Style * ActivePlacementsHonorsStartsOnPageOff
  -->
Style * ManualPlacementsHonorsStartsOnPageOff
.EE

.\" +++++++++++++++ placement options and stacking policy
.TP
.B Placement policy options and window stacking
.I NoPPosition
instructs fvwm to ignore the program specified position (PPosition
hint) when adding new windows.  Using PPosition is required for
some applications, but if you don't have one of those its a real
headache.  Many programs set PPosition to something obnoxious like
0,0 (upper left corner).

.I NoUSPosition
works like
.I NoPPosition
but applies suppresses using the user specified position indicated
by the program (USPosition hint).  It is generally a bad thing to
override the user's choice, but some applications misuse the
USPosition hint to force their windows to a certain spot on the
screen without the user's consent.

.IR NoTransientPPosition " and " UseTransientPPosition
work like
.IR NoPPosition " and " UsePPosition
but apply only to transient windows.

.I NoIconPosition
instructs fvwm to ignore the program specified icon position
(IconPosition hint) when iconifying the window.

.I StartsOnDesk
takes a numeric argument which is the desktop number on which the
window should be initially placed.  Note that standard Xt programs
can also specify this via a resource (e.g. "-xrm '*Desk: 1'").

.I StartsOnPage
takes 1, 2, or 3 numeric arguments.  If one or three arguments are
given, the first (or only) argument is the desktop number. If
three arguments are given, the 2nd and 3rd arguments identify the
x,y page position on the virtual window.  If two arguments are
given, they specify the page position, and indicate no desk
preference.  If only one argument is given,
.I StartsOnPage
functions exactly like
.IR StartsOnDesk .
For those standard Xt programs which understand this usage, the
starting desk/page can also be specified via a resource (e.g.,
"-xrm '*page: 1 0 2'").
.I StartsOnPage
in conjunction with
.I SkipMapping
is a useful technique when you want to start an app on some other
page and continue with what you were doing, rather than waiting
for it to appear.

.I StartsOnScreen
takes one argument.  It can be 'p' for the primary screen, 'c' for
the current screen (containing the mouse pointer), 'g' for the
global screen or the screen number itself (counting from zero).  A
new window is placed on the specified Xinerama screen.  The
default is to place windows on the screen that contains the mouse
pointer at the time the window is created.  However, those windows
which are not placed by fvwm (i.e., those with a USPosition hint
from a user specified geometry) are normally placed in a position
relative to the global screen.  The
.I StartsOnScreen
style is also useful to cause these windows to be placed relative
to a specific Xinerama screen.  For example:
.EX
Style * StartsOnScreen c
.EE
Would cause all windows, including those with their own geometry
to be placed relative to the current Xinerama screen rather than
the global screen.  For those standard Xt programs which
understand this usage, the starting desk/page can also be
specified via a resource (e.g., "-xrm '*fvwmscreen: c'").
('fvwmscreen' was chosen because some applications already use
\'.screen' for other purposes.)

.I StartsOnPageIncludesTransients
causes the
.I StartsOnPage
style to be applied even for transient windows.  This is not
usually useful, since transients are usually pop ups that you want
to appear in your visible viewport; but occasionally an
application uses a transient for something like a startup window
that needs to be coerced into place.

.I ManualPlacementIgnoresStartsOnPage
suppresses
.IR StartsOnPage " or " StartsOnDesk
placement in the event that both
.IR ManualPlacement " and " SkipMapping
are in effect when a window is created.  This prevents you from
interactively placing a window and then wondering where it
disappeared to, because it got placed on a different desk or page.
.I ManualPlacementHonorsStartsOnPage
allows this to happen anyway.  The option has no effect if
.I SkipMapping
is not in effect, because fvwm switches to the proper desk/page to
perform interactive placement.  The default is
.IR ManualPlacementIgnoresStartsOnPage "; "
.I ManualPlacementHonorsStartsOnPage
matches the way the old
.I StartsOnDesk
style used to handle the situation.

.I CaptureHonorsStartsOnPage
causes the initial capture (of an already existing window) at
startup to place the window according to the
.IR StartsOnPage " and " StartsOnScreen
desk, page and Xinerama screen specification.
.I CaptureIgnoresStartsOnPage
causes fvwm to ignore these settings (including
.IR StartsOnDesk )
on initial capture.  The default is
.IR CaptureIgnoresStartsOnPage .

.I RecaptureHonorsStartsOnPage
causes a window to be placed according to, or revert to, the
.IR StartsOnPage " and " StartsOnScreen
desk, page and Xinerama screen specification on
.BR Restart " or " Recapture .
.I RecaptureIgnoresStartsOnPage
causes fvwm to respect the current window position on
.BR Restart " or " Recapture .
The default is
.IR RecaptureIgnoresStartsOnPage .

.I Layer
accepts one optional argument: a non-negative integer.  This is
the layer the window is put in.  If no argument is given, any
previously set value is deleted and the default layer is implied.

.I StaysOnTop
puts the window in the top layer.  This layer can be changed by
the command
.BR DefaultLayers ;
the default is 6.

.I StaysPut
puts the window in the put layer.  This layer can be changed by
the command
.BR DefaultLayers ;
the default is 4.

.I StaysOnBottom
puts the window in the bottom layer.  This layer can be changed by
the command
.BR DefaultLayers ;
the default is 2.

.I StartsLowered
instructs fvwm to put the window initially at the bottom of its
layer rather than the default
.IR StartsRaised .

.I SkipMapping
tells fvwm not to switch to the desk the window is on when it gets
mapped initially (useful with
.IR StartsOnDesk " or " StartsOnPage ).

.I KeepWindowGroupsOnDesk
makes new windows that have the window group hint set appear on
the same desk as the other windows of the same group.  Since this
behavior may be confusing, the default setting is
.IR ScatterWindowGroups .
The window group hint is ignored when placing windows in this
case.

.\" +++++++++++++++ transient windows
.TP
.B Transient windows
.I DecorateTransient
causes transient windows, which are normally left undecorated, to
be given the usual fvwm decorations (title bar, buttons,
etc.). Note that some pop-up windows, such as the xterm menus, are
not managed by the window manager and still do not receive
decorations.
.I NakedTransient
(the default) causes transient windows not to be given the
standard decorations. You can only bind keys or mouse buttons to
the sides and the client window of an undecorated window ('S' and
\'W' contexts in bindings, see
.BR Mouse " and " Key
commands).

A window with the
.I RaiseTransient
style that has transient windows raises all its transients when it
is raised.  The
.I DontRaiseTransient
style disables this behavior.  All windows are then treated as if
they had no transients.

A window with the
.I LowerTransient
style that has transient windows lowers all its transients when it
is lowered.  The
.I DontLowerTransient
style disables this behavior.  All windows are then treated as if
they had no transients.

The
.I StackTransientParent
style augments
.IR RaiseTransient " and " LowerTransient
styles.  Raising a window with
.I StackTransientParent
style transfers the raise action to the main window if the window
being raised is a transient and its main window has
.I RaiseTransient
style; this effect makes raise on a transient act just like raise
on its main - the whole group is raised.  Similar behavior holds
for lowering a whole group of transients when the main has
.I LowerTransient
style.
.I DontStackTransientParent
turns this behavior off.
.I (Dont)StackTransientParent
has no effect if
.IR RaiseTransient " and " LowerTransient
are not used.

A reasonable emulation of Motif raise/lower on transients is
possible like this
.EX
Style * RaiseTransient
Style * LowerTransient
Style * StackTransientParent
.EE

.\" +++++++++++++++ Extended WM Hints styles
.TP
.B Extended Window Manager Hints styles
To understand the used terminology in this sub section, please
read the section
.BR "EXTENDED WINDOW MANAGER HINTS" .

.I EWMHDonateIcon
instructs fvwm to set the application ewmh icon hint with the icon
that is used by fvwm if the application does not provide such hint
(and if the icon used by fvwm is not an icon window).
.I EWMHDonateMiniIcon
does the same thing for mini icons. This allows compliant pager,
taskbar, iconbox ...etc to display the same (mini) icons as
fvwm. Note that on some hardware (e.g., 8-bit displays) these
styles can slow down window mapping and that in general only one
of these styles is needed by a compliant application.
.I EWMHDontDonateIcon
and
.I EWMHDontDonateMiniIcon
restore the defaults which are to not set any ewmh (mini) icons
hints.

By default, if an application provides an ewmh icon hint of small
size (i.e., height and width less than or equal to 22), then fvwm
uses this icon as its mini icon.
.I EWMHMiniIconOverride
instructs fvwm to ignore ewmh icons and to use the mini icon
provided by the
.I MiniIcon
style.
.I EWMHNoMiniIconOverride
restores the default.

.I EWMHUseStackingOrderHints
causes fvwm to use EWMH hints and respect EWMH hints which change
the window layer.
.I EWMHIgnoreStackingOrderHints
causes fvwm to ignore EWMH layer hints.

An application can ask for some reserved space on the desktop by a
hint.  In the EWMH terminology such a hint is called a strut and
it is used to compute the working area and may be used for window
placement and in the maximize command.
.I EWMHIgnoreStrutHints
causes fvwm to ignore such hints, as
.IR EWMHUseStrutHints ,
causes fvwm to use it which is the default.

.I EWMHIgnoreStateHints
causes fvwm to ignore initial EWMH state hints when a new window
is mapped. The default
.I EWMHUseStateHints
causes fvwm to accept such hints.

.I EWMHMaximizeIgnoreWorkingArea
causes fvwm to ignore the EWMH working area when it executes a
.I Maximize
command. With
.I EWMHMaximizeUseWorkingArea
the EWMH working area is used as with
.I EWMHMaximizeUseDynamicWorkingArea
the EWMH dynamic working area is used (the default).

.I EWMHPlacementIgnoreWorkingArea
causes fvwm to ignore the EWMH working area when it places (or
places again) a window. With
.I EWMHPlacementUseWorkingArea
the EWMH working area is taken in account as with
.I EWMHPlacementUseDynamicWorkingArea
the EWMH dynamic working area is taken in account (the default).
Note that with the
.IR MinOverlapPlacement " and " MinOverlapPercentPlacement
placement policy, the way the EWMH (dynamic) working area is taken
in account is configurable with the
.I MinOverlapPlacementPenalties
style.

.\" +++++++++++++++ miscellaneous
.TP
.B Miscellaneous
The
.IR BackingStore ", " BackingStoreOff " and " BackingStoreWindowDefault
determine if the X server uses backing store for the window or
not.
.I BackingStore
means that the X server tries to keep the obscured parts of a
window in memory.  This is usually slower if the client runs on
the same machine as the X server, but can be much faster if the
connection is slow (see also
.I SaveUnder
below).
.I BackingStoreOff
tells disables backing store for the window.  By default, fvwm
does not enable or disable backing store itself but leaves is as
the window requested it.  To revert back to the application's
choice, use the
.I BackingStoreWindowDefault
style.

Note: This style is useless if the X server does not allow backing
store.

.I SaveUnder
enables the corresponding window attribute in the X server.  For a
window using this style, the X server tries to store the graphics
below it in memory which is usually slower if the client runs on
the same machine as the X server.
.I SaveUnder
may speed up fvwm if the connection to the X server is slow
(e.g. over a modem link).  To disable backing store, use the
.I BackingStoreOff
style.  This is the default. See also
.I BackingStore
above.

Note: This style is useless if the X server does not allow save
under.

.I ParentalRelativity
enables clients that use a background pixmap of type
.IR ParentRelative
to achieve transparency. Fvwm modules that support transparent
colorsets require this setting.
.I Opacity
is the default and should be used for all non-transparent clients
for better performance.

.I MwmDecor
makes fvwm attempt to recognize and respect the mwm decoration
hints that applications occasionally use.  To switch this style
off, use the
.I NoDecorHint
style.

.I MwmFunctions
makes fvwm attempt to recognize and respect the mwm prohibited
operations hints that applications occasionally use.
.I HintOverride
makes fvwm shade out operations that mwm would prohibit, but it
lets you perform the operation anyway.
.I NoFuncHint
allows turns off the mwm hints completely.

.I OLDecor
makes fvwm attempt to recognize and respect the olwm and olvwm
hints that many older XView and OLIT applications use.  Switch
this option off with
.IR NoOLDecor .

With
.I GNOMEIgnoreHints
fvwm ignores all GNOME hints for the window, even if GNOME
compliance is compiled in.  This is useful for those pesky
applications that try to be more clever than the user and use
GNOME hints to force the window manager to ignore the user's
preferences.  The
.I GNOMEUseHints
style switches back to the default behavior.

.I UseDecor
This style is deprecated and will be removed in the future.  There
are plans to replace it with a more flexible solution in fvwm-3.0.

.I UseDecor
accepts one argument: the name of a decor created with
.BR AddToDecor .
If no decor name is specified, the "Default" decor is
used. Windows do not actually contain decors, but are always
assigned to one.  If the decor is later modified with
.BR AddToDecor ,
the changes are visible for all windows which are assigned to it.
The decor for a window can be reassigned with
.BR ChangeDecor .

.I UseStyle
This style is deprecated and will be removed in the future.  There
are plans to replace it with a more flexible solution in fvwm-3.0.

.I UseStyle
takes one arg, which is the name of another style.  That way you
can have unrelated window names easily inherit similar traits
without retyping.  For example:
.EX
  Style rxvt UseStyle XTerm
.EE
Warning: If a style is built from one or more parent styles and
the parent styles are changed, the derived style is not
modified. To achieve this you have to issue the
.I UseStyle
line again.

.I Unmanaged
Windows with the
.I Unmanaged
style option are ignored by fvwm.  They are not decorated, can not
be moved or resized, etc.  You probably want to use
.B Bugopts RaiseOverUnmanaged
too.  This option can be turned off with the
.IR !Unmanaged style .
However, windows that are already ignored at the time when the
option is set must be recaptured with the
.B Recapture
command in order to become managed.

.I State
sets the initial value of of one of the 32 user defined states
which are associated with each window.  The state number ranges
from 0 to 31 and must be given as an argument.  The states have no
meaning in fvwm, but they can be checked in conditional commands
like
.B Next
with the
.I State
condition and manipulated with the
.B State
command.
.EX
# turn on state 11 for xterms ...
Style xterm State 11
# ... but not for rxvts.
Style rxvt !State 11
.EE

.\" +++++++++++++++ styles affecting window selection

Windows with the
.I WindowListSkip
styles do not appear in the menu that is created with the
.B WindowList
command or the lists shown in several modules like
.BR FvwmIconMan " or " FvwmWinList .
In the modules, the style can usually be ignored with an option.
Please refer to the man pages of the module in question for
further information.  To disable this feature, use the default
style
.IR WindowListHit .

The styles
.IR CirculateSkip " and " CirculateHit
control wheter the window is considered by conditional commands,
for example
.BR Next ", " Prev " or " All .
Windows with
.IR CirculateSkip ,
are never selected by conditional commands.  However, the styles
can be overridden explicitly in the condition with the
.IR CirculateHit ", " CirculateHitIcon " or " CirculateHitShaded
conditions, and some conditional commands, e.g.
.B Current " and " All ,
do this by default.
The styles
.IR CirculateSkipIcon ", " CirculateHitIcon ,
.IR CirculateSkipShaded " and " CirculateHitShaded
work like
.IR CirculateSkip " and " CirculateHit
but apply only to iconic or shaded windows.
Note: if multiple ...Skip... options are combined, windows are
only selected if they match none of the given conditions.  So,
with
.EX
Style * CirculateSkipIcon, CirculateSkipShaded
.EE
only windows that are neither iconic nor shaded are selecte.
Note:  For historical reasons, the conditional commands understand
the names of these styles as condition names.  Take care no to
confuse them.

.\" +++++++++++++++ examples
.TP
.B Examples
.EX
# Change default fvwm behavior to no title-
# bars on windows! Also define a default icon.
Style *             NoTitle,               \\
                    Icon unknown1.xpm,     \\
                    BorderWidth 4,         \\
                    HandleWidth 5

# now, window specific changes:
Style Fvwm*       NoHandles, Sticky,       \\
                  WindowListSkip,          \\
                  BorderWidth 0
Style FvwmPager   StaysOnTop, BorderWidth 0
Style *lock       NoHandles, Sticky,       \\
                  StaysOnTop, WindowListSkip
Style xbiff       Sticky, WindowListSkip
Style FvwmButtons NoHandles, Sticky,       \\
                  WindowListSkip
Style sxpm        NoHandles

# Put title-bars back on xterms only!
Style xterm     Title, Color black/grey

Style rxvt        Icon term.xpm
Style xterm       Icon rterm.xpm
Style xcalc       Icon xcalc.xpm
Style xbiff       Icon mail1.xpm
Style xmh         Icon mail1.xpm,         \\
                    StartsOnDesk 2
Style xman        Icon xman.xpm
Style matlab      Icon math4.xpm,         \\
                    StartsOnDesk 3
Style xmag        Icon magnifying_glass2.xpm
Style xgraph      Icon graphs.xpm
Style FvwmButtons Icon toolbox.xpm
Style Maker       StartsOnDesk 1
Style signal      StartsOnDesk 3

# Fire up Netscape on the second desk, in the
# middle of my 3x3 virtual desktop, and don't
# bother me with it...
Style Netscape* SkipMapping,              \\
                StartsOnPage 1 1 1
.EE
Note that all properties for a window are or'ed together.  In the
above example "FvwmPager" gets the property
.I StaysOnTop
via an exact window name match but also gets
.IR NoHandles ", " Sticky " and " WindowListSkip
by a match to "Fvwm*".  It gets
.I NoTitle
by virtue of a match to "*".  If conflicting styles are specified
for a window, then the last style specified are used.

If the
.I NoIcon
attribute is set then the specified window simply disappears when
it is iconified.  The window can be recovered through the
window-list.  If
.I Icon
is set without an argument then the
.I NoIcon
attribute is cleared but no icon is specified.  An example which
allows only the FvwmPager module icon to exist:
.EX
Style * NoIcon
Style FvwmPager Icon
.EE

.TP
.BI "WindowStyle " "options"
sets attributes (styles) on the selected window. The
.I options
are exactly the same as for the
.B Style
command.

.SS OTHER COMMANDS CONTROLLING WINDOW STYLES

.TP
.B "AddButtonStyle \fIbutton\fP \
[\fIstate\fP\
] [\fIstyle\fP\
] [-- [!] \fIflag\fP \
...]"

Adds a button style to
.IR button .
.I button
can be a button number, or one of "All", "Left" or "Right".
.I state
can be "ActiveUp", "ActiveDown", "InactiveUp" or "InactiveDown",
or "Active" (the same as both "ActiveUp" and "ActiveDown")
or "Inactive" (the same as both "InactiveUp" and "InactiveDown")
or any of these 6 with "Toggled" prepended.
The "Active" states apply to the focussed window, the "Inactive"
ones apply to all other windows. The "Up" states apply to the
non pressed buttons, the "Down" ones apply to pressed buttons.
The "Toggled" prefix refers to maximized, shaded or sticky windows
that have the corresponding
.I MwmDecor...
button style set.
Additionally, the following shotcuts may be used: "AllNormal",
"AllToggled", "AllActive", "AllInactive", "AllUp", "AllDown".
They are actually different masks for 4 individual states from
8 total.  These are supported too: "AllActiveUp", "AllActiveDown",
"AllInactiveUp", "AllInactiveDown".

If
.I state
is omitted, then the style is added to every state.  If the
.IR style " and " flags
are enclosed in parentheses, then multiple
.I state
definitions can be placed on a single line.
.I Flags
for additional button styles cannot be changed after definition.

Buttons are drawn in the order of definition, beginning with the
most recent button style, followed by those added with
.BR AddButtonStyle .
To clear the button style stack, change style flags, or for
descriptions of available styles and flags, see the
.B ButtonStyle
command.  Examples:
.EX
ButtonStyle 1 Pixmap led.xpm -- Top Left
ButtonStyle 1 ActiveDown HGradient 8 grey \\
  black
ButtonStyle All --  UseTitleStyle
AddButtonStyle 1 ActiveUp (Pixmap a.xpm)  \\
  ActiveDown (Pixmap b.xpm -- Top)
AddButtonStyle 1 Vector 4 50x30@1 70x70@0 \\
  30x70@0 50x30@1
.EE
Initially for this example all button states are set to a pixmap.
The second line replaces the "ActiveDown" state with a gradient
(it overrides the pixmap assigned to it in the line before, which
assigned the same style to every state).  Then, the
.I UseTitleStyle
flag is set for all buttons, which causes fvwm to draw any styles
set with
.B TitleStyle
before drawing the buttons.  Finally,
.B AddButtonStyle
is used to place additional pixmaps for both "ActiveUp" and
"ActiveDown" states and a vector button style is drawn on top of
all state.

.TP
.B "AddTitleStyle [\fIstate\fP\
] [\fIstyle\fP\
] [-- [!] \fIflag\fP \
...]"
Adds a title style to the title-bar.
.I state
can be "ActiveUp", "ActiveDown", "InactiveUp" or "InactiveDown",
or "Active" (the same as both "ActiveUp" and "ActiveDown")
or "Inactive" (the same as both "InactiveUp" and "InactiveDown")
or any of these 6 with "Toggled" prepended.  If
.I state
is omitted, then the style is added to every state.  If the
.IR style " and " flags
are enclosed in parentheses, then multiple
.I state
definitions can be placed on a single line.  This command is quite
similar to the
.B AddButtonStyle
command (see above).

Title-bars are drawn in the order of definition, beginning with
the most recent
.BR TitleStyle ,
followed by those added with
.BR AddTitleStyle .
To clear the title style stack, change style flags, or for the
descriptions of available styles and flags, see the
.BR TitleStyle " and " ButtonStyle
commands.

.TP
.BI "AddToDecor " decor
This command is deprecated and will be removed in the future.  There
are plans to replace it with a more flexible solution in fvwm-3.0.

Add or divert commands to the decor named
.IR decor .
A decor is a name given to the set of commands which affect button
styles, title-bar styles and border styles.  If
.I decor
does not exist it is created; otherwise the existing
.I decor
is modified.  Note: Earlier versions allowed to use the
.BR HilightColor ", " HilightColorset " and " WindowFont
commands in decors.  This is no longer possible.  Please use the
.I Style
command with the
.IR Hilight... " and " Font
options.

New decors start out exactly like the "default" decor without any
style definitions.  A given decor may be applied to a set of
windows with the
.I UseDecor
option of the
.B Style
command.  Modifying an existing decor affects all windows which
are currently assigned to it.

.B AddToDecor
is similar in usage to the
.BR AddToMenu " and " AddToFunc
commands, except that menus and functions are replaced by
.BR ButtonStyle ", " AddButtonStyle ", " TitleStyle ,
.BR AddTitleStyle " and " BorderStyle
commands.  Decors created with
.B AddToDecor
can be manipulated with
.BR ChangeDecor ", " DestroyDecor ", " UpdateDecor
and the
.IB "UseDecor " Style
option.

The following example creates a decor "FlatDecor" and style
"FlatStyle".  They are distinct entities:
.EX
AddToDecor FlatDecor
+ ButtonStyle All \\
    Active   (-- flat) \\
    Inactive (-- flat)
+ TitleStyle  -- flat
+ BorderStyle -- HiddenHandles NoInset

Style FlatStyle \\
    UseDecor FlatDecor, HandleWidth 4, \\
    ForeColor   white, BackColor   grey40, \\
    HilightFore black, HilightBack grey70

Style xterm UseStyle FlatStyle
.EE
An existing window's decor may be reassigned with
.BR ChangeDecor .
A decor can be destroyed with
.BR DestroyDecor .
.EX
DestroyDecor FlatDecor
AddToDecor FlatDecor ...

Style FlatStyle UseDecor FlatDecor
.EE
and now apply the style again:
.EX
Style xterm UseStyle FlatStyle
.EE

.TP
.B "BorderStyle [\fIstate\fP\
] [\fIstyle\fP\
] [-- [!] \fIflag\fP \
...]"
Defines a border style for windows.
.I state
can be either "Active" or "Inactive".  If
.I state
is omitted, then the style is set for both states.  If the
.IR style " and " flags
are enclosed in parentheses, then multiple
.I state
definitions can be specified per line.

.I style
is a subset of the available button styles, and can only be
.I TiledPixmap
(uniform pixmaps which match the bevel colors work best this
way) or Colorset. If a
.RI ' ! '
is prefixed to any
.IR flag ,
the behavior is negated.  If
.I style
is not specified, then one can change flags without resetting the
style.

The
.I HiddenHandles
flag hides the corner handle dividing lines on windows with
handles (this option has no effect for NoHandle windows).  By
default,
.I HiddenHandles
is disabled.

The
.I NoInset
flag supplements
.IR HiddenHandles .
If given, the inner bevel around the window frame is not drawn.
If
.I HiddenHandles
is not specified, the frame looks a little strange.

.I Raised
causes a raised relief pattern to be drawn (default).
.I Sunk
causes a sunken relief pattern to be drawn.
.I Flat
inhibits the relief pattern from being drawn.

To decorate the active and inactive window borders with a textured
pixmap, one might specify:
.EX
BorderStyle Active TiledPixmap marble.xpm
BorderStyle Inactive TiledPixmap granite.xpm
BorderStyle Active -- HiddenHandles NoInset
.EE
To clear the style for both states:
.EX
BorderStyle Simple
.EE
To clear for a single state:
.EX
BorderStyle Active Simple
.EE
To unset a flag for a given state:
.EX
BorderStyle Inactive -- !NoInset
.EE
title-bar buttons can inherit the border style with the
.I UseBorderStyle
flag (see
.BR ButtonStyle ).

.TP
.B "ButtonState [\fIActiveDown\fP bool]\
 [\fIInactive\fP bool]\
 [\fIInactiveDown\fP bool]"
The
.B ButtonState
command controls which states of the window titles and title
buttons are used.  The default is to use all four states:
"ActiveUp", "ActiveDown", "InactiveUp" and "InactiveDown" (see
.BR ButtonStyle " and " TitleStyle
commands).  The
.I bool
argument after the key word controls if the designated state is
used ("True") or not ("False").  The "ActiveUp" state cannot be
deactivated. If no arguments are provided or the given arguments
are illegal, the default is restored.

If
.I ActiveDown
argument is "False", no different button style
for the pressed down buttons used, instead "ActiveUp" state is
used even when button is pressed.

If
.I Inactive
argument is "False", focused and unfocused windows
look similarly, the corresponding "Active" states are always used.

If
.I InactiveDown
argument is "False" (only applied when
.I Inactive
is "True"), the pressed titles and title buttons in non-focussed
windows are drawn using "InactiveUp" or "ActiveUp" states
depending on the values of the other key words.

.TP
.B "ButtonStyle \fIbutton\fP \
[\fIstate\fP\
] [\fIstyle\fP\
] [-- [!] \fIflag\fP \
...]"
Sets the button style for a title-bar button.
.I button
is the title-bar button number between 0 and 9, or one of "All",
"Left", "Right", or "Reset".  Button numbering is described in the
.B Mouse
command section.  If the
.IR style " and " flags
are enclosed in parentheses, then multiple
.I state
definitions can be specified per line.

.I state
refers to which button state should be set.  Button states are
defined as follows: "ActiveUp" and "ActiveDown" refer to the
un-pressed and pressed states for buttons on active windows; while
the "InactiveUp" and "InactiveDown" states denote buttons on
inactive windows.  The shortcut "Active" denotes both "ActiveUp" and
"ActiveDown" states.  Shortcut "Inactive" denotes both "InactiveUp"
and "InactiveDown" states.
The similar state names like just described, but with the "Toggled"
prefix are used instead for title buttons which have one of the
.IR MwmDecorMax ", " MwmDecorShade ", " MwmDecorStick " or " MwmDecorLayer
hints, if the window is maximized, shaded or sticky, respectively.
.EX
AddToDecor Default
 + ButtonStyle 6                   \\
   Vector 4 50x25@1 85x75@0 15x75@0 50x25@1
 + ButtonStyle 6 ToggledActiveUp   \\
   Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
 + ButtonStyle 6 ToggledActiveDown \\
   Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
 + ButtonStyle 6 ToggledInactive   \\
   Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
 + ButtonStyle 6 - MwmDecorShade
Mouse 0 6 N WindowShade
.EE
Additionally, the following shotcuts may be used: "AllNormal",
"AllToggled", "AllActive", "AllInactive", "AllUp", "AllDown".
They are actually different masks for 4 individual states from
8 total.  These are supported too: "AllActiveUp", "AllActiveDown",
"AllInactiveUp", "AllInactiveDown".

If
.I state
is specified,
that particular button state is set.  If
.I state
is omitted, every state is set.  Specifying a style destroys the
current style (use
.B AddButtonStyle
to avoid this).

If
.I style
is omitted, then state-dependent flags can be set for the primary
button style without destroying the current style.  Examples (each
line should be considered independent):
.EX
ButtonStyle Left -- flat
ButtonStyle All ActiveUp (-- flat) \\
  Inactive (-- flat)
.EE
The first line sets every state of the left buttons to flat, while
the second sets only the "ActiveUp" and "Inactive" states of every
button to flat (only flags are changed; the buttons' individual
styles are not changed).

If you want to reset all buttons to their defaults:
.EX
ButtonStyle Reset
.EE
To reset the "ActiveUp" button state of button 1 to the default:
.EX
ButtonStyle 1 ActiveUp Default
.EE
To reset all button states of button 1 to the default of
button number 2:
.EX
ButtonStyle 1 Default 2
.EE
For any button, multiple
.I state
definitions can be given on one line by enclosing the
.IR style " and " flags
in parentheses.  If only one definition per line is given the
parentheses can be omitted.

.I flags
affect the specified
.IR state .
If a
.RI ' ! '
is prefixed to any
.IR flag ,
its behavior is negated.  The available state-dependent flags for
all styles are described here (the
.B ButtonStyle
entry deals with state-independent flags).

.I Raised
causes a raised relief pattern to be drawn.

.I Sunk
causes a sunken relief pattern to be drawn.

.I Flat
inhibits the relief pattern from being drawn.

.I UseTitleStyle
causes the given button state to render the current title style
before rendering the buttons own styles.  The
.IR Raised ", " Flat " and " Sunk
.B TitleStyle
flags are ignored since they are redundant in this context.

.I UseBorderStyle
causes the button to inherit the decorated
.B BorderStyle
options.

.IR Raised ", " Sunk " and " Flat
are mutually exclusive, and can be specified for the initial
.B ButtonStyle
only.
.IR UseTitleStyle " and " UseBorderStyle
are also mutually exclusive (both can be off however).  The
default is
.I Raised
with both
.I UseBorderStyle " and " UseTitleStyle
left unset.

.I Important note
for the "ActiveDown" and "InactiveDown" states:  When a button is
pressed, the relief is inverted.  Because of this, to obtain the
raised look in "ActiveDown" or "InactiveDown" states you must
specify the opposite of the desired relief (i.e.
.I Sunk
for "ActiveDown" or "InactiveDown").  This behavior is consistent,
but may seem confusing at first.  The same applies to the
"Toggled" states.

Button styles are classified as non-destructive, partially
destructive, or fully destructive.  Non-destructive styles do not
affect the image. Partially destructive styles can obscure some or
all parts of the underlying image (i.e.
.IR Pixmap ).
Fully destructive styles obscure the entire underlying image (i.e.
.I Solid
or one of the
.I gradient
styles).  Thus, if stacking styles with
.BR AddButtonStyle " (or " AddTitleStyle
for title-bars), use care in sequencing styles to minimize redraw.

The available styles are:

.IR Simple ", " Default ", " Solid ", " Colorset ", " Vector ,
.IR ?Gradient ", " Pixmap ", " AdjustedPixmap ,
.IR ShrunkPixmap ", " StretchedPixmap ", " TiledPixmap ", " MiniIcon

The description of these styles and their arguments follow:

The
.I Simple
style does nothing.  There are no arguments, and this style is an
example of a non-destructive button style.

The
.I Default
style conditionally accepts one argument: a number which specifies
the default button number to load.  If the style command given is
.BR ButtonStyle " or " AddButtonStyle ,
the argument is optional (if given, it overrides the current button).
If a command other than
.BR ButtonStyle " or " AddButtonStyle
is used, the number must be specified.

The
.I Solid
style fills the button with a solid color.  The relief border
color is not affected.  The color is specified as a single
argument.  This style is fully destructive.

The
.IR Colorset " " cs " [" alpha "]"
style fills the button with the Colorset
.IR cs .
The optional
.I alpha
argument is a percentage between 0 and 100. It causes fvwm to
merge the colorset background onto the button using this
percentage. If the percentage is 0 the colorset background is
hidden and if it is 100 the colorset background is fully
applied. The default is 100. So, the destructivity depends on the
.I alpha
argument.

The
.I "Vector num"
.IB X [ offset p]x Y [ offset p]@ C " ..."
style draws a line pattern.  Since this is a standard button style,
the keyword
.I Vector
is optional,
.I num
is a number of point specifications of the form
.IB X [ offset p]x Y [ offset p]@ C " ..."
.IR X " and " Y
are point coordinates inside the button, given in percents
(from 0 to 100).  An optional absolute
.I offset
in pixels, can be given as "+<offset>p" for a positive or
"-<offset>p" for a negative offset.

.I C
specifies a line color (0 - the shadow color, 1 - the highlight
color, 2 - the background color, 3 - the foreground color, 4 -
only move the point, do not draw).  The first point color is not
used.  You can use up to 10000 points in a line pattern.  This
style is partially destructive.

The specification is a little cumbersome:
.EX
ButtonStyle 2 Vector 4 50x30@1 70x70@0 \\
  30x70@0 50x30@1
.EE
then the button 2 decoration uses a 4-point pattern consisting of
a line from (x=50,y=30) to (70,70) in the shadow color (@0), and
then to (30,70) in the shadow color, and finally to (50,30) in the
highlight color (@1).  Is that too confusing?  See the fvwm web
pages for some examples with screenshots.

A more complex example of
.IR Vector :
.EX
ButtonStyle 8 Vector 10 45x65@2 45x75@3 \\
  20x75@3 20x50@3 35x50@3 35x65@1 35x25@1 \\
  75x25@1 75x65@0 35x65@0
ButtonStyle 0 Vector 10 45x65@2 45x75@0 \\
  20x75@0 20x50@1 45x50@1 45x65@0 75x65@3 \\
  75x25@3 35x25@3 35x47@3
.EE
The
.I ?Gradient
styles denote color gradients.  Fill in the question mark with any
one of the defined gradient types.  Please refer to the
.B COLOR GRADIENTS
section for a description of the gradient syntax.  The gradient
styles are fully destructive.

The
.I Pixmap
style displays a pixmap.  A pixmap should be specified as an
argument.  For example, the following would give button number 2
the same pixmap for all 4 states (2 active and 2 inactive), and
button number 4 all different pixmaps.
.EX
ButtonStyle 2 Pixmap my_pixmap.xpm
ButtonStyle 4 \\
  ActiveUp   (Pixmap activeup.xpm) \\
  ActiveDown (Pixmap activedown.xpm) \\
  Inactive   (Pixmap inactiveup.xpm)
ButtonStyle 4 \\
  InactiveDown Pixmap inactivedown.xpm
.EE
The pixmap specification can be given as an absolute or relative
pathname (see
.BR ImagePath ).
If the pixmap cannot be found, the button style reverts to
.IR Simple .
Flags specific to the
.I Pixmap
style are
.IR Left ", " Right ", "
.IR Top ", and " Bottom .
These can be used to justify the pixmap (default is centered for
both directions).  Pixmap transparency is used for the color
"None."  This style is partially destructive.

The
.I AdjustedPixmap
style is similar to the
.I Pixmap
style. But the image is resized to exactly fit the button.

The
.I ShrunkPixmap
style is similar to the
.I Pixmap
style. But if the image is bigger than the button the image is
resized to fit into the button.

The
.I StretchedPixmap
style is similar to the
.I Pixmap
style. But if the image is smaller than the button the image is
resized to cover the button.

The
.I TiledPixmap
style accepts a pixmap to be tiled as the button background. One
pixmap is specified as an argument.  Pixmap transparency is not
used.  This style is fully destructive.

The
.I MiniIcon
style draws the window's miniature icon in the button, which is
specified with the
.I MiniIcon
option of the
.B Style
command.  This button style accepts no arguments.  Example:
.EX
Style *     MiniIcon mini-bx2.xpm
Style xterm MiniIcon mini-term.xpm
Style Emacs MiniIcon mini-doc.xpm

ButtonStyle 1 MiniIcon
.EE


.TP
.BI "ButtonStyle " button " - [!]" flag " ..."
Sets state-independent flags for the specified
.IR button .
State-independent flags affect button behavior.  Each
.I flag
is separated by a space.  If a
.RI ' ! '
is prefixed to the flag then the behavior is negated.  The special
flag
.I Clear
clears any existing flags.

The following flags are usually used to tell fvwm which buttons
should be affected by mwm function hints (see
.I MwmFunctions
option of the
.B Style
command.  This is not done automatically since you might have
buttons bound to complex functions, for instance.

.I MwmDecorMenu
should be assigned to title-bar buttons which display a menu.  The
default assignment is the leftmost button.  When a window with the
.I MwmFunctions
.B Style
option requests not to show this button, it is hidden.

.I MwmDecorMin
should be assigned to title-bar buttons which minimize or iconify
the window.  The default assignment is the second button over from
the rightmost button.  When a window with the
.I MwmFunctions
.B Style
option requests not to show this button, it is hidden.

.I MwmDecorMax
should be assigned to title-bar buttons which maximize the
window. The default assignment is the rightmost button.  When a
window with the
.I MwmFunctions
.B Style
option requests not to show this button, it is hidden.  When the
window is maximized, the vector pattern on the button looks
pressed in.

.I MwmDecorShade
should be assigned to title-bar buttons which shade the window
(see
.B WindowShade
command).  When the window is shaded, the vector pattern on the
button looks pressed in.

.I MwmDecorStick
should be assigned to title-bar buttons which make the window
sticky. When the window is sticky, the vector pattern on the
button looks pressed in.

The flag
.IB "MwmDecorLayer " layer
should be assigned to title-bar buttons which place the window in
the layer numbered
.BR layer .
When the window is on that specific layer, the vector pattern on
the button looks pressed in.

.TP
.BI "ChangeDecor " decor
This command is deprecated and will be removed in the future.  There
are plans to replace it with a more flexible solution in fvwm-3.0.

Changes the decor of a window to
.IR decor .
.I decor
is "Default" or the name of a decor defined with
.BR AddToDecor .
If
.I decor
is invalid, nothing occurs.  If called from somewhere in a window
or its border, then that window is affected.  If called from the
root window the user is allowed to select the target window.
.B ChangeDecor
only affects attributes which can be set using the
.B AddToDecor
command.
.EX
ChangeDecor CustomDecor1
.EE

.TP
.BI "DestroyDecor [" recreate "] " decor
This command is deprecated and will be removed in the future.  There
are plans to replace it with a more flexible solution in fvwm-3.0.

Deletes the
.I decor
defined with
.BR AddToDecor ,
so that subsequent references to it are no longer valid.  Windows
using this
.I decor
revert to the "Default" decor. The optional parameter
.I recreate
tells fvwm not to throw away the decor completely but to throw
away only its contents. If the decor is created again later,
windows do not use it before the
.I UseDecor
style is applied again unless the decor was destroyed with the
.I recreate
option.  The decor named "Default" cannot be destroyed.
.EX
DestroyDecor CustomDecor1
.EE

.TP
.BI "TitleStyle [" justification "] [" Height " [" num "]] [" MinHeight " [" num "]]"
Sets attributes for the title-bar.  Justifications can be
.IR Centered ", " RightJustified " or " LeftJustified .
.I Height
sets the title bar's height to an amount in pixels.
.I MinHeight
sets the minimal height in pixels of the title bar's.
Defaults are
.IR Centered ,
the window's font height and no minimal height.
To reset the font height to the
default value, omit the
.I num
argument after the
.I Height
keyword. The
.I MinHeight
height is reseted by
.I Height
or if given with no argument.
is Example:
.EX
TitleStyle LeftJustified Height 24
.EE

.TP
.B "TitleStyle [\fIstate\fP\
] [\fIstyle\fP\
] [-- [!] \fIflag\fP \
...]"
Sets the style for the title-bar.
See also
.BR AddTitleStyle " and " ButtonStyle .
.I state
can be one of "ActiveUp", "ActiveDown", "InactiveUp",
or "InactiveDown".  Shortcuts like "Active" and "Inactive" are
allowed.  The states with the "Toggled" prefix are allowed too,
the title itself does not use "Toggled" states, but these states
are used for the buttons with
.B ButtonStyle
.IR UseTitleStyle .
If
.I state
is omitted, then the
.I style
is added to every state.  If parentheses are placed around the
.IR style " and " flags ,
then multiple state definitions can be given per line.
.I style
can be omitted so that flags can be set while not destroying the
current style.

If a
.RI ' ! '
is prefixed to any
.IR flag ,
its behavior is negated.  Valid flags for each state include
.IR Raised ", " Flat " and " Sunk
(these are mutually exclusive).  The default is
.IR Raised .
See the note in
.B ButtonStyle
regarding the "ActiveDown" state.  Examples:
.EX
TitleStyle ActiveUp HGradient 16 navy black
TitleStyle ActiveDown (Solid red -- flat) \\
    Inactive (TiledPixmap wood.xpm)
TitleStyle ActiveUp (-- Flat) ActiveDown  \\
    (-- Raised) InactiveUp (-- Flat) \\
    InactiveDown (-- Sunk)
.EE
This sets the "ActiveUp" state to a horizontal gradient, the
"ActiveDown" state to solid red, and the "Inactive" states to a
tiled wood pixmap. Finally, "ActiveUp" and "InactiveUp" are set
to look flat, while "ActiveDown" set to be sunk (the
.I Raised
flag for the "ActiveDown" state causes it to appear sunk due to
relief inversion), and "InactiveDown" is set to look raised. An
example which sets flags for all states:
.EX
TitleStyle -- flat
.EE
For a flattened look:
.EX
TitleStyle -- flat
ButtonStyle All Active (-- flat) Inactive (-- flat)
.EE

.B TitleStyle
accepts all the
.B ButtonStyle
 styles and arguments:

.IR Simple ", " Default ", " Solid ", " Colorset ", " Vector ,
.IR ?Gradient ", " Pixmap ", " AdjustedPixmap ,
.IR ShrunkPixmap ", " StretchedPixmap ", " TiledPixmap ", " MiniIcon  .

See the
.B ButtonStyle
command for a description of all these styles and their arguments.

In addition to these styles
.B TitleStyle
accepts a powerful
.B MultiPixmap
option. This allows you to specify different pixmaps, colorsets or
colors for different parts of the titlebar. Some of them are tiled or
stretched to fit a particular space; others are discrete "transition"
images. The definable
.I sections
are:
.EX
.I Main
  The full titlebar
.I LeftMain
  Left of title text
.I RightMain
  Right of title text
.I UnderText
  Underneath title text
.I LeftOfText
  just to the left of the title text
.I RightOfText
  just to the right of the title text
.I LeftEnd
  at the far left end of the titlebar
  (just after left buttons if any)
.I RightEnd
  at the far right end of the titlebar
  (just before right buttons if any)
.I Buttons
  under buttons in case of UseTitleStyle
.I LeftButtons
  under left buttons in case of UseTitleStyle
.I RightButtons
  under right buttons in case of UseTitleStyle
.EE
None of these are mandatory except for
.I Main
(or, if you don't define
.IR Main ,
you must define both
.IR LeftMain " and " RightMain ")."
If no
.I Buttons
pixmaps are defined and
.I UseTitleStyle
is specified for one or more buttons,
.IR Main ", " LeftMain ", or " RightMain
are used as appropriate.

The syntax for this style type is:
.EX
MultiPixmap section style arg, ...
.EE
continuing for whatever you want to define. The
.I style
can be either
.IR TiledPixmap ", " AdjustedPixmap ", " Colorset " or " Solid .
See the
.B ButtonStyle
command for the description of these styles.
In the case of a transition section,
.IR LeftEnd ", " LeftOfText ", " RightOfText " or " RightEnd ","
.I AdjustedPixmap
only resize the pixmap in the "y" direction. For the
.IR Colorset " and " Solid
styles a width of the half of the title bar height is assumed
for the transition sections.

An example:
.EX
MultiPixmap Main AdjustedPixmap foo.xpm, \\
            UnderText TiledPixmap bar.xpm, \\
            Buttons Colorset 2
.EE
Note that the old syntax is still supported: if the style is omitted,
.I TiledPixmap
is assumed and adding "(stretched)" between the section and the
file name implies
.IR AdjustedPixmap .

.TP
.BI "UpdateDecor " [ "decor" ]
This command is deprecated and will be removed in the future.  There
are plans to replace it with a more flexible solution in fvwm-3.0.

This command is kept mainly for backward compatibility.  Since
all elements of a decor are updated immediately when they are
changed, this command is mostly useless.

Updates window decorations.
.I decor
is an optional argument which specifies the
.I decor
to update.  If given, only windows which are assigned to that
particular
.I decor
are updated.  This command is useful, for instance, after a
.BR ButtonStyle ", " TitleStyle " or " BorderStyle
(possibly used in conjunction with
.BR AddToDecor ).
Specifying an invalid decor results in all windows being
updated.  This command is less disturbing than
.BR Recapture ,
but does not affect window style options as
.B Recapture
does.


.SS COMMANDS CONTROLLING THE VIRTUAL DESKTOP

.TP
.B "Desk \fIarg1\fP \
[\fIarg2\fP\
] [\fImin max\fP\
]"
This command has been renamed.  Please see
.B GotoDesk
command.

.TP
.BI "DesktopName " desk name
Defines the name of the desktop number
.I desk
to
.I name .
This name is used in the
.B WindowList
command and in the
.B FvwmPager
where it override the
.I Label
configuration option. Moreover, if consecutive names starting from
desktop 0 are defined, then these names can be used by any EWMH
compliant application (as a pager).

.TP
.BI "DeskTopSize " Horizontal x Vertical
Defines the virtual desktop size in units of the physical screen
size.

.TP
.BI "EdgeResistance " "scrolling moving " [ "xinerama-moving" ]
Tells how hard it should be to change the desktop viewport by
moving the mouse over the edge of the screen and how hard it
should be to move a window over the edge of the screen.

The first parameter tells how many milliseconds the pointer must
spend on the screen edge before fvwm moves the viewport.  This is
intended for people who use
.EX
EdgeScroll 100 100
.EE
but find themselves accidentally flipping pages when they don't
want to.

The second parameter tells how many pixels over the edge of the
screen a window's edge must move before it actually moves
partially off the screen.  By default the viewport is moved a full
page in the requested direction, but if you used
.B EdgeScroll
and set any values other than zero they is used instead.

Note that, with
.EX
EdgeScroll 0 0
.EE
it is still possible to move or resize windows across the edge of
the current screen.  By making the first parameter to
.B EdgeResistance
10000 this type of motion is impossible.  With
.B EdgeResistance
less than 10000 but greater than 0 moving over pages becomes
difficult but not impossible.  See also
.BR EdgeThickness .

The optional third parameter does the same as the second, but for
individual Xinerama screens.  If omitted,
.I xinerama-moving
will be set to the value of
.IR moving .
Set
.I xinerama-moving
to zero to ignore individual screen edges.  Note that the center of
the window being moved determines the xinarema screen on which the
window should be kept.

.TP
.BI "EdgeScroll " horizontal "[" p "] " vertical "[" p "]"
Specifies the percentage of a page to scroll when the cursor hits
the edge of a page.  A trailing
.RI ' p '
changes the interpretation to mean pixels.  If you don't want any
paging or scrolling when you hit the edge of a page include
.EX
EdgeScroll 0 0
.EE
in your
.I config
file, or possibly better, set the
.B EdgeThickness
to zero.  See the
.B EdgeThickness
command. If you want whole pages, use
.EX
EdgeScroll 100 100
.EE
Both
.IR horizontal " and " vertical
should be positive numbers.

If the
.IR horizontal " and " vertical
percentages are multiplied by 1000 then scrolling wraps around at
the edge of the desktop.  If
.EX
EdgeScroll 100000 100000
.EE
is used fvwm scrolls by whole pages, wrapping around at the edge
of the desktop.

.TP
.BI "EdgeThickness " 0 | 1 | 2
This is the width or height of the invisible window that fvwm
creates on the edges of the screen that are used for the edge
scrolling feature.

In order to enable page scrolling via the mouse, four windows
called the "pan frames" are placed at the very edge of the
screen. This is how fvwm detects the mouse's presence at the
window edge. Because of the way this works, they need to be at the
top of the stack and eat mouse events, so if you have any kind of
error along the lines of: "mouse clicks at the edge of the screen
do the wrong thing" you're having trouble with the pan frames and
(assuming you don't use the mouse to flip between pages) should
set the EdgeThickness to 0.

A value of
.I 0
completely disables mouse edge scrolling, even while dragging a
window.
.I 1
gives the smallest pan frames, which seem to work best except on
some servers.

.I 2
is the default.

Pan frames of
.IR 1 " or " 2
pixels can sometimes be confusing, for example, if you drag a
window over the edge of the screen, so that it straddles a pan
frame, clicks on the window, near the edge of the screen are
treated as clicks on the root window.

.TP
.BI "EwmhBaseStruts " left " " right " " top " " bottom
Where left, right, top and bottom are positive or null integers
which define bands at the edge of the screen.
.I left
defines a band on the left of your screen of width
.IR left ","
.I right
defines a band on the right of your screen of width
.IR right ","
.I top
defines a band on the top of your screen of height
.I top
and
.I bottom
defines a band on the bottom of your screen of height
.IR bottom "."
The unit is the pixel and the default is 0 0 0 0.  These areas
define additional reserved space to the reserved space defined by
some ewmh compliant applications. This is used to compute the
Working Area. See the
.B EXTENDED WINDOW MANAGER HINTS
section for a definition of the Working Area.

.TP
.BI "EWMHNumberOfDesktops " num "  [" max "]"
This command is useful only for an ewmh compliant pager or taskbar
(as kpager or kicker taskbar) and not for fvwm modules (FvwmPager
or FvwmIconMan). It causes a compliant application to consider at
least
.I num
desktops (desktop 0 to desktop
.IR num "-1)."
The optional argument
.I max
causes a compliant application to never consider more than
.I max
desktops. If
.I max
is 0 (the default) there is no limitation.  The actual number of
desktops is determined dynamically.  It is at least
.IR num ","
but it can be d if there is a window on desktop d-1 (or if the
current desktop is desktop d-1) and d is less or equal to
.I max
or
.I max
is null.
Moreover, a compliant pager can ask to change
.I num
itself.
This is accepted by fvwm only if this number is
less than or equal to
.I max
or if
.I max
is null.  Note that negative desktops are not supported by the
ewmh specification.  The default is 4 0.

.TP
.B "GotoDesk \fIprev\fP \
| \fIarg1\fP \
[\fIarg2\fP\
] [\fImin max\fP\
]"
Switches the current viewport to another desktop (workspace,
room).

The command takes 1, 2, 3, or 4 arguments.  A single argument is
interpreted as a relative desk number.  Two arguments are
understood as a relative and an absolute desk number.  Three
arguments specify a relative desk and the minimum and maximum of
the allowable range. Four arguments specify the relative,
absolute, minimum and maximum values.  (Desktop numbers can be
negative).  If a literal
.I prev
is given as the single argument, the last visited desk number is
used.

If
.I arg1
is non zero then the next desktop number is the current desktop
number plus
.IR arg1 .

If
.I arg1
is zero then the new desktop number is
.IR arg2 .
(If
.I arg2
is not present, then the command has no effect.)

If
.IR min " and " max
are given, the new desktop number is no smaller than
.I min
and no bigger than
.IR max .
Values out of this range are truncated (if you gave an absolute
desk number) or wrapped around (if you gave a relative desk
number).

The syntax is the same as for
.BR MoveToDesk ,
which moves a window to a different desktop.

The number of active desktops is determined dynamically.  Only
desktops which contain windows or are currently being displayed
are active.  Desktop numbers must be between 2147483647 and
-2147483648 (is that enough?).

.TP
.BI "GotoDeskAndPage " prev " | " "desk xpage ypage"
Switches the current viewport to another desktop and page, similar
to the
.BR GotoDesk " and " GotoPage
commands.  The new desk is
.I desk
and the new page is
.RI ( xpage , ypage ).

.TP
.B "GotoPage \fIprev\fP \
| [\fIoptions\fP] \
\fIx\fP \
[\fIp\fP\
] \fIy\fP \
[\fIp\fP\
]"
Moves the desktop viewport to page (x,y).  The upper left page is
(0,0), the upper right is (M,0), where M is one less than the
current number of horizontal pages specified in the
.B DeskTopSize
command.  The lower left page is (0,N), and the lower right page
is (M,N), where N is the desktop's vertical size as specified in
the
.B DeskTopSize
command.  To switch to a page relative to the current one add a
trailing
.RI ' p '
after any or both numerical arguments.

Possible
.I options
are
.IR wrapx " and " wrapy
to wrap around the x or y coordinate when the viewport is moved
beyond the border of the desktop.

To go to the last visited page use
.I prev
as the first argument.  The
.B GotoPage
function should not be used in a pop-up menu.

Examples:
.EX
# Go to page (2,3)
GotoPage 2 3

# Go to lowest and rightmost page
GotoPage -1 -1

# Go to last page visited
GotoPage prev

# Go two pages to the right and one page up
GotoPage +2p -1p
.EE

.TP
.B "Scroll \fIhorizonal\fP \
[\fIp\fP\
] \fIvertical\fP \
[\fIp\fP\
]"
Scrolls the virtual desktop's viewport by
.I horizontal
pages in the x-direction and
.I vertical
pages in the y-direction.  Either or both entries may be negative.
Both
.IR horizontal " and " vertical
values are expressed in percent of pages, so
.EX
Scroll 100 100
.EE
means to scroll down and left by one full page.
.EX
Scroll 50 25
.EE
means to scroll left half a page and down a quarter of a page.
The
.B Scroll
function should not be called from pop-up menus.  Normally,
scrolling stops at the edge of the desktop.

If the
.IR horizontal " and " vertical
percentages are multiplied by 1000 then scrolling wraps around at
the edge of the desktop.  If
.EX
Scroll 100000 0
.EE
is executed over and over fvwm moves to the next desktop page on
each execution and wraps around at the edge of the desktop, so
that every page is hit in turn.

If the letter
.RI ' p '
is appended to each coordinate
.RI ( horizontal " and/or " vertical ),
then the scroll amount is measured in pixels.

.TP
.BI "Xinerama " bool
Enables Xinerama support if the boolean argument is true and
disables it if the argument is false.  Calling this command
without arguments turns on Xinerama support it was disabled before
and turns it off if it was enabled.  For example:
.EX
# Turn Xinerama support on, use primary screen 2
XineramaPrimaryScreen 2
Xinerama on
#Turn it off again
Xinerama off
.EE

.TP
.BI "XineramaPrimaryScreen [" primary-screen "]"
Takes an integer number or 'g' or 'c' as its argument.  A number
is taken as the number of the Xinerama screen that is to be used
as the primary screen.  The primary screen can be used as the
preferred screen to place windows with
.EX
XineramaPrimaryScreen <screen number>
Style * StartsOnScreen p
.EE
The primary screen is used in some of the modules and for the
default icon box too.  Any number that is zero or more is taken as
the primary screen's number.  Instead, the letter 'c' indicates to
use the current screen (containing the pointer) whenever the
primary screen is used.  This may be very confusing under some
circumstances.  With \'g', the global screen is used as the primary
screen, effectively disabling the primary screen.  Calling this
function with any other argument (including none) resets the
primary screen to 0.

.TP
.BI "XineramaSls [" bool "]"
For multi-screen implementations other than Xinerama, such as
Single Logical Screen, it is possible to simulate a Xinerama
configuration if the total screen seen by fvwm is made up of
equal sized monitors in a rectangular grid.  The
.B XineramaSls
command turns SLS support on or off or toggles it to the opposite
state, depending on if the boolean argument is "True", "False" or
"toggle".  If no argument is given, this is treated like "toggle".
The default layout uses 1 by one screens.  To configure the
layout, use the
.BR XineramaSlsSize " or " XineramaSlsScreens
command.

.TP
.BI "XineramaSlsSize " Horizontal x Vertical
This command configures the layout of the Single Logical screen
feature.  It takes two arguments,
.IR Horizontal " and " Vertical
which must be an integer value dividing evenly into the total
desktop width, and height height.  For an example with two
monitors side by side which appear as one screen through the
X-Server with the right screen as the primary screen, use:
.EX
XineramaSlsSize 2x1
XineramaSlsOn
XineramaPrimaryScreen 1
XineramaOn
.EE

.TP
.BI "XineramaSlsScreens " "number-of-screens screen-spec ..."
This command configures the layout of the Single Logical screen
feature.  Its first argument is the number of screens to use.  It
must be followed by exactly this number of
.I screen-spec
arguments.  Each of these can be written either in standard X
geometry format: "<width>x<height>+<x>+<y>" or as a space separated
list of numbers: "x y width height". Both ways of describing
screens can be mixed in a single command.  All four numbers must
be supplied.  The
.IR x and y
values specify the origin of the screen in relation to the global
screen's origin while
.IR width and height
specify the size of the screen in pixels.  No checks are done if
the geometries make sense, so it is possible to define overlapping
screens (with random results) or screens that are not visible at
all.
.EX
XineramaSlsScreens 3 \\
  512x768+0+0 512x300+512+0 512 300 512 468
XineramaSlsOn
XineramaPrimaryScreen 1
XineramaOn
.EE


.SS COMMANDS FOR USER FUNCTIONS AND SHELL COMMANDS

.TP
.B "AddToFunc [\fIname\fP \
[\fII\fP \
| \fIM\fP \
| \fIC\fP \
| \fIH\fP \
| \fID action\fP\
]]"
Begins or adds to a function definition.  Here is an example:
.EX
AddToFunc Move-or-Raise I Raise
 + M Move
 + D Lower
.EE
The function name is "Move-or-Raise", and could be invoked from a
menu or a mouse binding or key binding:
.EX
Mouse 1 TS A Move-or-Raise
.EE
The
.I name
must not contain embedded whitespace.  No guarantees are made
whether function names with embedded whitespace work or not.  This
behavior may also change in the future without further notice.
The letter before the
.I action
tells what kind of action triggers the command which follows it.
.RI ' I '
stands for "Immediate", and is executed as soon as the function is
invoked.
.RI ' M '
stands for "Motion", i.e. if the user starts moving the mouse.
.RI ' C '
stands for "Click", i.e., if the user presses and releases the
mouse.
.RI ' H '
stands for "Hold", i.e. if the user presses a mouse button and
holds it down for more than
.B ClickTime
milliseconds.
.RI ' D '
stands for "Double-click". The action
.RI ' I '
causes an action to be performed on the button-press, if the
function is invoked with prior knowledge of which window to act
on.

There is a number of predefined symbols that are replaced by
certain values if they appear on the command line.  Please refer
to the
.B COMMAND EXPANSION
section for details.

Warning:  Please read the comments on executing complex functions
in the section
.BR "SCRIPTING AND COMPLEX FUNCTIONS" .

Examples:

If you call
.EX
Key F10 R A Function MailFunction \\
  xmh "-font fixed"
.EE
and "MailFunction" is
.EX
AddToFunc MailFunction
 + I Next ($0) Iconify off
 + I Next (AcceptsFocus, $0) focus
 + I None ($0) Exec exec $0 $1
.EE
Then the last line of the function becomes
.EX
 + I None (xmh) Exec exec xmh -font fixed
.EE
The expansion is performed as the function is executed, so you can
use the same function with all sorts of different arguments.  You
could use
.EX
Key F11 R A Function MailFunction \\
  zmail "-bg pink"
.EE
in the same
.IR config ,
if you wanted.  An example of using "$[w.id]" is:
.EX
AddToFunc PrintFunction
 + I Raise
 + I Exec xdpr -id $[w.id]
.EE
Note that "$$" is expanded to '$'.

Another example: bind right mouse button within the window button
number 6 (this is a minimize button for the win95 theme) to
iconify all windows of the same resource:
.EX
AddToFunc FuncIconifySameResource "I" \\
  All ($r) Iconify on
Mouse 3 6 A FuncIconifySameResource
.EE

.TP
.BI "Beep"
As might be expected, this makes the terminal beep.

.TP
.BI "DestroyFunc " function
Deletes a function, so that subsequent references to it are no
longer valid.  You can use this to change the contents of a
function during a fvwm session.  The function can be rebuilt using
.BR AddToFunc .
.EX
DestroyFunc PrintFunction
.EE

.TP
.BI "Echo " string
Prints a message to
.IR stderr .
Potentially useful for debugging things in your
.IR config .
.EX
Echo Beginning style definitions...
.EE

.TP
.BI "Exec " command
Executes
.IR command .
You should not use an ampersand '&' at the end of the command. You
probably want to use an additional "exec" at the beginning of
.IR command .
Without that, the shell that fvwm invokes to run your command
stays until the command exits.  In effect, you'll have twice as
many processes running as you need.  Note that some shells are
smart enough to avoid this, but it never hurts to include the
"exec" anyway.

The following example binds function key
.SM F1
in the root window, with no modifiers, to the exec function. The
program rxvt is started with an assortment of options.

.EX
Key F1 R N Exec exec rxvt -fg yellow -bg blue \\
  -e /bin/tcsh
.EE
Note that this function doesn't wait for
.I command
to complete, so things like:
.EX
Exec "echo AddToMenu ... > /tmp/file"
Read /tmp/file
.EE
do not work reliably
(see the
.I PipeRead
command).


.TP
.BI "ExecUseShell [" shell "]"
Makes the
.B Exec
command use the specified shell, or the value of the
.I $SHELL
environment variable if no shell is specified, instead of the
default Bourne shell
.RI ( /bin/sh ).
.EX
ExecUseShell
ExecUseShell /usr/local/bin/tcsh
.EE

.TP
.BI "Function " FunctionName
Used to bind a previously defined function to a key or mouse
button. The following example binds mouse button 1 to a function
called "Move-or-Raise", whose definition was provided as an
example earlier in this man page.  After performing this binding
fvwm executes the "move-or-raise" function whenever button 1 is
pressed in a window's title-bar.
.EX
Mouse 1 T A Function Move-or-Raise
.EE
The keyword
.B Function
may be omitted if
.I FunctionName
does not coincide with an fvwm command.

Warning:  Please read the comments on executing complex functions
in the section
.BR "SCRIPTING AND COMPLEX FUNCTIONS" .

.TP
.BI "Nop"
Does nothing.  This is used to insert a blank line or separator in
a menu.  If the menu item specification is
.EX
AddToMenu MyMenu " " Nop
.EE
then a blank line is inserted.  If it looks like
.EX
+ "" Nop
.EE
then a separator line is inserted.  Can also be used as the
double-click action for
.BR Menu " or " Popup .

.TP
.BI "PipeRead " command " [" quiet "]"
Causes fvwm to read commands from the output of the
.IR command .
This
.I command
is executed by
.I /bin/sh
as if you typed it on the command line.  If the command consists
of more than one word it must be quoted.  Useful for building up
dynamic menu entries based on a directories contents, for
example. If the keyword
.I Quiet
follows the command no message is produced if the
.I command
is not found.

Example:
.EX
AddToMenu HomeDirMenu
PipeRead 'for i in $HOME/*; \\
  do echo "+ $i Exec xterm -e vi $i"; done'
.EE

Note: The
.B PipeRead
changes the pointer to a watch cursor by default during
execution.  However, some commands, for example xwd, need to take
control of the pointer themselves and do not work.  To disable the
watch cursor, use the command prior to
.B PipeRead
.EX
BusyCursor Read off
.EE

The
.B PipeRead
command executes synchronously.  If you want to
.B Exec
something, but need the command to run synchronously,
you might do something like:
.EX
PipeRead 'command 1>&2'
.EE
The redirection causes any output from the program to go to stderr
instead of being read as a sequence of commands by fvwm.
.B PipeRead
returns 1 if the given command could be executed or -1 if not
(see the section
.B CONDITIONAL COMMANDS
for the meaning of return codes).

.TP
.BI "Read " filename " [" quiet "]"
Causes fvwm to read commands from the file named
.IR filename .
If the keyword
.I Quiet
follows the command no message is produced if the file is not
found.  If the file name does not begin with a slash ('/'), fvwm
looks in the user's data directory, then the system data
directory.  The user's data directory is by default
.IR $HOME/.fvwm .
It can be overridden by exporting
.I FVWM_USERDIR
set to any other directory.  The
.B Read
command returns 1 if the given file could be read or -1 if not
(see the section
.B CONDITIONAL COMMANDS
for the meaning of return codes).


.TP
.BI "SetEnv " "variable value"
Set an environment variable to a new value, similar to the shell's
export or setenv command.  The
.I variable
and its
.I value
are inherited by processes started directly by fvwm.  This can be
especially useful in conjunction with the
.B FvwmM4
module.  For example:
.EX
SetEnv height HEIGHT
.EE
makes the FvwmM4-set variable
.I HEIGHT
usable by processes started by fvwm as the environment variable
.IR $height .
If
.I value
includes whitespace, you should enclose it in quotes.  If no
.I value
is given, the variable is deleted.

.TP
.BI "Silent " command
A number of commands require a window to operate on.  If
no window was selected when such a function is invoked the user is
asked to select a window.  Sometimes this behavior is unwanted,
for example if the function was called by a module and the window
that was selected at first does not exist anymore.  You can
prevent this by putting
.B Silent
in front of the fvwm
.IR command .
If a function that needs a window is called with
.B Silent
without a window selected, it simply returns without doing
anything. If
.B Silent
is used on a user defined function it affects all function and sub
function calls until the original function exits.

Another usage of
.B Silent
is with binding commands
.BR Key ", " PointerKey " and " Mouse ,
this disables error messages.

.B Silent
also disables the error message for non-existent commands.  Note:
This command is treated as a prefix to its
.IR command .
Expansion of the command line is done as if
.B Silent
was not there.

Examples:
.EX
Silent Move 0 0
Silent User_defined_function
# don't complain on keyboards without "Help" key
Silent Key Help R A Popup HelpMenu
.EE

.TP
.BI "UnsetEnv " "variable"
Unset an environment variable, similar to shell's export or
unsetenv command. The
.I variable
then is removed from the environment array inherited by processes
started directly by fvwm.

.TP
.BI "Wait " windowname
This command is intended to be used in fvwm functions only.  It
causes execution of a function to pause until a new window with
the title
.I windowname
appears.  This is particularly useful in the "InitFunction" if you
are trying to start windows on specific desktops:
.EX
AddToFunc InitFunction
 + I exec xterm -geometry 80x64+0+0
 + I Wait xterm
 + I Desk 0 2
 + I Exec exec xmh -font fixed -geometry \\
       507x750+0+0
 + I Wait xmh
 + I Desk 0 0
.EE
The above function starts an xterm on the current desk, waits for
it to map itself, then switches to desk 2 and starts an xmh.
After the xmh window appears control moves to desk 0.

Fvwm remains partially functional during a wait, but any input
from the modules is queued up and processed only after the window
appears or the command is aborted.  For example, windows can not
be focused with FvwmTaskBar or FvwmWinList during a wait.

You can escape from a
.B Wait
pause by pressing
.SM Ctrl-Alt-Escape
(where
.SM Alt
is the first modifier).  To redefine this key sequence see the
.B EscapeFunc
command.


.SS CONDITIONAL COMMANDS

Conditional command are command that are only executed if certain
conditions are met.  Most conditional commands work on windows,
like
.BR Next ", " ThisWindow " or " All .
There is one conditional command
.B Test
that works on global conditions unrelated to windows.  The syntax
of the conditions is described below.  For readability, the list
of conditions is located at the end of this section.

.SS Return Codes

All commands in this section (unless specifically stated for the
command) also have a return code that can be 1 (if the condition
was met) or 0 (if the condition was not met).  Some commands may
return -1 which means that an error occurred and the return code
is useless.  The
.B Break
command returns -2.  Additionally, the return codes of commands
run in a complex functions are passed to the invoking complex
function.  The return code is used by the
.B TestRc
command.  Please refer to the commands' description for examples.
The return code can also be accessed through the variable
.IR $[cond.rc] .
Non conditional commands do not modify the return code of the last
conditional command.  Important note:  return codes are only
defined inside functions created with the
.B AddToFunc
command and are not inherited by sub functions.  To run a command
without altering the return code, the
.B KeepRc
command can be used.

.SS The Ring of Windows

Fvwm stores windows in a ring internally.  Think of the focused
window as a cursor on the current position in the ring.  The
.B Next
command and many other command searche forwards through the ring
for a matching window, and
.B Prev
searches backwards.  The windows in the ring are either ordered by
creation time (if the
.I FPSortWindowlistByFocus
respecively
.IR NeverFocus " or " MouseFocus
styles are used) or by the last time they had the focus.

.SS List of Conditional Commands

.TP
.BI "All [(" conditions ")] " command
Execute
.I command
on all windows meeting the conditions.  It returns 1 if any window
matches the condition and 0 otherwise.
.RB "See " Conditions " section below for a list of conditions."

This command implies the conditions
.IR CirculateHit ", " CirculateHitIcon " and " CirculateHitShaded .
They can be turned off by specifying
.I !CirculateHit
etc. explicitly.

.TP
.BI "Any [(" conditions ")] " command
Performs
.I command
if any window which satisfies all
.I conditions
exists.  The command is run in the context of the root window.
.RB "See " Conditions " section below for a list of conditions."

.TP
.BI "Break [levels]"
If the break command is used in a function, function execution is
terminated immediately.  Further commands of the function are not
processed.  Normally, all nested invocations of complex functions
are left.  An optional integer number
.I levels
may be given to break out of the given number of nested function
and continue execution of a higher level function.
The
.B Break
command always has the return code -2.  Example:
.EX
AddToFunc PickWindowRaiseAndDeiconify
+ I Pick
+ I TestRc (Error) Break
+ I Raise
+ I Iconify off
.EE

.TP
.BI "Current [(" conditions ")] " command
Performs
.I command
on the currently focused window if it satisfies all
.IR conditions .
.RB "See " Conditions " section below for a list of conditions."

This command implies the conditions
.IR CirculateHit ", " CirculateHitIcon " and " CirculateHitShaded .
They can be turned off by specifying
.I !CirculateHit
etc. explicitly.

.TP
.B "Direction \
[\fIFromPointer\fP] \
\fIdirection\fP \
[(\fIconditions\fP)] \
\fIcommand\fP"
Performs
.I command
(typically
.BR Focus )
on a window in the given direction which satisfies all
.IR conditions .
Normally, the center of the currently focused window or the
context window in which the command was invoked is taken as the
starting point.  Lacking such a window, or when the
.I FromPointer
option is given, the current position of the pointer is taken as
the starting point.  The
.I direction
may be one of "North", "Northeast", "East", "Southeast", "South",
"Southwest", "West", "Northwest" and "Center".  Which window
.B Direction
selects depends on angle and distance between the center points of
the windows.  Closer windows are considered a better match than
those farther away.  The
.I Center
direction simply selects the window closest to the starting point.
Returns -1 if an invalid direction was given.
.RB "See " Conditions " section below for a list of conditions."

.TP
.BI "KeepRc " command
Runs the
.I command
but does not alter the return code of the previous command.  Note:
.B KeepRc
is treated as a prefix to its
.IR command .
Expansion of the command line is done as if
.B KeepRc
was not there.

.TP
.BI "Next [(" conditions ")] " command
Performs
.I command
(typically
.BR Focus )
on the next window which satisfies all
.IR conditions .
If the command is running in a window context, it starts looking
for a matching window from there.  Otherwise it starts at the
focused window.
.RB "See " Conditions " section below for a list of conditions."

.TP
.BI "None [(" conditions ")] " command
Performs
.I command
if no window which satisfies all
.I conditions
exists.  The command is run in the context of the root window.
Returns 1 if no window matches the conditions and 0 otherwise.
.RB "See " Conditions " section below for a list of conditions."

This command implies the conditions
.IR CirculateHit ", " CirculateHitIcon " and " CirculateHitShaded .
They can be turned off by specifying
.I !CirculateHit
etc. explicitly.

.TP
.BI NoWindow " command"
Performs
.IR command ,
but removes the window context if any.  This is not really a
conditional command, but a prefix that may be useful in menu items
that should operate without a window even if such menu is bound to
window decorations.

.TP
.BI "Pick [(" conditions ")] " command
.B Pick
works like
.B Function
if invoked in the context of a window.  If invoked in the root
window, it first asks the user to pick a window and then executes
the
.I command
in the context of that window.  This avoids annoying multiple
selections with complex functions.  The command is executed only
if the given
.I conditions
are met.  Returns -1 if no window was selected.
.RB "See " Conditions " section below for a list of conditions."

This command implies the conditions
.IR CirculateHit ", " CirculateHitIcon " and " CirculateHitShaded .
They can be turned off by specifying
.I !CirculateHit
etc. explicitly.

.TP
.BI "PointerWindow [(" conditions ")] " command
Performs
.I command
if the window under the pointer satisfies all
.IR conditions .
Returns -1 if there is no window under the pointer.
.RB "See " Conditions " section below for a list of conditions."

This command implies the conditions
.IR CirculateHit ", " CirculateHitIcon " and " CirculateHitShaded .
They can be turned off by specifying
.I !CirculateHit
etc. explicitly.

.TP
.BI "Prev [(" conditions ")] " command
Performs
.I command
(typically
.BR Focus )
on the previous window which satisfies all
.IR conditions .
If the command is running in a window context, it starts looking
for a matching window from there.  Otherwise it starts at the
focused window.
.RB "See " Conditions " section below for a list of conditions."

.TP
.B "ScanForWindow \
[\fIFromPointer\fP] \
\fIdirection\fP \
\fIdirection2\fP \
[(\fIconditions\fP)] \
\fIcommand\fP"
Performs
.I command
(typically
.BR Focus )
on a window in the given direction which satisfies all
.IR conditions .
Normally, the center of the currently focused window or the
context window in which the command was invoked is taken as the
starting point.  Lacking such a window, or when the
.I FromPointer
option is given, the current position of the pointer is taken as
the starting point.  The
.I direction
may be one of "North", "NorthEast", "East", "SouthEast", "South",
"SouthWest", "West", and "NorthWest".  Which window
.B ScanForWindow
selects depends first on the position along the primary axis given
by
.IR direction .
If any windows have the exact same coordinate along the primary
axis, the secondary direction is used to order the windows.  The
.I direction2
may be one of the same set of values as
.IR direction .
If
.I direction2
is not perfectly perpendicular to
.IR direction ,
ScanForWindow will return a failure.  When using ScanForWindow
repeatedly with the same arguments, it is guaranteed that all
windows matching the conditions will eventually be found.  If the
focus reaches a limit along the primary axis, it will wrap around
to the opposite side.  Returns -1 if an invalid direction was
given.
.RB "See " Conditions " section below for a list of conditions."

.TP
.BI "Test [(" test-conditions ")] " command
Performs
.I command
if all
.I test-conditions
are satisfied.  The
.I test-conditions
are keywords with possible arguments from the list below
and are separated by commas or whitespace.  They include
.IR "Version operator x.y.z" ,
.IR Start ,
.IR Init ,
.IR Restart ,
.IR Exit ,
.IR Quit " and"
.IR ToRestart ,
.IR True ,
.IR False ,
.IR F ,
.IR R ,
.IR W ,
.IR X ,
.IR I .
A test-condition prefixed with "!" is reverted.

The
.I "Version operator x.y.z"
test-condition is fulfilled if the logical condition of the expression is
true. Valid
.I operator
values are:
.IR >= ,
.IR > ,
.IR <= ,
.IR < ,
.I ==
and
.IR != .

Example:
.EX
Test (Version >= 2.5.11) Echo 2.5.11 or later.
.EE
The
.I Start
test-condition is the same as either
.IR Init " or " Restart .
It is only true on startup or restart prior and during
.B StartFunction
execution.
The
.I Exit
test-condition is the same as either
.IR Quit " or " ToRestart .
It is only valid on shutdown during
.B ExitFunction
function execution.

The
.I True
and
.I False
test-conditions are, well, unconditionally true and false.

Additionally, if a test-condition name is not recognized, the Error
return code is set and the command is not executed.

The
.IR "F file" ,
.IR "R file" ,
.IR "W file" ,
.IR "X file" " and"
.IR "I file"
test-conditions test for existance of the given [F]ile (possibly
with [R]ead/[W]rite permissions), e[X]ecutable (in $PATH),
or the [I]mage (in ImagePath).

Example:
.EX
AddToFunc StartFunction I Test (Init) Exec exec xterm

AddToFunc VerifyVersion
+ I Test (Version 2.5.*) Echo 2.5.x detected
+ I TestRc (NoMatch) Test (!Version 2.6.*) Echo Future version
+ I TestRc (NoMatch) Echo 2.6.x is detected

Test (f $[FVWM_USERDIR]/local-config) Read local-config
Test (x xterm-utf16) Exec exec xterm-utf16
.EE

.TP
.BI "TestRc [([!]" returncode ")] " command
Performs
.I command
if the last conditional command returned the value
.IR returncode .
Instead of the numeric values 0 (no match), 1 (match), -1 (error),
and -2 (break) the symbolic names "NoMatch", "Match", "Error" and
"Break" can be used.  If no
.I returncode
is given, the default 0 is assumed.  If the return code is
prefixed with '!', the command is executed if
.I returncode
does not match the value returned by the conditional command.
.B TestRc
command can only be used inside functions.  If the
.I command
is another conditional command, the previous return code is
replaced by the new one.  Example:
.EX
AddToFunc ToggleXterm
+ I Any (my_xtermwindow) Close
+ I TestRc (NoMatch) Exec xterm -T my_xtermwindow
.EE

.TP
.BI "ThisWindow [(" conditions ")] " command
.B ThisWindow
executes the specified
.I command
in the context of the current operand window.  If there is no
operand window (it is invoked in the root window), the command is
ignored.
.B ThisWindow
is never interactive.  The command is executed only if the given
.I conditions
are met.  It returns -1 if used outside a window context.
.RB "See " Conditions " section below for a list of conditions."

This command implies the conditions
.IR CirculateHit ", " CirculateHitIcon " and " CirculateHitShaded .
They can be turned off by specifying "!CirculateHit"
etc. explicitly.

.TP
.B "WindowId [\fIid\fP\
] [(\fIconditions\fP\
)] | [\fIroot\fP \
[\fIscreen\fP\
]] \fIcommand"
The
.B WindowId
command looks for a specific window
.I id
and runs the specified
.I command
on it.  The second form of syntax retrieves the window id of the
root window of the given
.IR screen .
If no
.I screen
is given, the current screen is assumed.  The window indicated by
.I id
may belong to a window not managed by fvwm or even a window on a
different screen.  Although most commands can not operate on such
windows, there are some exceptions, for example the
.B WarpToWindow
command.
Returns -1 if no window with the given id exists.
.RB "See " Conditions " section below for a list of conditions."

This command implies the conditions
.IR CirculateHit ", " CirculateHitIcon " and " CirculateHitShaded .
They can be turned off by specifying
.I !CirculateHit
etc. explicitly.

Examples:
.EX
WindowId 0x34567890 Raise
WindowId root 1 WarpToWindow 50 50
WindowId $0 (Silly_Popup) Delete
.EE
In the past this command was mostly useful for functions used with
the
.B WindowList
command, or for selective processing of
.B FvwmEvent
calls (as in the last example), but currently these handler functions
are called within a window context, so this command is not really
needed in these cases.  Still it may be useful if, for example, the
window id should be stored in the environment variable for a further
proceeding.
.EX
Pick SetEnv BOOKMARKED_WINDOW $[w.id]
WindowId $[BOOKMARKED_WINDOW] WarpToWindow
.EE

.SS Conditions

The
.I conditions
that may be given as an argument to any conditional command are a
list of keywords separated by commas or whitespace, enclosed in
parentheses.  Unless stated otherwise, conditional commands accept
all the conditions listed below.  Note that earlier versions of
fvwm required the conditions to be enclosed in brackets instead of
parentheses (this is still supported for backward compatibility).

In addition, the
.I conditions
may include one or more window names to match to.  If more than
one window name is given, all of them must match.  The window
name, icon name, class, and resource are considered when
attempting to find a match. Each name may include the wildcards
'*' and '?', and may consist of two or more alternatives,
separated by the character '|', which acts as an OR operator.  (If
OR operators are used, they must not be separated by spaces from
the names.)  Each window name can begin with '!', which prevents
.I command
if any of the window name, icon name, class or resource match.
However, '!' must not be applied to individual names in a group
separated by OR operators; it may only be applied to the beginning
of the group, and then it operates on the whole group.

Examples:
.EX
 Next ("Netscape|konqueror|Mozilla*") WarpToWindow 99 90
.EE
This goes to the next web browser window, no matter which of the
three named web browsers is being used.
.EX
 Next ("Mozilla*", "Bookmark*") WarpToWindow 99 90
.EE
This goes to Mozilla's bookmark manager window, ignoring other
Mozilla windows and other browsers' bookmark windows.
.EX
 All ("XTerm|rxvt", !console) Iconify
.EE
This iconifies all the xterm and rxvt windows on the current page,
except that the one named "console" (with the -name option to xterm)
is excluded.
.EX
 Next (!"FvwmPager|FvwmForm*|FvwmButtons") Raise
 Next (!FvwmPager, !FvwmForm*, !FvwmButtons) Raise
.EE
These two commands are equivalent; either one raises the next window
which is not one of the named fvwm modules.

Any condition can be negated by using a an exclamation mark ('!')
directly in front of its name.

.IR AcceptsFocus ,
.IR AnyScreen ,
.IR CirculateHit ,
.IR CirculateHitIcon ,
.IR CirculateHitShaded ,
.IR Closable ,
.IR CurrentDesk ,
.IR CurrentGlobalPage ,
.IR CurrentGlobalPageAnyDesk ,
.IR CurrentPage ,
.IR CurrentPageAnyDesk ,
.IR CurrentScreen ,
.IR FixedSize ,
.IR Focused ,
.IR HasHandles ,
.IR HasPointer ,
.IR Iconic ,
.IR Iconifiable ,
.IR "Layer [n]" ,
.IR Maximizable ,
.IR Maximized ,
.IR Overlapped ,
.IR PlacedByButton3 ,
.IR PlacedByFvwm ,
.IR Raised ,
.IR Shaded ,
.IR "State n" ,
.IR Sticky ,
.IR StickyAcrossDesks ,
.IR StickyAcrossPages ,
.IR Transient ,
.IR Visible .

The
.I AcceptsFocus
condition excludes all windows that do not want the input focus
(the application has set the "Input hints" for the window to
False) and do not use the
.I Lenience
option of the
.B Style
command.  Also, all windows using the
.I NeverFocus
style are ignored.

With the
.I AnyScreen
condition used together with any of the
.I Current...
conditions, windows that do not intersect the Xinerama screen
containing the mouse pointer are considered for a match too.  For
example:
.EX
# Focus next window on current page,
# regardless of Xinerama screen
Next (CurrentPage, AnyScreen) Focus
.EE

The
.IR CirculateHit " and " CirculateHitIcon
options override the
.I CirculateSkip
.B Style
attribute for normal or iconic windows.  The
.I CirculateHitShaded
option overrides the
.I CirculateSkipShaded
.B Style.
All three options are turned on
by default for the
.B Current
command.  They can be turned off by specifying
.I !CirculateHit
etc. explicitly.
Note:  Do not confuse these conditions with the style options of
the same name.  Specifically,
.EX
Style foo CirculateSkip
Next (foo, CirculateHit) ...
.EE
is not the same as
.EX
Style foo CirculateHit ...
Next (foo)
.EE
The prior selects windows with the name foo only in the Next
command.  In the second example, these windows are always matched
in all conditional commands.

The
.I Closable
condition matches only windows that are allowed to be closed.

The
.I CurrentDesk
condition matches only windows that are on the current desk.

The
.I CurrentGlobalPage
condition matches only windows that are on the current page of the
current desk, regardless of whether Xinerama support is enabled or
not.  This conditions implicitly activates the
.I CurrentDesk
condition.

The
.I CurrentGlobalPageAnyDesk
condition matches only windows that are on the current page of any
desk, regardless of whether Xinerama support is enabled or not.

The
.I CurrentPage
condition matches only windows that are on the current page of the
current desk.  If Xinerama support is enabled, it only matches
windows that are at least partially on the Xinerama screen
containing the mouse pointer.  This conditions implicitly
activates the
.I CurrentDesk
condition.

The
.IR CurrentPageAnyDesk " and " CurrentScrene
conditions matche only windows that are on the current page of any
desk.  If Xinerama support is enabled, they only match windows
that are at least partially on the Xinerama screen containing the
mouse pointer.

The
.I FixedSize
condition excludes all windows that don't have a fixed size,
either set through WM hints or the
.B Style
option
.IR FixedSize .

The
.I Focused
matches on the the window the currently has the keyboard focus.
This is not useful for the
.B Current
command but can be used with the other conditional commands.

The
.I HasHandles
condition excludes all windoows that don't have resize handles.

The
.I HasPointer
condition excludes all windows that do not contain the pointer.

The
.I Iconic
condition matches only iconic windows.

The
.I Iconifiable
condition matches only windows that are allowed to be iconified.

The
.I "Layer [n]"
condition matches only windows on the specified layer.  The
optional argument of the
.I Layer
condition defaults to the layer of the focused window.  The
negation
.I !Layer
switches off the
.I Layer
condition.

The
.I Maximizable
condition matches only windows that are allowed to be maximized.

The
.I Maximized
condition matches only maximized windows.

The
.I Overlapped
condition matches only windows that are overlapped by other windows
on the same layer (or unmanaged windows if the option
.I RaiseOverUnmanaged
of the
.B BugOpts
command is used).  Note that this condition can be slow if you
have many windows or if RaiseOverUnmanaged is used and the
connection to the X server is slow.

The
.I PlacedByButton3
condition is fulfilled if the last interactive motion of the
window (with the
.B Move
command) was ended by pressing mouse button 3.  This is especially
useful with the
.I ManualPlacement
option of the
.B Style
command.

The
.I PlacedByFvwm
condition excludes all windows that have been placed manually or
by using the user or program position hint.

The
.I Raised
conditions matches only windows that are fully visible on the
current viewport and not overlapped by any other window.

The
.I Shaded
conditions matches only shaded windows (see
.B WindowShade
command).

The
.IR "State n" " or " "!State n"
conditions match only windows with the specified integer state set
(or unset).  See the
.B State
command for details.  The argument may range from 0 to 31.

The
.IR Sticky ", " StickyAcrossDesks " and " StickyAcrossPages
match only windows that are currently sticky, sticky across all
desks or sticky across all pages.  Please refer to the
.B Style
options with the same name and the commands
.BR Stick ", " StickAcrossDesks " and " StickAcrossPages
for details.

The
.I Transient
condition matches only windows that have the "transient"
property set by the application.  This it usually the case for
application popup menus and dialogs.  The
.B FvwmIdent
module can be used to find out whether a specific window is
transient.

The
.I Visible
conditions matches only windows that are at least partially
visible on the current viewport and not completely overlapped by
other windows.

.SS MODULE COMMANDS

Fvwm maintains a database of module configuration lines in a form
.EX
.BI "*" "<ModuleName>" ": " "<Config-Resource>"
.EE
where
.I "<ModuleName>"
is either a real module name or an alias.

This database is initially filled from config file (or from
output of
.B \-cmd
config command), and can be later modified either by user (via
.BR FvwmCommand )
or by modules.

When modules are run, they read appropriate portion of database.
(The concept of this database is similar to one used in X resource
database).

Commands for manipulating module configuration database are
described below.

.TP
.BI "*" module_config_line
Defines a module configuration.
.I module_config_line
consists of a module name (or a module alias) and a module
resource line. The new syntax allows a delimiter, a colon and
optional spaces, between the module name and the rest of the line,
this is recommended to avoid conflicts.
.EX
*FvwmIconBox: MaxIconSize 48x48
*FvwmPager: WindowBorderWidth 1
*FvwmButtons-TopRight: Geometry 100x100-0+0
*FvwmButtons-Bottom: Geometry +0-0
.EE

.TP
.BI "DestroyModuleConfig " module_config
Deletes module configuration entries, so that new configuration
lines may be entered instead.  This also sometimes the only way to
turn back some module settings, previously defined.  This changes
the way a module runs during a fvwm session without restarting.
Wildcards can be used for portions of the name as well.

The new non-conflicting syntax allows a delimiter, a colon and
optional spaces between the module name and the rest of the line.
In this case a module name (or alias) can't have wildcards.
.EX
DestroyModuleConfig FvwmButtons*
DestroyModuleConfig FvwmForm: Fore
DestroyModuleConfig FvwmIconBox: Max*
.EE

.TP
.BI "KillModule " modulename " [" modulealias ]
Causes the module which was invoked with name
.I modulename
to be killed.  The name may include wildcards. If
.I modulealias
is given, only modules started with the given alias are killed.
.EX
KillModule FvwmPager  # kill all pagers

Module FvwmEvent SoundEvent
KillModule FvwmEvent SoundEvent
.EE

.TP
.BI "Module " modulename " [" moduleparams ]
Specifies a module with its optional parameters which should be
spawned. Currently several modules, including
.BR FvwmButtons ", " FvwmEvent ", " FvwmForm ", " FvwmGtk ", "
.BR FvwmPager ", " FvwmScript
support aliases.  Aliases are useful if more than one instance of
the module should be spawned.  Aliases may be configured
separately using
.B *
syntax described above.  To start a module
.B FvwmForm
using an alias
.IR MyForm ,
the following syntax may be used:
.EX
Module FvwmForm MyForm
.EE

At the current time the available modules (included with fvwm) are
.B FvwmAnimate
(produces animation effects when a window is iconified or
de-iconified),
.B FvwmAudio
(makes sounds to go with window manager actions),
.B FvwmAuto
(an auto raise module),
.B FvwmBacker
(to change the background when you change desktops),
.B FvwmBanner
(to display a spiffy XPM, XBM or PNG),
.B FvwmButtons
(brings up a customizable tool bar),
.B FvwmCommandS
(a command server to use with shell's FvwmCommand client),
.B FvwmConsole
(to execute fvwm commands directly),
.B FvwmCpp
(to preprocess your
.I config
with cpp),
.B FvwmDebug
(to help debug fvwm),
.B FvwmDragWell
(the place to drag&drop to),
.B FvwmEvent
(trigger various actions by events),
.B FvwmForm
(to bring up dialogs),
.B FvwmGtk
(to bring up GTK menus and dialogs),
.B FvwmIconBox
(like the mwm IconBox),
.B FvwmIconMan
(a flexible icon manager),
.B FvwmIdent
(to get window info),
.B FvwmM4
(to preprocess your
.I config
with m4),
.B FvwmPager
(a mini version of the desktop),
.B FvwmSave
(saves the desktop state in .xinitrc style),
.B FvwmSaveDesk
(saves the desktop state in fvwm commands),
.B FvwmScript
(another powerful dialog toolkit),
.B FvwmScroll
(puts scrollbars on any window),
.B FvwmTaskBar
(a Windows like task bar),
.B FvwmTheme
(managed colorsets, obsolete),
.B FvwmWinList
(a window list),
.B FvwmWharf
(an AfterStep like button bar).  These modules have their own man
pages.  There may be other modules out on there as well.


Modules can be short lived transient programs or, like
.BR FvwmButtons ,
can remain for the duration of the X session.  Modules are
terminated by the window manager prior to restarts and quits, if
possible.  See the introductory section on modules.  The keyword
.B Module
may be omitted if
.I modulename
is distinct from all fvwm commands.

.TP
.BI "ModulePath " path
Specifies a colon separated list of directories in which to search
for modules.  To find a module, fvwm searches each directory in
turn and uses the first file found.  Directory names on the list
do not need trailing slashes.

The
.BI ModulePath
may contain environment variables such as
.IR $HOME " (or " ${HOME} ).
Further, a '+' in the
.I path
is expanded to the previous value of the
.IR path ,
allowing easy appending or prepending to the
.IR path .

For example:
.EX
ModulePath ${HOME}/lib/fvwm/modules:+
.EE
The directory containing the standard modules is available via the
environment variable
.IR $FVWM_MODULEDIR .

.TP
.BI "ModuleSynchronous  [" "Expect string" "] [" "Timeout secs" "] " modulename
The
.B ModuleSynchronous
command is very similar to
.BI Module .
Fvwm stops processing any commands and user input until the module
sends a string beginning with "NOP FINISHED STARTUP" back to fvwm.
If the optional
.I Timeout
is given fvwm gives up if the module sent no input back to fvwm
for
.I secs
seconds.  If the
.I Expect
option is given, fvwm waits for the given
.I string
instead.
.B ModuleSynchronous
should only be used during fvwm startup to enforce the order in
which modules are started.  This command is intended for use with
the (currently hypothetical) module that should be in place before
other modules are started.

Warning: It is quite easy to hang fvwm with this command, even if
a timeout is given.  Be extra careful choosing the string to wait
for. Although all modules in the fvwm distribution send back the
"NOP FINISHED STARTUP" string once they have properly started up,
this may not be the case for third party modules.  Moreover, you
can try to escape from a locked
.B ModuleSynchronous
command by using the key sequence
.SM Ctrl-Alt-Escape
(see the
.BR EscapeFunc ).

.TP
.BI "ModuleTimeout " timeout
Specifies how many seconds fvwm waits for a module to respond. If
the module does not respond within the time limit then fvwm kills
it.
.I timeout
must be greater than zero, or it is reset to the default value of
30 seconds.

.TP
.BI "SendToModule " "modulename string"
Sends an arbitrary string (no quotes required) to all modules,
whose alias or name matching
.IR modulename ,
which may contain wildcards.  This only makes sense if the module
is set up to understand and deal with these strings though. Can be
used for module to module communication, or implementation of more
complex commands in modules.


.SS QUIT, RESTART AND SESSION MANAGEMENT COMMANDS

.TP
.BI "Quit"
Exits fvwm, generally causing X to exit too.

.TP
.BI "QuitScreen"
Causes fvwm to stop managing the screen on which the command was
issued.

.TP
.BI "QuitSession"
Causes a session manager (if any) to shutdown the session.  This
command does not work for xsm, it seems that xsm does not
implement this functionality.  Use Unix signals to manage xsm
remotely.

.TP
.BI "Restart [" window_manager " [" params "]]"
Causes fvwm to restart itself if
.I window_manager
is left blank, or to switch to an alternate window manager (or
other fvwm version) if
.I window_manager
is specified.  If the window manager is not in your default search
path, then you should use the full path name for
.IR window_manager .

This command should not have a trailing ampersand.  The command
can have optional parameters with simple shell-like syntax.  You
can use
.I ~
(is expanded to the user home directory) and environmental
variables
.IR $VAR " or " ${VAR} . Here are several examples:
.EX
Key F1 R N Restart
Key F1 R N Restart fvwm -s
Key F1 R N Restart ~/bin/fvwm -f $HOME/.fvwm/main
Key F1 R N Restart fvwm1 -s -f .fvwmrc
Key F1 R N Restart xterm -n '"X console"' \\
  -T \\"X\\ console\\" -e fvwm1 -s
.EE
If you need a native restart, we suggest only to use
.B Restart
command without parameters unless there is a reason not to.  If you
still use an old command 'Restart fvwm2' that was correct in 2.2.x,
all current command line arguments are lost.  On a restart without
parameters or with --pass-args, they are preserved.  Here are some
cases when 'Restart fvwm2' or 'Restart fvwm' cause troubles:
.EX
* running fvwm under a session manager
* running fvwm with multi headed displays
* having command line arguments, like
  -f themes-rc or -cmd
* if the first fvwm2 in the $PATH is a
  different one
.EE
This is why we are issuing a warning on an old usage. If you
really want to restart to fvwm with no additional arguments, you
may get rid of this warning by using "Restart fvwm -s" or
"Restart /full/path/fvwm".

Note, currently with multi headed displays, restart of fvwms on
different screens works independently.

.TP
.BI "Restart " "--pass-args window_manager"
The same as
.B Restart
without parameters but the name for the current window manager is
replaced with the specified
.I window_manager
and original arguments are preserved.

This command is useful if you use initial arguments like
.EX
-cmd FvwmCpp
.EE
and want to switch to another fvwm version without losing the
initial arguments.

.TP
.BI "Restart " --dont-preserve-state " [" other-params "]"
The same as
.EX
.BI "Restart [" other-params "]"
.EE
but it does not save any window states over the restart.

Without this option,
.B Restart
preserves most per-window state by writing it to a file named
.I .fs-restart-$HOSTDISPLAY
in the user's home directory.

.TP
.BI "SaveSession"
Causes a session manager (if any) to save the session.  This
command does not work for xsm, it seems that xsm does not
implement this functionality.  Use Unix signals to manage xsm
remotely.

.TP
.BI "SaveQuitSession"
Causes a session manager (if any) to save and then shutdown the
session. This command does not work for xsm, it seems that xsm
does not implement this functionality.  Use Unix signals to manage
xsm remotely.


.SS COLORSETS

Colorsets are a powerful method to control colors. Colorsets
create appearance resources that are shared by fvwm and its
modules.  When a colorset is modified all parts of fvwm react to
that change. A colorset includes a foreground color, background
color, shadow and highlight color (often based on the background
color), background face (this includes images and all kinds of
gradients).  There is a way to render background face and specify
other color operations.

In the 2.4.x versions a special module
.B FvwmTheme
was introduced to manage colorsets.  Starting with the 2.5.x beta
version, the FvwmTheme functionality was moved to the core fvwm,
so this module became obsolete.

The old syntax:
.EX
DestroyModuleConfig FvwmTheme: *
*FvwmTheme: Colorset 0 fg black, bg rgb:b4/aa/94
*FvwmTheme: Colorset 1 fg black, bg rgb:a1/b2/c8
.EE
corresponds to the new syntax:
.EX
CleanupColorsets
Colorset 0 fg black, bg rgb:b4/aa/94
Colorset 1 fg black, bg rgb:a1/b2/c8
.EE

.TP
.BI "Colorset " num " [" options "]"
Creates or modifies colorset
.IR num .
Colorsets are identified by this number. The number can start at
zero and can be a very large number.

Warning: The highest colorset number used determines memory
consumption. Thus, if you define 'Colorset 100000', the memory for
100001 colorsets is used.  Keep your colorset numbers as small as
possible.

By convention, colorsets are numbered like this:
.EX
# 0 = Default colors
# 1 = Inactive windows
# 2 = Active windows
# 3 = Inactive menu entry and menu background
# 4 = Active menu entry
# 5 = greyed out menu entry (only bg used)
# 6 = module foreground and background
# 7 = hilight colors
.EE

If you need to have more colors and do not want to reinvent the
wheel, you may use the convention used in fvwm-themes, it defines
the meaning of the first 40 colorsets for nearly all purposes:

.B http://fvwm-themes.sourceforge.net/doc/colorsets

Each colorset has four colors, an optional pixmap and an optional
shape mask.  The four colors are used by modules as the
foreground, background, highlight and shadow colors.  When a
colorset is created it defaults to a foreground of black and
background of gray.  The background and foreground are marked as
"average" and "contrast" (see later) so that just specifying a
pixmap or gradient gives sensible results.

.I options
is a comma separated list containing some of the keywords:
fg, Fore, Foreground,
bg, Back, Background,
hi, Hilite, Hilight,
sh, Shade, Shadow,
fgsh,
Pixmap, TiledPixmap, AspectPixmap,
Transparent, RootTransparent,
Shape, TiledShape, AspectShape, NoShape,
?Gradient,
Tint, fgTint, bgTint,
Alpha, fgAlpha,
Dither, NoDither,
IconTint,
IconAlpha,
Plain.

.IR fg ", " Fore " and " Foreground
take a color name as an argument and set the foreground color.
The special name
.I Contrast
may be used to select a color that contrasts well with the
background color.  To reset the foreground color to the default
value you can simply omit the color name.

.IR bg ", " Back " and " Background
take a color name as an argument and set the background color.  It
also sets the highlight and shadow colors to values that give a 3d
effect unless these have been explicitly set with the options
below.  The special name
.I Average
may be used to select a color that is the average color of the
pixmap.  If the pixmap is tinted with the
.I Tint
option, the tint is not taken in account in the computation of the
average color. You should use the
.I bgTint
option to get the "real" average color.  The background color is
reset to the default value if the color name is omitted.

.IR hi ", " Hilite " and " Hilight
take a color name as as argument and set the highlight color.  If
the highlight color is not explicitly set, the default is to
calculate it from the background color.  To switch back to the
default behavior the color name can be omitted.

.I sh ", " Shade " and " Shadow
take a color name as as argument and set the shadow color.  If the
shadow color is not explicitly set, the default is to calculate it
from the background color.  To switch back to the default behavior
the color name can be omitted.

.I fgsh
takes a color name as an argument and sets the color used by the
shadowing font effect. See the
.B FONT SHADOW EFFECTS
section of the fvwm man page.  By default this color is computed
from the foreground and background colors.  To switch back to the
default the color name can be omitted.

.IR Pixmap ", " TiledPixmap " and " AspectPixmap
take a file name as an argument, search the
.B ImagePath
and use it as the background pixmap.  Any transparent parts are
filled with the background color.  Not specifying a file name
removes any existing image from the colorset.
.I TiledPixmap
produces repeated copies of the image with no scaling,
.I Pixmap
causes the image to be stretched to fit whatever object the
colorset is applied to and
.I AspectPixmap
stretches to fit but retains the image aspect ratio.

.I Transparent
creates a transparent background pixmap.  The pixmap is used as a
window background to achieve root transparency.  For this you
should use the
.I ParentalRelativity
option to the
.B Style
command.
A subsequent root background change may be detected or not, this
depends on the program used to set the background.  If you use
fvwm-root, xsetbg (xli), FvwmBacker with solid or colorset colors
or a recent version of Esetroot (>= 9.2) a background change is
detected. If background changes are not detected (e.g., if you use
xv or xsetroot) you can force detection by using the -d option of
fvwm-root:
.EX
xv -root -quit mybg.png; fvwm-root -d
.EE
Due to the way X implements transparency no guarantees can be made
that the desired effect can be achieved.  The application may even
crash.  If you experience any problems with this option, do not
use it.

Using outline move and resize (see the
.B OpaqueMoveSize
command and the
.I ResizeOpaque
.B Style
option) as well as setting the
.I WindowShadeShrinks
style may help.  The transparency achieved with
.I Transparent
depends on whether the colorset is applied to the foreground or
the background of a window. In the second case the transparency is
relative to the parent window of the window on which the colorset
is defined.  For example:
.EX
Colorset 12 VGradient 200 grey30 gery60
Colorset 17 Transparent
*FvwmIconMan: Colorset 10
*FvwmIconMan: PlainColorset 17
.EE
gives an IconMan with a vertical grey gradient background and the
buttons use the background (by transparency). To obtain a (root)
transparent IconMan:
.EX
Colorset 12 Transparent
Colorset 17 Transparent
Colorset 18 Transparent
Colorset 19 Transparent
...
*FvwmIconMan: Colorset 12
*FvwmIconMan: PlainColorset 17
*FvwmIconMan: FocusColorset 18
*FvwmIconMan: IconColorset  19
.EE
The Colorset IconMan option defines the IconMan window background,
but the PlainColorset and the FocusColorset are drawn on the
foreground. So, the transparency of the IconMan buttons is
achieved by drawing nothing.  Now if this IconMan is swallowed in
an FvwmButtons as:
.EX
FvwmButtons:(Colorset 10, Swallow \\
  "FvwmIconMan" 'FvwmIconMan')
.EE
then,
.B FvwmIconMan
becomes a child of
.B FvwmButtons
and it is transparent relative to
.BR FvwmButtons .
So, in this case
.B FvwmIconMan
uses Colorset 10 as background. If you want root transparency use
the
.I RootTransparent
option.
.BR FvwmButtons ", " FvwmIconMan ", " FvwmIdent ", " FvwmScroll
and
.B FvwmTaskBar
are relatively simple. There is one main colorset option which
defines the background of the window and the other colorsets (if
any) are drawn on the foreground. The case of
.BR FvwmWinList " and " FvwmProxy
are simpler. With
.B FvwmWinList
all the colorsets are drawn on the foreground and with
.B FvwmProxy
the two colorsets refer to the window backgrounds.
.B FvwmPager
is more complicated as almost everything in the pager are windows
with some parental relations (the mini windows are the child and
the desktops are the parents and all this is complicated by the
hilighted page). So, the colorsets apply to the background of
these windows. You should experiment. For
.BR FvwmForm " and " FvwmScript
the situation is similar. There is a main window (a child of the
root window) which corresponds to the main colorset and most of
the widgets are windows which are children of the main window.
.I Tint
may work or not with the
.I Transparent
option. When the colorset is drawn on the foreground
.I Tint
should work. In some cases, tinting may be very slow. Tinting may
work with fvwm menu (without animation). Tinting may work better
if your X server has backing store enabled (try xdpyinfo to see if
this the case). There is a chance that the backing store support
of your X server does not work well with the terrible hack used to
Tint the ParentRelative Pixmap. So, to get tinted root
transparency it is more safe to use the
.I RootTransparent
option.

.IR RootTransparent " [ " buffer " ] "
creates a root transparent background. To make this option work,
you must use an Esetroot compatible program, fvwm-root with the
--retain-pixmap option or FvwmBacker with the RetainPixmap option
(and colorset or solid backgrounds).  The
.I buffer
keyword is useful only when the
.I Tint
option is used too. This speeds up creation of windows which use
the colorset (useful for fvwm menus) at the cost of memory
usage. It also speeds up opaque move and resize which can be
unacceptably slow without
.IR buffer .
However, this option may add a lot of memory to your X server
(depending on the size of the image used to set the
background). In summary, using outline move and resize for modules
which use such a colorset may be a good idea.

.IR Shape ", " TiledShape " and " AspectShape
take a file name as an argument, search the
.B ImagePath
and use it as the shape bitmap.
.I TiledShape
produces repeated copies of the bitmap with no scaling,
.I Shape
causes the bitmap to be stretched to fit whatever object the
colorset is applied to and
.I AspectShape
stretches to fit but retains the bitmap aspect ratio.  If the file
is a pixmap in xpm format, the shape mask of the pixmap is used.

Warning: Due to the way X11 implements shapes you cannot take back
making windows shaped. You may have to restart fvwm or the shaped
application.

.I ?Gradient ...
creates a pixmap and stretches it to fit the window.
.I ?Gradient
may be one of HGradient, VGradient, DGradient, BGradient,
SGradient, CGradient, RGradient or YGradient.  The gradient types
are as follows:  H is horizontal; V is vertical; D is diagonal
from top left to bottom right; B is a backwards diagonal from
bottom left to top right; S is concentric squares; C is concentric
circles; R is a radar like pattern and Y is a Yin Yang style (but
without the dots).
Please refer to the
.B COLOR GRADIENTS
section for the syntax of gradients.

.I Tint
takes 2 arguments, a color and a percentage between 0 and 100. It
causes the image defined using
.I ?Pixmap
or
.I ?Gradient
to be tinted with the specified color using the percentage. If the
image is transparent
.I Tint
tints only the image part. Unfortunately, a colorset background
specified using the
.I Transparent
option can give strange results. See the
.I Transparent
option for details. With no arguments this option removes the
tint.

.I fgTint
takes 2 arguments, a color and a percentage between 0 and 100. It
causes the color defined using
.I fg
to be tinted with the specified color using the percentage. With
no arguments this option removes the tint.

.I bgTint
takes 2 arguments, a color and a percentage between 0 and 100. It
causes the color defined using
.I bg
to be tinted with the specified color using the percentage. If the
.I sh
and
.I hi
colors are not specified, they are recomputed from the tinted bg
color. With no arguments this option removes the tint.

.I Alpha
takes a percentage between 0 and 100 as an argument. It causes
fvwm to merge the image defined using
.I ?Pixmap
or
.I ?Gradient
with the
.I bg
color using the percentage. If the percentage is 0 the image is
hidden and if it is 100 the image is displayed as usual (no
merge). The default is 100 and it is restored if no argument is
given.

.I fgAlpha
takes a percentage between 0 and 100 as an argument. It causes
fvwm to merge the text and the colorset background using the
percentage. If the percentage is 0 the text is hidden and if it is
100 the text is displayed as usual (no merge). This option has an
effect only with fonts loaded by Xft, see the
.B FONT NAMES AND FONT LOADING
section. The default is 100 and it is restored if no argument is
given.

.I Dither
causes fvwm to dither the image defined using
.I ?Pixmap
or
.I ?Gradient.
This is useful only with displays with depth less than or equal to
16 (i.e., on displays which can only display less than 65537
colors at once). The dithering effect lets you simulate having
more colors available that you actually have.
.I NoDither
causes fvwm to do not dither the images.
.I Dither
is the default if the depth is less than or equal to 8 (a screen
with 256 colors or less). In depth 15 (32768 colors) and 16 (65536
colors), the default is
.IR NoDither ,
however this effect can be useful with images which contain a lot
of close colors. For example a fine gradient will look more
smooth.

.I IconTint
takes 2 arguments, a color and a percentage between 0 and 100. It
causes fvwm or a module to tint the "icons" which are rendered
into the colorset background with the specified color using a
percentage. Here "icons" means, fvwm Icons, fvwm menu icons,
MiniIcons which represent applications in various modules, images
loaded by modules (e.g., images specified by the
.I Icon
.B FvwmButtons
button option) ...etc. With no arguments this option removes the
icon tint.

.I IconAlpha
takes a percentage between 0 and 100 as an argument. It causes
fvwm to merge the "icons" which are rendered into the colorset
background using this percentage. The default is 100 and it is
restored if no argument is given.

.IR Note :
It is equivalent to use "Tint a_color rate" and "Alpha a" if a =
100 and the bg color is a_color. This equivalence does not hold
for IconAlpha and IconTint as the background can be an image or a
gradient (and not a uniform color background).
However, in some cases you can achieve (almost) the same effect by
using IconTint in the place of IconAlpha. This is preferable as,
in general, IconAlpha generates more redrawing than IconTint.

.I NoShape
removes the shape mask from the colorset while
.I Plain
removes the background pixmap or gradient.

.SH EXAMPLES

.EX
Colorset 3 fg tan, bg navy
.EE

If necessary this creates colorsets 0, 1, 2 and 3 and then changes
colorset 3 to have a foreground of tan, a background of navy.

.EX
Colorset 3 bg "navy blue"
.EE

changes the background color of colorset 3 to navy blue. The
foreground and pixmap are unchanged.

.EX
Colorset 3 AspectPixmap large_murky_dungeon.xpm
.EE

Causes depression.

.EX
Colorset 3 bg Average
.EE

Sets the background color and the relief colors to match the
background pixmap. This is the default setting but it must be used
if a background color was specified and is now not required.
.EX
Colorset 3 YGradient 200 3 blue 1000 navy 1 blue 1000 navy
.EE
Adds a Yin Yang gradient background pixmap to colorset 3.  If the
background is set to average it is recomputed along with the
foreground if that is set to contrast.

.EX
#!/bin/sh
FvwmCommand "Colorset 7 fg navy, bg gray"
while true
do
  FvwmCommand "Colorset 7 fg gray"
  sleep 1
  FvwmCommand "Colorset 7 fg navy"
  sleep 1
done
.EE
Makes colorset 7 blink.

The color names used in colorsets are saved as fvwm variables can
be substituted in any fvwm command. For example:
.EX
AddToFunc InitFunction
+ I Exec exec xterm -fg $[fg.cs0] -bg $[bg.cs0]
.EE
Where $[fg.cs0] is the foreground color of colorset zero. Please
refer to the
.B COMMAND EXPANSION
section for more information.

.TP
.B CleanupColorsets
Resets a definition of all colorsets.


.SS COLOR GRADIENTS

A color gradient is a background that changes its color gradually
from one hue to a different one.  Color gradients can be used by
various commands and modules of fvwm.  There are eight types of
gradients:
.B HGradient
is a horizontal gradient,
.B VGradient
is vertical,
.B DGradient
is diagonal from top left to bottom right,
.B BGradient
is backwards diagonal from bottom left to top right,
.B SGradient
is concentric squares,
.B CGradient
is concentric circles,
.B RGradient
is a radar like pattern and
.B YGradient
is a Yin Yang style (but without the dots).

The color gradient syntax has two forms:

.TP
.BI "?Gradient " "colors start-color end-color"
This form specifies a linear gradient.  The arguments denote the
total number of
.I colors
to allocate (between 2 and 1000), the initial color and the final
color.

Example:
.EX
TitleStyle VGradient 20 \\
rgb:b8/ce/bc rgb:5b/85/d0
.EE

.TP
.BI "?Gradient " "colors segments color length color" " [" "length color" "] ..."
The second form specifies a nonlinear gradient.  The arguments are:
the total number of
.I colors
to allocate (between 2 and 1000), then the number of
.IR segments .
For each segment, specify the starting
.IR color ,
a relative
.IR length ,
then the ending color.  Each subsequent segment begins with the
second color of the last segment.  The lengths may be any
non-negative integers.  The length of one segment divided by the
sum of all segments lengths is the fraction of the colors that
are used for the segment.
.in -2

Examples:
.EX
MenuStyle * MenuFace DGradient \\
  128 2 lightgrey 50 blue 50 white

# 20% gradient from red to blue,
# 30% from blue to black,
# 50% from black to grey
MenuStyle * DGradient 100 3 Red 20 Blue 30 \\
  Black 50 Grey

# 50% from blue to green, then
# 50% from yellow to red
Colorset 0 Blue Red HGradient \\
  128 3 Blue 1000 Green 1 Yellow 1000 Red
.EE

.SH ENVIRONMENT

.TP
.I DISPLAY
Fvwm starts on this display unless the
.I -display
option is given.
.TP
.I FVWM_MODULEDIR
Set by fvwm to the directory containing the standard fvwm modules.
.TP
.I FVWM_USERDIR
Used to determine the user's data directory for reading and
sometimes writing personal files. If this variable is not already
set, it is set by fvwm to $HOME/.fvwm, which is the default user's
data directory.
.TP
.I SESSION_MANAGER
Fvwm tries to contact this session manager.
.TP
.I SESSION_MANAGER_NAME
This is used mainly to determine xsm running to work around its
bug. If this variable is set to "xsm", DiscardCommand is set as
xsm expects it and not as XSMP requires.  If you run fvwm under
xsm, you should set this variable to "xsm", otherwise old state
files are not removed.
.TP
.I SM_SAVE_DIR
If this is set, fvwm saves its session data in this
directory. Otherwise it uses
.IR $HOME .
Note, the state files are named
.I .fs-??????
and normally are removed automatically when not used anymore.

.SH AUTHORS

Robert Nation with help from many people, based on twm code, which
was written by Tom LaStrange.  After Robert Nation came Charles
Hines, followed by Brady Montz. Currently fvwm is developed by a
number of people on the fvwm-workers mailing list.

.SH COPYRIGHT

Fvwm and all the modules, scripts and other files coming with the
distribution are subject to the GNU General Public License
(GPL). Please refer to the
.I COPYING
file that came with fvwm for details.

.SH BUGS

As of fvwm version 2.4.0 there were exactly 71.8 unidentified
bugs. Since then 22.825 bugs have been fixed.  Assuming that there
are at least 10 unidentified bugs for every identified one, that
leaves us with 71.8 - 22.825 + 10 * 22.825 = 277.225 unidentified
bugs. If we follow this to its logical conclusion we will have an
infinite number of unidentified bugs before the number of bugs can
start to diminish, at which point the program will be bug-free.
Since this is a computer program infinity = 3.4028e+38 if you
don't insist on double-precision.  At the current rate of bug
discovery we should expect to achieve this point in 4.27e+27
years.  I guess we better plan on passing this thing on to our
children...

Known bugs can be found in the fvwm bug tracking system
(accessible from the fvwm home page).

Bug reports can be sent to the fvwm-workers mailing list at
@FVWMWORKERSLIST@ (see the
.IR FAQ )
or reported through the bug tracking system.

The official fvwm homepage is
.BR @FVWMHOMEPAGE@ .