.\" Title: fvwm
.\" Author:
.\" Generator: DocBook XSL Stylesheets vsnapshot_6661
.\" Date: 19-Oct-2022
.\" Manual: Fvwm 2.7.0
.\" Source:
.\"
.TH "FVWM" "1" "19-Oct-2022" "" "Fvwm 2.7.0"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH NAME
.PP
Fvwm \- F? Virtual Window Manager for X11
.SH SYNOPSIS
.HP 5
\fBfvwm\fR [\fB\-c\fR\ \fIconfig\-command\fR] [\fB\-d\fR\ \fIdisplayname\fR] [\fB\-f\fR\ \fIconfig\-file\fR] [\fB\-r\fR] [\fB\-s\fR\ [\fIscreen_num\fR]] [\fB\-V\fR] [\fB\-C\fR\ \fIvisual\-class\fR | \fB\-I\fR\ \fIvisual\-id\fR] [\fB\-l\fR\ \fIcolors\fR\ [\fB\-L\fR]\ [\fB\-A\fR]\ [\fB\-S\fR]\ [\fB\-P\fR]] [\fB\-D\fR] [\fB\-h\fR] [\fB\-i\fR\ \fIclient\-id\fR] [\fB\-F\fR\ \fIstate\-file\fR] [\fB\-\-debug\-stack\-ring\fR] [\fB\-blackout\fR]
.SH DESCRIPTION
.PP
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\.
.PP
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\.
.PP
Fvwm provides both a large
\fIvirtual desktop\fR
and
\fImultiple disjoint desktops\fR
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\.
.PP
Fvwm provides
\fIkeyboard accelerators\fR
that allow you to perform most window manager functions,
including moving and resizing windows and operating the menus,
using keyboard shortcuts\.
.PP
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, and 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\.
.PP
Other noteworthy differences between fvwm and other X11 window
managers are the introduction of the \fISloppyFocus\fR and \fINeverFocus\fR
focus methods\. Focus policy can be separately specified for
different window groups\. Windows using \fISloppyFocus\fR 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
\fINeverFocus\fR
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
NeverFocus
decoration window does not deprive the terminal of focus\.
.SH OPTIONS
.PP
These are the command line options that are recognized by fvwm:
.PP
\fB\-i\fR | \fB\-\-clientid\fR \fIid\fR
.RS 4
This option is used when fvwm is started by a session manager\. Should not be used by a user\.
.RE
.PP
\fB\-c\fR | \fB\-\-cmd\fR \fIconfig\-command\fR
.RS 4
Causes fvwm to use
\fIconfig\-command\fR
instead of '\fBRead\fR
\fIconfig\fR' (or '\fBRead\fR
\fI\.fvwm2rc\fR') as its initialization command\. (Note that up to 10
\fB\-f\fR
and
\fB\-c\fR
parameters can be given, and they are executed in the order specified\.)
.sp
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
\fBFvwmCpp\fR/\fBFvwmM4\fR/\fBFvwmPerl\fR
but there is a timeout so fvwm eventually gets going\.
.sp
As an example, starting the pager this way hangs fvwm until the timeout, but the following should work well:
.sp
.RS 4
.nf
fvwm \-c "\fBAddToFunc\fR StartFunction I \fBModule\fR \fBFvwmPager\fR"
.fi
.RE
.RE
.PP
\fB\-d\fR | \fB\-\-display\fR \fIdisplayname\fR
.RS 4
Manage the display called
\fIdisplayname\fR
instead of the name obtained from the environment variable
\fI$DISPLAY\fR\.
.RE
.PP
\fB\-D\fR | \fB\-\-debug\fR
.RS 4
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\.
.RE
.PP
\fB\-f\fR \fIconfig\-file\fR
.RS 4
Causes fvwm to read
\fIconfig\-file\fR
instead of
\fI~/\.fvwm/config\fR
as its initialization file\. This is equivalent to \-c '\fBRead\fR
\fIconfig\-file\fR'\.
.RE
.PP
\fB\-h\fR | \fB\-\-help\fR
.RS 4
A short usage description is printed\.
.RE
.PP
\fB\-r\fR | \fB\-\-replace\fR
.RS 4
Try to take over from a previously running wm\. This does not work unless the other wm is
ICCCM2
2\.0 compliant\.
.RE
.PP
\fB\-F\fR | \fB\-\-restore\fR \fIstate\-file\fR
.RS 4
This option is used when fvwm is started by a session manager\. Should not be used by a user\.
.RE
.PP
\fB\-s\fR | \fB\-\-single\-screen\fR [\fIscreen_num\fR]
.RS 4
On a multi\-screen display, run fvwm only on the screen named in the
\fI$DISPLAY\fR
environment variable or provided through the
\fB\-d\fR
option\. The optional argument
\fIscreen_num\fR
should be positive or null and override the screen number\. Normally, fvwm attempts to start up on all screens of a multi\-screen display\.
.RE
.PP
\fB\-V\fR | \fB\-\-version\fR
.RS 4
Prints the version of fvwm to
\fIstderr\fR\. Also prints an information about the compiled in support for readline, rplay, stroke, xpm, png, svg,
GNOME
hints,
EWMH
hints, session management, bidirectional text, multibyte characters, xinerama and Xft aa font rendering\.
.RE
.PP
\fB\-C\fR | \fB\-\-visual\fR \fIvisual\-class\fR
.RS 4
Causes fvwm to use
\fIvisual\-class\fR
for the window borders and menus\.
\fIvisual\-class\fR
can be "StaticGray", "GrayScale", "StaticColor", "PseudoColor", "TrueColor" or "DirectColor"\.
.RE
.PP
\fB\-I\fR | \fB\-\-visualid\fR \fIid\fR
.RS 4
Causes fvwm to use
\fIid\fR
as the visual id for the window borders and menus\.
\fIid\fR
can be specified as N for decimal or 0xN for hexadecimal\. See man page of xdpyinfo for a list of supported visuals\.
.RE
.PP
\fB\-l\fR | \fB\-\-color\-limit\fR \fIlimit\fR
.RS 4
Specifies a
\fIlimit\fR
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
\fIlimit\fR
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
\fB\-l\fR
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
\fB\-l\fR
must not be used\. Moreover, in this case the
\fB\-A\fR
and
\fB\-S\fR
options are forced\. Note that XFree\-4\.2 pre\-allocates 244 colors (if you use a driver with Render support) leaving only a few free colors\. This may lead to some color 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:
.PP
Display depth 8 (256 colors)
.RS 4
.nf
.IP "" 4
PseudoColor: 68 (4x4x4 color cube + 4 grey)
GrayScale: 64 regular grey
DirectColor: 32 (3x3x3 color cube + 5 grey)
.fi
.RE
.PP
Display depth 4 (16 colors)
.RS 4
.nf
.IP "" 4
PseudoColor: 10 (2x2x2 color cube + 2 grey)
GrayScale: 8 regular grey
DirectColor: 10 (2x2x2 color cube + 2 grey)
.fi
.RE
.sp
These defaults may change before version 2\.6\. Note that if you use a private color map (i\.e\., fvwm is started with the
\fB\-C\fR
or the
\fB\-I\fR
options), then other defaults are used\.
.sp
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
\fB\-C\fR
option with
\fITrueColor\fR
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 use 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 may 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
or
QT
applications with the \-\-cmap option, use the
\fB\-C\fR
option for fvwm\. The disadvantage of this method is that it is visually disturbing (see the
\fBColormapFocus\fR
command for a better control of the color maps switching)\. The second method is to limit the number of colors that the applications use\. 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 cube plus 6 grey), 29 (a 3x3x3 color cube plus 2 grey), 10 or 9\. Also, you may use the
\fB\-L\fR
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
\fB\-l\fR
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
\fBPrintInfo\fR
\fIColors\fR
[\fI1\fR]
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)\.
.RE
.PP
\fB\-L\fR | \fB\-\-strict\-color\-limit\fR
.RS 4
If the screen displays 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\.
.RE
.PP
\fB\-P\fR | \fB\-\-visual\-palette\fR
.RS 4
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 prefer to use named colors)\. If the
\fB\-l\fR
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
\fB\-l\fR
option\.
.RE
.PP
\fB\-A\fR | \fB\-\-allocate\-palette\fR
.RS 4
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
\fB\-static\-palette\fR
option\. By default, fvwm allocates (reserves) a color in its palette only if it needs this color\.
.RE
.PP
\fB\-S\fR | \fB\-\-static\-palette\fR
.RS 4
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\.
.RE
.PP
\fB\-blackout\fR
.RS 4
This option is provided for backward compatibility only\. Blacking out the screen during startup is not necessary (and doesn't work) anymore\. This option will be removed in the future\.
.RE
.PP
\fB\-\-debug\-stack\-ring\fR
.RS 4
Enables stack ring debugging\. This option is only intended for internal debugging and should only be used by developers\.
.RE
.SH ANATOMY OF A WINDOW
.PP
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\.
.PP
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\.
.PP
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
\fBMouse\fR
command\.
.SH THE VIRTUAL DESKTOP
.PP
Fvwm provides multiple virtual desktops for users who wish to use
them\. The screen is a viewport onto a
\fIdesktop\fR
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
\fIpages\fR
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\.
.PP
The (m by n) size (i\.e\. number of pages) of the virtual desktops
can be changed any time, by using the
\fBDesktopSize\fR
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
\fBFvwmPager\fR,
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 using the
\fBWindowList\fR
command or the
\fBFvwmIconMan\fR
module\.
.PP
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
\fBLayer\fR
command\. The concept of layers is a generalization of the
\fIStaysOnTop\fR
flag of older fvwm versions\. The
\fIStaysOnTop\fR and
\fIStaysPut\fR
\fBStyle\fR
options are now implemented by putting the windows in suitable
layers and the previously missing
\fIStaysOnBottom\fR
\fBStyle\fR
option has been added\.
.PP
\fISticky\fR
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 xbiffs, 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\.
.PP
Window geometries are specified relative to the current viewport\.
That is:
.sp
.RS 4
.nf
xterm \-geometry +0+0
.fi
.RE
.PP
.PP
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:
.sp
.RS 4
.nf
xterm \-geometry +1000+1000
.fi
.RE
.PP
.PP
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:
.sp
.RS 4
.nf
xterm \-geometry \-5\-5
.fi
.RE
.PP
.PP
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\.
.PP
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\.
.PP
A better way to place windows on a different page, screen or desk
from the currently mapped viewport is to use the
\fIStartsOnPage\fR or
\fIStartsOnScreen\fR
style specification (the successors to the older
\fIStartsOnDesk\fR
style) in your
\fIconfig\fR
file\. The placement is consistent: it does
not depend on your current location on the virtual desktop\.
.PP
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:
.sp
.RS 4
.nf
xterm \-xrm "*Desk:1"
.fi
.RE
.PP
.PP
starts an xterm on desk number 1;
.sp
.RS 4
.nf
xterm \-xrm "*Page:3 2 1"
.fi
.RE
.PP
.PP
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
\fI\.Xdefaults\fR
file:
.sp
.RS 4
.nf
XTerm*Desk: 1
.fi
.RE
.PP
.PP
or
.sp
.RS 4
.nf
XTerm*Page: 3 2 1
.fi
.RE
.PP
.SH USE ON MULTI\-SCREEN DISPLAYS
.PP
If the
\fB\-s\fR
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
.sp
.RS 4
.nf
\fBEdgeScroll\fR 0 0
.fi
.RE
.PP
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
.PP
Fvwm supports the Xinerama extension of newer X servers
which is similar to multi head support (multiple screens) but
allows one to 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 \fIEdgeResistance\fR option
of the \fBStyle\fR command 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
\fBXinerama\fR command\. Many modules and commands work
nicely with Xinerama displays\.
.PP
Whenever 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\.
.sp
.RS 4
.nf
\fBStyle\fR * \fIIconBox\fR 64x300\-0\-0@p
.fi
.RE
.PP
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
\fBXineramaPrimaryScreen\fR
command\.
.PP
Xinerama support was designed to work out of the box with the same
configuration file that would work on a single screen\. It may
not perform very 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\. When
this happens, the windows or icons can be retrieved with the
command
.sp
.RS 4
.nf
\fBAll\fR \fBMoveToScreen\fR
.fi
.RE
.PP
that can be entered in an \fBFvwmConsole\fR window or
with \fBFvwmCommand\fR\.
.PP
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
\fBXineramaSls\fR, \fBXineramaSlsSize\fR and \fBXineramaSlsScreens\fR
are used to configure this feature\.
.SH INITIALIZATION
.PP
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
.sp
.RS 4
.nf
\fBRead\fR \fIconfig\fR
.fi
.RE
.PP
This looks for file
\fIconfig\fR in \fI$FVWM_USERDIR\fR and \fI$FVWM_DATADIR\fR
directories, as described in
\fBRead\fR\. 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):
.nf
.IP "" 4
\fI$HOME\fR/\.fvwm/config
/usr/local/share/fvwm/config
.fi
.nf
.IP "" 4
\fI$HOME\fR/\.fvwm/\.fvwm2rc
\fI$HOME\fR/\.fvwm2rc
/usr/local/share/fvwm/\.fvwm2rc
/usr/local/share/fvwm/system\.fvwm2rc
/etc/system\.fvwm2rc
.fi
.PP
Please note, the last 5 locations are not guaranteed to be
supported in the future\.
.PP
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\.
.PP
Fvwm sets two environment variables which are inherited by its
children\. These are
\fI$DISPLAY\fR
which describes the display on which fvwm is running\.
\fI$DISPLAY\fR
may be
\fIunix:0\.0\fR
or
\fI:0\.0\fR,
which doesn't work too well when passed through ssh to another
machine, so
\fI$HOSTDISPLAY\fR
is set to a network\-ready description of the display\.
\fI$HOSTDISPLAY\fR
always uses the TCP/IP transport protocol (even for a local
connection) so
\fI$DISPLAY\fR
should be used for local connections, as it may use Unix\-domain
sockets, which are faster\.
.PP
If you want to start some applications or modules with fvwm, you
can simply put
.sp
.RS 4
.nf
\fBExec\fR app
.fi
.RE
.PP
or
.sp
.RS 4
.nf
\fBModule\fR FvwmXxx
.fi
.RE
.PP
into your
\fIconfig\fR,
but it is not recommended; do this only if you know what you are
doing\. It is usually important 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\.
.PP
The standard way to start applications or modules on fvwm's start
up is to add them to an initialization function (usually
\fBStartFunction\fR or \fBInitFunction\fR)\.
This way they are only started after fvwm finishes to read and
execute
\fIconfig\fR
file\.
.PP
Fvwm has three special functions for initialization:
\fBStartFunction\fR,
which is executed on startups and restarts;
\fBInitFunction\fR and \fBRestartFunction\fR,
which are executed during initialization and restarts
(respectively) just after StartFunction\. These functions may be
customized in a user's
\fIconfig\fR
file using the
\fBAddToFunc\fR
command (described later) to start up modules, xterms, or whatever
you'd like to have started by fvwm\.
.PP
Fvwm has also a special exit function:
\fBExitFunction\fR,
executed when exiting or restarting before actually quitting\.
It could be used to explicitly kill modules, etc\.
.PP
If fvwm is run under a session manager, functions
\fBSessionInitFunction\fR and \fBSessionRestartFunction\fR
are executed instead of InitFunction and RestartFunction\.
This helps to define the user's
\fIconfig\fR
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
\fBSessionExitFunction\fR
is used instead of ExitFunction\.
.sp
.RS 4
.nf
\fBDestroyFunc\fR StartFunction
\fBAddToFunc\fR StartFunction
+ I \fBModule\fR \fBFvwmPager\fR * *
+ I \fBModule\fR \fBFvwmButtons\fR
\fBDestroyFunc\fR InitFunction
\fBAddToFunc\fR InitFunction
+ I \fBModule\fR \fBFvwmBanner\fR
+ I \fBModule\fR \fBFvwmIconMan\fR
+ I \fBExec\fR xsetroot \-solid cyan
+ I \fBExec\fR xterm
+ I \fBExec\fR netscape
\fBDestroyFunc\fR RestartFunction
\fBAddToFunc\fR RestartFunction
+ I \fBModule\fR \fBFvwmIconMan\fR
\fBDestroyFunc\fR SessionInitFunction
\fBAddToFunc\fR SessionInitFunction
+ I \fBModule\fR \fBFvwmBanner\fR
\fBDestroyFunc\fR SessionRestartFunction
\fBAddToFunc\fR SessionRestartFunction
+ I \fBNop\fR
.fi
.RE
.PP
You do not need to define all special functions if some are empty\.
Also note, all these special functions may be emulated now using
\fBStartFunction\fR and \fBExitFunction,\fR
like this:
.sp
.RS 4
.nf
\fBDestroyFunc\fR StartFunction
\fBAddToFunc\fR StartFunction
+ I \fBTest\fR (Init) \fBModule\fR \fBFvwmBanner\fR
+ I \fBModule\fR \fBFvwmPager\fR * *
+ I \fBTest\fR (Restart) \fBBeep\fR
\fBDestroyFunc\fR ExitFunction
\fBAddToFunc\fR ExitFunction
+ I \fBTest\fR (Quit) \fBEcho\fR Bye\-bye
+ I \fBKillModule\fR MyBuggyModule
+ I \fBTest\fR (ToRestart) \fBBeep\fR
.fi
.RE
.SH COMPILATION OPTIONS
.PP
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 \fIconfig\.h\fR file that is generated
during compilation\.
.SH ICONS AND IMAGES
.PP
Fvwm can load \fB\.xbm,\fR \fB\.xpm,\fR
\fB\.png\fR and
\fB\.svg\fR images\. \fBXBM\fR
images are monochrome\. Fvwm can always display
\fBXBM\fR files\. \fBXPM\fR
and \fBPNG\fR formats are color images\.
SVG is a vector graphics image format\.
Compile\-time options determine whether fvwm can display
\fBXPM\fR, \fBPNG\fR or
\fBSVG\fR
icons and images\. See the \fIINSTALL\.fvwm\fR
file for more information\.
.PP
The related \fBSHAPE\fR
compile\-time option can make fvwm display spiffy shaped icons\.
.SS SVG rendering options
.PP
SVG images are generated from (XML) text files\. A really simple SVG file
might look something like this:
.sp
.RS 4
.nf
.fi
.RE
.PP
By default, SVG images are rendered as the image creator intended
them to\. But since SVG is a vector graphics format, the images can
be rendered at any chosen size and rotation, e\.g\. making it possible
to use the same icon file rendered at different sizes for the
\fIIcon\fR and \fIMiniIcon\fR
styles\.
.PP
The rendering options are specified as a string appended to the SVG
filename as follows:
.HP 1
\fI\fIimage\.svg\fR\fR:[!] [(1)\ \fIsize\fR] [(2)\ \fIposition\fR]\ [(3)\ \fIrotation\fR]\ [(4)\ \fIscale\fR] ...
.HP 4
(1) [\-]\fIwidth\fR{x}[\-]\fIheight\fR
.sp -1n
.HP 4
(2) {\- | +}\fIxpos\fR{\- | +}\fIypos\fR
.sp -1n
.HP 4
(3) @[\-]\fIangle\fR
.sp -1n
.HP 4
(4) {* | /}[\-]\fIfactor\fR[x | y]
.PP
The option string always starts with a colon (':')
to separate it from the filename\. An empty option string can skip this
colon, but it might still be a good idea to include it to prevent
ambiguity if the filename contains any colon\.
.sp
.RS 4
.nf
filename_without_colon\.svg
filename:with:colon\.svg:
.fi
.RE
.PP
An exclamation point ('!') transposes the entire final
image (including the rendering area), i\.e\. all the horizontal and all the
vertical coordinates are swapped with each other\.
.sp
.RS 4
.nf
image\.svg:!
.fi
.RE
.PP
\fIwidth\fR and \fIheight\fR
specifies the dimensions of the rendering area in pixels, i\.e\. the
dimensions of the resulting image\. The actual image is fitted to fill
the entire rendering area\.
.sp
.RS 4
.nf
image\.svg:60x60
.fi
.RE
.PP
Use a \fIwidth\fR or \fIheight\fR
value of 0 to keep the aspect ratio\.
.sp
.RS 4
.nf
image\.svg:0x60
image\.svg:60x0
.fi
.RE
.PP
A '\-' before \fIwidth\fR
mirrors the rendering area horizontally\.
.sp
.RS 4
.nf
image\.svg:\-0x0
.fi
.RE
.PP
A '\-' before \fIheight\fR
mirrors the rendering area vertically\.
.sp
.RS 4
.nf
image\.svg:0x\-0
.fi
.RE
.PP
\fIxpos\fR and \fIypos\fR
specifies a translation of the image in pixels\. A positive
\fIxpos\fR value moves the image to the right\. A
positive \fIypos\fR value moves it down\. Moving
it partially outside of the rendering area results in a cropped
image\.
.sp
.RS 4
.nf
image\.svg:\-30\-0
image\.svg:\-0+10
image\.svg:\-30+10
.fi
.RE
.PP
\fIangle\fR specifies a rotation around the actual
image center in degrees\. This might result in a cropped image\. A
positive value rotates the image clockwise\. Floating point values are
recognized\.
.sp
.RS 4
.nf
image\.svg:@180
image\.svg:@\-90
image\.svg:@30
image\.svg:@57\.3
.fi
.RE
.PP
\fIfactor\fR specifes a scaling of the actual
image (not the rendering area)\. Scaling it up results in a cropped
image\. Floating point values are recognized\. Division by zero is
ignored\. If \fIfactor\fR is directly followed
by a 'x' or a 'y', the scaling
is horizontal or vertical respectively\. Otherwise the scaling is
uniform\.
.sp
.RS 4
.nf
image\.svg:*2
image\.svg:/2
image\.svg:/3x
image\.svg:/2y
.fi
.RE
.PP
Scaling down a translated or rotated image can prevent cropping\.
.sp
.RS 4
.nf
image\.svg:@30*0\.6
.fi
.RE
.PP
Repeated usage of translation, rotation, and scaling is allowed\.
Translation and rotation are additive\. Scaling is multiplicative\.
.sp
.RS 4
.nf
image\.svg:*2/3
image\.svg:/3x/2y
.fi
.RE
.PP
When combining affine transformations, the scaling is always done first,
then the rotation, and finally the translation\.
.sp
.RS 4
.nf
image\.svg:\-30+10@30/3x/2y
.fi
.RE
.PP
Use a negative scale \fIfactor\fR to mirror the
actual image\.
.sp
.RS 4
.nf
image\.svg:\-30+10@30/\-3x/2y
.fi
.RE
.PP
Mirroring of the rendering area is done after any scaling, rotation or
translation of the image\.
.sp
.RS 4
.nf
image\.svg:\-0x0\-30+10@30/3x/2y
.fi
.RE
.PP
Transposing is done last of all, after everything else\.
.sp
.RS 4
.nf
image\.svg:!\-0x0\-30+10@30/3x/2y
.fi
.RE
.SH MODULES
.PP
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\.
.PP
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\.
.PP
Modules can be spawned by fvwm at any time during the X session by
use of the
\fBModule\fR
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\.
.PP
Modules simply transmit commands to the fvwm command
engine\. Commands are formatted just as in the case of a
mouse binding in the
\fIconfig\fR
setup file\. Certain auxiliary information is also transmitted, as
in the sample module
\fBFvwmButtons\fR\.
.PP
Please refer to the
\fBModule Commands\fR
section for details\.
.SH ICCCM COMPLIANCE
.PP
Fvwm attempts to be
ICCCM
2\.0 compliant\. Check
\fIhttp://tronche\.com/gui/x/icccm/\fR for more info\. In addition,
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\.
.PP
The
ICCCM
states that windows possessing the property
.sp
.RS 4
.nf
WM_HINTS(WM_HINTS):
Client accepts input or input focus: False
.fi
.RE
.PP
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,
\fILenience\fR,
which allows fvwm to overlook this
ICCCM
rule\. Even with this window style it is not guaranteed that the
application accepts focus\.
.PP
The differences between
ICCCM
1\.1 and 2\.0 include the ability to take over from a running
ICCCM
2\.0 compliant window manager; thus
.sp
.RS 4
.nf
fvwm; vi ~/\.fvwm/config; fvwm \-replace
.fi
.RE
.PP
.PP
resembles the
\fBRestart\fR
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
\fI\.Xclients\fR or \fI\.Xsession\fR
file\.
.PP
Further additions are support for client\-side colormap
installation (see the
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 user's 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:
.sp
.RS 4
.nf
\fBAddToFunc\fR UrgencyFunc
+ I \fBIconify\fR off
+ I \fBFlipFocus\fR
+ I \fBRaise\fR
+ I \fBWarpToWindow !raise\fR 5p 5p
\fBAddToFunc\fR UrgencyDoneFunc
+ I \fBNop\fR
.fi
.RE
.SH GNOME COMPLIANCE
.PP
Fvwm attempts to be GNOME (version 1) compliant\.
Check \fIhttp://www\.gnome\.org\fR
for what that may mean\. To disable GNOME hints for some
or all windows, the
\fIGNOMEIgnoreHints\fR
style can be used\.
.SH EXTENDED WINDOW MANAGER HINTS
.PP
Fvwm attempts to respect the extended window manager hints (ewmh
or EWMH for short) specification:
\fIhttp://www\.freedesktop\.org/wiki/Standards_2fwm_2dspec\fR
and some extensions of this specification\. This allows fvwm to
work with
KDE
version >= 2,
GNOME
version 2 and other applications which respect this specification
(any application based on
\fIGTK+\fR
version 2)\. Applications which respect this specification are
called ewmh compliant applications\.
.PP
This support is configurable with styles and commands\.
These styles and commands have
EWMH
as the prefix (so you can find them easily in this man page)\.
.PP
There is a new Context 'D' for the
\fBKey\fR,
\fBPointerKey\fR,
\fBMouse\fR and
\fBStroke\fR
commands\. This context is for desktop applications (such as
kdesktop and Nautilus desktop)\.
.PP
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
\fBEWMHActivateWindowFunc\fR
which by default is Iconify Off, Focus and Raise\. You can redefine
this function\. For example:
.sp
.RS 4
.nf
\fBDestroyFunc\fR EWMHActivateWindowFunc
\fBAddToFunc\fR EWMHActivateWindowFunc I \fBIconify\fR Off
+ I \fBFocus\fR
+ I \fBRaise\fR
+ I \fBWarpToWindow\fR 50 50
.fi
.RE
.PP
additionally warps the pointer to the center of the window\.
.PP
The
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
\fBEwmhBaseStruts\fR
command\.
.SH MWM COMPATIBILITY
.PP
Fvwm provides options to emulate Motif Window Manager (Mwm) as
well as possible\. Please refer to the
\fBEmulate\fR
command as well as to the Mwm specific options of the
\fBStyle\fR and
\fBMenuStyle\fR
commands for details\.
.SH OPEN LOOK AND XVIEW COMPATIBILITY
.PP
Fvwm supports all the Open Look decoration hints (except
pushpins)\. Should you use any such application, please add the
following line to your config:
.sp
.RS 4
.nf
\fBStyle\fR * \fIOLDecor\fR
.fi
.RE
.PP
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 \fINeverFocus\fR
focus policy and the \fILenience\fR
style for all such applications (the windows still get the
focus):
.sp
.RS 4
.nf
\fBStyle\fR \fINeverFocus\fR, \fILenience\fR
.fi
.RE
.PP
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
\fILenience\fR style:
.sp
.RS 4
.nf
\fBStyle\fR \fIMouseFocus\fR, \fILenience\fR
\fBStyle\fR \fISloppyFocus\fR, \fILenience\fR
\fBStyle\fR \fIClickToFocus\fR, \fILenience\fR
.fi
.RE
.SH M4 PREPROCESSING
.PP
M4 pre\-processing is handled by a module in fvwm\. To get more
details, try man
\fBFvwmM4\fR\.
In short, if you want fvwm to parse your files with m4, then
replace the command
\fBRead\fR
with
\fBFvwmM4\fR
in your
\fI~/\.fvwm/config\fR
file (if it appears at all), and start fvwm with the command
.sp
.RS 4
.nf
fvwm \-cmd "\fBFvwmM4\fR config"
.fi
.RE
.PP
.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
\fBM4\fR
section, but replace "m4" with "cpp"\.
.SH CONFIGURATION
.SS Configuration Files
.PP
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
\fIconfig\fR (or \fI\.fvwm2rc\fR)\.
By using the
\fBRead\fR
command, it is easy to read in new configuration files as you go\.
.PP
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\.
.PP
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\.
.SS Supplied Configuration
.PP
A sample configuration file,
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 from \fI/usr/local/share/fvwm/config\fR file\.
.PP
Alternatively, the built\-in menu (accessible when no
configuration file is found) has options to create an initial
config file for the user\.
.SH FONTS
.SS Font names and font loading
.PP
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 \fBStyle\fR, the Font \fBMenuStyle\fR and the \fBDefaultFont\fR
commands\. 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\.
.PP
First, you can use what we can call a usual font name, for
example,
.sp
.RS 4
.nf
\-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
.fi
.RE
.PP
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
.sp
.RS 4
.nf
\-adobe\-courier\-bold\-r\-normal\-\-10\-*
.fi
.RE
.PP
if the locale charset is ISO8859\-1, then fvwm tries to load a
font which matches
.sp
.RS 4
.nf
\-adobe\-courier\-bold\-r\-normal\-\-10\-*\-ISO8859\-1
.fi
.RE
.PP
with the locale charset ISO8859\-15 fvwm tries to load
.sp
.RS 4
.nf
\-adobe\-courier\-bold\-r\-normal\-\-10\-*\-ISO8859\-15\.
.fi
.RE
.PP
A font name can be given as an extended XLFD\. This
is a comma separated list of (simple) XLFD font names, for example:
.sp
.RS 4
.nf
\-adobe\-courier\-bold\-r\-normal\-\-14\-*,\-*\-courier\-medium\-r\-normal\-\-14\-*
.fi
.RE
.PP
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\.
.PP
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\.
.PP
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:
.sp
.RS 4
.nf
"xft:Luxi Mono"
"xft:Luxi Mono:Medium:Roman:size=14:encoding=iso8859\-1"
.fi
.RE
.PP
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 possibilities: 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
\fBFvwmIdent\fR, 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\.
.PP
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))\.
.PP
After an Xft font name you can add after a ";" an XLFD
font name (simple or extended) as:
.sp
.RS 4
.nf
xft:Verdana:pixelsize=14;\-adobe\-courier\-bold\-r\-normal\-\-14\-*
.fi
.RE
.PP
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\.
.SS Font and string encoding
.PP
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\.
.PP
To override the previous rules, it is possible to specify the
string encoding in the beginning of a font description as follow:
.sp
.RS 4
.nf
StringEncoding=\fIenc\fR:_full_font_name_
.fi
.RE
.PP
where
\fIenc\fR
is an encoding supported by fvwm (usually font name charset plus some
unicode encodings: UTF\-8, USC\-2, USC\-4 and UTF\-16)\.
.PP
For example, you may use an iso8859\-1 locale charset and have an
\fBFvwmForm\fR in Russian using koi8\-r encoding\. In this case, you just
have to ask \fBFvwmForm\fR 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:
.sp
.RS 4
.nf
StringEncoding=jisx0208\.1983\-0:\-*\-fixed\-medium\-r\-*\-ja\-*\-iso10646\-1
.fi
.RE
.PP
or
.sp
.RS 4
.nf
"StringEncoding=jisx0208\.1983\-0:xft:Bitstream Cyberbit"
.fi
.RE
.PP
if your
\fBFvwmForm\fR
configuration uses jisx0208\.1983\-0 encoding\. Another possibility
is to use UTF\-8 encoding for your \fBFvwmForm\fR configuration and use
an iso10646\-1 font:
.sp
.RS 4
.nf
\-*\-fixed\-medium\-r\-*\-ja\-*\-iso10646\-1
.fi
.RE
.PP
or
.sp
.RS 4
.nf
"StringEncoding=UTF\-8:xft:Bitstream Cyberbit"
.fi
.RE
.PP
or equivalently
.sp
.RS 4
.nf
"xft:Bitstream Cyberbit:encoding=iso10646\-1"
.fi
.RE
.PP
In general iso10646\-1 fonts together with UTF\-8 string encoding
allows the display of any characters in a given menu, \fBFvwmForm\fR
etc\.
.PP
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:
.sp
.RS 4
.nf
StringEncoding=UTF\-8:\-*\-pretty_font\-*\-12\-*
.fi
.RE
.PP
In most cases, fvwm correctly determines the encoding of the
font\. However, some fonts do not end with valid encoding
names\. When the font name isn't normal, for example:
.sp
.RS 4
.nf
\-misc\-fixed\-*\-\-20\-*\-my_utf8\-36
.fi
.RE
.PP
you need to add the encoding after the font name using a slash as
a delimiter\. For example:
.sp
.RS 4
.nf
\fBMenuStyle\fR * \fIFont\fR \-misc\-fixed\-*\-\-20\-*\-my_utf8\-36/iso10646\-1
.fi
.RE
.PP
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:
.sp
.RS 4
.nf
\fBStyle\fR * \fIFont\fR \-misc\-fixed\-*\-\-14\-*\-iso8859\-1/*/latin1
.fi
.RE
.PP
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:
.sp
.RS 4
.nf
\fBStyle\fR * \fIFont\fR \e
\-misc\-fixed\-*\-\-14\-*\-local8859\-6/iso8859\-6/local_iso8859_6_iconv
.fi
.RE
.PP
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\.
.SS Font Shadow Effects
.PP
Fonts can be given 3d effects\. At the beginning of the font name
(or just after a possible StringEncoding specification) add
.sp
.RS 4
.nf
Shadow=\fIsize\fR [\fIoffset\fR] [\fIdirections]\fR]:
.fi
.RE
.PP
\fIsize\fR
is a positive integer which specifies the number of pixels of shadow\.
\fIoffset\fR
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\.
\fIdirections\fR
is an optional set of directions the shadow emanates from the
character\. The
\fIdirections\fR
are a space separated list of fvwm directions:
.PP
\fIN\fR, \fINorth\fR, \fITop\fR, \fIt\fR, \fIUp\fR, \fIu\fR, \fI\-\fR
.PP
\fIE\fR, \fIEast\fR, \fIRight\fR, \fIr\fR, \fIRight\fR, \fIr\fR, \fI]\fR
.PP
\fIS\fR, \fISouth\fR, \fIBottom\fR, \fIb\fR, \fIDown\fR, \fId\fR, \fI_\fR
.PP
\fIW\fR, \fIWest\fR, \fILeft\fR, \fIl\fR, \fILeft\fR, \fIl\fR, \fI[\fR
.PP
\fINE\fR, \fINorthEast\fR, \fITopRight\fR, \fItr\fR, \fIUpRight\fR, \fIur\fR, \fI^\fR
.PP
\fISE\fR, \fISouthEast\fR, \fIBottomRight\fR, \fIbr\fR, \fIDownRight\fR, \fIdr\fR, \fI>\fR
.PP
\fISW\fR, \fISouthWest\fR, \fIBottomLeft\fR, \fIbl\fR, \fIDownLeft\fR, \fIdl\fR, \fIv\fR
.PP
\fINW\fR, \fINorthWest\fR, \fITopLeft\fR, \fItl\fR, \fIUpLeft\fR, \fIul\fR, \fI<\fR
.PP
\fIC\fR, \fICenter\fR, \fICentre\fR, \fI\.\fR
.PP
A shadow is displayed in each given direction\.
\fIAll\fR
is equivalent to all the directions\. The default
\fIdirection\fR
is
\fIBottomRight\fR\.
With the
\fICenter\fR
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\.
.PP
The shadow effect only works with colorsets\. The color of the
shadow is defined by using the
\fIfgsh\fR
option of the
\fBColorset\fR
command\. Please refer to the
\fBColorsets\fR
section for details about colorsets\.
.PP
Note: It can be difficult to find the font,
\fIfg\fR, \fIfgsh\fR and \fIbg\fR
colors to make this effect look good, but it can look quite good\.
.SH BI\-DIRECTIONAL TEXT
.PP
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
\fIbidi\fR
(bi\-directional) support\. For example, this includes iso8859\-6,
iso8859\-8 and iso10646\-1 (unicode), but not other iso8859\-* fonts\.
.PP
This bi\-directional text support is done using the
\fIfribidi\fR
library compile time option, see
\fIINSTALL\.fvwm\fR\.
.SH KEYBOARD SHORTCUTS
.PP
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
\fBScroll\fR
command to appropriate keys,
\fBPopup\fR,
\fBMove\fR,
\fBResize\fR,
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
.PP
Fvwm supports session management according to the X Session
Management Protocol\. It saves and restores window position, size,
stacking order, desk, stickiness, shadiness, maximizedness,
iconifiedness for all windows\. Furthermore, some global state is
saved\.
.PP
Fvwm doesn't save any information regarding styles, decors,
functions or menus\. If you change any of these resources during a
session (e\.g\. by issuing
\fBStyle\fR
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\.
.PP
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
\fBQuit\fR
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
\fBQuit\fR
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,
.sp
.RS 4
.nf
\fBExec\fR exec killall fvwm
.fi
.RE
.PP
still kills all copies of fvwm\. Your system must have the
\fBkillall\fR
command though\.
.SH BOOLEAN ARGUMENTS
.PP
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 BUILTIN KEY AND MOUSE BINDINGS
.PP
The following commands are built\-in to fvwm:
.sp
.RS 4
.nf
\fBKey\fR Help R A \fBPopup\fR MenuFvwmRoot
\fBKey\fR F1 R A \fBPopup\fR MenuFvwmRoot
\fBKey\fR Tab A M \fBWindowList\fR Root c c NoDeskSort
\fBKey\fR Escape A MC \fBEscapeFunc\fR
\fBMouse\fR 1 R A \fBMenu\fR MenuFvwmRoot
\fBMouse\fR 1 T A FuncFvwmRaiseLowerX \fBMove\fR
\fBMouse\fR 1 FS A FuncFvwmRaiseLowerX \fBResize\fR
\fBMouse\fR 2 FST A FuncFvwmRaiseLowerX \fBMove\fR
\fBAddToFunc\fR FuncFvwmRaiseLowerX
+ I \fBRaise\fR
+ M $0
+ D \fBLower\fR
.fi
.RE
.PP
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\.
.PP
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\.
.PP
Mouse button 1 on the title\-bar or side frame can move, raise or
lower a window\.
.PP
Mouse button 1 on the window corners can resize, raise or lower a
window\.
.PP
You can override or remove these bindings\. To remove the window
list binding, use this:
.sp
.RS 4
.nf
\fBKey\fR Tab A M \-
.fi
.RE
.SH COMMAND EXECUTION
.SS Module and Function Commands
.PP
If fvwm encounters a command that it doesn't recognize,
it checks to see if the
specified command should have been
.sp
.RS 4
.nf
\fBFunction\fR (rest of command)
.fi
.RE
.PP
or
.sp
.RS 4
.nf
\fBModule\fR (rest of command)
.fi
.RE
.PP
This allows complex functions or modules to be invoked in a manner
which is fairly transparent to the configuration file\.
.PP
Example: the
\fIconfig\fR
file contains the line
.sp
.RS 4
.nf
HelpMe
.fi
.RE
.PP
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"\.
.SS Delayed Execution of Commands
.PP
Note: There are many commands that affect look and feel of
specific, some or all windows, like
\fBStyle\fR, \fBMouse\fR, \fBColorset\fR, \fBTitleStyle\fR
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
\fBStyle\fR
options that are set in a function are not applied until after the
function has completed\. This can sometimes lead to unwanted
effects\.
.PP
To force that all pending changes are applied immediately, use the
\fBUpdateStyles\fR, \fBRefresh\fR or \fBRefreshWindow\fR
commands\.
.SH QUOTING
.PP
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 do not need
quotes:
.sp
.RS 4
.nf
\fBPopup\fR Window\-Ops
.fi
.RE
.PP
but if you replace the dash with a space, then you need
quotes:
.sp
.RS 4
.nf
\fBPopup\fR "Window Ops"
.fi
.RE
.PP
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
.PP
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 "$$"\.
.PP
If a command is prefixed with a '\-' parameter expansion isn't
performed\. This applies to the command immediately following the '\-',
in which the expansion normally would have taken place\. When uesed
together with other prefix commands it must be added before the other
prefix\.
.PP
Example:
.sp
.RS 4
.nf
\fBPick\fR \-\fBExec\fR exec xmessage '$[w\.name]'
.fi
.RE
.PP
opens an xmessage dialog with "$[w\.name]" unexpanded\.
.PP
The longer variables may contain additional variables inside the
name, which are expanded before the outer variable\.
.PP
In earlier versions of fvwm, some single letter variables were
supported\. It is deprecated now, since they cause a number of
problems\. You should use the longer substitutes instead\.
.PP
Example:
.sp
.RS 4
.nf
# Print the current desk number, horizontal page number
# and the window's class (unexpanded here, no window)\.
\fBEcho\fR $[desk\.n] $[page\.nx] $[w\.class]
.fi
.RE
.PP
Note: If the command is called outside a window context, it
prints "$[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
\fBCurrent\fR
command can be used:
.sp
.RS 4
.nf
\fBCurrent\fR \fBEcho\fR $[desk\.n] $[page\.nx] $[w\.class]
.fi
.RE
.PP
The parameters known by fvwm are:
.PP
$$
.RS 4
A literal '$'\.
.RE
.PP
$\.
.RS 4
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 '\.'\.
.RE
.PP
$0 to $9
.RS 4
The positional parameters given to a complex function (a function that has been defined with the
\fBAddToFunc\fR
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\.
.RE
.PP
$*
.RS 4
All positional parameters given to a complex function\. This includes parameters that follow after "$9"\.
.RE
.PP
$[\fIn\fR]
.RS 4
The
\fIn\fR:th positional parameter given to a complex function, counting from 0\. If the corresponding parameter is undefined, the "$[\fIn\fR]" is deleted from the command line\. The parameter is expanded unquoted\.
.RE
.PP
$[\fIn\fR\-\fIm\fR]
.RS 4
The positional parameters given to a complex function, starting with parameter
\fIn\fR
and ending with parameter
\fIm\fR\. If all the corresponding parameters are undefined, the "$[\.\.\.]" is deleted from the command line\. If only some of the parameters are defined, all defined parameters are expanded, and the remaining silently ignored\. All parameters are expanded unquoted\.
.RE
.PP
$[\fIn\fR\-]
.RS 4
All the positional parameters given to a complex function, starting with parameter
\fIn\fR\. If all the corresponding parameters are undefined, the "$[\.\.\.]" is deleted from the command line\. All parameters are expanded unquoted\.
.RE
.PP
$[*]
.RS 4
All the positional parameters given to a complex function\. This is equivalent of $[0\-]\.
.RE
.PP
$[version\.num]
.RS 4
The version number, like "2\.6\.0"\.
.RE
.PP
$[version\.info]
.RS 4
The version info, like " (from cvs)", empty for the official releases\.
.RE
.PP
$[version\.line]
.RS 4
The first line printed by the \-\-version command line option\.
.RE
.PP
$[vp\.x] $[vp\.y] $[vp\.width] $[vp\.height]
.RS 4
Either coordinate or the width or height of the current viewport\.
.RE
.PP
$[wa\.x] $[wa\.y] $[wa\.width] $[wa\.height]
.RS 4
Either coordinate or the width or height of the EWMH working area\.
.RE
.PP
$[dwa\.x] $[dwa\.y] $[dwa\.width] $[dwa\.height]
.RS 4
Either coordinate or the width or height of the dynamic EWMH working area\.
.RE
.PP
$[desk\.n]
.RS 4
The current desk number\.
.RE
.PP
$[desk\.name]
.RS 4
These parameters are replaced with the name of the desktop number that is defined with the
\fBDesktopName\fR
command\. If no name is defined, then the default name is returned\.
.RE
.PP
$[desk\.width] $[desk\.height]
.RS 4
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\.
.RE
.PP
$[desk\.pagesx] $[desk\.pagesy]
.RS 4
The number of total pages in a desk in x or y direction\. This is the same as the values set by
\fBDesktopSize\fR\.
.RE
.PP
$[page\.nx] $[page\.ny]
.RS 4
The current page numbers, by X and Y axes, starting from 0\.
\fIpage\fR
is equivalent to
\fIarea\fR
in the
GNOME
terminology\.
.RE
.PP
$[w\.id]
.RS 4
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\.
.RE
.PP
$[w\.name] $[w\.iconname] $[w\.class] $[w\.resource] $[w\.visiblename] $[w\.iconfile] $[w\.miniiconfile] $[w\.iconfile\.svgopts] $[w\.miniiconfile\.svgopts]
.RS 4
The window's name, icon name, resource class and resource name, visible name, file name of its icon or mini icon defined with the
\fIIcon\fR
or
\fIMiniIcon\fR
style (including the full path if the file was found on disk), and (if fvwm is compiled with
SVG
support) the icon or mini icon svg rendering options (including the leading colon), or unexpanded "$[w\.]" string if no window is associated with the command\.
.sp
Note, the first 5 variables may include any kind of characters, so these variables are quoted\. It means that the value is surrounded by single quote characters and any contained single quote is prefixed with a backslash\. This guarantees that commands like:
.sp
.RS 4
.nf
\fBStyle\fR $[w\.resource] \fIIcon\fR norm/network\.png
.fi
.RE
.sp
work correctly, regardless of any special symbols the value may contain, like spaces and different kinds of quotes\.
.sp
In the case of the window's visible name, this is the value returned from the literal title of the window shown in the titlebar\. Typically this will be the same as $[w\.name] once expanded, although in the case of using
\fIIndexedWindowName\fR
then this is more useful a distinction, and allows for referencing the specific window by its visible name for inclusion in things like
\fBStyle\fR
commands\.
.RE
.PP
$[w\.x] $[w\.y] $[w\.width] $[w\.height]
.RS 4
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\.
.RE
.PP
$[w\.desk]
.RS 4
The number of the desk on which the window is shown\. If the window is sticky the current desk number is used\.
.RE
.PP
$[w\.layer]
.RS 4
The layer of the window\.
.RE
.PP
$[w\.screen]
.RS 4
The screen number the window is on\. If Xinerama is not present, this returns the number 0\.
.RE
.PP
$[cw\.x] $[cw\.y] $[cw\.width] $[cw\.height]
.RS 4
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\.
.RE
.PP
$[i\.x], $[it\.x], $[ip\.x] $[i\.y], $[it\.y], $[ip\.y] $[i\.width], $[it\.width], $[ip\.width] $[i\.height], $[it\.height], $[ip\.height]
.RS 4
These work like $[w\.\.\.\.] but return the geometry of the icon ($[i\.\.\.\.]), the icon title ($[it\.\.\.\.]) or the icon picture ($[ip\.\.\.\.])\.
.RE
.PP
$[pointer\.x] $[pointer\.y]
.RS 4
These return the position of the pointer on the screen\. If the pointer is not on the screen, these variables are not expanded\.
.RE
.PP
$[pointer\.wx] $[pointer\.wy]
.RS 4
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\.
.RE
.PP
$[pointer\.cx] $[pointer\.cy]
.RS 4
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\.
.RE
.PP
$[pointer\.screen]
.RS 4
The screen number the pointer is currently on\. Returns 0 if Xinerama is not enabled\.
.RE
.PP
$[screen]
.RS 4
The screen number fvwm is running on\. Useful for setups with multiple screens\.
.RE
.PP
$[fg\.cs] $[bg\.cs] $[hilight\.cs] $[shadow\.cs]
.RS 4
These parameters are replaced with the name of the foreground (fg), background (bg), hilight (hilight) or shadow (shadow) color that is defined in colorset (replace 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
\fBColorsets\fR
section for details about colorsets\.
.RE
.PP
$[schedule\.last]
.RS 4
This is replaced by the id of the last command that was scheduled with the
\fBSchedule\fR
command, even if this command was already executed\.
.RE
.PP
$[schedule\.next]
.RS 4
This is replaced by the id the next command used with
\fBSchedule\fR
will get (unless a different id is specified explicitly)\.
.RE
.PP
$[cond\.rc]
.RS 4
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
\fBConditional Commands\fR
in the command list\.
.RE
.PP
$[func\.context]
.RS 4
The context character of the running command as used in the
\fBMouse\fR,
\fBKey\fR
or
\fBPointerKey\fR
command\. This is useful for example with:
.sp
.RS 4
.nf
\fBMouse\fR 3 FS N \fBWindowShade\fR $$[func\.context]
.fi
.RE
.sp
.RE
.PP
$[gt\.\fIstr\fR]
.RS 4
return the translation of
\fIstr\fR
by looking in the current locale catalogs\. If no translation is found
\fIstr\fR
is returned as is\. See the
\fBLocalePath\fR
command\.
.RE
.PP
$[infostore\.\fIkey\fR]
.RS 4
Return the value of the item stored in the InfoStore at the given
\fIkey\fR\. If no key is present, the unexpanded string is returned\.
.RE
.PP
$[\.\.\.]
.RS 4
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\.
.RE
.PP
Some examples can be found in the description of the
\fBAddToFunc\fR
command\.
.SH SCRIPTING & COMPLEX FUNCTIONS
.PP
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
\fBRead\fR,
from the output of a command with
\fBPipeRead\fR
or written as a complex function with the
\fBAddToFunc\fR
command\. For the curious, section 7 of the fvwm FAQ shows some
real life applications of scripting\. Please refer to the sections
\fBUser Functions and Shell Commands\fR
and
\fBConditional Commands\fR
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
\fBRead\fR
or
\fBPipeRead\fR
command instead\.
.SH LIST OF FVWM COMMANDS
.PP
The command descriptions below are grouped together in the
following sections\. The sections are hopefully sorted in order of
usefulness to the newcomer\.
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBMenu commands\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBMiscellaneous commands\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBCommands affecting window movement and placement\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBCommands for focus and mouse movement\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBCommands controlling window state\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBCommands for mouse, key and stroke bindings\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBThe Style command (controlling window styles)\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBOther commands controlling window styles\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBCommands controlling the virtual desktop\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBCommands for user functions and shell commands\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBConditional commands\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBModule commands\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBQuit, restart and session management commands\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBColorsets\fR
.sp
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'\fBColor gradients\fR
.sp
.RE
.SS Menus
.PP
Before a menu can be opened, it has to be populated with menu
items using the
\fBAddToMenu\fR
command and bound to a key or mouse button with the
\fBKey\fR,
\fBPointerKey\fR or
\fBMouse\fR
command (there are many other ways to invoke a menu too)\. This is
usually done in the configuration file\.
.PP
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
\fBMenuStyle\fR
command to learn more\.
.TP
.B Types of Menus
.RS
.\".PP
In fvwm there are four slightly different types of menus:
.PP
\fBPopup\fR menus
can appear everywhere on the screen on their own or attached to a
part of a window\. The
\fBPopup\fR
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\.
.PP
\fBMenu\fR
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\.
.PP
\fITear off menus\fR or \fIPin up menus\fR
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
\fBTearMenuOff\fR
command from inside a menu\.
.PP
\fISub menus\fR
are menus inside menus\. When a menu item that has the
\fBPopup\fR
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\.
.RE
.TP
.B Menu Anatomy
.RS
.\".PP
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\.
.PP
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\. The
"More\.\.\." string honors the locale settings\.
.PP
Finally, there may be a picture running up either side of the menu
(a "side bar")\.
.RE
.TP
.B Menu Navigation
.RS
.\".PP
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
\fBTear Off Menus\fR
section for details\.
.RE
.TP
.B Mouse Navigation
.RS
.\".PP
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 by default 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\.
.PP
Scrolling a mouse wheel over a menu either wraps the pointer along the
menu (default), scrolls the menu under the pointer or act as if the
menu was clicked depending on the
\fIMouseWheel\fR menu style\.
.PP
Clicking on a selected item activates it \- what happens exactly
depends on the type of the item\.
.PP
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)\.
.PP
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\.
.RE
.TP
.B Keyboard Navigation
.RS
.\".PP
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)\.
.PP
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
\fIAutomaticHotkeys\fR
menu style fvwm automatically assigns hotkeys to all menu items\.
.PP
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 by default:
.PP
\fIEnter\fR,
\fIReturn\fR,
\fISpace\fR
activate the current item\.
.PP
\fIEscape\fR,
\fIDelete\fR,
\fICtrl\-G\fR
exit the current sequence of menus or destroy a tear off menu\.
.PP
\fIJ\fR,
\fIN\fR,
\fICursor\-Down\fR,
\fITab\fR,
\fIMeta\-Tab\fR,
\fICtrl\-F\fR,
move to the next item\.
.PP
\fIK\fR,
\fIP\fR,
\fICursor\-Up\fR,
\fIShift\-Tab\fR,
\fIShift\-Meta\-Tab\fR,
\fICtrl\-B\fR,
move to the prior item\.
.PP
\fIL\fR,
\fICursor\-Right\fR,
\fIF\fR
enter a sub menu\.
.PP
\fIH\fR,
\fICursor\-Left\fR,
\fIB\fR
return to the prior menu\.
.PP
\fICtrl\-Cursor\-Up\fR,
\fICtrl\-K\fR
\fICtrl\-P\fR,
\fIShift\-Ctrl\-Meta\-Tab\fR,
\fIPage\-Up\fR
move up five items\.
.PP
\fICtrl\-Cursor\-Down\fR,
\fICtrl\-J\fR
\fICtrl\-N\fR,
\fICtrl\-Meta\-Tab\fR
\fIPage\-Down\fR
move down five items\.
.PP
\fIShift\-P\fR,
\fIHome\fR,
\fIShift\-Cursor\-Up\fR,
\fICtrl\-A\fR
move to the first item\.
.PP
\fIShift\-N\fR,
\fIEnd\fR,
\fIShift\-Cursor\-Down\fR,
\fICtrl\-E\fR
move to the last item\.
.PP
\fIMeta\-P\fR,
\fIMeta\-Cursor\-Up\fR,
\fICtrl\-Cursor\-Left\fR,
\fIShift\-Ctrl\-Tab\fR,
move up just below the next separator\.
.PP
\fIMeta\-N\fR,
\fIMeta\-Cursor\-Down\fR,
\fICtrl\-Cursor\-Right\fR,
\fICtrl\-Tab\fR,
move down just below the next separator\.
.PP
\fIInsert\fR
opens the "More\.\.\." sub menu if any\.
.PP
\fIBackspace\fR
tears off the menu\.
.RE
.TP
.B Menu Bindings
.RS
.\".PP
The keys and mouse buttons used to navigate the menu can be configured
using the
\fBKey\fR
and
\fBMouse\fR
commands with the special context 'M', possible combined with 'T' for
the menu title, 'I' for other menu items, 'S' for any border or
sidepic, '[' for left border including a left sidepic, ']' for right
border including a right sidepic, '\-' for top border, '_' for bottom
border\. The menu context uses its own set of actions that can be bound
to keys and mouse buttons\. These are
\fIMenuClose\fR,
\fIMenuCloseAndExec\fR,
\fIMenuEnterContinuation\fR,
\fIMenuEnterSubmenu\fR,
\fIMenuLeaveSubmenu\fR,
\fIMenuMoveCursor\fR,
\fIMenuCursorLeft\fR,
\fIMenuCursorRight\fR,
\fIMenuSelectItem\fR,
\fIMenuScroll\fR and
\fIMenuTearOff\fR\.
.PP
It is not possible to override the key Escape with no modifiers for
closing the menu\. Neither is it possible to undefine mouse button 1,
the arrow keys or the enter key for minimal navigation\.
.PP
\fBMenuClose\fR
exits from the current sequence of menus or destroys a tear off menu\.
.PP
\fBMenuCloseAndExec\fR
exits from the current sequence of menus or destroys a tear off menu and
executes the rest of the line as a command\.
.PP
\fBMenuEnterContinuation\fR
opens the "More\.\.\." sub menu if any\.
.PP
\fBMenuEnterSubmenu\fR
enters a sub menu\.
.PP
\fBMenuLeaveSubmenu\fR
returns to the prior menu\.
.PP
\fBMenuMoveCursor\fR
\fIn\fR
[\fIm\fR]
moves the selection to another item\. If the first argument is zero
the second argument specifies an absolute item in the menu to move
the pointer to\. Negative items are counted from the end of the menu\.
If the first argument is non\-zero, the second argument must be omitted,
and the first argument specifies a relative change in the selected item\.
The positions may be suffixed with a 's' to indicate that the items should
refer only to the first items after separators\.
.PP
\fBMenuCursorLeft\fR
enters a sub menu with the
\fISubmenusLeft\fR
menu style, and returns to the prior menu with the
\fISubmenusRight\fR menu style\.
.PP
\fBMenuCursorRight\fR
enters a sub menu with the
\fISubmenusRight\fR
menu style, and returns to the prior menu with the
\fISubmenusLeft\fR menu style\.
.PP
\fBMenuSelectItem\fR
triggers the action for the menu item\.
.PP
\fBMenuScroll \fR\fIn\fR
performs menu scrolling according to the
\fIMouseWheel\fR menu style with
\fIn\fR items\. The distance can be
suffixed with an 's' to indicate the items should refer only to the
first items after separators\.
.PP
\fBMenuTearOff\fR
turns a normal menu into a "torn off" menu\. See
\fBTear Off Menus\fR
for details\.
.RE
.TP
.B Tear Off Menus
.RS
.\".PP
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
\fBTearMenuOff\fR\.
.PP
The builtin tear off actions can be overridden by undefining the
builtin menu actions bound to tear off\. To remove the builtin mouse
button 2 binding, use:
.sp
.RS 4
.nf
\fBMouse\fR 2 MT A \-
.fi
.RE
.PP
and to remove the builtin backspace binding, use:
.sp
.RS 4
.nf
\fBKey\fR Backspace M A \-
.fi
.RE
.PP
See the section
\fBMenu Bindings\fR
for details on how to assign other bindings for tear off\.
.PP
Note that prior to fvwm 2\.5\.20 the tear off mouse bindings were
redefined in different way, which no longer work\.
.PP
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:
.sp
.RS 4
.nf
\fBStyle\fR fvwm_menu \fIUsePPosition\fR
.fi
.RE
.PP
To remove borders and buttons from a tear\-off menu but keep the
menu title, you can use
.sp
.RS 4
.nf
\fBStyle\fR fvwm_menu !\fIButton\fR 0, !\fIButton\fR 1
\fBStyle\fR fvwm_menu !\fIButton\fR 2, !\fIButton\fR 3
\fBStyle\fR fvwm_menu !\fIButton\fR 4, !\fIButton\fR 5
\fBStyle\fR fvwm_menu !\fIButton\fR 6, !\fIButton\fR 7
\fBStyle\fR fvwm_menu !\fIButton\fR 8, !\fIButton\fR 9
\fBStyle\fR fvwm_menu \fITitle\fR, \fIHandleWidth\fR 0
.fi
.RE
.PP
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\.
.PP
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\.
.PP
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\.
.PP
To create a tear off menu without opening the normal menu first,
the option
\fITearOffImmediately\fR
can be added to the
\fBMenu\fR or \fBPopup\fR
command\.
.RE
.TP
\fBAddToMenu\fR \fImenu\-name\fR [\fImenu\-label\fR\ \fIaction\fR]
.RS
.\".PP
Begins or adds to a menu definition\. Typically a menu definition
looks like this:
.sp
.RS 4
.nf
AddToMenu Utilities Utilities \fBTitle\fR
+ Xterm \fBExec\fR exec xterm \-e tcsh
+ Rxvt \fBExec\fR exec rxvt
+ "Remote Logins" \fBPopup\fR Remote\-Logins
+ Top \fBExec\fR exec rxvt \-T Top \-n Top \-e top
+ Calculator \fBExec\fR exec xcalc
+ Xman \fBExec\fR exec xman
+ Xmag \fBExec\fR exec xmag
+ emacs \fBExec\fR exec xemacs
+ Mail MailFunction xmh "\-font fixed"
+ "" \fBNop\fR
+ Modules \fBPopup\fR Module\-Popup
+ "" \fBNop\fR
+ Exit Fvwm \fBPopup\fR Quit\-Verify
.fi
.RE
.PP
The menu could be invoked via
.sp
.RS 4
.nf
\fBMouse\fR 1 R A \fBMenu\fR Utilities Nop
.fi
.RE
.PP
or
.sp
.RS 4
.nf
\fBMouse\fR 1 R A \fBPopup\fR Utilities
.fi
.RE
.PP
There is no end\-of\-menu symbol\. Menus do not have to be defined
in a contiguous region of the
\fIconfig\fR
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
\fBNop\fR
function are used to insert a separator into the menu\.
.PP
The keywords
\fIDynamicPopUpAction\fR
and
\fIDynamicPopDownAction\fR
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
\fBDestroyMenu\fR
and the rebuild from scratch\. When the menu has been destroyed
(unless you used the
\fIrecreate\fR
option when destroying the menu), do not forget to add the dynamic
action again\.
.PP
Note: Do not trigger actions that require user interaction\. They
may fail and may screw up your menus\. See the
\fBSilent\fR
command\.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
\fBWarning\fR
Do not issue
\fBMenuStyle\fR
commands as dynamic menu actions\. Chances are good that this
crashes fvwm\.
.PP
There are several configurable scripts installed together with fvwm
for automatic menu generation\. They have their own man pages\.
Some of them, specifically
\fBfvwm\-menu\-directory\fR and
\fBfvwm\-menu\-desktop\fR, may be used with
\fIDynamicPopupAction\fR
to create a directory listing or GNOME/KDE
application listing\.
.PP
Example (File browser):
.sp
.RS 4
.nf
# You can find the shell script fvwm_make_browse_menu\.sh
# in the utils/ directory of the distribution\.
AddToMenu BrowseMenu
+ DynamicPopupAction \fBPipeRead\fR \e
'fvwm_make_browse_menu\.sh BrowseMenu'
.fi
.RE
.PP
Example (Picture menu):
.sp
.RS 4
.nf
# Build a menu of all \.jpg files in
# $HOME/Pictures
AddToMenu JpgMenu foo title
+ DynamicPopupAction \fBFunction\fR MakeJpgMenu
\fBAddToFunc\fR MakeJpgMenu
+ I \fBDestroyMenu\fR recreate JpgMenu
+ I AddToMenu JpgMenu Pictures \fBTitle\fR
+ I \fBPipeRead\fR 'for i in \fI$HOME\fR/Pictures/*\.jpg; \e
do echo AddToMenu JpgMenu "`basename $i`" \fBExec\fR xv $i; done'
.fi
.RE
.PP
The keyword
\fIMissingSubmenuFunction\fR
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 if the name of an item (that is a submenu) defined with
\fBAddToFunc\fR
follows it, fvwm executes this command:
.sp
.RS 4
.nf
\fBFunction\fR
.fi
.RE
.PP
i\.e\. the name is passed to the function as its first argument and
can be referred to with "$0"\.
.PP
The
\fBfvwm\-menu\-directory\fR
script mentioned above may be used with
\fIMissingSubmenuFunction\fR
to create an up to date recursive directory listing\.
.PP
Example:
.sp
.RS 4
.nf
# 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:
\fBDestroyFunc\fR MakeMissingDirectoryMenu
\fBAddToFunc\fR MakeMissingDirectoryMenu
+ I \fBPipeRead\fR fvwm_make_directory_menu\.sh $0
\fBDestroyMenu\fR SomeMenu
AddToMenu SomeMenu
+ MissingSubmenuFunction MakeMissingDirectoryMenu
+ "Root directory" \fBPopup\fR /
.fi
.RE
.PP
This is another implementation of the file browser that uses
sub menus for subdirectories\.
.PP
Titles can be used within the menu\. If you add the option
\fItop\fR
behind the keyword
\fBTitle\fR,
the title is added to the top of the menu\. If there was a title
already, it is overwritten\.
.sp
.RS 4
.nf
AddToMenu Utilities Tools Title top
.fi
.RE
.PP
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 Tab
s
are replaced by spaces\. Note that you can change this format with
the
\fIItemFormat\fR
option of the
\fBMenuStyle\fR
command\.
.PP
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\.
.PP
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
.sp
.RS 4
.nf
+ Calculator*xcalc\.xpm* \fBExec\fR exec xcalc
.fi
.RE
.PP
inserts a menu item labeled "Calculator" with a picture of a
calculator above it\. The following:
.sp
.RS 4
.nf
+ *xcalc\.xpm* \fBExec\fR exec xcalc
.fi
.RE
.PP
Omits the "Calculator" label, but leaves the picture\.
.PP
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
.sp
.RS 4
.nf
+ Calculator%xcalc\.xpm% \fBExec\fR exec xcalc
.fi
.RE
.PP
inserts a menu item labeled "Calculator" with a picture of a
calculator to the left\. The following:
.sp
.RS 4
.nf
+ %xcalc\.xpm% \fBExec\fR exec xcalc
.fi
.RE
.PP
Omits the "Calculator" label, but leaves the picture\. The
pictures used with this feature should be small (perhaps 16x16)\.
.PP
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 image file to draw along the left
side of the menu (a side pixmap)\. You may want to use the
\fISidePic\fR
option of the
\fBMenuStyle\fR
command instead\. To get a literal '@', insert "@@"\. For example
.sp
.RS 4
.nf
AddToMenu StartMenu@linux\-menu\.xpm@
.fi
.RE
.PP
creates a menu with a picture in its bottom left corner\.
.PP
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
\fISideColor\fR
option of the
\fBMenuStyle\fR
command\. To get a literal '^', insert "^^"\. Example:
.sp
.RS 4
.nf
AddToMenu StartMenu@linux\-menu\.xpm@^blue^
.fi
.RE
.PP
creates a menu with a picture in its bottom left corner and
colors with blue the region of the menu containing the picture\.
.PP
In all the above cases, the name of the resulting menu is name
specified, stripped of the substrings between the various
delimiters\.
.RE
.TP
\fBChangeMenuStyle\fR \fImenustyle\fR \fImenu\fR ...
.RS
.\".PP
Changes the menu style of
\fImenu\fR to \fImenustyle\fR\.
You may specify more than one menu in each call of
\fBChangeMenuStyle\fR\.
.RE
.TP
\fBCopyMenuStyle\fR \fIorig\-menustyle\fR \fIdest\-menustyle\fR
.RS
.\".PP
Copy
\fIorig\-menustyle\fR to
\fIdest\-menustyle\fR,
where
\fIorig\-menustyle\fR
is an existing menu style\. If the menu style
\fIdest_menustyle\fR
does not exist, then it is created\.
.RE
.TP
\fBDestroyMenu\fR [recreate] \fImenu\fR
.RS
.\".PP
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
\fBAddToMenu\fR\.
The optional parameter
\fIrecreate\fR
tells fvwm not to throw away the menu completely but to throw away
all the menu items (including the title)\.
.sp
.RS 4
.nf
DestroyMenu Utilities
.fi
.RE
.RE
.TP
\fBDestroyMenuStyle\fR \fImenustyle\fR
.RS
.\".PP
Deletes the menu style named
\fImenustyle\fR
and changes all menus using this style to the default style, you
cannot destroy the default menu style\.
.sp
.RS 4
.nf
DestroyMenuStyle pixmap1
.fi
.RE
.RE
.TP
\fBMenu\fR \fImenu\-name\fR [\fIposition\fR] [\fIdouble\-click\-action\fR]
.RS
.\".PP
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
\fIdouble\-click\-action\fR
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)\.
.PP
The pointer is warped to where it was when the menu was invoked if
it was both invoked and closed with a keystroke\.
.PP
The
\fIposition\fR
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
\fIcontext\-rectangle\fR
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
\fIposition\fR
arguments consist of several parts:
.HP 1
[\fIcontext\-rectangle\fR] \fIx\fR \fIy\fR [\fIspecial\-options\fR]
.PP
The
\fIcontext\-rectangle\fR
can be one of:
.PP
\fIRoot\fR
.RS 4
the root window of the current screen\.
.RE
.PP
\fIXineramaRoot\fR
.RS 4
the root window of the whole Xinerama screen\. Equivalent to "root" when Xinerama is not used\.
.RE
.PP
\fIMouse\fR
.RS 4
a 1x1 rectangle at the mouse position\.
.RE
.PP
\fIWindow\fR
.RS 4
the frame of the context window\.
.RE
.PP
\fIInterior\fR
.RS 4
the inside of the context window\.
.RE
.PP
\fITitle\fR
.RS 4
the title of the context window or icon\.
.RE
.PP
\fIButton\fR
.RS 4
button #n of the context window\.
.RE
.PP
\fIIcon\fR
.RS 4
the icon of the context window\.
.RE
.PP
\fIMenu\fR
.RS 4
the current menu\.
.RE
.PP
\fIItem\fR
.RS 4
the current menu item\.
.RE
.PP
\fIContext\fR
.RS 4
the current window, menu or icon\.
.RE
.PP
\fIThis\fR
.RS 4
whatever widget the pointer is on (e\.g\. a corner of a window or the root window)\.
.RE
.PP
\fIRectangle\fR <\fIgeometry\fR>
.RS 4
the rectangle defined by <\fIgeometry\fR> in X geometry format\. Width and height default to 1 if omitted\.
.RE
.PP
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)\.
.PP
The offset values
\fIx\fR
and
\fIy\fR
specify how far the menu is moved from its default position\. By
default, the numeric value given is interpreted as a percentage of
the context rectangle's width (height), but with a trailing '\fIm\fR'
the menu's width (height) is used instead\. Furthermore a trailing '\fIp\fR'
changes the interpretation to mean pixels\.
.PP
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\.
.PP
If
\fIx\fR or \fIy\fR
are prefixed with "'\fIo\fR" where 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 percent of the
rectangle's width/height is right over the pixel at
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" is an abbreviation for "+\-m"\.
.PP
A prefix of '\fIc\fR'
is equivalent to "o50"\. Examples:
.sp
.RS 4
.nf
# window list in the middle of the screen
\fBWindowList\fR Root c c
# menu to the left of a window
Menu name window \-100m c+0
# popup menu 8 pixels above the mouse pointer
\fBPopup\fR name mouse c \-100m\-8p
# somewhere on the screen
Menu name rectangle 512x384+1+1 +0 +0
# centered vertically around a menu item
\fBAddToMenu\fR foobar\-menu
+ "first item" \fBNop\fR
+ "special item" \fBPopup\fR "another menu" item +100 c
+ "last item" \fBNop\fR
# above the first menu item
\fBAddToMenu\fR foobar\-menu
+ "first item" \fBPopup\fR "another menu" item +0 \-100m
.fi
.RE
.PP
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\.
.PP
The
\fIspecial\-options\fR:
.PP
To create a tear off menu without opening the normal menu, add the
option
\fITearOffImmediately\fR\.
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:
.sp
.RS 4
.nf
# Forbid fvwm to place the menu window
\fBStyle\fR UsePPosition
# Menu at top left corner of screen
Menu Root 0p 0p TearOffImmediately
.fi
.RE
.PP
The
\fIAnimated\fR and
\fIMwm\fR or
\fIWin\fR
menu styles may move a menu somewhere else on the screen\. If you
do not want this you can add
\fIFixed\fR
as an option\. This might happen for example if you want the menu
always in the top right corner of the screen\.
.PP
Where do you want a menu to appear when you click on its menu
item? The default is to place the title under the cursor, but if
you want it where the position arguments say, use the
\fISelectInPlace\fR
option\. If you want the pointer on the title of the menu, use
\fISelectWarp\fR
too\. Note that these options apply only if the
\fIPopupAsRootMenu\fR \fBMenuStyle\fR
option is used\.
.PP
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
(\fIfvwm\fR
menu style) or never warped to the title at all
(\fIMwm\fR or
\fIWin\fR
menu styles)\. You can force (forbid) warping whenever the
sub menu is opened with the
\fIWarpTitle\fR (\fINoWarp\fR) option\.
.PP
Note that the
\fIspecial\-options\fR
do work with a normal menu that has no other position arguments\.
.RE
.TP
\fBMenuStyle\fR \fIstylename\fR [\fIoptions\fR]
.RS
.\".PP
Sets a new menu style or changes a previously defined style\. The
\fIstylename\fR
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
\fBWindowList\fR
command) that had not be assigned a style using the
\fBChangeMenuStyle\fR\.
See also
\fBDestroyMenuStyle\fR\.
When using monochrome color options are ignored\.
.PP
\fIoptions\fR
is a comma separated list containing some of the keywords
Fvwm / Mwm / Win,
BorderWidth,
Foreground,
Background,
Greyed,
HilightBack / !HilightBack,
HilightTitleBack,
ActiveFore / !ActiveFore,
MenuColorset,
ActiveColorset,
GreyedColorset,
TitleColorset,
Hilight3DThick / Hilight3DThin / Hilight3DOff,
Hilight3DThickness,
Animation / !Animation,
Font,
TitleFont,
MenuFace,
PopupDelay,
PopupOffset,
TitleWarp / !TitleWarp,
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,
VerticalMargins,
VerticalTitleSpacing,
AutomaticHotkeys / !AutomaticHotkeys,
UniqueHotkeyActivatesImmediate / !UniqueHotkeyActivatesImmediate,
MouseWheel,
ScrollOffPage / !ScrollOffPage,
TrianglesUseFore / !TrianglesUseFore\.
.PP
In the above list some options are listed as option pairs or
triples with a '/' in between\. These options exclude each other\.
All paired options can be negated to have the effect of the
counterpart option by prefixing ! to the option\.
.PP
Some options are now negated by prefixing ! to the option\. This
is the preferred form for all such options\. The other negative
forms are now deprecated and will be removed in the future\.
.PP
This is a list of MenuStyle deprecated negative options:
ActiveForeOff, AnimationOff, AutomaticHotkeysOff, HilightBackOff,
TitleWarpOff
.PP
\fIFvwm\fR,
\fIMwm\fR,
\fIWin\fR
reset all options to the style with the same name in former
versions of fvwm\. The default for new menu styles is
\fIFvwm\fR
style\. These options override all others except
\fIForeground\fR, \fIBackground\fR, \fIGreyed\fR, \fIHilightBack\fR,
\fIActiveFore\fR and \fIPopupDelay\fR,
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\.
.PP
\fIMwm\fR and \fIWin\fR
style menus popup sub menus automatically\.
\fIWin\fR
menus indicate the current menu item by changing the background to
dark\.
\fIFvwm\fR
sub menus overlap the parent menu,
\fIMwm\fR and \fIWin\fR
style menus never overlap the parent menu\.
.PP
\fIFvwm\fR
style is equivalent to !HilightBack, Hilight3DThin,
!ActiveFore,
!Animation, Font, MenuFace, PopupOffset 0 67,
TitleWarp, TitleUnderlines1, SeparatorsShort, TrianglesRelief,
PopupDelayed, PopdownDelayed, PopupDelay 150, PopdownDelay 150,
PopupAsSubmenu, HoldSubmenus,
SubmenusRight, BorderWidth 2, !AutomaticHotkeys,
UniqueHotkeyActivatesImmediate,
PopupActiveArea 75\.
.PP
\fIMwm\fR
style is equivalent to !HilightBack, Hilight3DThick,
!ActiveFore,
!Animation, Font, MenuFace, PopupOffset \-3 100,
!TitleWarp, TitleUnderlines2, SeparatorsLong, TrianglesRelief,
PopupImmediately, PopdownDelayed, PopdownDelay 150,
PopupAsSubmenu, HoldSubmenus, SubmenusRight, BorderWidth 2,
UniqueHotkeyActivatesImmediate,
!AutomaticHotkeys, PopupActiveArea 75\.
.PP
\fIWin\fR
style is equivalent to HilightBack, Hilight3DOff, ActiveFore,
!Animation, Font, MenuFace, PopupOffset \-5 100, !TitleWarp,
TitleUnderlines1, SeparatorsShort, TrianglesSolid,
PopupImmediately, PopdownDelayed, PopdownDelay 150,
PopupAsSubmenu, RemoveSubmenus, SubmenusRight, BorderWidth 2,
UniqueHotkeyActivatesImmediate,
!AutomaticHotkeys, PopupActiveArea 75\.
.PP
\fIBorderWidth\fR
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\.
.PP
\fIForeground\fR and
\fIBackground\fR
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\.
.PP
\fIGreyed\fR
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\.
.PP
\fIHilightBack\fR and
\fI!HilightBack\fR
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
\fIHilightBack\fR\.
If you use this option without an argument the color is based on
the menu's background color\. The
\fIActiveColorset\fR
option overrides the specified color\. If the colorset has a
non solid background it is used for the hilighting\.
.PP
\fIHilightTitleBack\fR
switches hilighting the background of menu titles on\. If a
\fITitleColorset\fR
was used, the background colour is taken from there\. Otherwise
the color is based on the menu's background color\. If the colorset
has a non solid background it is used for the hilighting\.
.PP
\fIActiveFore\fR and
\fI!ActiveFore\fR
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
\fIActiveFore\fR\.
Omitting the color turns hilighting on when an
\fIActiveColorset\fR
is used\.
\fIActiveFore\fR
turns off hilighting the foreground completely\. The
\fIActiveColorset\fR
option overrides the specified color\.
.PP
\fIMenuColorset\fR
controls if a colorset is used instead of the
\fIForeground\fR, \fIBackground\fR and \fIMenuFace\fR
menu styles\. If the
\fIMenuColorset\fR
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
\fIMenuFace\fR
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
\fBColorsets\fR
section for details about colorsets\.
.PP
\fIActiveColorset\fR
works exactly like
\fIMenuColorset\fR,
but the foreground from the colorset replaces the color given with
the
\fIActiveFore\fR
menu style and the colorset's background color replaces the color
given with the
\fIHilightBack\fR
command (to turn on background hilighting you have to use the
\fIHilightBack\fR
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
\fI!ActiveFore\fR or \fI!HilightBack\fR
menu styles\.
.PP
\fIGreyedColorset\fR
works exactly like
\fIMenuColorset\fR,
but the foreground from the colorset replaces the color given with
the
\fIGreyed\fR
menu style\. No other parts of the colorset are used\.
.PP
\fITitleColorset\fR
works exactly like
\fIMenuColorset\fR,
but is used only for menu titles\.
.PP
\fIHilight3DThick\fR,
\fIHilight3DThin\fR and
\fIHilight3DOff\fR
determine if the selected menu item is hilighted with a 3D
relief\. Thick reliefs are two pixels wide, thin reliefs are one
pixel wide\.
.PP
\fIHilight3DThickness\fR
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\.
.PP
\fIAnimation\fR and
\fI!Animation\fR
turn menu animation on or off\. When animation is on, sub menus
that do not fit on the screen cause the parent menu to be shifted
to the left so the sub menu can be seen\.
.PP
\fIFont\fR and
\fITitleFont\fR
take 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\. If a
\fITitleFont\fR
is given, it is used for all menu titles instead of the normal font\.
.PP
\fIMenuFace\fR
enforces a fancy background upon the menus\. You can use the same
options for
\fIMenuFace\fR
as for the
\fBButtonStyle\fR\.
See description of
\fBButtonStyle\fR
command and the
\fBColor Gradients\fR
sections for more information\. If you use
\fIMenuFace\fR
without arguments the style is reverted back to normal\.
.PP
Some examples of MenuFaces are:
.sp
.RS 4
.nf
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
.fi
.RE
.PP
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:
.PP
Turn hilighting of the active menu item other than foreground
color off:
.sp
.RS 4
.nf
MenuStyle