FVWM(1) Fvwm 2.7.0 FVWM(1)
NAME
Fvwm - F? Virtual Window Manager for X11
SYNOPSIS
fvwm [-c config-command] [-d displayname] [-f config-file] [-r] [-s [screen_num]] [-V] [-C visual-class |
-I visual-id] [-l colors [-L] [-A] [-S] [-P]] [-D] [-h] [-i client-id] [-F state-file] [--debug-stack-ring]
[-blackout]
DESCRIPTION
Fvwm is a window manager for X11. It is designed to minimize memory consumption, provide a 3D look to window frames,
and a virtual desktop.
Note that there are several window managers around that have "fvwm" in their name. In the past, version 2.x of fvwm
was commonly called fvwm2 to distinguish it from the former version 1.x (fvwm or even fvwm1). Since version 1.x has
been replaced by version 2.x a long time ago we simply call version 2.x and all versions to come, fvwm, throughout
this document, and the executable program is named fvwm. There is an fvwm offspring called fvwm95, it is mostly a
patched version of fvwm-2.0.43. The main goal of fvwm95 was to supply a Windows 95 like look and feel. Since then,
fvwm has been greatly enhanced and practically all fvwm95 features can be achieved by fvwm.
Fvwm provides both a large virtual desktop and multiple disjoint desktops which can be used separately or together.
The virtual desktop allows you to pretend that your video screen is really quite large, and you can scroll around
within the desktop. The multiple disjoint desktops allow you to pretend that you really have several screens to work
at, but each screen is completely unrelated to the others.
Fvwm provides keyboard accelerators that allow you to perform most window manager functions, including moving and
resizing windows and operating the menus, using keyboard shortcuts.
Fvwm has also overcome the distinction between configuration commands and action commands that most window managers
make. Configuration commands typically set fonts, colors, menu contents, 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.
Other noteworthy differences between fvwm and other X11 window managers are the introduction of the SloppyFocus and
NeverFocus focus methods. Focus policy can be separately specified for different window groups. Windows using
SloppyFocus acquire focus when the pointer moves into them and retain focus until some other window acquires it.
Such windows do not lose focus when the pointer moves into the root window. The NeverFocus policy is provided for
use with windows into which one never types (e.g. xclock, oclock, xbiff, xeyes, tuxeyes) - for example, if a
SloppyFocus terminal window has focus, moving the pointer over a NeverFocus decoration window does not deprive the
terminal of focus.
OPTIONS
These are the command line options that are recognized by fvwm:
-i | --clientid id
This option is used when fvwm is started by a session manager. Should not be used by a user.
-c | --cmd config-command
Causes fvwm to use config-command instead of 'Read config' (or 'Read .fvwm2rc') as its initialization command.
(Note that up to 10 -f and -c parameters can be given, and they are executed in the order specified.)
Any module started by command line arguments is assumed to be a module that sends back config commands. All
command line modules have to quit before fvwm proceeds on to the StartFunction and setting border decorations and
styles. There is a potential deadlock if you start a module other than FvwmCpp/FvwmM4/FvwmPerl but there is a
timeout so fvwm eventually gets going.
As an example, starting the pager this way hangs fvwm until the timeout, but the following should work well:
fvwm -c "AddToFunc StartFunction I Module FvwmPager"
-d | --display displayname
Manage the display called displayname instead of the name obtained from the environment variable $DISPLAY.
-D | --debug
Puts X transactions in synchronous mode, which dramatically slows things down, but guarantees that fvwm's
internal error messages are correct. Also causes fvwm to output debug messages while running.
-f config-file
Causes fvwm to read config-file instead of ~/.fvwm/config as its initialization file. This is equivalent to -c
'Read config-file'.
-h | --help
A short usage description is printed.
-r | --replace
Try to take over from a previously running wm. This does not work unless the other wm is ICCCM2 2.0 compliant.
-F | --restore state-file
This option is used when fvwm is started by a session manager. Should not be used by a user.
-s | --single-screen [screen_num]
On a multi-screen display, run fvwm only on the screen named in the $DISPLAY environment variable or provided
through the -d option. The optional argument screen_num should be positive or null and override the screen
number. Normally, fvwm attempts to start up on all screens of a multi-screen display.
-V | --version
Prints the version of fvwm to stderr. 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.
-C | --visual visual-class
Causes fvwm to use visual-class for the window borders and menus. visual-class can be "StaticGray", "GrayScale",
"StaticColor", "PseudoColor", "TrueColor" or "DirectColor".
-I | --visualid id
Causes fvwm to use id as the visual id for the window borders and menus. id can be specified as N for decimal or
0xN for hexadecimal. See man page of xdpyinfo for a list of supported visuals.
-l | --color-limit limit
Specifies a limit on the colors used in image, gradient and possibly simple colors used by fvwm. In fact, fvwm
(and all the modules) uses a palette with at most limit colors. This option is only useful with screens that
display 256 colors (or less) with a dynamic visual (PseudoColor, GrayScale or DirectColor). The default depends
on your X server and how you run fvwm. In most case this default is reasonable. The -l option should be used
only if you encounter problems with colors. By default, fvwm tries to detect large pre-allocated palettes. If
such a palette is detected fvwm uses it and a priori the -l must not be used. Moreover, in this case the -A and
-S 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:
Display depth 8 (256 colors)
PseudoColor: 68 (4x4x4 color cube + 4 grey)
GrayScale: 64 regular grey
DirectColor: 32 (3x3x3 color cube + 5 grey)
Display depth 4 (16 colors)
PseudoColor: 10 (2x2x2 color cube + 2 grey)
GrayScale: 8 regular grey
DirectColor: 10 (2x2x2 color cube + 2 grey)
These defaults may change before version 2.6. Note that if you use a private color map (i.e., fvwm is started
with the -C or the -I options), then other defaults are used.
Now what to do if you encounter problems with colors? The first thing to do is to check if you really cannot run
your X server with depth 15, 16 or better. Check your X server documentation. Note that some hardware can
support two different depths on the same screen (typically depth 8 and depth 24). If depth 8 is the default, you
can force fvwm to use the best depth by using the -C option with TrueColor as argument. So now we assume that
you are forced to run in depth 8 with a dynamic visual because your hardware/driver cannot do better or because
you need to use an application which needs to run under this mode (e.g., because this application needs
read-write colors). What it should be understand is that you have only 256 colors and that all the applications
which 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 -C option for fvwm. The
disadvantage of this method is that it is visually disturbing (see the ColormapFocus 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 -L option. However, limiting the number of colors is not the definitive solution. The
definitive solution is to try cause applications which use a lot of colors use the same colors. This is a
difficult task as there are no formal standards for this goal. However, some toolkits as QT and GTK use color
cubes as palettes. So, the idea is to configure your applications/toolkits to all use the same color cube.
Moreover, you can use the colors in this color cube in your X resources configuration files and/or as arguments
to colors options. Fvwm can use any color cube of the form RxGxB with 2 <= R <= 6, R = G, R-1 =< B <= R and B >=
2. To get an RxGxB color cube give an argument to -l an integer c >= R*G*B and < (R+1)*(G+1)*B if B=R and <
R*G*(B+1) if B < R (and different from 61). If c > R*G*B, then some grey may be added to the color cube. You
can use the PrintInfo Colors [1] command to get information on your fvwm colors setting. In particular, this
command prints the palette used by fvwm in rgb format (the last integer gives the number of times fvwm has
allocated the colors).
-L | --strict-color-limit
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.
-P | --visual-palette
If the screen displays 256 colors (or less) and has a dynamic visual, this option causes fvwm to use a palette
designed for limiting the "visual" color distance between the points of the palette. Moreover, for better color
sharing, if possible colors with a name in the X rgb data base are used for defining the colors (with the hope
that applications and images prefer to use named colors). If the -l option is not used this palette has 61
colors. This palette is also automatically selected if 61 or 9 is used as argument to the -l option.
-A | --allocate-palette
If the screen displays 256 colors (or less) and has a dynamic visual this option causes fvwm to allocate all the
colors of its palette at start up for reserving these colors for future use. This option forces the
-static-palette option. By default, fvwm allocates (reserves) a color in its palette only if it needs this
color.
-S | --static-palette
If the screen displays 256 colors (or less) and has a dynamic visual this option causes fvwm to never free the
colors in its palette. By default, when fvwm does not need a color any more it frees this color so that a new
color can be used. This option may speed up image loading and save a few bits of memory.
-blackout
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.
--debug-stack-ring
Enables stack ring debugging. This option is only intended for internal debugging and should only be used by
developers.
ANATOMY OF A WINDOW
Fvwm puts a decorative border around most windows. This border consists of a bar on each side and a small L-shaped
section on each corner. There is an additional top bar called the title-bar which is used to display the name of the
window. In addition, there are up to 10 title-bar buttons. The top, side, and bottom bars are collectively known as
the side-bars. The corner pieces are called the frame.
With the built-in minimal configuration, dragging mouse button 1 in the frame or side-bars begins a resize operation
on the window. Dragging mouse button 2 in the frame or side-bars begins a move operation. There are raise/lower
operations bound to a single clicking on borders. Similarly for the window title.
Up to ten title-bar buttons may exist. Their use is completely user definable. One popular configuration uses one
button on the left that is used to bring up a list of window options and two buttons on the right used to iconify and
maximize the window. Another popular configuration adds a close button to the right. The number of title-bar
buttons used depends on which ones have mouse actions bound to them. See the Mouse command.
THE VIRTUAL DESKTOP
Fvwm provides multiple virtual desktops for users who wish to use them. The screen is a viewport onto a desktop
which may be larger than the screen. Several distinct desktops can be accessed (concept: one desktop for each
project, or one desktop for each application, when view applications are distinct). Since each desktop can be larger
than the physical screen, divided into m by n pages which are each the size of the physical screen, windows which are
larger than the screen or large groups of related windows can easily be viewed.
The (m by n) size (i.e. number of pages) of the virtual desktops can be changed any time, by using the DesktopSize
command. All virtual desktops must be (are) the same size. The total number of distinct desktops does not need to
be specified, but is limited to approximately 4 billion total. All windows on a range of desktops can be viewed in
the FvwmPager, a miniature view of the desktops. The pager is an accessory program, called a module, which is not
essential for the window manager to operate. Windows may also be listed using the WindowList command or the
FvwmIconMan module.
Fvwm keeps the windows on the desktop in a layered stacking order; a window in a lower layer never obscures a window
in a higher layer. The layer of a window can be changed by using the Layer command. The concept of layers is a
generalization of the StaysOnTop flag of older fvwm versions. The StaysOnTop and StaysPut Style options are now
implemented by putting the windows in suitable layers and the previously missing StaysOnBottom Style option has been
added.
Sticky windows are windows which transcend the virtual desktop by "Sticking to the screen's glass". They always stay
put on the screen. This is convenient for things like clocks and 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.
Window geometries are specified relative to the current viewport. That is:
xterm -geometry +0+0
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:
xterm -geometry +1000+1000
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:
xterm -geometry -5-5
places the window's lower right hand corner 5 pixels from the lower right corner of the visible portion of the
screen. Not all applications support window geometries with negative offsets. Some applications place the window's
upper right hand corner 5 pixels above and to the left of the upper left hand corner of the screen; others may do
just plain bizarre things.
There are several ways to cause a window to map onto a desktop or page other than the currently active one. The
geometry technique mentioned above (specifying x,y coordinates larger than the physical screen size), however,
suffers from the limitation of being interpreted relative to the current viewport: the window may not consistently
appear on a specific page, unless you always invoke the application from the same page.
A better way to place windows on a different page, screen or desk from the currently mapped viewport is to use the
StartsOnPage or StartsOnScreen style specification (the successors to the older StartsOnDesk style) in your config
file. The placement is consistent: it does not depend on your current location on the virtual desktop.
Some applications that understand standard Xt command line arguments and X resources, like xterm and xfontsel, allow
the user to specify the start-up desk or page on the command line:
xterm -xrm "*Desk:1"
starts an xterm on desk number 1;
xterm -xrm "*Page:3 2 1"
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 .Xdefaults file:
XTerm*Desk: 1
or
XTerm*Page: 3 2 1
USE ON MULTI-SCREEN DISPLAYS
If the -s command line argument is not given, fvwm automatically starts up on every screen on the specified display.
After fvwm starts each screen is treated independently. Restarts of fvwm need to be performed separately on each
screen. The use of
EdgeScroll 0 0
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.
XINERAMA SUPPORT
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 EdgeResistance
option of the Style 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 Xinerama command. Many modules and commands work nicely with Xinerama displays.
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.
Style * IconBox 64x300-0-0@p
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 XineramaPrimaryScreen command.
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
All MoveToScreen
that can be entered in an FvwmConsole window or with FvwmCommand.
For multi-screen implementations other than Xinerama, such as Single Logical Screen, it is possible to simulate a
Xinerama configuration if the total screen seen by fvwm is made up of equal sized monitors in a rectangular grid.
The commands XineramaSls, XineramaSlsSize and XineramaSlsScreens are used to configure this feature.
INITIALIZATION
During initialization, fvwm searches for a configuration file which describes key and button bindings, and many other
things. The format of these files is described later. Fvwm first searches for configuration files using the command
Read config
This looks for file config in $FVWM_USERDIR and $FVWM_DATADIR directories, as described in Read. 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):
$HOME/.fvwm/config
/usr/local/share/fvwm/config
$HOME/.fvwm/.fvwm2rc
$HOME/.fvwm2rc
/usr/local/share/fvwm/.fvwm2rc
/usr/local/share/fvwm/system.fvwm2rc
/etc/system.fvwm2rc
Please note, the last 5 locations are not guaranteed to be supported in the future.
If a configuration file is not found, the left mouse button, or Help or F1 keys on the root window bring up menus and
forms that can create a starting configuration file.
Fvwm sets two environment variables which are inherited by its children. These are $DISPLAY which describes the
display on which fvwm is running. $DISPLAY may be unix:0.0 or :0.0, which doesn't work too well when passed through
ssh to another machine, so $HOSTDISPLAY is set to a network-ready description of the display. $HOSTDISPLAY always
uses the TCP/IP transport protocol (even for a local connection) so $DISPLAY should be used for local connections, as
it may use Unix-domain sockets, which are faster.
If you want to start some applications or modules with fvwm, you can simply put
Exec app
or
Module FvwmXxx
into your config, 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.
The standard way to start applications or modules on fvwm's start up is to add them to an initialization function
(usually StartFunction or InitFunction). This way they are only started after fvwm finishes to read and execute
config file.
Fvwm has three special functions for initialization: StartFunction, which is executed on startups and restarts;
InitFunction and RestartFunction, which are executed during initialization and restarts (respectively) just after
StartFunction. These functions may be customized in a user's config file using the AddToFunc command (described
later) to start up modules, xterms, or whatever you'd like to have started by fvwm.
Fvwm has also a special exit function: ExitFunction, executed when exiting or restarting before actually quitting.
It could be used to explicitly kill modules, etc.
If fvwm is run under a session manager, functions SessionInitFunction and SessionRestartFunction are executed instead
of InitFunction and RestartFunction. This helps to define the user's config file to be good for both running under a
session manager and without it. Generally it is a bad idea to start xterms or other applications in "Session*"
functions. Also someone can decide to start different modules while running under a session manager or not. For the
similar purposes SessionExitFunction is used instead of ExitFunction.
DestroyFunc StartFunction
AddToFunc StartFunction
+ I Module FvwmPager * *
+ I Module FvwmButtons
DestroyFunc InitFunction
AddToFunc InitFunction
+ I Module FvwmBanner
+ I Module FvwmIconMan
+ I Exec xsetroot -solid cyan
+ I Exec xterm
+ I Exec netscape
DestroyFunc RestartFunction
AddToFunc RestartFunction
+ I Module FvwmIconMan
DestroyFunc SessionInitFunction
AddToFunc SessionInitFunction
+ I Module FvwmBanner
DestroyFunc SessionRestartFunction
AddToFunc SessionRestartFunction
+ I Nop
You do not need to define all special functions if some are empty. Also note, all these special functions may be
emulated now using StartFunction and ExitFunction, like this:
DestroyFunc StartFunction
AddToFunc StartFunction
+ I Test (Init) Module FvwmBanner
+ I Module FvwmPager * *
+ I Test (Restart) Beep
DestroyFunc ExitFunction
AddToFunc ExitFunction
+ I Test (Quit) Echo Bye-bye
+ I KillModule MyBuggyModule
+ I Test (ToRestart) Beep
COMPILATION OPTIONS
Fvwm has a number of compile-time options. If you have trouble using a certain command or feature, check to see if
support for it was included at compile time. Optional features are described in the config.h file that is generated
during compilation.
ICONS AND IMAGES
Fvwm can load .xbm, .xpm, .png and .svg images. XBM images are monochrome. Fvwm can always display XBM files. XPM
and PNG formats are color images. SVG is a vector graphics image format. Compile-time options determine whether
fvwm can display XPM, PNG or SVG icons and images. See the INSTALL.fvwm file for more information.
The related SHAPE compile-time option can make fvwm display spiffy shaped icons.
SVG rendering options
SVG images are generated from (XML) text files. A really simple SVG file might look something like this:
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 Icon and MiniIcon styles.
The rendering options are specified as a string appended to the SVG filename as follows:
image.svg:[!] [(1) size] [(2) position] [(3) rotation] [(4) scale] ...
(1) [-]width{x}[-]height
(2) {- | +}xpos{- | +}ypos
(3) @[-]angle
(4) {* | /}[-]factor[x | y]
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.
filename_without_colon.svg
filename:with:colon.svg:
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.
image.svg:!
width and height 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.
image.svg:60x60
Use a width or height value of 0 to keep the aspect ratio.
image.svg:0x60
image.svg:60x0
A '-' before width mirrors the rendering area horizontally.
image.svg:-0x0
A '-' before height mirrors the rendering area vertically.
image.svg:0x-0
xpos and ypos specifies a translation of the image in pixels. A positive xpos value moves the image to the right. A
positive ypos value moves it down. Moving it partially outside of the rendering area results in a cropped image.
image.svg:-30-0
image.svg:-0+10
image.svg:-30+10
angle 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.
image.svg:@180
image.svg:@-90
image.svg:@30
image.svg:@57.3
factor 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 factor is directly followed by a 'x' or a
'y', the scaling is horizontal or vertical respectively. Otherwise the scaling is uniform.
image.svg:*2
image.svg:/2
image.svg:/3x
image.svg:/2y
Scaling down a translated or rotated image can prevent cropping.
image.svg:@30*0.6
Repeated usage of translation, rotation, and scaling is allowed. Translation and rotation are additive. Scaling is
multiplicative.
image.svg:*2/3
image.svg:/3x/2y
When combining affine transformations, the scaling is always done first, then the rotation, and finally the
translation.
image.svg:-30+10@30/3x/2y
Use a negative scale factor to mirror the actual image.
image.svg:-30+10@30/-3x/2y
Mirroring of the rendering area is done after any scaling, rotation or translation of the image.
image.svg:-0x0-30+10@30/3x/2y
Transposing is done last of all, after everything else.
image.svg:!-0x0-30+10@30/3x/2y
MODULES
A module is a separate program which runs as a separate Unix process but transmits commands to fvwm to execute.
Users can write their own modules to do any weird or bizarre manipulations without bloating or affecting the
integrity of fvwm itself.
Modules must be spawned by fvwm so that it can set up two pipes for fvwm and the module to communicate with. The
pipes are already open for the module when it starts and the file descriptors for the pipes are provided as command
line arguments.
Modules can be spawned by fvwm at any time during the X session by use of the Module command. Modules can exist for
the duration of the X session, or can perform a single task and exit. If the module is still active when fvwm is
told to quit, then fvwm closes the communication pipes and waits to receive a SIGCHLD from the module, indicating
that it has detected the pipe closure and has exited. If modules fail to detect the pipe closure fvwm exits after
approximately 30 seconds anyway. The number of simultaneously executing modules is limited by the operating system's
maximum number of simultaneously open files, usually between 60 and 256.
Modules simply transmit commands to the fvwm command engine. Commands are formatted just as in the case of a mouse
binding in the config setup file. Certain auxiliary information is also transmitted, as in the sample module
FvwmButtons.
Please refer to the Module Commands section for details.
ICCCM COMPLIANCE
Fvwm attempts to be ICCCM 2.0 compliant. Check http://tronche.com/gui/x/icccm/ 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.
The ICCCM states that windows possessing the property
WM_HINTS(WM_HINTS):
Client accepts input or input focus: False
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, Lenience, which allows fvwm to overlook this ICCCM rule.
Even with this window style it is not guaranteed that the application accepts focus.
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
fvwm; vi ~/.fvwm/config; fvwm -replace
resembles the Restart command. It is not exactly the same, since killing the previously running wm may terminate
your X session, if the wm was started as the last client in your .Xclients or .Xsession file.
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:
AddToFunc UrgencyFunc
+ I Iconify off
+ I FlipFocus
+ I Raise
+ I WarpToWindow !raise 5p 5p
AddToFunc UrgencyDoneFunc
+ I Nop
GNOME COMPLIANCE
Fvwm attempts to be GNOME (version 1) compliant. Check http://www.gnome.org for what that may mean. To disable
GNOME hints for some or all windows, the GNOMEIgnoreHints style can be used.
EXTENDED WINDOW MANAGER HINTS
Fvwm attempts to respect the extended window manager hints (ewmh or EWMH for short) specification:
http://www.freedesktop.org/wiki/Standards_2fwm_2dspec 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 GTK+ version 2). Applications which respect this specification are called ewmh compliant applications.
This support is configurable with styles and commands. These styles and commands have EWMH as the prefix (so you can
find them easily in this man page).
There is a new Context 'D' for the Key, PointerKey, Mouse and Stroke commands. This context is for desktop
applications (such as kdesktop and Nautilus desktop).
When a compliant taskbar asks fvwm to activate a window (typically when you click on a button which represents a
window in such a taskbar), then fvwm calls the complex function EWMHActivateWindowFunc which by default is Iconify
Off, Focus and Raise. You can redefine this function. For example:
DestroyFunc EWMHActivateWindowFunc
AddToFunc EWMHActivateWindowFunc I Iconify Off
+ I Focus
+ I Raise
+ I WarpToWindow 50 50
additionally warps the pointer to the center of the window.
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 EwmhBaseStruts command.
MWM COMPATIBILITY
Fvwm provides options to emulate Motif Window Manager (Mwm) as well as possible. Please refer to the Emulate command
as well as to the Mwm specific options of the Style and MenuStyle commands for details.
OPEN LOOK AND XVIEW COMPATIBILITY
Fvwm supports all the Open Look decoration hints (except pushpins). Should you use any such application, please add
the following line to your config:
Style * OLDecor
Most (perhaps all) Open Look applications have a strange notion of keyboard focus handling. Although a lot of work
went into fvwm to work well with these, you may still encounter problems. It is recommended to use the NeverFocus
focus policy and the Lenience style for all such applications (the windows still get the focus):
Style NeverFocus, Lenience
But in case you can not live with that focus policy, you can try using one of the other focus policies in combination
with the Lenience style:
Style MouseFocus, Lenience
Style SloppyFocus, Lenience
Style ClickToFocus, Lenience
M4 PREPROCESSING
M4 pre-processing is handled by a module in fvwm. To get more details, try man FvwmM4. In short, if you want fvwm
to parse your files with m4, then replace the command Read with FvwmM4 in your ~/.fvwm/config file (if it appears at
all), and start fvwm with the command
fvwm -cmd "FvwmM4 config"
CPP PREPROCESSING
Cpp is the C-language pre-processor. fvwm offers cpp processing which mirrors the m4 pre-processing. To find out
about it, re-read the M4 section, but replace "m4" with "cpp".
CONFIGURATION
Configuration Files
The configuration file is used to describe mouse and button bindings, colors, the virtual display size, and related
items. The initialization configuration file is typically called config (or .fvwm2rc). By using the Read command,
it is easy to read in new configuration files as you go.
Lines beginning with '#' are ignored by fvwm. Lines starting with '*' are expected to contain module configuration
commands (rather than configuration commands for fvwm itself). Like in shell scripts embedded newlines in a
configuration file line can be quoted by preceding them with a backslash. All lines linked in this fashion are
treated as a single line. The newline itself is ignored.
Fvwm makes no distinction between configuration commands and action commands, so anything mentioned in the fvwm
commands section can be placed on a line by itself for fvwm to execute as it reads the configuration file, or it can
be placed as an executable command in a menu or bound to a mouse button or a keyboard key. It is left as an exercise
for the user to decide which function make sense for initialization and which ones make sense for run-time.
Supplied Configuration
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 /usr/local/share/fvwm/config file.
Alternatively, the built-in menu (accessible when no configuration file is found) has options to create an initial
config file for the user.
FONTS
Font names and font loading
The fonts used for the text of a window title, icon titles, menus and geometry window can be specified by using the
Font and IconFont Style, the Font MenuStyle and the DefaultFont 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.
First, you can use what we can call a usual font name, for example,
-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
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
-adobe-courier-bold-r-normal--10-*
if the locale charset is ISO8859-1, then fvwm tries to load a font which matches
-adobe-courier-bold-r-normal--10-*-ISO8859-1
with the locale charset ISO8859-15 fvwm tries to load
-adobe-courier-bold-r-normal--10-*-ISO8859-15.
A font name can be given as an extended XLFD. This is a comma separated list of (simple) XLFD font names, for
example:
-adobe-courier-bold-r-normal--14-*,-*-courier-medium-r-normal--14-*
Each simple font name is tried until a matching font with the locale charset is found and if this fails each simple
font name is tried without constraint on the charset.
More details on the XLFD can be found in the X manual page, the X Logical Font Description Conventions document
(called xlfd) and the XLoadFont and XCreateFontSet manual pages. Some useful font utilities are: xlsfonts, xfontsel,
xfd and xset.
If you have Xft support you can specify an Xft font name (description) of a true type (or Type1) font prefixed by
"xft:", for example:
"xft:Luxi Mono"
"xft:Luxi Mono:Medium:Roman:size=14:encoding=iso8859-1"
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 FvwmIdent, button height in some fvwm modules ...etc. With a LCD monitor you may try to add "rgba=mode"
where mode is either rgb, bgr, vrgb or vbgr to enable subpixel rendering. The best mode depends on the way your LCD
cells are arranged. You can pass other specifications in between ":", as "foundry=foundry_name", "spacing=type"
where type can be monospace, proportional or charcell, "charwidth=integer", "charheight=integer" or "antialias=bool"
where bool is True or False. It seems that these parameters are not always taken in account.
To determine which Xft fonts are really loaded you can export XFT_DEBUG=1 before starting fvwm and take a look to the
error log. With Xft2 you may use fc-list to list the available fonts. Anyway, Xft support is experimental (from the
X and the fvwm point of view) and the quality of the rendering depends on number of parameters (the XFree and the
freetype versions and your video card(s)).
After an Xft font name you can add after a ";" an XLFD font name (simple or extended) as:
xft:Verdana:pixelsize=14;-adobe-courier-bold-r-normal--14-*
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.
Font and string encoding
Once a font is loaded, fvwm finds its encoding (or charset) using its name (the last two fields of the name). fvwm
assumes that the strings which are displayed with this font use this encoding (an exception is that if an iso10646-1
font is loaded, then UTF-8 is assumed for string encoding). In a normal situation, (i) a font is loaded by giving a
font name without specifying the encoding, (ii) the encoding of the loaded font is the locale encoding, and then
(iii) the strings in the fvwm configuration files should use the locale encoding as well as the window and icon name.
With Xft the situation is bit different as Xft supports only iso10646-1 and iso8859-1. If you do not specify one of
these encodings in the Xft font name, then fvwm does strings conversion using (iii). Note that with multibyte fonts
(and in particular with "CJK" fonts) for good text rendering, the locale encoding should be the charset of the font.
To override the previous rules, it is possible to specify the string encoding in the beginning of a font description
as follow:
StringEncoding=enc:_full_font_name_
where enc is an encoding supported by fvwm (usually font name charset plus some unicode encodings: UTF-8, USC-2,
USC-4 and UTF-16).
For example, you may use an iso8859-1 locale charset and have an FvwmForm in Russian using koi8-r encoding. In this
case, you just have to ask FvwmForm to load a koi8-r font by specifying the encoding in the font name. With a
multibyte language, (as multibyte font works well only if the locale encoding is the charset of the font), you should
use an iso10646-1 font:
StringEncoding=jisx0208.1983-0:-*-fixed-medium-r-*-ja-*-iso10646-1
or
"StringEncoding=jisx0208.1983-0:xft:Bitstream Cyberbit"
if your FvwmForm configuration uses jisx0208.1983-0 encoding. Another possibility is to use UTF-8 encoding for your
FvwmForm configuration and use an iso10646-1 font:
-*-fixed-medium-r-*-ja-*-iso10646-1
or
"StringEncoding=UTF-8:xft:Bitstream Cyberbit"
or equivalently
"xft:Bitstream Cyberbit:encoding=iso10646-1"
In general iso10646-1 fonts together with UTF-8 string encoding allows the display of any characters in a given menu,
FvwmForm etc.
More and more, unicode is used and text files use UTF-8 encoding. However, in practice the characters used range
over your locale charset (this is the case when you generate a menu with fvwm-menu-desktop with recent versions of
KDE and GNOME). For saving memory (an iso10646-1 font may have a very large number of characters) or because you
have a pretty font without an iso10646-1 charset, you can specify the string encoding to be UTF-8 and use a font in
the locale charset:
StringEncoding=UTF-8:-*-pretty_font-*-12-*
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:
-misc-fixed-*--20-*-my_utf8-36
you need to add the encoding after the font name using a slash as a delimiter. For example:
MenuStyle * Font -misc-fixed-*--20-*-my_utf8-36/iso10646-1
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:
Style * Font -misc-fixed-*--14-*-iso8859-1/*/latin1
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:
Style * Font \
-misc-fixed-*--14-*-local8859-6/iso8859-6/local_iso8859_6_iconv
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.
Font Shadow Effects
Fonts can be given 3d effects. At the beginning of the font name (or just after a possible StringEncoding
specification) add
Shadow=size [offset] [directions]]:
size is a positive integer which specifies the number of pixels of shadow. offset is an optional positive integer
which defines the number of pixels to offset the shadow from the edge of the character. The default offset is zero.
directions is an optional set of directions the shadow emanates from the character. The directions are a space
separated list of fvwm directions:
N, North, Top, t, Up, u, -
E, East, Right, r, Right, r, ]
S, South, Bottom, b, Down, d, _
W, West, Left, l, Left, l, [
NE, NorthEast, TopRight, tr, UpRight, ur, ^
SE, SouthEast, BottomRight, br, DownRight, dr, >
SW, SouthWest, BottomLeft, bl, DownLeft, dl, v
NW, NorthWest, TopLeft, tl, UpLeft, ul, <
C, Center, Centre, .
A shadow is displayed in each given direction. All is equivalent to all the directions. The default direction is
BottomRight. With the Center direction, the shadow surrounds the whole string. Since this is a super set of all
other directions, it is a waste of time to specify this along with any other directions.
The shadow effect only works with colorsets. The color of the shadow is defined by using the fgsh option of the
Colorset command. Please refer to the Colorsets section for details about colorsets.
Note: It can be difficult to find the font, fg, fgsh and bg colors to make this effect look good, but it can look
quite good.
BI-DIRECTIONAL TEXT
Arabic and Hebrew text require bi-directional text support to be displayed correctly, this means that logical strings
should be converted before their visual presentation, so left-to-right and right-to-left sub-strings are determined
and reshuffled. In fvwm this is done automatically in window titles, menus, module labels and other places if the
fonts used for displaying the text are of one of the charsets that require bidi (bi-directional) support. For
example, this includes iso8859-6, iso8859-8 and iso10646-1 (unicode), but not other iso8859-* fonts.
This bi-directional text support is done using the fribidi library compile time option, see INSTALL.fvwm.
KEYBOARD SHORTCUTS
Almost all window manager operations can be performed from the keyboard so mouse-less operation should be possible.
In addition to scrolling around the virtual desktop by binding the Scroll command to appropriate keys, Popup, Move,
Resize, and any other command can be bound to keys. Once a command is started the pointer is moved by using the up,
down, left, and right arrows, and the action is terminated by pressing return. Holding down the Shift key causes the
pointer movement to go in larger steps and holding down the control key causes the pointer movement to go in smaller
steps. Standard emacs and vi cursor movement controls ( n , p , f , b , and j , k , h , l ) can be used instead of
the arrow keys.
SESSION MANAGEMENT
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.
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 Style commands or by using various modules), these changes are lost after saving
and restarting the session. To become permanent, such changes have to be added to the configuration file.
Note further that the current implementation has the following anomaly when used on a multi-screen display: Starting
fvwm for the first time, fvwm manages all screens by forking a copy of itself for each screen. Every copy knows its
parent and issuing a Quit command to any instance of fvwm kills the master and thus all copies of fvwm. When you
save and restart the session, the session manager brings up a copy of fvwm on each screen, but this time they are
started as individual instances managing one screen only. Thus a Quit kills only the copy it was sent to. This is
probably not a very serious problem, since with session management, you are supposed to quit a session through the
session manager anyway. If it is really needed,
Exec exec killall fvwm
still kills all copies of fvwm. Your system must have the killall command though.
BOOLEAN ARGUMENTS
A number of commands take one or several boolean arguments. These take a few equivalent inputs: "yes", "on", "true",
"t" and "y" all evaluate to true while "no", "off", "false", "f" and "n" evaluate to false. Some commands allow
"toggle" too which means that the feature is disabled if it is currently enabled and vice versa.
BUILTIN KEY AND MOUSE BINDINGS
The following commands are built-in to fvwm:
Key Help R A Popup MenuFvwmRoot
Key F1 R A Popup MenuFvwmRoot
Key Tab A M WindowList Root c c NoDeskSort
Key Escape A MC EscapeFunc
Mouse 1 R A Menu MenuFvwmRoot
Mouse 1 T A FuncFvwmRaiseLowerX Move
Mouse 1 FS A FuncFvwmRaiseLowerX Resize
Mouse 2 FST A FuncFvwmRaiseLowerX Move
AddToFunc FuncFvwmRaiseLowerX
+ I Raise
+ M $0
+ D Lower
The Help and F1 keys invoke a built-in menu that fvwm creates. This is primarily for new users that have not created
their own configuration file. Either key on the root (background) window pops up an menu to help you get started.
The Tab key pressed anywhere with the Meta key (same as the Alt key on PC keyboards) held down pop-ups a window list.
Mouse button 1 on the title-bar or side frame can move, raise or lower a window.
Mouse button 1 on the window corners can resize, raise or lower a window.
You can override or remove these bindings. To remove the window list binding, use this:
Key Tab A M -
COMMAND EXECUTION
Module and Function Commands
If fvwm encounters a command that it doesn't recognize, it checks to see if the specified command should have been
Function (rest of command)
or
Module (rest of command)
This allows complex functions or modules to be invoked in a manner which is fairly transparent to the configuration
file.
Example: the config file contains the line
HelpMe
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".
Delayed Execution of Commands
Note: There are many commands that affect look and feel of specific, some or all windows, like Style, Mouse,
Colorset, TitleStyle and many others. For performance reasons such changes are not applied immediately but only when
fvwm is idle, i.e. no user interaction or module input is pending. Specifically, new Style options that are set in a
function are not applied until after the function has completed. This can sometimes lead to unwanted effects.
To force that all pending changes are applied immediately, use the UpdateStyles, Refresh or RefreshWindow commands.
QUOTING
Quotes are required only when needed to make fvwm consider two or more words to be a single argument. Unnecessary
quoting is allowed. If you want a quote character in your text, you must escape it by using the backslash character.
For example, if you have a pop-up menu called "Window-Ops", then you do not need quotes:
Popup Window-Ops
but if you replace the dash with a space, then you need quotes:
Popup "Window Ops"
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.
COMMAND EXPANSION
Whenever an fvwm command line is executed, fvwm performs parameter expansion. A parameter is a '$' followed by a
word enclosed in brackets ($[...]) or a single special character. If fvwm encounters an unquoted parameter on the
command line it expands it to a string indicated by the parameter name. Unknown parameters are left untouched.
Parameter expansion is performed before quoting. To get a literal '$' use "$$".
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.
Example:
Pick -Exec exec xmessage '$[w.name]'
opens an xmessage dialog with "$[w.name]" unexpanded.
The longer variables may contain additional variables inside the name, which are expanded before the outer variable.
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.
Example:
# Print the current desk number, horizontal page number
# and the window's class (unexpanded here, no window).
Echo $[desk.n] $[page.nx] $[w.class]
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 Current command can be used:
Current Echo $[desk.n] $[page.nx] $[w.class]
The parameters known by fvwm are:
$$
A literal '$'.
$.
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 '.'.
$0 to $9
The positional parameters given to a complex function (a function that has been defined with the AddToFunc
command). "$0" is replaced with the first parameter, "$1" with the second parameter and so on. If the
corresponding parameter is undefined, the "$..." is deleted from the command line.
$*
All positional parameters given to a complex function. This includes parameters that follow after "$9".
$[n]
The n:th positional parameter given to a complex function, counting from 0. If the corresponding parameter is
undefined, the "$[n]" is deleted from the command line. The parameter is expanded unquoted.
$[n-m]
The positional parameters given to a complex function, starting with parameter n and ending with parameter m. 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.
$[n-]
All the positional parameters given to a complex function, starting with parameter n. If all the corresponding
parameters are undefined, the "$[...]" is deleted from the command line. All parameters are expanded unquoted.
$[*]
All the positional parameters given to a complex function. This is equivalent of $[0-].
$[version.num]
The version number, like "2.6.0".
$[version.info]
The version info, like " (from cvs)", empty for the official releases.
$[version.line]
The first line printed by the --version command line option.
$[vp.x] $[vp.y] $[vp.width] $[vp.height]
Either coordinate or the width or height of the current viewport.
$[wa.x] $[wa.y] $[wa.width] $[wa.height]
Either coordinate or the width or height of the EWMH working area.
$[dwa.x] $[dwa.y] $[dwa.width] $[dwa.height]
Either coordinate or the width or height of the dynamic EWMH working area.
$[desk.n]
The current desk number.
$[desk.name]
These parameters are replaced with the name of the desktop number that is defined with the DesktopName
command. If no name is defined, then the default name is returned.
$[desk.width] $[desk.height]
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.
$[desk.pagesx] $[desk.pagesy]
The number of total pages in a desk in x or y direction. This is the same as the values set by DesktopSize.
$[page.nx] $[page.ny]
The current page numbers, by X and Y axes, starting from 0. page is equivalent to area in the GNOME terminology.
$[w.id]
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.
$[w.name] $[w.iconname] $[w.class] $[w.resource] $[w.visiblename] $[w.iconfile] $[w.miniiconfile]
$[w.iconfile.svgopts] $[w.miniiconfile.svgopts]
The window's name, icon name, resource class and resource name, visible name, file name of its icon or mini icon
defined with the Icon or MiniIcon 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.
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:
Style $[w.resource] Icon norm/network.png
work correctly, regardless of any special symbols the value may contain, like spaces and different kinds of
quotes.
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
IndexedWindowName then this is more useful a distinction, and allows for referencing the specific window by its
visible name for inclusion in things like Style commands.
$[w.x] $[w.y] $[w.width] $[w.height]
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.
$[w.desk]
The number of the desk on which the window is shown. If the window is sticky the current desk number is used.
$[w.layer]
The layer of the window.
$[w.screen]
The screen number the window is on. If Xinerama is not present, this returns the number 0.
$[cw.x] $[cw.y] $[cw.width] $[cw.height]
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.
$[i.x], $[it.x], $[ip.x] $[i.y], $[it.y], $[ip.y] $[i.width], $[it.width], $[ip.width] $[i.height], $[it.height],
$[ip.height]
These work like $[w....] but return the geometry of the icon ($[i....]), the icon title ($[it....]) or the icon
picture ($[ip....]).
$[pointer.x] $[pointer.y]
These return the position of the pointer on the screen. If the pointer is not on the screen, these variables are
not expanded.
$[pointer.wx] $[pointer.wy]
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.
$[pointer.cx] $[pointer.cy]
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.
$[pointer.screen]
The screen number the pointer is currently on. Returns 0 if Xinerama is not enabled.
$[screen]
The screen number fvwm is running on. Useful for setups with multiple screens.
$[fg.cs] $[bg.cs] $[hilight.cs] $[shadow.cs]
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 Colorsets section for details about colorsets.
$[schedule.last]
This is replaced by the id of the last command that was scheduled with the Schedule command, even if this command
was already executed.
$[schedule.next]
This is replaced by the id the next command used with Schedule will get (unless a different id is specified
explicitly).
$[cond.rc]
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 Conditional Commands in the command list.
$[func.context]
The context character of the running command as used in the Mouse, Key or PointerKey command. This is useful for
example with:
Mouse 3 FS N WindowShade $$[func.context]
$[gt.str]
return the translation of str by looking in the current locale catalogs. If no translation is found str is
returned as is. See the LocalePath command.
$[infostore.key]
Return the value of the item stored in the InfoStore at the given key. If no key is present, the unexpanded
string is returned.
$[...]
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.
Some examples can be found in the description of the AddToFunc command.
SCRIPTING & COMPLEX FUNCTIONS
To achieve the more complex effects, fvwm has a number of commands that improve its scripting abilities. Scripts can
be read from a file with Read, from the output of a command with PipeRead or written as a complex function with the
AddToFunc command. For the curious, section 7 of the fvwm FAQ shows some real life applications of scripting.
Please refer to the sections User Functions and Shell Commands and Conditional Commands for details. A word of
warning: during execution of complex functions, fvwm needs to take all input from the mouse pointer (the pointer is
"grabbed" in the slang of X). No other programs can receive any input from the pointer while a function is run.
This can confuse some programs. For example, the xwd program refuses to make screen shots when run from a complex
function. To achieve the same functionality you can use the Read or PipeRead command instead.
LIST OF FVWM COMMANDS
The command descriptions below are grouped together in the following sections. The sections are hopefully sorted in
order of usefulness to the newcomer.
• Menu commands
• Miscellaneous commands
• Commands affecting window movement and placement
• Commands for focus and mouse movement
• Commands controlling window state
• Commands for mouse, key and stroke bindings
• The Style command (controlling window styles)
• Other commands controlling window styles
• Commands controlling the virtual desktop
• Commands for user functions and shell commands
• Conditional commands
• Module commands
• Quit, restart and session management commands
• Colorsets
• Color gradients
Menus
Before a menu can be opened, it has to be populated with menu items using the AddToMenu command and bound to a key or
mouse button with the Key, PointerKey or Mouse command (there are many other ways to invoke a menu too). This is
usually done in the configuration file.
Fvwm menus are extremely configurable in look and feel. Even the slightest nuances can be changed to the user's
liking, including the menu item fonts, the background, delays before popping up sub menus, generating menus
dynamically and many other features. Please refer to the MenuStyle command to learn more.
Types of Menus
In fvwm there are four slightly different types of menus:
Popup menus can appear everywhere on the screen on their own or attached to a part of a window. The Popup
command opens popup menus. If the popup menu was invoked with a mouse button held down, it is closed when the
button is released. The item under the pointer is then activated and the associated action is executed.
Menu is a very similar command, but the menus it opens are slightly less transient. When invoked by clicking
a mouse button, it stays open and can be navigated with no button held. But if it is invoked by a button
press followed by mouse motion, it behaves exactly like a popup menu.
Tear off menus or Pin up menus are menus from either of the above two commands that have been "torn off" their
original context and pinned on the desktop like a normal window. They are created from other menus by certain
key presses or mouse sequences or with the TearMenuOff command from inside a menu.
Sub menus are menus inside menus. When a menu item that has the Popup command as its action is selected, the
named menu is opened as an inferior menu to the parent. Any type of menu can have sub menus.
Menu Anatomy
Menus consist of any number of titles which are inactive menu items that usually appear at the top of the
menu, normal items triggering various actions when selected, separator lines between the items, tear off bars
(a horizontal broken line) that tear off the menu when selected, and sub menu items indicated with a triangle
pointing left or right, depending on the direction in which the sub menu appears. All the above menu items
are optional.
Additionally, if the menu is too long to fit on the screen, the excess menu items are put in a continuation
menu and a sub menu with the string "More..." is placed at the bottom of the menu. The "More..." string
honors the locale settings.
Finally, there may be a picture running up either side of the menu (a "side bar").
Menu Navigation
Menus can be navigated either with the keyboard or with the mouse. Many people prefer to use the mouse, but
it can be rather tedious. Once you get the hang of it, keyboard navigation can be much faster. While fvwm
displays a menu, it can do nothing else. For example, new windows do not appear before the menu is closed.
However, this is not exactly true for tear off menus. See the Tear Off Menus section for details.
Mouse Navigation
Moving the pointer over a menu selects the item below it. Normally this is indicated by a 3d border around
the item, but not all parts of a menu can be selected. Pressing any mouse button while a menu is open 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.
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 MouseWheel menu style.
Clicking on a selected item activates it - what happens exactly depends on the type of the item.
Clicking on a title, a separator, the side bar, or outside the menu closes the menu (exception: tear off menus
can not be closed this way). Pressing mouse button 2 over a menu title or activating a tear off bar creates a
tear off menu from the current menu. Clicking on a normal menu item invokes the command that is bound to it,
and clicking on a sub menu item either closes all open menus and replaces them with the sub menu or posts the
menu (default).
Posting menus is meant to ease mouse navigation. Once a sub menu is posted, only items from that sub menu can
be selected. This can be very useful to navigate the menu if the pointer tends to stray off the menu. To
unpost the menu and revert back to normal operation, either click on the same sub menu item or press any key.
Keyboard Navigation
Just like with mouse navigation, the item below the pointer is selected. This is achieved by warping the
pointer to the menu items when necessary. While a menu is open, all key presses are intercepted by the menu.
No other application can get keyboard input (although this is not the case for tear off menus).
Items can be selected directly by pressing a hotkey that can be configured individually for each menu item.
The hotkey is indicated by underlining it in the menu item label. With the AutomaticHotkeys menu style fvwm
automatically assigns hotkeys to all menu items.
The most basic keys to navigate through menus are the cursor keys (move up or down one item, enter or leave a
sub menu), Space (activate item) and Escape (close menu). Numerous other keys can be used to navigate through
menus by default:
Enter, Return, Space activate the current item.
Escape, Delete, Ctrl-G exit the current sequence of menus or destroy a tear off menu.
J, N, Cursor-Down, Tab, Meta-Tab, Ctrl-F, move to the next item.
K, P, Cursor-Up, Shift-Tab, Shift-Meta-Tab, Ctrl-B, move to the prior item.
L, Cursor-Right, F enter a sub menu.
H, Cursor-Left, B return to the prior menu.
Ctrl-Cursor-Up, Ctrl-K Ctrl-P, Shift-Ctrl-Meta-Tab, Page-Up move up five items.
Ctrl-Cursor-Down, Ctrl-J Ctrl-N, Ctrl-Meta-Tab Page-Down move down five items.
Shift-P, Home, Shift-Cursor-Up, Ctrl-A move to the first item.
Shift-N, End, Shift-Cursor-Down, Ctrl-E move to the last item.
Meta-P, Meta-Cursor-Up, Ctrl-Cursor-Left, Shift-Ctrl-Tab, move up just below the next separator.
Meta-N, Meta-Cursor-Down, Ctrl-Cursor-Right, Ctrl-Tab, move down just below the next separator.
Insert opens the "More..." sub menu if any.
Backspace tears off the menu.
Menu Bindings
The keys and mouse buttons used to navigate the menu can be configured using the Key and Mouse 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 MenuClose, MenuCloseAndExec, MenuEnterContinuation,
MenuEnterSubmenu, MenuLeaveSubmenu, MenuMoveCursor, MenuCursorLeft, MenuCursorRight, MenuSelectItem,
MenuScroll and MenuTearOff.
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.
MenuClose exits from the current sequence of menus or destroys a tear off menu.
MenuCloseAndExec exits from the current sequence of menus or destroys a tear off menu and executes the rest of
the line as a command.
MenuEnterContinuation opens the "More..." sub menu if any.
MenuEnterSubmenu enters a sub menu.
MenuLeaveSubmenu returns to the prior menu.
MenuMoveCursor n [m] 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.
MenuCursorLeft enters a sub menu with the SubmenusLeft menu style, and returns to the prior menu with the
SubmenusRight menu style.
MenuCursorRight enters a sub menu with the SubmenusRight menu style, and returns to the prior menu with the
SubmenusLeft menu style.
MenuSelectItem triggers the action for the menu item.
MenuScroll n performs menu scrolling according to the MouseWheel menu style with n items. The distance can be
suffixed with an 's' to indicate the items should refer only to the first items after separators.
MenuTearOff turns a normal menu into a "torn off" menu. See Tear Off Menus for details.
Tear Off Menus
A tear off menu is any menu that has been "torn off" the window it was attached to and pinned to the root
window. There are three ways to tear off a menu: click on the menu title with mouse button 2, press 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 TearMenuOff.
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:
Mouse 2 MT A -
and to remove the builtin backspace binding, use:
Key Backspace M A -
See the section Menu Bindings for details on how to assign other bindings for tear off.
Note that prior to fvwm 2.5.20 the tear off mouse bindings were redefined in different way, which no longer
work.
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:
Style fvwm_menu UsePPosition
To remove borders and buttons from a tear-off menu but keep the menu title, you can use
Style fvwm_menu !Button 0, !Button 1
Style fvwm_menu !Button 2, !Button 3
Style fvwm_menu !Button 4, !Button 5
Style fvwm_menu !Button 6, !Button 7
Style fvwm_menu !Button 8, !Button 9
Style fvwm_menu Title, HandleWidth 0
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 Escape key.
Tear off menus behave somewhat differently than normal menus and windows. They do not take the keyboard
focus, but while the pointer is over one of them, all key presses are sent to the menu. Other fvwm key
bindings are disabled as long as the pointer is inside the tear off menu or one of its sub menus. When the
pointer leaves this area, all sub menus are closed immediately. Note that the window containing a tear off
menu is never hilighted as if it had the focus.
A tear off menu is an independent copy of the menu it originated from. As such, it is not affected by adding
items to that menu or changing its menu style.
To create a tear off menu without opening the normal menu first, the option TearOffImmediately can be added to
the Menu or Popup command.
AddToMenu menu-name [menu-label action]
Begins or adds to a menu definition. Typically a menu definition looks like this:
AddToMenu Utilities Utilities Title
+ Xterm Exec exec xterm -e tcsh
+ Rxvt Exec exec rxvt
+ "Remote Logins" Popup Remote-Logins
+ Top Exec exec rxvt -T Top -n Top -e top
+ Calculator Exec exec xcalc
+ Xman Exec exec xman
+ Xmag Exec exec xmag
+ emacs Exec exec xemacs
+ Mail MailFunction xmh "-font fixed"
+ "" Nop
+ Modules Popup Module-Popup
+ "" Nop
+ Exit Fvwm Popup Quit-Verify
The menu could be invoked via
Mouse 1 R A Menu Utilities Nop
or
Mouse 1 R A Popup Utilities
There is no end-of-menu symbol. Menus do not have to be defined in a contiguous region of the config file.
The quoted (or first word) portion in the above examples is the menu label, which appears in the menu when the
user pops it up. The remaining portion is an fvwm command which is executed if the user selects that menu
item. An empty menu-label ("") and the Nop function are used to insert a separator into the menu.
The keywords DynamicPopUpAction and DynamicPopDownAction have a special meaning when used as the name of a
menu item. The action following the keyword is executed whenever the menu is popped up or down. This way you
can implement dynamic menus. It is even possible to destroy itself with DestroyMenu and the rebuild from
scratch. When the menu has been destroyed (unless you used the recreate option when destroying the menu), do
not forget to add the dynamic action again.
Note: Do not trigger actions that require user interaction. They may fail and may screw up your menus. See
the Silent command.
Warning Do not issue MenuStyle commands as dynamic menu actions. Chances are good that this crashes fvwm.
There are several configurable scripts installed together with fvwm for automatic menu generation. They have
their own man pages. Some of them, specifically fvwm-menu-directory and fvwm-menu-desktop, may be used with
DynamicPopupAction to create a directory listing or GNOME/KDE application listing.
Example (File browser):
# You can find the shell script fvwm_make_browse_menu.sh
# in the utils/ directory of the distribution.
AddToMenu BrowseMenu
+ DynamicPopupAction PipeRead \
'fvwm_make_browse_menu.sh BrowseMenu'
Example (Picture menu):
# Build a menu of all .jpg files in
# $HOME/Pictures
AddToMenu JpgMenu foo title
+ DynamicPopupAction Function MakeJpgMenu
AddToFunc MakeJpgMenu
+ I DestroyMenu recreate JpgMenu
+ I AddToMenu JpgMenu Pictures Title
+ I PipeRead 'for i in $HOME/Pictures/*.jpg; \
do echo AddToMenu JpgMenu "`basename $i`" Exec xv $i; done'
The keyword MissingSubmenuFunction has a similar meaning. It is executed whenever you try to pop up a sub
menu that does not exist. With this function you can define and destroy menus on the fly. You can use any
command after the keyword, but if the name of an item (that is a submenu) defined with AddToFunc follows it,
fvwm executes this command:
Function
i.e. the name is passed to the function as its first argument and can be referred to with "$0".
The fvwm-menu-directory script mentioned above may be used with MissingSubmenuFunction to create an up to date
recursive directory listing.
Example:
# There is another shell script fvwm_make_directory_menu.sh
# in the utils/ directory of the distribution. To use it,
# define this function in your configuration file:
DestroyFunc MakeMissingDirectoryMenu
AddToFunc MakeMissingDirectoryMenu
+ I PipeRead fvwm_make_directory_menu.sh $0
DestroyMenu SomeMenu
AddToMenu SomeMenu
+ MissingSubmenuFunction MakeMissingDirectoryMenu
+ "Root directory" Popup /
This is another implementation of the file browser that uses sub menus for subdirectories.
Titles can be used within the menu. If you add the option top behind the keyword Title, the title is added to
the top of the menu. If there was a title already, it is overwritten.
AddToMenu Utilities Tools Title top
All text up to the first Tab in the menu label is aligned to the left side of the menu, all text right of the
first Tab is aligned to the left in a second column and all text thereafter is placed right aligned in the
third column. All other Tab s are replaced by spaces. Note that you can change this format with the
ItemFormat option of the MenuStyle command.
If the menu-label contains an ampersand ('&'), the next character is taken as a hot-key for the menu item.
Hot-keys are underlined in the label. To get a literal '&', insert "&&". Pressing the hot-key moves through
the list of menu items with this hot-key or selects an item that is the only one with this hot-key.
If the menu-label contains a sub-string which is set off by stars, then the text between the stars is expected
to be the name of an image file to insert in the menu. To get a literal '*', insert "**". For example
+ Calculator*xcalc.xpm* Exec exec xcalc
inserts a menu item labeled "Calculator" with a picture of a calculator above it. The following:
+ *xcalc.xpm* Exec exec xcalc
Omits the "Calculator" label, but leaves the picture.
If the menu-label contains a sub-string which is set off by percent signs, then the text between the percent
signs is expected to be the name of image file (a so called mini icon to insert to the left of the menu label.
A second mini icon that is drawn at the right side of the menu can be given in the same way. To get a literal
'%', insert "%%". For example
+ Calculator%xcalc.xpm% Exec exec xcalc
inserts a menu item labeled "Calculator" with a picture of a calculator to the left. The following:
+ %xcalc.xpm% Exec exec xcalc
Omits the "Calculator" label, but leaves the picture. The pictures used with this feature should be small
(perhaps 16x16).
If the menu-name (not the label) contains a sub-string which is set off by at signs ('@'), then the text
between them is expected to be the name of an image file to draw along the left side of the menu (a side
pixmap). You may want to use the SidePic option of the MenuStyle command instead. To get a literal '@',
insert "@@". For example
AddToMenu StartMenu@linux-menu.xpm@
creates a menu with a picture in its bottom left corner.
If the menu-name also contains a sub-string surrounded by '^'s, then the text between '^'s is expected to be
the name of an X11 color and the column containing the side picture is colored with that color. You can set
this color for a menu style using the SideColor option of the MenuStyle command. To get a literal '^', insert
"^^". Example:
AddToMenu StartMenu@linux-menu.xpm@^blue^
creates a menu with a picture in its bottom left corner and colors with blue the region of the menu containing
the picture.
In all the above cases, the name of the resulting menu is name specified, stripped of the substrings between
the various delimiters.
ChangeMenuStyle menustyle menu ...
Changes the menu style of menu to menustyle. You may specify more than one menu in each call of
ChangeMenuStyle.
CopyMenuStyle orig-menustyle dest-menustyle
Copy orig-menustyle to dest-menustyle, where orig-menustyle is an existing menu style. If the menu style
dest_menustyle does not exist, then it is created.
DestroyMenu [recreate] menu
Deletes a menu, so that subsequent references to it are no longer valid. You can use this to change the
contents of a menu during an fvwm session. The menu can be rebuilt using AddToMenu. The optional parameter
recreate tells fvwm not to throw away the menu completely but to throw away all the menu items (including the
title).
DestroyMenu Utilities
DestroyMenuStyle menustyle
Deletes the menu style named menustyle and changes all menus using this style to the default style, you cannot
destroy the default menu style.
DestroyMenuStyle pixmap1
Menu menu-name [position] [double-click-action]
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 double-click-action is invoked
if the user double-clicks a button (or hits the key rapidly twice if the menu is bound to a key) when bringing
up the menu. If the double click action is not specified, double clicking on the menu does nothing. However,
if the menu begins with a menu item (i.e. not with a title or a separator) and the double click action is not
given, double clicking invokes the first item of the menu (but only if the pointer really was over the item).
The pointer is warped to where it was when the menu was invoked if it was both invoked and closed with a
keystroke.
The position arguments allow placement of the menu somewhere on the screen, for example centered on the
visible screen or above a title bar. Basically it works like this: you specify a context-rectangle and an
offset to this rectangle by which the upper left corner of the menu is moved from the upper left corner of the
rectangle. The position arguments consist of several parts:
[context-rectangle] x y [special-options]
The context-rectangle can be one of:
Root
the root window of the current screen.
XineramaRoot
the root window of the whole Xinerama screen. Equivalent to "root" when Xinerama is not used.
Mouse
a 1x1 rectangle at the mouse position.
Window
the frame of the context window.
Interior
the inside of the context window.
Title
the title of the context window or icon.
Button
button #n of the context window.
Icon
the icon of the context window.
Menu
the current menu.
Item
the current menu item.
Context
the current window, menu or icon.
This
whatever widget the pointer is on (e.g. a corner of a window or the root window).
Rectangle
the rectangle defined by in X geometry format. Width and height default to 1 if omitted.
If the context-rectangle is omitted or illegal (e.g. "item" on a window), "Mouse" is the default. Note that
not all of these make sense under all circumstances (e.g. "Icon" if the pointer is on a menu).
The offset values x and y 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 'm' the menu's width (height) is used instead. Furthermore a trailing 'p' changes the interpretation
to mean pixels.
Instead of a single value you can use a list of values. All additional numbers after the first one are
separated from their predecessor by their sign. Do not use any other separators.
If x or y are prefixed with "'o" 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".
A prefix of 'c' is equivalent to "o50". Examples:
# window list in the middle of the screen
WindowList Root c c
# menu to the left of a window
Menu name window -100m c+0
# popup menu 8 pixels above the mouse pointer
Popup name mouse c -100m-8p
# somewhere on the screen
Menu name rectangle 512x384+1+1 +0 +0
# centered vertically around a menu item
AddToMenu foobar-menu
+ "first item" Nop
+ "special item" Popup "another menu" item +100 c
+ "last item" Nop
# above the first menu item
AddToMenu foobar-menu
+ "first item" Popup "another menu" item +0 -100m
Note that you can put a sub menu far off the current menu so you could not reach it with the mouse without
leaving the menu. If the pointer leaves the current menu in the general direction of the sub menu the menu
stays up.
The special-options:
To create a tear off menu without opening the normal menu, add the option TearOffImmediately. Normally the
menu opens in normal state for a split second before being torn off. As tearing off places the menu like any
other window, a position should be specified explicitly:
# Forbid fvwm to place the menu window
Style UsePPosition
# Menu at top left corner of screen
Menu Root 0p 0p TearOffImmediately
The Animated and Mwm or Win menu styles may move a menu somewhere else on the screen. If you do not want this
you can add Fixed as an option. This might happen for example if you want the menu always in the top right
corner of the screen.
Where do you want a menu to appear when you click on 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 SelectInPlace option. If you want
the pointer on the title of the menu, use SelectWarp too. Note that these options apply only if the
PopupAsRootMenu MenuStyle option is used.
The pointer is warped to the title of a sub menu whenever the pointer would be on an item when the sub menu is
popped up (fvwm menu style) or never warped to the title at all (Mwm or Win menu styles). You can force
(forbid) warping whenever the sub menu is opened with the WarpTitle (NoWarp) option.
Note that the special-options do work with a normal menu that has no other position arguments.
MenuStyle stylename [options]
Sets a new menu style or changes a previously defined style. The stylename is the style name; if it contains
spaces or tabs it has to be quoted. The name "*" is reserved for the default menu style. The default menu
style is used for every menu-like object (e.g. the window created by the WindowList command) that had not be
assigned a style using the ChangeMenuStyle. See also DestroyMenuStyle. When using monochrome color options
are ignored.
options 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.
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.
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.
This is a list of MenuStyle deprecated negative options: ActiveForeOff, AnimationOff, AutomaticHotkeysOff,
HilightBackOff, TitleWarpOff
Fvwm, Mwm, Win reset all options to the style with the same name in former versions of fvwm. The default for
new menu styles is Fvwm style. These options override all others except Foreground, Background, Greyed,
HilightBack, ActiveFore and PopupDelay, so they should be used only as the first option specified for a menu
style or to reset the style to defined behavior. The same effect can be created by setting all the other
options one by one.
Mwm and Win style menus popup sub menus automatically. Win menus indicate the current menu item by changing
the background to dark. Fvwm sub menus overlap the parent menu, Mwm and Win style menus never overlap the
parent menu.
Fvwm 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.
Mwm 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.
Win 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.
BorderWidth takes the thickness of the border around the menus in pixels. It may be zero to 50 pixels. The
default is 2. Using an illegal value reverts the border width to the default.
Foreground and Background may have a color name as an argument. This color is used for menu text or the
menu's background. You can omit the color name to reset these colors to the built-in default.
Greyed may have a color name as an argument. This color is the one used to draw a menu-selection which is
prohibited (or not recommended) by the Mwm hints which an application has specified. If the color is omitted
the color of greyed menu entries is based on the background color of the menu.
HilightBack and !HilightBack 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 HilightBack. If you use
this option without an argument the color is based on the menu's background color. The ActiveColorset option
overrides the specified color. If the colorset has a non solid background it is used for the hilighting.
HilightTitleBack switches hilighting the background of menu titles on. If a TitleColorset 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.
ActiveFore and !ActiveFore 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 ActiveFore. Omitting the color
turns hilighting on when an ActiveColorset is used. ActiveFore turns off hilighting the foreground
completely. The ActiveColorset option overrides the specified color.
MenuColorset controls if a colorset is used instead of the Foreground, Background and MenuFace menu styles.
If the MenuColorset keyword is followed by a number equal to zero or greater, this number is taken as the
number of the colorset to use. If the number is omitted, the colorset is switched off and the regular menu
styles are used again. The foreground and background colors of the menu items are replaced by the colors from
the colorset. If the colorset has a pixmap defined, this pixmap is used as the background of the menu. Note
that the MenuFace menu style has been optimized for memory consumption and may use less memory than the
background from a colorset. The shape mask from the colorset is used to shape the menu. Please refer to the
Colorsets section for details about colorsets.
ActiveColorset works exactly like MenuColorset, but the foreground from the colorset replaces the color given
with the ActiveFore menu style and the colorset's background color replaces the color given with the
HilightBack command (to turn on background hilighting you have to use the HilightBack menu style too). If
specified, the hilight and shadow colors from the colorset are used too. The pixmap and shape mask from the
colorset are not used. Hilighting the background or foreground can be turned off individually with the
!ActiveFore or !HilightBack menu styles.
GreyedColorset works exactly like MenuColorset, but the foreground from the colorset replaces the color given
with the Greyed menu style. No other parts of the colorset are used.
TitleColorset works exactly like MenuColorset, but is used only for menu titles.
Hilight3DThick, Hilight3DThin and Hilight3DOff determine if the selected menu item is hilighted with a 3D
relief. Thick reliefs are two pixels wide, thin reliefs are one pixel wide.
Hilight3DThickness takes one numeric argument that may be between -50 and +50 pixels. With negative values
the menu item gets a pressed in look. The above three commands are equivalent to a thickness of 2, 1 and 0.
Animation and !Animation 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.
Font and TitleFont 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
TitleFont is given, it is used for all menu titles instead of the normal font.
MenuFace enforces a fancy background upon the menus. You can use the same options for MenuFace as for the
ButtonStyle. See description of ButtonStyle command and the Color Gradients sections for more information.
If you use MenuFace without arguments the style is reverted back to normal.
Some examples of MenuFaces are:
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
Note: The gradient styles H, V, B and D are optimized for high speed and low memory consumption in menus.
This is not the case for all the other gradient styles. They may be slow and consume huge amounts of memory,
so if you encounter performance problems with them you may be better off by not using them. To improve
performance you can try one or all of the following:
Turn hilighting of the active menu item other than foreground color off:
MenuStyle