Home
Authors History
Donations Cats
News
News FVWM Logo
Logo Competition
Features
Features
Download
Download
Icons and Sounds
Screenshots
Desktop Screenshots Menu Screenshots
Window Decor Screenshots Vectorbuttons
Documentation
Documentation Man pages
FAQ Developer Info
Mailing Lists
Mailing Lists
Links
Links
Customize
 
 Official FVWM Home Page plain theme

FVWM - Man page - fvwm2


FVWM2

Section: User Commands (1)
Updated: 30 May 2003
This page contents - Return to main index
 

NAME

fvwm2 - F(?) Virtual Window Manager (version 2) for X11  

SYNOPSIS

fvwm2 [-blackout] [-clientId id] [-cmd config_command] [-d displayname] [-debug] [-debug_stack_ring] [-f config_file] [-h] [-replace] [-restore state_file] [-s] [-version] [-visual visual_class] [-visualId id]

 

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, although the executable program is named fvwm2. There is an fvwm offspring called fvwm95. Although it is very similar to older versions of fvwm version 2 it is technically a different window manager that has been developed by different people. The main goal of fvwm95 was to supply a Windows 95 like look and feel. Since then fvwm has been greatly enhanced and only very few features of fvwm95 can not be imitated by fvwm. No active development has been going on for fvwm95 for several years now. Unfortunately Red Hat (a popular Linux distributor) has a pre-configured fvwm package based on fvwm version 2.x that is called fvwm95 too.

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 which allow you to perform most window-manager functions, including moving and resizing windows, and operating the menus, using keyboard shortcuts.

Fvwm has also blurred the distinction between configuration commands and built-in commands that most window-managers make. Configuration commands typically set fonts, colors, menu contents, key and mouse function bindings, while built-in commands typically do things like raise and lower windows. Fvwm makes no such distinction, and allows, to the extent that is practical, 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 specified for individual windows. 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 cursor over a NeverFocus decoration window won't deprive the terminal of focus.

 

OPTIONS

These are the command line options that are recognized by fvwm:

-blackout
This option is provided for backward compatibility only. Blacking out the screen during startup is not necessary anymore.
-clientId id
This option is used when fvwm is started by a session manager. Should not be used by a user.

-cmd config_command
Causes fvwm to use config_command instead of 'Read .fvwm2rc' as its initialization command. (Note that up to 10 -f and -cmd parameters can be given, and they are executed in the order specified.)
-d displayname
Manage the display called displayname instead of the name obtained from the environment variable $DISPLAY.
-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.
-debug_stack_ring
Enables stack ring debugging. This option is only intended for internal debugging and should only be used by developers.
-f config_file
Causes fvwm to read config_file instead of .fvwm2rc as its initialization file. This is equivalent to -cmd 'Read config_file'.
-h
A short usage description is printed.
-replace
Try to take over from a previously running wm. This does not work unless the other wm is ICCCM 2.0 compliant.
-restore state_file
This option is used when fvwm is started by a session manager. Should not be used by a user.
-s
On a multi-screen display, run fvwm only on the screen named in the $DISPLAY environment variable or provided through the -d option. Normally, fvwm attempts to start up on all screens of a multi-screen display.
-version
Prints the version of fvwm to stderr. Also prints an information about the compiled in support for readline, rplay, stroke, xpm, gnome hints, session management and multibyte characters.
-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".
-visualId id
Causes fvwm to use id as the visualId 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.

 

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.

Unless the standard defaults files are modified, pressing mouse button 1 in the title or side-bars begins a move operation on the window. Pressing button 1 in the corner frame pieces begins a resize operation. Pressing button 2 anywhere in the border brings up an extensive list of window operations.

Up to ten title-bar buttons may exist. Their use is completely user definable. The default configuration has a title-bar button on each side of the title-bar. The one on the left is used to bring up a list of window options, regardless of which mouse button is used. The one on the right is used to iconify the window. The number of title-bar buttons used depends on which ones have mouse actions bound to them. See the section on the Mouse command below.

 

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 built-in 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, along with their geometries, in a window list, accessible as a pop-up menu, or as a separate window, called the FvwmWinList (another module).

Fvwm keeps the windows on the desktop in a layered stacking order; a window in a lower layer never obscures a window in a higher layer. The layer of a window can be changed by using the 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 xbiff's, so you only need to run one such gadget and it always stays with you. Icons can also be made to stick to the glass, if desired.

Window geometries are specified relative to the current viewport. That is:

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 StartsOnPageorStartsOnScreen style specification (the successors to the older StartsOnDesk style) in the .fvwm2rc configuration 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 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 command allows to specify 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.

Everywhere where a geometry in the usual X format can be supplied, fvwm's Xinerama extension allows to specify 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. Fwvm 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 configurations file that would work on a single screen. It may not work too well if the involved screens use different screen resolutions. In this situation, windows may get stuck in the portion of the whole desktop that belongs to neither screen. If this happens, the windows or icons can be retrieved with the command

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 and XineramaSlsSize 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 .fvwm2rc

This looks for .fvwm2rc in $HOME/.fvwm or $FVWM_USERDIR directories, as described in Read below. If this fails, fvwm also searches for this file in the $HOME directory or for system.fvwm2rc file in the system place. If a configuration file is not found, any mouse button or the Help or F1 keys on the root window brings 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 rsh 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 .fvwm2rc, but it is not recommended; do this only if you know what you are doing. It is usually critical to start applications or modules after .fvwm2rc 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 reads the entire .fvwm2rc.

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 .fvwm2rc file via 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 .fvwm2rc 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 ModuleSynchronous FvwmTheme
 + I Module FvwmPager * *
 + I Module FvwmButtons

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

DestroyFunc RestartFunction
AddToFunc RestartFunction
 + I Module FvwmTaskBar

DestroyFunc SessionInitFunction
AddToFunc SessionInitFunction
 + I Module FvwmBanner

DestroyFunc SessionRestartFunction
AddToFunc SessionRestartFunction
 + I Nop

You don't need to define all special functions if some are empty.

 

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

The basic fvwm configuration uses monochrome bitmap icons. If XPM extensions are compiled in, then color icons can be used. In order to use these options you need the XPM package, as described in the INSTALL.fvwm file.

If both the SHAPE and XPM options are compiled in you get shaped color icons, which are very spiffy.

 

MODULES

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

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

Modules can be spawned during fvwm at any time during the X session by use of the Module built-in 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 text commands to the fvwm built-in command engine. Text commands are formatted just as in the case of a mouse binding in the .fvwm2rc setup file. Certain auxiliary information is also transmitted, as in the sample module FvwmButtons. The FvwmButtons module is documented in its own man page.

Please refer to the MODULE COMMANDS section for details.

 

ICCCM COMPLIANCE

Fvwm attempts to be ICCCM 2.0 compliant. 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

fvwm2; vi .fvwm2rc; fvwm2 -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 .SM ICCCM for details) and the urgency hint. Clients can set this hint in the WM_HINTS property of their window and expect the window manager to attract the users attention to the window. Fvwm has two re-definable functions for this purpose, "UrgencyFunc" and "UrgencyDoneFunc", which are executed when the flag is set/cleared. Their default definitions are:

AddToFunc UrgencyFunc
 + I Iconify off
 + I FlipFocus
 + I Raise
 + I WarpToWindow 5p 5p
AddToFunc UrgencyDoneFunc
 + I Nop

 

GNOME COMPLIANCE

Fvwm attempts to be GNOME compliant. Check http://www.gnome.org for what that may mean. GNOME support is a compile time option which is on by default. To disable GNOME hints for some or all windows, the GNOMEIgnoreHints style can be used.

 

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

 

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 .fvwm2rc:

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 NoLenience style for all such applications (the windows will still get the focus):

Style <application name> NeverFocus, NoLenience

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 <application name> MouseFocus, Lenience
Style <application name> SloppyFocus, Lenience
Style <application name> 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 .fvwm2rc file (if it appears at all), and start fvwm with the command

fvwm2 -cmd "FvwmM4 .fvwm2rc"

 

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 above, but replace "m4" with "cpp".

 

AUTO-RAISE

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

 

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 .fvwm2rc. By using the Read built-in, 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 built-in commands, so anything mentioned in the built-in 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, .fvwm2rc, is supplied with the fvwm distribution. It is well commented and can be used as a source of examples for fvwm configuration.

 

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 built-in to appropriate keys, Popup, Move, Resize, and most other built-ins can be bound to keys. Once a built in function 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 cursor 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, shadedness, maximizedness, iconifiedness for all windows. Furthermore, some global state is saved.

Fvwm doesn't save any information regarding styles, decors, functions or menus. If you change any on these resources during a session (e.g. by issuing 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 fvwm2

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.

 

BUILT IN 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 0 R N Menu MenuFvwmRoot
Mouse 1 TS A FuncFvwmRaiseLowerX Move
Mouse 1 F  A FuncFvwmRaiseLowerX Resize
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 -

 

BUILT IN COMMANDS

Fvwm supports a set of built-in functions which can be bound to keyboard or mouse buttons. If fvwm expects to find a built-in function in a command, but fails, 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 .fvwm2rc file contains the line

HelpMe

Fvwm looks for a built-in command called "HelpMe", and fails. Next it looks for a user-defined complex function called "HelpMe". If no such user defined function exists, Fvwm tries to execute a module called "HelpMe".

Note: There are many commands that affect look and feel of specific, some or all windows, like Style, Mouse, the FvwmTheme module 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 don't 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 a 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 quote a '$' use "$$".

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

Example:

# Print the current desk number, horizontal
# page and the window's class.
Echo $[desk.n] $[page.nx] $[w.class]

Note: If the command is called outside a window context, it will print "$[w.class]" instead of the class name. It is usually not enough to have the pointer over a window to have a context window. To force using the window with the focus, the 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 '.'.

$c
The window's resource class name or "$c" if no window is associated with the command.

(Deprecated, use $[w.class] instead.)

$d
The current desk number.

(Deprecated, use $[desk.n] instead.)

$n
The window's name or "$n" if no window is associated with the command.

(Deprecated, use $[w.name] instead.)

$r
The window's resource name or "$r" if no window is associated with the command.

(Deprecated, use $[w.resource] instead.)

$v
The first line printed by the -version command line option.

(Deprecated, use $[version.line] instead.)

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

(Deprecated, use $[w.id] instead.)

$x
The x coordinate of the current viewport.

(Deprecated, use $[vp.x] instead.)

$y
The y coordinate of the current viewport.

(Deprecated, use $[vp.y] instead.)

$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".

$[version.num]
The version number, like "2.6.0".

$[version.info]
The version info, like " (from cvs)", empty for the official releases. (Always empty in this branch.)

$[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.

$[desk.n]
The current desk number.

$[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.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.name] $[w.iconname] $[w.class] $[w.resource]
The window's name or icon name or resource class or resource name respectivelly, or unexpended "$[w.<attribute>]" string if no window is associated with the command.

$[screen]
The screen number fvwm is running on. Useful for setups with multiple screens.

$[fg.cs<n>]
$[bg.cs<n>]
$[hilight.cs<n>]
$[shadow.cs<n>]
These class of parameters is replaced with the name of the foreground (fg), background (bg), hilight (hilight) or shadow (shadow) color that is defined in colorset <n> (replace <n> with zero or a positive integer). For example "$[fg.cs3]" is expanded to the name of the foreground color of colorset 3 (in rgb:rrrr/gggg/bbbb form). Please refer to the man page of the FvwmTheme module for details about colorsets. Note that although other parameters cannot be used in module configuration lines, it is possible to use this class of parameters. They can be used wherever a module expects a color name. Since the FvwmTheme module is not running when fvwm first passes through its configuration file, you may not get the desired results if you use this in commands like

Style * HilightFore $[fg.cs0], HilightBack $[bg.cs0]

$[...]
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.

 

THE LIST OF BUILTIN COMMANDS

The commands 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
- Color gradients

 

COMMANDS FOR MENUS

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 .fvwm2rc file. The quoted portion in the above examples is the menu label, which appears in the menu when the user pops it up. The remaining portion is a built-in command which should be executed if the user selects that menu item. An empty menu-label ("") and the Nop function can be 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 will probably fail and may screw up your menus. See Silent command.

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

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 the name of a function defined with AddToFunc follows it, fvwm executes this command:

Function <function-name> <menu-name>

I.e. the name is passed to the function as its first argument and can be referred to with "$0".

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:

AddToFunc MakeMissingDirectoryMenu
+ I Exec fvwm_make_directory_menu.sh $0

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 Tabs 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 xpm-icon or bitmap-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 an xpm-icon or bitmap-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 xpm or bitmap 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 specified more than one menu in each call of ChangeMenuStyle.

ChangeMenuStyle pixmap1 \
  ScreenSaverMenu ScreenLockMenu

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 pixamp1

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

Several other commands affect menu operation. See MenuStyle and SetAnimation. When in a menu, keyboard shortcuts work as expected. Cursor keystrokes are also allowed. Specifically, Tab, Meta-Tab, Cursor-Down, Ctrl-N, or Ctrl-J move to the next item; Shift-Tab, Shift-Meta-Tab, Cursor-Up, Ctrl-P, or Ctrl-K move to the prior item; Cursor-Left or Ctrl-B returns to the prior menu; Cursor-Right or Ctrl-F pop up the next menu; Ctrl-Cursor-Up, Shift-Ctrl-Meta-Tab and Page-Up move up five items; Ctrl-Cursor-Down, Ctrl-Meta-Tab and Page-Down move down five items, respectively; Home, Shift-Cursor-Up or End, Shift-Cursor-Down move to the first or last item, respectively; Meta-Cursor-Up or Meta-Cursor-Down move just behind the next or previous separator; Shift-Ctrl-Tab or Ctrl-Tab work exactly the same; Enter, Return, or Space executes the current item; Insert opens the "More..." sub-menu if any; Escape and Delete exit the current sequence of menus.

The pointer is warped to where it was when the menu was invoked if it was both invoked and terminated 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 window with the focus.
Interior
the inside of the focused window.
Title
the title of the focused window or icon.
Button<n>
button #n of the focused window.
Icon
the focused icon.
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 <geometry>
the rectangle defined by <geometry> 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 it's default position. By default, the numeric value given is interpreted as a percentage of the context rectangle's width (height), but with a trailing '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<number>" where <number> is an integer, the menu and the rectangle are moved to overlap at the specified position before any other offsets are applied. The menu and the rectangle are placed so that the pixel at <number> percent of the rectangle's width/height is right over the pixel at <number> percent of the menu's width/height. So "o0" means that the top/left borders of the menu and the rectangle overlap, with "o100" it's the bottom/right borders and if you use "o50" they are centered upon each other (try it and you will see it is much simpler than this description). The default is "o0". The prefix "o<number>" is an abbreviation for "+<number>-<number>m".

A prefix of '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:

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 it's menu item? The default is to place the title under the cursor, but if you want it where the position arguments say, use the 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 / HilightBackOff, ActiveFore / ActiveForeOff, MenuColorset, ActiveColorset, GreyedColorset, Hilight3DThick / Hilight3DThin / Hilight3DOff, Hilight3DThickness, Animation / AnimationOff, Font, MenuFace, PopupDelay, PopupOffset, TitleWarp / TitleWarpOff, TitleUnderlines0 / TitleUnderlines1 / TitleUnderlines2, SeparatorsLong / SeparatorsShort, TrianglesSolid / TrianglesRelief, PopupImmediately / PopupDelayed, PopdownImmediately / PopdownDelayed, DoubleClickTime, SidePic, SideColor, PopupAsRootMenu / PopupAsSubmenu, RemoveSubmenus / HoldSubmenus, SubmenusRight / SubmenusLeft, SelectOnRelease, ItemFormat, VerticalItemSpacing, VerticalTitleSpacing, AutomaticHotkeys / AutomaticHotkeysOff.

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

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, HilightFore 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 HilightBackOff, Hilight3DThin, ActiveForeOff, AnimationOff, Font, MenuFace, PopupOffset 0 67, TitleWarp, TitleUnderlines1, SeparatorsShort, TrianglesRelief, PopupDelayed, PopdownDelayed, PopupAsSubmenu, HoldSubmenus, SubmenusRight, BorderWidth 2, AutomaticHotkeysOff.

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

Win style is equivalent to HilightBack, Hilight3DOff, ActiveForeOff, AnimationOff, Font, MenuFace, PopupOffset -5 100, TitleWarpOff, TitleUnderlines1, SeparatorsShort, TrianglesSolid, PopupImmediately, PopdownDelayed, PopupAsSubmenu, RemoveSubmenus, SubmenusRight, BorderWidth 2, AutomaticHotkeysOff.

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 HilightBackOff switch hilighting the background of the selected menu item on and off. A specific background color may be used by providing the color name as an argument to HilightBack. If you use this option without an argument the color is based on the menu's background color.

ActiveFore and ActiveForeOff switch hilighting the foreground of the selected menu item on and off. A specific foreground color may be used by providing the color name as an argument to ActiveFore. Omitting the color name has the same effect as using ActiveForeOff.

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 description of the Colorset command and the documentation of the FvwmTheme module 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.

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.

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 AnimationOff turn menu animation on or off. When animation is on, sub-menus that don't fit on the screen cause the parent menu to be shifted to the left so the sub-menu can be seen.

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

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 <style> Hilight3DOff, HilightBackOff
MenuStyle <style> ActiveFore <preferred color>

Make sure sub-menus do not overlap the parent menu. This can prevent menus being redrawn every time a sub-menu pops up or down.

MenuStyle <style> PopupOffset 1 100

Run your X server with backing storage. If your X Server is started with the -bs option, turn it off. If not try the -wm option.

startx -- -wm

You may have to adapt this example to your system (e.g. if you use xinit to start X).

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

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

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

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

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

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

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

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

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

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

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

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

PopupAsRootMenu and PopupAsSubmenu change the behavior when you click on a menu item that opens a sub-menu. With PopupAsRootMenu the original menu is closed before the sub-menu appears, with PopupAsSubmenu it is not, so you can navigate back into the parent menu. Furthermore, with PopupAsSubmenu the sub-menu is held open (posted) regardless of where you move the mouse. Depending on your menu style this may simplify navigating through the menu. Any keystroke while a menu is posted reverts the menu back to the normal behavior. PopupAsSubmenu is the default.

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

SelectOnRelease takes an optional key name as an argument. If the given key is release in a menu using this style, the current menu item is selected. This is intended for Alt-Tab WindowList navigation. The key name is a standard X11 key name as defined in /usr/include/X11/keysymdef.h, with the leading "XK_" omitted. To disable this behaviour, omit the key name.

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

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

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

You can define an additional space before and after each of the objects like this:

%left.rightp

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

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

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

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

Examples:

MenuStyle * ItemFormat \
  "%.4s%.1|%.5i%.5l%.5l%.5r%.5i%2.3>%1|"

Is the default string used by fvwm: (side picture + 4 pixels gap) (beginning of the hilighted area + 1 pixel gap) (mini icon + 5p) (first column left aligned + 5p) (second column left aligned + 5p) (third column right aligned + 5p) (second mini icon + 5p) (2p + sub-menu triangle + 3p) (1p + end of hilighted area).

MenuStyle * ItemFormat \
  "%.1|%3.2<%5i%5l%5l%5r%5i%1|%4s"

Is used by fvwm with the SubmenusLeft option below.

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

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

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

Examples:

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

MenuStyle red Mwm
MenuStyle red Foreground Yellow
MenuStyle red Background Maroon
MenuStyle red Greyed Red, ActiveFore Red
MenuStyle red HilightBackOff, Hilight3DOff
MenuStyle red Font lucidasanstypewriter-12
MenuStyle red MenuFace DGradient 64 Red Black

Note that all style options could be placed on a single line for each style name.

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

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

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

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

Popup PopupName [position] [default-action]
This built-in has two purposes: to bind a menu to a key or mouse button, and to bind a sub-menu into a menu. The formats for the two purposes differ slightly. The position arguments are the same as for Menu. The command default-action is invoked if the user clicks a button to invoke the menu and releases it immediately again (or hits the key rapidly twice if the menu is bound to a key). If the default action is not specified, double clicking on the menu does nothing. However, if the menu begins with a menu item (i.e. not with a title or a separator) and the default action is not given, double clicking invokes the first item of the menu (but only if the pointer really was over the item).

To bind a previously defined pop-up menu to a key or mouse button:

The following example binds mouse buttons 2 and 3 to a pop-up called "Window Ops". The menu pops up if the buttons 2 or 3 are pressed in the window frame, side-bar, or title-bar, with no modifiers (none of shift, control, or meta).

Mouse 2 FST N Popup "Window Ops"
Mouse 3 FST N Popup "Window Ops"

Pop-ups can be bound to keys through the use of the Key built-in. Pop-ups can be operated without using the mouse by binding to keys and operating via the up arrow, down arrow, and enter keys.

To bind a previously defined pop-up menu to another menu, for use as a sub-menu:

The following example defines a sub-menu "Quit-Verify" and binds it into a main menu, called "RootMenu":

AddToMenu Quit-Verify
 + "Really Quit Fvwm?" Title
 + "Yes, Really Quit"  Quit
 + "Restart Fvwm"      Restart
 + "Restart Fvwm 1.xx" Restart fvwm1 -s
 + ""                  Nop
 + "No, Don't Quit"    Nop

AddToMenu RootMenu "Root Menu" Title
 + "Open XTerm Window" Popup NewWindowMenu
 + "Login as Root"     Exec exec xterm \
                         -fg green -T Root \
                         -n Root -e su -
 + "Login as Anyone"   Popup AnyoneMenu
 + "Remote Hosts"      Popup HostMenu
 + ""                  Nop
 + "X utilities"       Popup Xutils
 + ""                  Nop
 + "Fvwm Modules"      Popup Module-Popup
 + "Fvwm Window Ops"   Popup Window-Ops
 + ""                  Nop
 + "Previous Focus"    Prev (AcceptsFocus) Focus
 + "Next Focus"        Next (AcceptsFocus) Focus
 + ""                  Nop
 + "Refresh screen"    Refresh
 + "Recapture screen"  Recapture
 + ""                  Nop
 + "Reset X defaults"  Exec xrdb -load \
                       $HOME/.Xdefaults
 + ""                  Nop
 + ""                  Nop
 + Quit                Popup Quit-Verify

Popup differs from Menu in that pop-ups do not stay up if the user simply clicks. These are popup-menus, which are a little hard on the wrist. Menu menus stay up on a click action. See the Menu command for an explanation of the interactive behavior of menus. A menu can be open up to ten times at once, so a menu may even use itself or any of its predecessors as a sub-menu.

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

 

MISCELLANEOUS COMMANDS

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

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

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

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

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

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

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

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

BusyCursor DynamicMenu False, \
  ModuleSynchronous False, Read False, \
  Recapture True, Wait False

The option * refers to all available options.

The Read option also controls the PipeRead command.

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

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

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

ColorLimit limit
Specifies a limit on the colors used in pixmaps used by fvwm. Zero (the default) sets no limit. Fvwm uses pixmaps for icons, mini-icons, and pixmap borders, menu backgrounds and titles. This command limits pixmap colors to a set of colors that starts out with common colors. The current list contains about 60 colors and starts with white, black, grey, green, blue, red, cyan, yellow, and magenta. The command

ColorLimit 9

would limit pixmaps to these 9 colors.

It makes the most sense to put this command at the front of the .fvwm2rc file. This command should occur before any menu definitions that contain mini-icons.

Solid frame and title colors (including shadows and gradients) are not controlled by this command.

This command only makes sense on screens that display a limited number of colors at once. If your display can display more than 2 million colors at once, this command is ignored. Screens that only display 256 colors at once are known as 8 bit displays. The 2 million color cutoff point corresponds to 21 bit color, the most common screen that exceeds this limit would be 24 bit.

On 8 bit displays, the default color limit is set to the size of the built in table (about 60). We recommend that you start with the default value, and not include this command in your .fvwm2rc.

ColormapFocus FollowsMouse|FollowsFocus
By default, fvwm installs the colormap of the window that the cursor is in. If you use

ColormapFocus FollowsFocus

then the installed colormap is the one for the window that currently has the keyboard focus.

CursorStyle context [ number | name | xpm | None | Tiny [ fore back ]]
Defines a new cursor for the specified context. The various contexts are:

POSITION (top_left_corner)
used when initially placing windows

TITLE (top_left_arrow)

used in a window title-bar

DEFAULT (top_left_arrow)

used in windows that don't set their cursor

SYS (hand2)

used in one of the title-bar buttons

MOVE (fleur)

used when moving or resizing windows

RESIZE (sizing)

used when moving or resizing windows

WAIT (watch)

used during certain fvwm commands (see BusyCursor for details).

MENU (top_left_arrow)

used in menus

SELECT (crosshair)

used when the user is required to select a window

DESTROY (pirate)

used for DESTROY, CLOSE, and DELETE built-ins

TOP (top_side)

used in the top side-bar of a window

RIGHT (right_side)

used in the right side-bar of a window

BOTTOM (bottom_side)

used in the bottom side-bar of a window

LEFT (left_side)

used in the left side-bar of a window

TOP_LEFT (top_left_corner)

used in the top left corner of a window

TOP_RIGHT (top_right_corner)

used in the top right corner of a window

BOTTOM_LEFT (bottom_left_corner)

used in the bottom left corner of a window

BOTTOM_RIGHT (bottom_right_corner)

used in the bottom right corner of a window

TOP_EDGE (top_side)

used at the top edge of the screen.

RIGHT_EDGE (right_side)

used at the right edge of the screen.

BOTTOM_EDGE (bottom_side)

used at the bottom edge of the screen.

LEFT_EDGE (left_side)

used at the left edge of the screen.

ROOT (left_ptr)

used as the root cursor.

STROKE (plus)

used during a StrokeFunc command.

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

The second is either the numeric value of the cursor as defined in the include file X11/cursorfont.h or its name (without the XC_ prefix) or the name of an xpm file containing a pixmap of depth 1 with a mask and an optional hot-spot (if no hot-spot is defined, the hot-spot is placed in the center of the image). Furthermore the name can be None (no cursor) or Tiny (a single pixel as the cursor). For example:

# make the kill cursor be XC_gumby (both forms work):
CursorStyle DESTROY 56
CursorStyle DESTROY gumby

CursorStyle TOP_LEFT topl.xpm
CursorStyle ROOT hand1 yellow black

The optional fg and bg arguments specify the foreground and background colors for the cursor, defaulting to black and white.

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

DefaultColorset [num]
DefaultColorset sets the colorset used by the windows controlled by the DefaultColors command. To revert back to the DefaultColors colors use

DefaultColorset -1

or any variant of the DefaultColors command.

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

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

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

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

EscapeFunc
By default the key sequence Ctrl-Alt-Escape allows to escape from a Wait pause and from a locked ModuleSynchronous command. The EscapeFunc command used with the Key command allows to configure this key sequence. An example:

Key Escape A MC -
Key Escape A  S EscapeFunc

replaces the Ctrl-Alt-Escape key sequence with Shift-Escape for aborting a Wait pause and ModuleSynchronous command. EscapeFunc used outside the Key command does nothing.

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

 FakeClick depth 2 press 1 wait 250 release 1

This simulates a click with button 1 in the parent window (depth 2) with a delay of 250 milliseconds between the press and the release.

GlobalOpts [options]
As announced in the past, this command has been removed. Please replace the global options in your configuration file according to the following table:

GlobalOpts WindowShadeShrinks
  -->
Style * WindowShadeShrinks

GlobalOpts WindowShadeScrolls
  -->
Style * WindowShadeScrolls

GlobalOpts SmartPlacementIsReallySmart
  -->
Style * MinOverlapPlacement

GlobalOpts SmartPlacementIsNormal
  -->
Style * TileCascadePlacement

GlobalOpts ClickToFocusDoesntPassClick
  -->
Style * ClickToFocusPassesClickOff

GlobalOpts ClickToFocusPassesClick
  -->
Style * ClickToFocusPassesClick

GlobalOpts ClickToFocusDoesntRaise
  -->
Style * ClickToFocusRaisesOff

GlobalOpts ClickToFocusRaises
  -->
Style * ClickToFocusRaises

GlobalOpts MouseFocusClickDoesntRaise
  -->
Style * MouseFocusClickRaisesOff

GlobalOpts MouseFocusClickRaises
  -->
Style * MouseFocusClickRaises

GlobalOpts NoStipledTitles
  -->
Style * StippledTitleOff

GlobalOpts StipledTitles
  -->
Style * StippledTitle

GlobalOpts CaptureHonorsStartsOnPage
  -->
Style * CaptureHonorsStartsOnPage

GlobalOpts CaptureIgnoresStartsOnPage
  -->
Style * CaptureIgnoresStartsOnPage

GlobalOpts RecaptureHonorsStartsOnPage
  -->
Style * RecaptureHonorsStartsOnPage

GlobalOpts RecaptureIgnoresStartsOnPage
  -->
Style * RecaptureIgnoresStartsOnPage

GlobalOpts ActivePlacementHonorsStartsOnPage
  -->
Style * ManualPlacementHonorsStartsOnPage

GlobalOpts ActivePlacementIgnoresStartsOnPage
  -->
Style * ManualPlacementIgnoresStartsOnPage

GlobalOpts RaiseOverNativeWindows
  -->
BugOpts RaiseOverNativeWindows on

GlobalOpts IgnoreNativeWindows
  -->
BugOpts RaiseOverNativeWindows off

HilightColor textcolor backgroundcolor
This command is obsoleted by the Style options HilightFore and HilightBack. Please use

Style * HilightFore textcolor, \
        HilightBack backgroundcolor

instead.

HilightColorset [num]
This command is obsoleted by the Style option HilightColorset. Please use

Style * HilightColorset num

instead.

IconFont [fontname]
This command is obsoleted by the Style option IconFont. Please use

Style * IconFont fontname

instead.

IconPath path
This command is obsolete. Please use ImagePath instead.

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

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

For example:

ImagePath $HOME/icons:+:/usr/include/X11/bitmaps

Note: if the FvwmM4 module is used to parse your .fvwm2rc files, then m4 may want to mangle the word "include" which frequently shows up in the ImagePath command. To fix this one may add

undefine(`include')

prior to the ImagePath command, or better: use the -m4-prefix option to force all m4 directives to have a prefix of "m4_" (see the FvwmM4 man page).

PixmapPath path
This command is obsolete. Please use ImagePath instead.

WindowFont [fontname]
This command is obsoleted by the Style option Font. Please use

Style * Font fontname

instead.

WindowList [( conditions )] [ position ] [ options ] [ double-click-action ]
Generates a pop-up menu (and pops it up) in which the title and geometry of each of the windows currently on the desktop are shown.

The format of the geometry part is: desk(layer): x-geometry sticky, where desk and layer are the corresponding numbers and sticky is empty or a capital S. The geometry of iconified windows is shown in parentheses. Selecting an item from the window list pop-up menu causes the interpreted function "WindowListFunc" to be run with the window id of that window passed in as $0. The default "WindowListFunc" looks like this:

AddToFunc WindowListFunc
 + I Iconify off
 + I FlipFocus
 + I Raise
 + I WarpToWindow 5p 5p

You can destroy the builtin "WindowListFunc" and create your own if these defaults do not suit you.

The window list menu uses the "WindowList" menu style if it is defined (see MenuStyle command). Otherwise the default menu style is used. To switch back to the default menu style, issue the command

DestroyMenuStyle WindowList

Example:

MenuStyle WindowList SelectOnRelease Meta_L

The conditions can be used to exclude certain windows from the window list. Please refer to the Current command for details. Only windows that match the given conditions are displayed in the window list. The options below work vice versa: windows that would otherwise not be included in the window list can be selected with them. The conditions always override the options.

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

The double-click-action is useful to define a default window if you have bound the window list to a key (or button) like this:

# Here we call an existing function, but it may be different
AddToFunc SwitchToWindow
+ I WindowListFunc

Key Tab A M WindowList "Prev SwitchToWindow"

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

The options passed to WindowList can be NoGeometry, NoGeometryWithInfo, Function funcname, Desk desknum, CurrentDesk, NoIcons / Icons / OnlyIcons, NoNormal / Normal / OnlyNormal, NoSticky / Sticky / OnlySticky, NoOnTop / OnTop / OnlyOnTop, NoOnBottom / OnBottom / OnlyOnBottom, Layer m [n], UseListSkip / OnlyListSkip, NoDeskSort, CurrentAtEnd, ReverseOrder, UseIconName, Alphabetic / NotAlphabetic, NoHotkeys, SelectOnRelease.

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

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

If you pass in a function via Function funcname, it is called within a window context of the selected window:

AddToFunc IFunc I Iconify toggle
WindowList Function IFunc, NoSticky, \
  CurrentDesk, NoIcons

If you use the Layer m [n] option, only windows in layers between m and n are displayed. n defaults to m. With the ReverseOrder option the order of the windows in the list is reversed.

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

If you wanted to use the WindowList as an icon manager, you could invoke the following:

WindowList OnlyIcons, Sticky, OnTop, Geometry

(Note - the Only options essentially wipe out all other ones... but the OnlyListSkip option which just causes WindowList to only consider the windows with WindowListSkip style.)

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

 

COMMANDS AFFECTING WINDOW MOVEMENT AND PLACEMENT

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

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

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

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

Lower
Allows the user to lower a window. Note that this lowers a window only in its layer. To bring a window to the absolute bottom, use

AddToFunc lower-to-bottom
 + I Layer 0 0
 + I Lower

Move [[ w | m ] x [ p ] [ w | m ] y [ p ] [ Warp ]] | [ pointer ]
Allows the user to move a window. If called from somewhere in a window or its border, then that window is moved. If called from the root window then the user is allowed to select the target window. If the optional argument Warp is specified the pointer is warped with the window. If the single argument pointer is given, the top left corner of the window window is moved to the pointer position before starting the operation; this is mainly intended for internal use by modules like FvwmPager.

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

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

Simple Examples:

# Interactive move
Mouse 1 T A Move
# Move window so top left is at (10%,10%)
Mouse 2 T A Move 10 10
# Move top left to (10pixels,10pixels)
Mouse 3 T A Move 10p 10p

More complex examples (these can be bound as actions to keystrokes, etc.; only the command is shown, though):

# Move window so bottom right is at bottom
# right of screen
Move -0 -0

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

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

# Move window to the mouse pointer location
#
Move m+0 m+0

See also the AnimatedMove command above.

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

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

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

MoveToPage [ x [ p ] y [ p ]] | [prev ]
Moves the selected window to another page (x,y). The upper left page is (0,0), the upper right is (M,0), where M is one less than the current number of horizontal pages specified in the DeskTopSize command. Similarly the lower left page is (0,N), and the lower right page is (M,N). Negative page numbers refer to pages from the rightmost/lowest page. If x and y are not given, the window is moved to the current page (a window that has the focus but is off-screen can be retrieved with this). Moving windows to a page relative to the current one can be achieved by adding a trailing 'p' after any or both numerical arguments. To move a window to the previous page use prev as the single argument. Using MoveToPage on a sticky window makes the window non-sticky (see Stick command).

Examples:

# Move window to page (2,3)
MoveToPage 2 3

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

# Move window to last page visited
MoveToPage prev

# Move window two pages to the right and one
# page up
MoveToPage +2p -1p

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

OpaqueMoveSize [percentage]
Tells fvwm the maximum size window with which opaque window movement should be used. The percentage is percent of the total screen area (may be greater than 100). With

OpaqueMoveSize 0

all windows are moved using the traditional rubber-band outline. With

OpaqueMoveSize unlimited

or if a negative percentage is given all windows are moved as solid windows. The default is

OpaqueMoveSize 5

which allows small windows to be moved in an opaque manner but large windows are moved as rubber-bands. If percentage is omitted or invalid the default value is set. To resize windows in an opaque manner you can use the ResizeOpaque style. See Style command.

PlaceAgain [Anim]
Causes the current window's position to be re-computed using the initial window placement logic. The window is moved to where it would have been if it were a new window that had just appeared. Most useful with Smart or Clever (ReallySmart) placement. If the optional argument Anim is specified, an animated move is used to place the window in its new position.

Raise
Allows the user to raise a window. Note that this raises a window only in its layer. To bring a window to the absolute top, use

AddToFunc raise-to-top
 + I Layer 0 ontop
 + I Raise

where ontop is the highest layer used in your setup.

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

Resize [ width [ p | c ] height [ p | c ]] | [ bottomright | br x y ]
Allows to resize a window. If called from somewhere in a window or its border, then that window is resized. If called from the root window then the user is allowed to select the target window.

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

If the optional arguments width and height are provided, then the window is resized so that its dimensions are width by height. The units of width and height are percent-of-screen, unless a letter 'p' is appended to one or both coordinates, in which case the location is specified in pixels. With a 'c' suffix the unit defined by the client application (hence the c) is used. So you can say

Resize 80c 24c

to make a terminal window just big enough for 80x24 characters. Both, width and height can be negative. In this case the new size is the screen size minus the given value. If either value is "keep", the corresponding dimension of the window is left untouched.

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

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

Example:

# Move the window to the top left corner
ResizeMove w+0 -10p 0 -20p

SetAnimation milliseconds-delay [fractions-to-move-list]
Sets the time between frames and the list of fractional offsets to customize the animated moves of the AnimatedMove command and the animation of menus (if the menu style is set to animated; see MenuStyle command). If the fractions-to-move-list is omitted, only the time between frames is altered. The fractions-to-move-list specifies how far the window should be offset at each successive frame as a fraction of the difference between the starting location and the ending location. e.g.:

SetAnimation 10 -.01 0 .01 .03 .08 .18 .3 \
  .45 .6 .75 .85 .90 .94 .97 .99 1.0

Sets the delay between frames to 10 milliseconds, and sets the positions of the 16 frames of the animation motion. Negative values are allowed, and in particular can be used to make the motion appear more cartoonish, by briefly moving slightly in the opposite direction of the main motion. The above settings are the default.

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

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

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

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

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

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

This command has been removed and must be replaced by MoveToDesk, the arguments for which are the same as for the GotoDesk command. Important note: You cannot simply change the name of the command: the syntax has changed. If you used

WindowsDesk n

to move a window to desk n, you have to change it to

MoveToDesk 0 n

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

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

 

COMMANDS FOR FOCUS AND MOUSE MOVEMENT

CursorMove horizontal[p] vertical[p]
Moves the mouse pointer by horizontal pages in the X direction and vertical pages in the Y direction. Either or both entries may be negative. Both horizontal and vertical values are expressed in percent of pages, so

CursorMove 100 100

means to move down and right by one full page.

CursorMove 50 25

means to move right half a page and down a quarter of a page. Alternatively, the distance can be specified in pixels by appending a 'p' to the horizontal and/or vertical specification. For example

CursorMove -10p -10p

means move ten pixels up and ten pixels left. The CursorMove function should not be called from pop-up menus.

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

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

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

To raise and/or warp a pointer to a window together with Focus or FlipFocus, use a function, like:

AddToFunc SelectWindow
+ I Focus
+ I Iconify false
+ I Raise
+ I WarpToWindow 50 8p

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

WindowId root 1 WarpToWindow 50 50

 

COMMANDS CONTROLLING WINDOW STATE

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

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

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

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

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

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

Maximize [screen screen-spec] [bool] [horizontal[p] vertical[p]]
Without its optional arguments (or if the bool bit has the value "toggle") Maximize causes the window to alternately switch from a full-screen size to its normal size. To force a window into maximized (normal) state you can use a "True" or "False" value for the bool argument.

With the optional arguments horizontal and vertical, which are expressed as percentage of a full screen, the user can control the new size of the window. An optional suffix 'p' can be used to indicate pixels instead of percents of the screen size. If horizontal is greater than 0 then the horizontal dimension of the window is set to horizontal*screen_width/100. If the value is smaller than 0 the size is subtracted from the screen width, i.e. -25 is the same as 75. If horizontal is "grow", it is maximized to current available space until finding any obstacle. The vertical resizing is similar. If both horizontal and vertical values are "grow", it expands vertically first, then horizontally to find space. Instead of the horizontal "grow" argument, "growleft" or "growright" can be used respectively "growup" and "growdown". For example, the following adds a title-bar button to switch a window to the full vertical size of the screen:

Mouse 0 4 A Maximize 0 100

The following causes windows to be stretched to the full width:

Mouse 0 4 A Maximize 100 0

This makes a window that is half the screen size in each direction:

Mouse 0 4 A Maximize 50 50

To expand a window horizontally until any other window is found:

Mouse 0 4 A Maximize 0 grow

To expand a window but leave the lower 60 pixels of the screen unoccupied

Mouse 0 4 A Maximize 100 -60p

Values larger than 100 can be used with caution.

If the first argument is the word screen, the screen-spec argument specifies the Xinerama screen on which to operate. It can be 'p' for the primary screen, 'c' for the current screen (containing the mouse pointer), 'g' for the global screen or the screen number itself (counting from zero). This option is only useful with multiple Xinerama screens.

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

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

RecaptureWindow
Causes fvwm to recapture the chosen window. See Recapture command above.

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

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

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

WindowShade [bool]
Toggles the window shade feature for titled windows. Windows in the shaded state only display a title-bar. If bool is not given or "toggle", the window shade state is toggled. If bool is "True", the window is forced to the shaded state. If bool is "False", then the window is forced to the non-shaded state. Windows without titles can be shaded too. See also WindowShadeSteps option of the Style command.

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

WindowShadeAnimate [steps[p]]
This command is obsolete. Please use the WindowShadeSteps option of the Style command instead.

 

COMMANDS FOR MOUSE, KEY AND STROKE BINDINGS

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

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

IgnoreModifiers L25

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

GnomeButton
Used in conjunction with Mouse to pass mouse button presses on the root window to a GNOME program (such as GMC). The following example passes presses of mouse buttons 1 and 3 to such a program.

Mouse 1 R A GnomeButton
Mouse 3 R A GnomeButton

Key Keyname Context Modifiers Function
Binds a keyboard key to a specified fvwm built-in function, or removes the binding if Function is '-'. The syntax is the same as for a Mouse binding except that the mouse button number is replaced with a Keyname. The Keyname is one of the entries from /usr/include/X11/keysymdef.h, with the leading XK_ omitted. The Context and Modifiers fields are defined as in the Mouse binding. However, when you press a key the context window is the window that has the keyboard focus. That is not necessarily the same as the window the pointer is over (with SloppyFocus or ClickToFocus). Note that key bindings with the 'R' (root window) context do not work properly with SloppyFocus and ClickToFocus. If you encounter problems, use the PointerKey command instead. If you want to bind keys to a window with SloppyFocus or ClickToFocus that are supposed to work when the pointer is not over the window, fvwm assumes the pointer is over the client window (i.e. you have to use the 'W' modifier).

The following example binds the built in window list to pop up when Alt-Ctrl-Shift-F11 is hit, no matter where the mouse pointer is:

Key F11 A SCM WindowList

Binding a key to a title-bar button causes that button to appear. Please refer to the Mouse command for details.

Mouse Button Context Modifiers Function
Defines a mouse binding, or removes the binding if Function is '-'. Button is the mouse button number. If Button is zero then any button performs the specified function. Context describes where the binding applies. Valid contexts are 'R' for the root window, 'W' for an application window, 'T' for a window title-bar, 'S' for a window side, top, or bottom bar, 'F' for a window frame (the corners), 'I' for an Icon window, or '0' through '9' for title-bar buttons, or any combination of these letters. 'A' is for any context except for title-bar buttons. For instance, a context of "FST" applies when the mouse is anywhere in a window's border except the title-bar buttons. Only 'S' and 'W' are valid for an undecorated window.

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

Function is one of fvwm's built-in functions.

The title-bar buttons are numbered with odd numbered buttons on the left side of the title-bar and even numbers on the right. Smaller-numbered buttons are displayed toward the outside of the window while larger-numbered buttons appear toward the middle of the window (0 is short for 10). In summary, the buttons are numbered:

1 3 5 7 9    0 8 6 4 2

The highest odd numbered button which has an action bound to it determines the number of buttons drawn on the left side of the title bar. The highest even number determines the number or right side buttons which are drawn. Actions can be bound to either mouse buttons or keyboard keys.

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

Example:

Style * SloppyFocus
PointerKey f1 a m Menu MainMenu

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

Strokes sequences are defined in a telephone grid like this:

 1  2  3

 4  5  6

 7  8  9

or in a numeric pad grid like this:

 7  8  9

 4  5  6

 1  2  3

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

Because of the default button menu in fvwm, you may need to remove a mouse button binding (using an empty action) before using the stroke

Mouse 3 R N

Also, you can still use the stroke "sequence 0" to simulate a click:

Stroke 0 3 R N Menu WindowList Nop

The following example starts xterm when the mouse drags an 'I' on the root window with button 3 pressed down:

Stroke 258  3  R  N  Exec exec xterm

An example for Netscape:

Stroke 7415963    3  R  N  Exec exec netscape
Stroke 74148963   3  R  N  Exec exec netscape
Stroke 74158963   3  R  N  Exec exec netscape
Stroke 7418963    3  R  N  Exec exec netscape
Stroke 415963     3  R  N  Exec exec netscape

You may prefer to use the numeric pad grid since you have such a grid on your machine. Here an example:

Stroke N78963314   3  R  N  FvwmForm FvwmForm-QuitVerify
Stroke N789633147  3  R  N  FvwmForm FvwmForm-QuitVerify

This example starts the "QuitVerify" form if you draw a box that begins in the top left corner.

Note: You need libstroke installed and fvwm compiled with stroke support. libstroke can be obtained at

http://www.etla.net/~willey/projects/libstroke/

StrokeFunc [Options]
Causes fvwm to record a mouse stroke sequence and to execute the corresponding action as defined in a Stroke command. The cursor is modified to the STROKE context of the CursorStyle command during recording. When the stroke is finished StrokeFunc looks for a stroke binding of the form

Stroke sequence 0 Context Modifiers action

and executes the corresponding action (Note the 0). Normal use of this function is via a Mouse or Key command. Examples:

Mouse 3 A M StrokeFunc
Key x R N StrokeFunc

If you press mouse button 3 and Alt anywhere (respectively, press the key x when the cursor is on the root window), then fvwm records the mouse motions until the mouse button 3 (respectively, the x key) is released and then check if the recorded sequence corresponds to a stroke binding of the form

Stroke sequence 0 A M action 
Stroke sequence 0 R N action 

Note that the Context and Modifiers are taken at the beginning of the execution of the StrokeFunc command (so you can release the modifiers before the end of the stroke recording in the case of a mouse binding and if you used, say, a title-bar context the mouse motion can go through an application window). The keys Escape and Delete allow you to abort the command.

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

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

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

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

 

THE STYLE COMMAND (CONTROLLING WINDOW STYLES)

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

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

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

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

options is a comma separated list containing one or more of the keywords BorderWidth, HandleWidth, NoIcon / Icon, MiniIcon, IconBox, IconGrid, IconFill, NoTitle / Title, TitleAtBottom / TitleAtTop, StippledTitle / StippledTitleOff, NoHandles / Handles, WindowListSkip / WindowListHit, CirculateSkip / CirculateHit, CirculateSkipShaded / CirculateHitShaded, Layer, StaysOnTop / StaysOnBottom / StaysPut, Sticky / Slippery, StartIconic / StartNormal, Color, ForeColor, BackColor, Colorset, HilightFore, HilightBack, HilightColorset, BorderColorset, HilightBorderColorset, Font, IconFont, StartsOnDesk / StartsOnPage / StartsAnyWhere, StartsOnScreen, ManualPlacementHonorsStartsOnPage / ManualPlacementIgnoresStartsOnPage, CaptureHonorsStartsOnPage / CaptureIgnoresStartsOnPage, RecaptureHonorsStartsOnPage / RecaptureIgnoresStartsOnPage, StartsOnPageIncludesTransients / StartsOnPageIgnoresTransients, IconTitle / NoIconTitle, MwmButtons / FvwmButtons, MwmBorder / FvwmBorder, MwmDecor / NoDecorHint, MwmFunctions / NoFuncHint, HintOverride / NoOverride, NoButton / Button, ResizeHintOverride / NoResizeOverride, OLDecor / NoOLDecor, GNOMEUseHints / GNOMEIgnoreHints, StickyIcon / SlipperyIcon, ManualPlacement / CascadePlacement / MinOverlapPlacement / MinOverlapPercentPlacement / TileManualPlacement / TileCascadePlacement, DecorateTransient / NakedTransient, RaiseTransient / DontRaiseTransient, LowerTransient / DontLowerTransient, StackTransientParent / DontStackTransientParent, SkipMapping / ShowMapping, ScatterWindowGroups / KeepWindowGroupsOnDesk, UseDecor, UseStyle, NoPPosition / UsePPosition, NoUSPosition / UseUSPosition, NoTransientPPosition / UseTransientPPosition, NoTransientUSPosition / UseTransientUSPosition, NoIconPosition / UseIconPosition, Lenience / NoLenience, ClickToFocus / SloppyFocus / MouseFocus|FocusFollowsMouse / NeverFocus, ClickToFocusPassesClickOff / ClickToFocusPassesClick, ClickToFocusRaisesOff / ClickToFocusRaises, MouseFocusClickRaises / MouseFocusClickRaisesOff, StartsLowered / StartsRaised, GrabFocus / GrabFocusOff, GrabFocusTransient / GrabFocusTransientOff, IgnoreRestack / AllowRestack, FixedPosition / VariablePosition, IconOverride / NoIconOverride / NoActiveIconOverride, DepressableBorder / FirmBorder, MaxWindowSize, IconifyWindowGroups / IconifyWindowGroupsOff, ResizeOpaque / ResizeOutline, BackingStore / BackingStoreOff, Opacity / ParentalRelativity, SaveUnder / SaveUnderOff, WindowShadeShrinks / WindowShadeScrolls, WindowShadeSteps.

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

Focus policy
ClickToFocus instructs fvwm to give the focus to the window when it is clicked in. The default MouseFocus (or its alias FocusFollowsMouse) tells fvwm to give the window the focus as soon as the pointer enters the window, and take it away when the pointer leaves the window. SloppyFocus is similar, but doesn't give up the focus if the pointer leaves the window to pass over the root window or a ClickToFocus window (unless you click on it, that is), which makes it possible to move the mouse out of the way without losing focus. A window with the style NeverFocus never receives the focus. This is useful for modules like FvwmButtons, for example.

The focus model can be augmented with several additional options. ClickToFocusPassesClickOff and ClickToFocusPassesClick controls if a mouse click to focus a window using the ClickToFocus model is sent to the application or not. Similarly, ClickToFocusRaisesOff and ClickToFocusRaises control if the window is raised, while MouseFocusClickRaises and MouseFocusClickRaisesOff are equivalent but apply only to windows using SloppyFocus, MouseFocus and NeverFocus. The defaults are ClickToFocusPassesClick, ClickToFocusRaises and MouseFocusClickRaisesOff.

GrabFocus causes a newly mapped window to grab the focus, while GrabFocusOff turns this off. GrabFocus is the default for ClickToFocus windows and GrabFocusOff is the default for MouseFocus and SloppyFocus windows. Note that this option is switched back to the default every time you change the focus policy. You have to use it after the initial ClickToFocus/MouseFocus/SloppyFocus. This style does not apply to transient windows. The GrabFocusTransient and GrabFocusTransientOff styles are responsible for this behavior. By default, GrabFocusTransient is turned on.

Lenience instructs fvwm to ignore the convention in the ICCCM which states that if an application sets the input field of the wm_hints structure to False, then it never wants the window manager to give it the input focus. The only application that we know of which needs this is sxpm, and that is a silly bug with a trivial fix and has no overall effect on the program anyway. Rumor is that some older applications have problems too.

Window title
The Title and NoTitle options determine if the window has a title-bar or not. By default all windows have a title-bar.

Windows with the TitleAtBottom style have a title-bar below the window instead of above as usual. The TitleAtTop style restores the default placement. Even if the window has the NoTitle style set, this affects the WindowShade command.

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

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

Colorset takes the colorset number as its sole argument and overrides the colors set by Color. Instead, the corresponding colors from the given colorset are used. Note that all other features of a colorset are unsupported yet. To stop using the colorset, the colorset number can be omitted.

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

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

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

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

Title buttons
Button and NoButton take a numeric argument which is the number of the title-bar button which is to be included/omitted.

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

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

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

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

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

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

There is one exception to these rules, namely

Style * Icon unknown.xpm

doesn't force the unknown.xpm icon on every window, it just sets the default icon like the DefaultIcon command. If you really want all windows to have the same icon, you can use

Style ** Icon unknown.xpm

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

Style * NoIcon
Style FvwmPager Icon

IconBox takes no argument, four numeric arguments (plus optionally a screen specification), an X11 geometry string or the string "none":

IconBox [screen scr-spec] l t r b

or

IconBox geometry

Where l is the left coordinate, t is the top, r is right and b is bottom. Negative coordinates indicate distance from the right or bottom of the screen. If the first argument is the word screen, the scr-spec argument specifies the Xinerama screen on which the IconBox is defined. It can be the usual screen Xinerama specification, 'p', 'c', 'g', a screen number or the additional 'w' for the screen where the window center is located. This is only useful with multiple Xinerama screens. Perhaps easier to use is an X11 geometry string:

IconBox -80x200-1-1

Which would place an 80 by 240 pixel icon box in the lower right hand corner of the screen. The icon box is a region of the screen where fvwm attempts to put icons for any matching window, as long as they do not overlap other icons. Multiple icon boxes can be defined as overflow areas. When the first icon box is full, the second one is filled. All the icon boxes for one style must be defined in one Style command. For example:

Style * IconBox -80x200-1-1, \
        IconBox 1000x70-1-1

A Style command with the IconBox option replaces any icon box previously defined for the same style. Thats why the backslash in the previous example is required.

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

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

Hint: You can auto arrange your icons in the icon box with a simple fvwm function. Put the "DeiconifyAndRearrange" function below in your configuration file:

AddToFunc DeiconifyAndRearrange
 + C Iconify off
 + C All (CurrentPage Iconic) RecaptureWindow

And then replace all places where you call the Iconify builtin function to de-iconify an icon with a call to the new function. For example replace

AddToFunc IconFunc
 + C Iconify off
 + M Raise
 + M Move
 + D Iconify off

Mouse 1 I A Iconify off

with

AddToFunc IconFunc
 + C DeiconifyAndRearrange
 + M Raise
 + M Move
 + D DeiconifyAndRearrange

Mouse 1 I A DeiconifyAndRearrange

IconGrid takes 2 numeric arguments greater than zero.

IconGrid x y

Icons are placed in an icon box by stepping through the icon box using the x and y values for the icon grid, looking for a free space. The default grid is 3 by 3 pixels which gives a tightly packed appearance. To get a more regular appearance use a grid larger than your largest icon. Currently there is no way to clip an icon to a maximum size. An IconGrid definition must follow the IconBox definition that it applies to:

Style * IconBox -80x240-1-1, IconGrid 90 90

IconFill takes 2 arguments.

IconFill Bottom Right

Icons are placed in an icon box by stepping through the icon box using these arguments to control the direction the box is filled in. By default the direction is left to right, then top to bottom. This would be expressed as:

IconFill left top

To fill an icon box in columns instead of rows, specify the vertical direction (top or bottom) first. The directions can be abbreviated or spelled out as follows: "t", "top", "b", "bot", "bottom", "l", "lft", "left", "r", "rgt", "right". An IconFill definition must follow the IconBox definition that it applies to:

Style * IconBox -80x240-1-1, IconFill b r

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

WindowShadeShrinks and WindowShadeScrolls control if the contents of a window that is being shaded with the WindowShade command are scrolled (default) or if they stay in place.

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

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

Style * ResizeOpaque
Style rxvt ResizeOutline
Style emacs ResizeOutline

Sticky makes the window sticky, i.e. it is always visible on each page and each desk. The opposite style, Slippery reverts back to the default.

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

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

FixedPosition makes fvwm ignore attempts of the user to move the window. To allow user movement of windows, use the VariablePosition style.

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

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

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

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

CascadePlacement automatically place new windows in a cascading fashion.

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

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

MinOverlapPlacement automatically places new windows in a location in which the overlapping area in pixels of other windows is minimal. This placement policy especially tries to avoid overlapping icons and windows on higher layers.

MinOverlapPercentPlacement is similar to MinOverlapPlacement but tries to minimize the overlapped percentages of other windows instead of the overlapped area in pixels. This placement policy tries to avoid covering other windows completely and tries even harder not to cover small windows.

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

Example:

Style * ManualPlacement

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

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

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

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

GlobalOpts SmartPlacementIsReallySmart
Style * SmartPlacement
  -->
Style * SmartPlacement, CleverPlacement

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

Style * DumbPlacement, RandomPlacement
  -->
Style * CascadePlacement

Style * DumbPlacement, ActivePlacement
  -->
Style * ManualPlacement

Style * SmartPlacement + RandomPlacement + CleverPlacementOff
  -->
Style * TileCascadePlacement

Style * SmartPlacement + ActivePlacement + CleverPlacementOff
  -->
Style * TileManualPlacement

Style * SmartPlacement + CleverPlacement
  -->
Style * MinOverlapPlacement

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

Style * ActivePlacementsHonorsStartsOnPage
  -->
Style * ManualPlacementsHonorsStartsOnPage

Style * ActivePlacementsHonorsStartsOnPageOff
  -->
Style * ManualPlacementsHonorsStartsOnPageOff

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

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

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

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

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

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

StartsOnScreen takes one argument. It can be 'p' for the primary screen, 'c' for the current screen (containing the mouse pointer), 'g' for the global screen or the screen number itself (counting from zero). A new window is placed on the specified Xinerama screen. The default is to place windows on the screen that contains the mouse pointer at the time the window is created. However, those windows which are not placed by FVWM (i.e., those with a USPosition hint from a user specified geometry) are normally placed in a position relative to the global screen. The StartsOnScreen style is also useful to cause these windows to be placed relative to a specific Xinerama screen. For example:

Style * StartsOnScreen c

Would cause all windows, including those with their own geometry to be placed relative to the current Xinerama screen rather than the global screen. For those standard Xt programs which understand this usage, the starting desk/page can also be specified via a resource (e.g., "-xrm '*fvwmscreen: c'"). ('fvwmscreen' was chosen because some applications already use '.screen' for other purposes.)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A reasonable emulation of Motif raise/lower on transients is possible like this

Style * RaiseTransient
Style * LowerTransient
Style * StackTransientParent

Miscellaneous
The BackingStore and SaveUnder styles enable the corresponding window attributes in the X server. BackingStore means that the X server tries to keep the obscured parts of a window in memory while windows with SaveUnder store the graphics below them. Either option can speed up fvwm if the connection to the X server is slow (e.g. over a modem link). By default both styles are turned off. To switch them off explicitly you can use the BackingStoreOff and SaveUnderOff styles.

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

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

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

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

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

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

UseStyle takes one arg, which is the name of another style. That way you can have unrelated window names easily inherit similar traits without retyping. For example:

  Style rxvt UseStyle XTerm

Warning: If a style is built from one or more parent styles and the parent styles are changed, the derived style is not modified. To achieve this you have to issue the UseStyle line again.

Examples

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

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

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

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

# Fire up Netscape on the second desk, in the
# middle of my 3x3 virtual desktop, and don't
# bother me with it...
Style Netscape* SkipMapping,              \
                StartsOnPage 1 1 1

Note that all properties for a window are or'ed together. In the above example "FvwmPager" gets the property StaysOnTop via an exact window name match but also gets NoHandles, Sticky and WindowListSkip by a match to "Fvwm*". It gets NoTitle by virtue of a match to "*". If conflicting styles are specified for a window, then the last style specified are used.

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

Style * NoIcon
Style FvwmPager Icon

DestroyStyle style
Deletes the style named style. The changes take effect immediately. Note that style is not a wild-carded search string, but rather a case-sensitive string that should exactly match the original Style command.

Destroying style "*" can be done, but isn't really to be recommended. For example:

DestroyStyle Application*

This removes all settings for the style named "Application*", NOT all styles starting with "Application".

 

OTHER COMMANDS CONTROLLING WINDOW STYLES

AddButtonStyle button [ state ] [ style ] [-- [!] flag ...]

Adds a button style to button. button can be a button number, or one of "All", "Left" or "Right". state can be "ActiveUp," "ActiveDown" or "Inactive" or any of these three with "Toggled" prepended. "ActiveUp" selects the style of the button when the window has the focus and the button is not pressed. "ActiveDown" is similar but applies when the button is pressed while the "Inactive" style is used for windows without the focus. The "Toggled" prefix refers to maximized, shaded or sticky windows that have the corresponding MwmDecor... button style set. If state is omitted, then the style is added to every state. If the style and flags are enclosed in parentheses, then multiple state definitions can be placed on a single line. Flags for additional button styles cannot be changed after definition.

Buttons are drawn in the order of definition, beginning with the most recent button style, followed by those added with AddButtonStyle. To clear the button style stack, change style flags, or for descriptions of available styles and flags, see the ButtonStyle command. Examples:

ButtonStyle 1 Pixmap led.xpm -- Top Left
ButtonStyle 1 ActiveDown HGradient 8 grey \
  black
ButtonStyle All --  UseTitleStyle
AddButtonStyle 1 ActiveUp (Pixmap a.xpm)  \
  ActiveDown (Pixmap b.xpm -- Top)
AddButtonStyle 1 Vector 4 50x30@1 70x70@0 \
  30x70@0 50x30@1

Initially for this example all button states are set to a pixmap. The second line replaces the "ActiveDown" state with a gradient (it overrides the pixmap assigned to it in the line before, which assigned the same style to every state). Then, the UseTitleStyle flag is set for all buttons, which causes fvwm to draw any styles set with TitleStyle before drawing the buttons. Finally, AddButtonStyle is used to place additional pixmaps for both "ActiveUp" and "ActiveDown" states and a vector button style is drawn on top of all state.

AddTitleStyle [ state ] [ style ] [-- [!] flag ...]
Adds a title style to the title-bar. state can be one of "ActiveUp," "ActiveDown" or "Inactive" or any of these with "Toggled" prepended. If state is omitted, then the style is added to every state. If the style and flags are enclosed in parentheses, then multiple state definitions can be placed on a single line. This command is quite similar to the AddButtonStyle command (see above).

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

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

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

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

The following example creates a decor "FlatDecor" and style "FlatStyle". They are distinct entities:

AddToDecor FlatDecor
 + ButtonStyle All ActiveUp (-- flat) \
   Inactive (-- flat)
 + TitleStyle -- flat
 + BorderStyle -- HiddenHandles NoInset

Style FlatStyle UseDecor FlatDecor, \
     Color white/grey40,HandleWidth 4

Style xterm UseStyle FlatStyle

An existing window's decor may be reassigned with ChangeDecor. A decor can be destroyed with DestroyDecor.

DestroyDecor FlatDecor
AddToDecor FlatDecor ...

Style FlatStyle UseDecor FlatDecor, \
     Color white/grey40,HandleWidth 4

and now apply the style again:

Style xterm UseStyle FlatStyle

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

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

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

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

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

To decorate the active and inactive window borders with a textured pixmap, one might specify:

BorderStyle Active TiledPixmap marble.xpm
BorderStyle Inactive TiledPixmap granite.xpm
BorderStyle Active -- HiddenHandles NoInset

To clear the style for both states:

BorderStyle Simple

To clear for a single state:

BorderStyle Active Simple

To unset a flag for a given state:

BorderStyle Inactive -- !NoInset

title-bar buttons can inherit the border style with the UseBorderStyle flag (see ButtonStyle).

ButtonState [ActiveDown bool] [inactive bool]
The ButtonState command controls which states of the window titles and title buttons are used. The default is to use all three states: "ActiveUp", "ActiveDown" and "Inactive" (see ButtonStyle and TitleStyle commands). The bool argument after the key word controls if the designated state is used ("True") or not ("False"). The "ActiveUp" state cannot be deactivated. If no arguments are provided or the given arguments are illegal, the default is restored.

The "ActiveDown" state allows different button styles for pressed down buttons and titles on active windows. Otherwise the "ActiveUp" state is used instead. The "Inactive" state allows different button and title styles for inactive windows. Otherwise the "ActiveUp" state is used instead.

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

state refers to which button state should be set. Button states are defined as follows: "ActiveUp" and "ActiveDown" refer to the un-pressed and pressed states for buttons on active windows; while the "Inactive" state denotes buttons on inactive windows. The "ToggledActiveUp", "ToggledActiveDown" and "ToggledInactive" states are used instead for buttons which have one of the MwmDecorMax, MwmDecorShade or MwmDecorStick hints, if the window is maximized, shaded or sticky, respectively.

AddToDecor Default
 + ButtonStyle 6                   \
   Vector 4 50x25@1 85x75@0 15x75@0 50x25@1
 + ButtonStyle 6 ToggledActiveUp   \
   Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
 + ButtonStyle 6 ToggledActiveDown \
   Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
 + ButtonStyle 6 ToggledInactive   \
   Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
 + ButtonStyle 6 - MwmDecorShade
Mouse 0 6 N WindowShade

If state is "ActiveUp", "ActiveDown", "Inactive", or a "Toggled" variant, that particular button state is set. If state is omitted, every state is set. Specifying a style destroys the current style (use AddButtonStyle to avoid this).

If style is omitted, then state-dependent flags can be set for the primary button style without destroying the current style. Examples (each line should be considered independent):

ButtonStyle Left -- flat
ButtonStyle All ActiveUp (-- flat) \
  Inactive (-- flat)

The first line sets every state of the left buttons to flat, while the second sets only the "ActiveUp" and "Inactive" states of every button to flat (only flags are changed; the buttons' individual styles are not changed).

If you want to reset all buttons to their defaults:

ButtonStyle Reset

To reset the "ActiveUp" button state of button 1 to the default:

ButtonStyle 1 ActiveUp Default

To reset all button states of button 1 to the default of button number 2:

ButtonStyle 1 Default 2

For any button, multiple state definitions can be given on one line by enclosing the style and flags in parentheses. If only one definition per line is given the parentheses can be omitted.

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

Raised causes a raised relief pattern to be drawn.

Sunk causes a sunken relief pattern to be drawn.

Flat inhibits the relief pattern from being drawn.

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

UseBorderStyle causes the button to inherit the decorated BorderStyle options.

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

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

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

The available styles and their arguments now follow.

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

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

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

The Vector num XxY@C ... style draws a line pattern. Since this is a standard button style, the keyword Vector is optional, num is a number of point specifications of the form XxY@C. X and Y are point coordinates inside the button, given in percents (from 0 to 100). C specifies a line color (0 - the shadow color, 1 - the highlight color, 2 - the background color, 3 - the foreground color). The first point color is not used. You can use up to 32 points in a line pattern. This style is partially destructive.

The specification is a little cumbersome:

ButtonStyle 2 Vector 4 50x30@1 70x70@0 \
  30x70@0 50x30@1

then the button 2 decoration uses a 4-point pattern consisting of a line from (x=50,y=30) to (70,70) in the shadow color (@0), and then to (30,70) in the shadow color, and finally to (50,30) in the highlight color (@1). Is that too confusing? See the fvwm web pages for some examples with screenshots.

A more complex example of Vector:

ButtonStyle 8 Vector 10 45x65@2 45x75@3 20x75@3 20x50@3 \
  35x50@3 35x65@1 35x25@1 75x25@1 75x65@0 35x65@0
ButtonStyle 0 Vector 10 45x65@2 45x75@0 20x75@0 20x50@1 \
  45x50@1 45x65@0 75x65@3 75x25@3 35x25@3 35x47@3

The ?Gradient styles denote color gradients. Fill in the question mark with any one of the defined gradient types. Please refer to the COLOR GRADIENTS section for a description of the gradient syntax. The gradient styles are fully destructive.

The Pixmap style displays a pixmap. A pixmap should be specified as an argument. For example, the following would give button 2 the same pixmap for both states, and button 4 different pixmaps for the up, down and inactive states.

ButtonStyle 2 Pixmap my_pixmap.xpm
ButtonStyle 4 ActiveUp (Pixmap up.xpm) \
  ActiveDown (Pixmap down.xpm)
ButtonStyle 4 Inactive Pixmap inactive.xpm

The pixmap specification can be given as an absolute or relative pathname (see ImagePath). If the pixmap cannot be found, the button style reverts to Simple. Flags specific to the Pixmap style are Left, Right, Top, and Bottom. These can be used to justify the pixmap (default is centered for both directions). Pixmap transparency is used for the color "None." This style is partially destructive.

The MiniIcon style draws the window's miniature icon in the button, which is specified with the MiniIcon option of the Style command. This button style accepts no arguments. Example:

Style *     MiniIcon mini-bx2.xpm
Style xterm MiniIcon mini-term.xpm
Style Emacs MiniIcon mini-doc.xpm

ButtonStyle 1 MiniIcon

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

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

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

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

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

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

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

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

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

ChangeDecor CustomDecor1

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

DestroyDecor CustomDecor1

TitleStyle [justification] [height [num]]
Sets attributes for the title-bar. Justifications can be Centered, RightJustified or LeftJustified. height sets the title bar's height to an amount in pixels. Defaults are Centered and the window's font height. To reset the font height to the default value, omit the num argument after the height keyword. Example:

TitleStyle LeftJustified Height 24

TitleStyle [ state ] [ style ] [-- [!] flag ...]
Sets the style for the title-bar. state can be one of "ActiveUp", "ActiveDown", or "Inactive". If state is omitted, then the style is added to every state. If parentheses are placed around the style and flags, then multiple state definitions can be given per line. style can be omitted so that flags can be set while not destroying the current style.

If a '!' is prefixed to any flag, its behavior is negated. Valid flags for each state include Raised, Flat and Sunk (these are mutually exclusive). The default is Raised. See the note in ButtonStyle regarding the "ActiveDown" state. Examples:

TitleStyle ActiveUp HGradient 16 navy black
TitleStyle ActiveDown (Solid red -- flat) \
  Inactive (TiledPixmap wood.xpm)
TitleStyle ActiveUp (-- Flat) ActiveDown  \
  (-- Raised) Inactive (-- Flat)

This sets the "ActiveUp" state to a horizontal gradient, the "ActiveDown" state to solid red, and the "Inactive" state to a tiled wood pixmap. Finally, "ActiveUp" is set to look flat, while "ActiveDown" set to be sunk (the Raised flag for the "ActiveDown" state causes it to appear sunk due to relief inversion), and "Inactive" is set to flat as well. An example which sets flags for all states:

TitleStyle -- flat

For a flattened look:

TitleStyle -- flat
ButtonStyle All ActiveUp (-- flat) Inactive \
  (-- flat)

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

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

 

COMMANDS CONTROLLING THE VIRTUAL DESKTOP

Desk arg1 [ arg2 ] [ min max ]
This command has been renamed. Please see GotoDesk command.

DeskTopSize HorizontalxVertical
Defines the virtual desktop size in units of the physical screen size.

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

The first parameter tells how many milliseconds the pointer must spend on the screen edge before fvwm moves the viewport. This is intended for people who use

EdgeScroll 100 100

but find themselves accidentally flipping pages when they don't want to.

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

Note that, with

EdgeScroll 0 0

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

The optional third parameter does the same as the second, but for individual Xinerama screens. If omitted, xinerama-moving will be set to the value of moving. Set xinerama-moving to zero to ignore individual screen edges.

EdgeScroll horizontal[p] vertical[p]
Specifies the percentage of a page to scroll when the cursor hits the edge of a page. A trailing 'p' changes the interpretation to mean pixels. If you don't want any paging or scrolling when you hit the edge of a page include

EdgeScroll 0 0

in your .fvwm2rc file, or possibly better, set the EdgeThickness to zero. See the EdgeThickness command. If you want whole pages, use

EdgeScroll 100 100

Both horizontal and vertical should be positive numbers.

If the horizontal and vertical percentages are multiplied by 1000 then scrolling wraps around at the edge of the desktop. If

EdgeScroll 100000 100000

is used fvwm scrolls by whole pages, wrapping around at the edge of the desktop.

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

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

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

2 is the default.

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

GotoDesk prev | arg1 [ arg2 ] [ min max ]
Switches the current viewport to another desktop (workspace, room).

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

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

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

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

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

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

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

GotoPage prev | x [ p ] y [ p ]
Moves the desktop viewport to page (x,y). The upper left page is (0,0), the upper right is (M,0), where M is one less than the current number of horizontal pages specified in the DeskTopSize command. The lower left page is (0,N), and the lower right page is (M,N), where N is the desktop's vertical size as specified in the DeskTopSize command. To switch to a page relative to the current one add a trailing 'p' after any or both numerical arguments. To go to last visited page use prev as the first argument. The GotoPage function should not be used in a pop-up menu.

Examples:

# Go to page (2,3)
GotoPage 2 3

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

# Go to last page visited
GotoPage prev

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

Scroll horizonal [ p ] vertical [ p ]
Scrolls the virtual desktop's viewport by horizontal pages in the x-direction and vertical pages in the y-direction. Either or both entries may be negative. Both horizontal and vertical values are expressed in percent of pages, so

Scroll 100 100

means to scroll down and left by one full page.

Scroll 50 25

means to scroll left half a page and down a quarter of a page. The Scroll function should not be called from pop-up menus. Normally, scrolling stops at the edge of the desktop.

If the horizontal and vertical percentages are multiplied by 1000 then scrolling wraps around at the edge of the desktop. If

Scroll 100000 0

is executed over and over fvwm moves to the next desktop page on each execution and wraps around at the edge of the desktop, so that every page is hit in turn.

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

Xinerama bool
Enables Xinerama support if the boolean argument is true and disables it if the argument is false. Calling this command without arguments turns on Xinerama support it was disabled before and turns it off if it was enabled. For example:

# Turn Xinerama support on, use primary screen 2
XineramaPrimaryScreen 2
Xinerama on
#Turn it off again
Xinerama off

XineramaPrimaryScreen [primary-screen]
Takes an integer number or 'g' or 'c' as its argument. A number is taken as the number of the Xinerama screen that is to be used as the primary screen. The primary screen can be used as the preferred screen to place windows with

XineramaPrimaryScreen <screen number>
Style * StartsOnScreen p

The primary screen is used in some of the modules and for the default icon box too. Any number that is zero or more is taken as the primary screen's number. Instead, the letter 'c' indicates to use the curent screen (containing the pointer) whenever the primary screen is used. This may be very confusing under some circumstances. With 'g', the global screen is used as the primary screen, effectively disabling the primary screen. Calling this function with any other argument (including none) resets the primary screen to 0.

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

XineramaSlsSize HorizontalxVertical
This command configures the layout of the Single Logical screen feature. It takes two arguments, Horizontal and Vertical which must be an integer value dividing evenly into the total desktop width, and height height. For an example with two monitors side by side which appear as one screen through the X-Server with the right screen as the primary screen, use:

XineramaSlsSize 2x1
XineramaSlsOn
XineramaPrimaryScreen 1
XineramaOn

 

COMMANDS FOR USER FUNCTIONS AND SHELL COMMANDS

AddToFunc [ name [ I | M | C | H | D action ]]
Begins or adds to a function definition. Here is an example:

AddToFunc Move-or-Raise I Raise
 + M Move
 + D Lower

The function name is "Move-or-Raise", and could be invoked from a menu or a mouse binding or key binding:

Mouse 1 TS A Move-or-Raise

The name must not contain embedded whitespace. No guarantees are made whether function names with embedded whitespace work or not. This behaviour may also change in the future without further notice. The letter before the action tells what kind of action triggers the command which follows it. 'I' stands for "Immediate", and is executed as soon as the function is invoked. 'M' stands for "Motion", i.e. if the user starts moving the mouse. 'C' stands for "Click", i.e., if the user presses and releases the mouse. 'H' stands for "Hold", i.e. if the user presses a mouse button and holds it down for more than ClickTime milliseconds. 'D' stands for "Double-click". The action 'I' causes an action to be performed on the button-press, if the function is invoked with prior knowledge of which window to act on.

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

Examples:

If you call

Key F10 R A Function MailFunction \
  xmh "-font fixed"

and "MailFunction" is

AddToFunc MailFunction
 + I Next ($0) Iconify off
 + I Next (AcceptsFocus, $0) focus
 + I None ($0) Exec exec $0 $1

Then the last line of the function becomes

 + I None (xmh) Exec exec xmh -font fixed

The expansion is performed as the function is executed, so you can use the same function with all sorts of different arguments. You could use

Key F11 R A Function MailFunction \
  zmail "-bg pink"

in the same .fvwm2rc, if you wanted. An example of using "$w" is:

AddToFunc PrintFunction
 + I Raise
 + I Exec xdpr -id $[w.id]

Note that "$$" is expanded to '$'.

Another example: bind right mouse button within the window button number 6 (this is a minimize button for the win95 theme) to iconify all windows of the same resource:

AddToFunc FuncIconifySameResource "I" \
  All ($r) Iconify on
Mouse 3 6 A FuncIconifySameResource

Beep
As might be expected, this makes the terminal beep.

DestroyFunc function
Deletes a function, so that subsequent references to it are no longer valid. You can use this to change the contents of a function during a fvwm session. The function can be rebuilt using AddToFunc.

DestroyFunc PrintFunction

Echo string
Prints a message to stderr. Potentially useful for debugging things in your .fvwm2rc.

Echo Beginning style definitions...

Exec command
Executes command. You should not use an ampersand '&' at the end of the command. You probably want to use an additional "exec" at the beginning of command. Without that, the shell that fvwm invokes to run your command stays until the command exits. In effect, you'll have twice as many processes running as you need. Note that some shells are smart enough to avoid this, but it never hurts to include the "exec" anyway.

The following example binds function key F1 in the root window, with no modifiers, to the exec function. The program rxvt is started with an assortment of options.

Key F1 R N Exec exec rxvt -fg yellow -bg blue \
  -e /bin/tcsh

Note that this function doesn't wait for command to complete, so things like:

Exec "echo AddToMenu ... > /tmp/file"
Read /tmp/file

do not work reliably.

ExecUseShell [shell]
Makes the Exec command use the specified shell, or the value of the $SHELL environment variable if no shell is specified, instead of the default Bourne shell (/bin/sh).

ExecUseShell
ExecUseShell /usr/local/bin/tcsh

Function FunctionName
Used to bind a previously defined function to a key or mouse button. The following example binds mouse button 1 to a function called "Move-or-Raise", whose definition was provided as an example earlier in this man page. After performing this binding fvwm executes the "move-or-raise" function whenever button 1 is pressed in a window's title-bar.

Mouse 1 T A Function Move-or-Raise

The keyword Function may be omitted if FunctionName does not coincide with a fvwm built-in function name

Nop
Does nothing. This is used to insert a blank line or separator in a menu. If the menu item specification is

AddToMenu MyMenu " " Nop

then a blank line is inserted. If it looks like

+ "" Nop

then a separator line is inserted. Can also be used as the double-click action for Menu or Popup.

PipeRead command [quiet]
Causes fvwm to read commands from the output of the command. This command is executed by /bin/sh as if you typed it on the command line. If the command consists of more than one word it must be quoted. Useful for building up dynamic menu entries based on a directories contents, for example. If the keyword Quiet follows the command no message is produced if the command is not found.

Example:

AddToMenu HomeDirMenu
PipeRead 'for i in $HOME/*; \
  do echo "+ $i Exec xterm -e vi $i"; done'

Note: The PipeRead changes the pointer to a watch cursor by default during execution. However, some commands, for example xwd, need to take control of the pointer themselves and do not work. To disable the watch cursor, use the command prior to PipeRead

BusyCursor Read off

The PipeRead command executes synchronously. If you want to Exec something, but need the command to run sunchronously, you might do something like:

PipeRead 'command 1>&2'

The redirection causes any output from the program to go to stderr instead of being read as a sequence of commands by fvwm.

Read filename [quiet]
Causes fvwm to read commands from the file named filename. If the keyword Quiet follows the command no message is produced if the file is not found. If the file name does not begin with a slash ('/'), fvwm looks in the user's data directory, then the system data directory. The user's data directory is by default $HOME/.fvwm. It can be overridden by exporting FVWM_USERDIR set to any other directory.

SetEnv variable value
Set an environment variable to a new value, similar to the shell's export or setenv command. The variable and its value are inherited by processes started directly by fvwm. This can be especially useful in conjunction with the FvwmM4 module. For example:

SetEnv height HEIGHT

makes the FvwmM4-set variable HEIGHT usable by processes started by fvwm as the environment variable $height. If value includes whitespace, you should enclose it in quotes. If no value is given, the command is ignored.

Silent command
A number of built in functions require a window to operate on. If no window was selected when such a function is invoked the user is asked to select a window. Sometimes this behavior is unwanted, for example if the function was called by a module and the window that was selected at first does not exist anymore. You can prevent this by putting Silent in front of the fvwm command. If a function that needs a window is called with Silent without a window selected, it simply returns without doing anything. If Silent is used on a user defined function it affects all function and sub function calls until the original function exits.

Another usage of Silent is with binding commands Key, PointerKey and Mouse, this disables error messages.

Examples:

Silent Move 0 0
Silent User_defined_function
# don't complain on keabords without "Help" key
Silent Key Help R A Popup HelpMenu

UnsetEnv variable
Unset an environment variable, similar to shell's export or unsetenv command. The variable then is removed from the environment array inherited by processes started directly by fvwm.

Wait windowname
This built-in is intended to be used in fvwm functions only. It causes execution of a function to pause until a new window with the title windowname appears. Fvwm remains partially functional during a wait. This is particularly useful in the "InitFunction" if you are trying to start windows on specific desktops:

AddToFunc InitFunction
 + I exec xterm -geometry 80x64+0+0
 + I Wait xterm
 + I Desk 0 2
 + I Exec exec xmh -font fixed -geometry \
       507x750+0+0
 + I Wait xmh
 + I Desk 0 0

The above function starts an xterm on the current desk, waits for it to map itself, then switches to desk 2 and starts an xmh. After the xmh window appears control moves to desk 0.

You can escape from a Wait pause by pressing Ctrl-Alt-Escape (where Alt is the first modifier). To redefine this key sequence see the EscapeFunc command.

 

CONDITIONAL COMMANDS

All [(conditions)] command
Execute. command on all windows meeting the conditions. Conditions are used exactly as with the Current command.

Current [(condition...)] command
Performs command on the currently focused window if it satisfies all conditions. The conditions are a list of keywords from the list below and are separated by commas or whitespace. Conditions include "AcceptsFocus", "!AcceptsFocus" "Iconic", "!Iconic", "Visible", "!Visible", "Raised", "!Raised", "Layer [n]", "Sticky", "!Sticky", "Maximized", "!Maximized", "Shaded", "!Shaded", "Transient", "!Transient", "PlacedByButton3", "!PlacedByButton3", "PlacedByFvwm", "!PlacedByFvwm", "CurrentDesk", "CurrentPage", "CurrentScreen" "CurrentGlobalPage", "CurrentPageAnyDesk" and "CurrentGlobalPageAnyDesk". In addition, the condition may include one window name to match to. The window name may include the wildcards '*' and '?'. The window name, icon name, class, and resource are considered when attempting to find a match. The window name can begin with '!' which prevents command if any of the window name, icon name, class or resource match.

The "AcceptsFocus" condition excludes all windows that do not want the input focus (the application has set the "Input hints" for the window to False) and do not use the Lenience option of the Style command. Also, all windows using the NeverFocus style are ignored.

The "CurrentDesk" condition excludes all window that are not on the current desk.

The "CurrentPage" condition excludes all window that are not on the current desk or not on the current page. If Xinerama support is enabled, only windows on the screen that contains the mouse pointer are considered to match.

The "CurrentGlobalPage" condition excludes all window that are not on the current desk or not on the current page. The screen does not matter if Xinerama support is enabled.

The "CurrentScreen" and "CurrentPageAnyDesk" conditions exclude all window that are not on the current page but that may be on any desk.

The "CurrentGlobalPage" condition excludes all window that are not on the current desk or not on the current page. If Xinerama support is enabled, only windows on the screen that contains the mouse pointer are considered to match.

The "CurrentGlobalPageAnyDesk" condition excludes all window that are not on the current page but that may be on any desk. The screen does not matter if Xinerama support is enabled.

The argument of the "Layer" condition defaults to the layer of the focus window.

The "PlacedByButton3" condition is fulfilled if the last interactive motion of the window (with the Move command) was ended by pressing mouse button 3. This is especially useful with the ManualPlacement option of the Style command.

The "PlacedByFvwm" condition excludes all windows that have been placed manually or by using the user or program position hint.

Note that earlier versions of fvwm required the conditions to be enclosed in brackets instead of parentheses (this is still supported for backwards compatibility).

Direction direction [(conditions)] command
Performs command (typically Focus) on a window in the given direction which satisfies all conditions. Conditions are the same as for Current. The direction may be one of "North", "Northeast", "East", "Southeast", "South", "Southwest", "West" and "Northwest". Which window Direction selects depends on angle and distance between the center points of the windows. Closer windows are considered a better match than those farther away.

Next [(conditions)] command
Performs command (typically Focus) on the next window which satisfies all conditions. Conditions are the same as for Current with the addition of "CirculateHit" which overrides the CirculateSkip Style attribute, "CirculateHitIcon" which overrides the CirculateSkipIcon Style attribute for iconified windows and "CirculateHitShaded" which does the same for shaded windows.

None [(conditions)] command
Performs command if no window which satisfies all conditions exists. Conditions are the same as for Next.

Pick [(conditions)] command
Pick works like Function if invoked in the context of a window. If invoked in the root window, it first asks the user to pick a window and then executes the command in the context of that window. This avoids annoying multiple selections with complex functions. The command is executed only if the given conditions are met. The conditions are the same as for Next.

Prev [(conditions)] command
Performs command (typically Focus) on the previous window which satisfies all conditions. Conditions are the same as for Next.

ThisWindow [(conditions)] command
ThisWindow executes the specified command in the context of the current operand window. If there is no operand window (it is invoked in the root window), the command is ignored. ThisWindow is always non-interactive. The command is executed only if the given conditions are met. The conditions are the same as for Current. It returns -1 if used outside a window context.

WindowId [ id ] [( conditions )] | [ root [ screen ]] command
The WindowId function is similar to the Next and Prev functions, except that it looks for a specific window id and runs the specified command on it. The optional conditions are the same as for Current. The second form of syntax retrieves the window id of the root window of the given screen. If no screen is given, the current screen is assumed. The window indicated by id may belong to a window not managed by fvwm or even a window on a different screen. Although most commands can not operate on such windows, there are some exceptions, for example the WarpToWindow command.

WindowId 0x34567890 Raise
WindowId root 1 WarpToWindow 50 50
WindowId $0 (Silly_Popup) Delete

In the past this command was mostly useful for functions used with the WindowList built-in, or for selective processing of FvwmEvent calls (as in the last example), but currently these handler functions are called within a window context, so this command is not really needed in these cases. Still it may be useful if, for example, the window id should be stored in the environment variable for a further proceeding.

Pick SetEnv BOOKMARKED_WINDOW $[w.id]
WindowId $[BOOKMARKED_WINDOW] WarpToWindow

 

MODULE COMMANDS

Fvwm maintains a database of module configuration lines in a form

*<ModuleName>: <Config-Resource>

where <ModuleName> is either a real module name or an alias.

This database is initially filled from config file (or from output of -cmd config command), and can be later modified either by user (via FvwmCommand) or by modules.

When modules are run, they read appropriate portion of database. (The concept of this database is similar to one used in X resource database).

Commands for manipulating module configuration database are described below.

*module_config_line
Defines a module configuration. module_config_line consists of a module name (or a module alias) and a module resource line. The new syntax allows a delimiter, a colon and optional spaces, between the module name and the rest of the line, this is recommended to avoid conflicts.

*FvwmIconBox: MaxIconSize 48x48
*FvwmPager: WindowBorderWidth 1
*FvwmButtons-TopRight: Geometry 100x100-0+0
*FvwmButtons-Bottom: Geometry +0-0

DestroyModuleConfig module_config
Deletes module configuration entries, so that new configuration lines may be entered instead. This also sometimes the only way to turn back some module settings, previously defined. This changes the way a module runs during a fvwm session without restarting. Wildcards can be used for portions of the name as well.

The new non-conflicting syntax allows a delimiter, a colon and optional spaces between the module name and the rest of the line. In this case a module name (or alias) can't have wildcards.

DestroyModuleConfig FvwmButtons*
DestroyModuleConfig FvwmForm: Fore
DestroyModuleConfig FvwmIconBox: Max*

KillModule modulename [modulealias]
Causes the module which was invoked with name modulename to be killed. The name may include wildcards. If modulealias is given, only modules started with the given alias are killed.

KillModule FvwmPager  # kill all pagers

Module FvwmEvent SoundEvent
KillModule FvwmEvent SoundEvent

Module modulename [moduleparams]
Specifies a module with its optional parameters which should be spawned. Currently several modules, including FvwmButtons, FvwmEvent, FvwmForm, FvwmGtk, FvwmPager, FvwmScript support aliases. Aliases are useful if more than one instance of the module should be spawned. Aliases may be configured separately using * syntax described above. To start a module FvwmForm using an alias MyForm, the following syntax may be used:

Module FvwmForm MyForm

At the current time the available modules (included with fvwm) are FvwmAnimate (produces animation effects when a window is iconified or de-iconifed), FvwmAudio (makes sounds to go with window manager actions), FvwmAuto (an auto raise module), FvwmBacker (to change the background when you change desktops), FvwmBanner (to display a spiffy XPM), FvwmButtons (brings up a customizable tool bar), FvwmCommandS (a command server to use with shell's FvwmCommand client), FvwmConsole (to execute fvwm commands directly), FvwmCpp (to preprocess your .fvwm2rc with cpp), FvwmDebug (to help debug fvwm), FvwmDragWell (the place to drag&drop to), FvwmEvent (trigger various actions by events), FvwmForm (to bring up dialogs), FvwmGtk (to bring up GTK menus and dialogs), FvwmIconBox (like the mwm IconBox), FvwmIconMan (a flexible icon manager), FvwmIdent (to get window info), FvwmM4 (to preprocess your .fvwm2rc with m4), FvwmPager (a mini version of the desktop), FvwmSave (saves the desktop state in .xinitrc style), FvwmSaveDesk (saves the desktop state in fvwm commands), FvwmScript (another powerful dialog toolkit), FvwmScroll (puts scrollbars on any window), FvwmTaskBar (a Windows like task bar), FvwmTheme (manages colorsets, see below), FvwmWinList (a window list), FvwmWharf (an AfterStep like button bar). These modules have their own man pages. There may be other modules out on there as well.

Note, FvwmTheme is a special module which manages colorsets. Most of other modules and fvwm itself support colorsets and changing colors dynamically. Colorsets will probably be the only method to specify colors in the next stable fvwm release, and then the functionality of FvwmTheme will be moved to the core fvwm.

Modules can be short lived transient programs or, like FvwmButtons, can remain for the duration of the X session. Modules are terminated by the window manager prior to restarts and quits, if possible. See the introductory section on modules. The keyword Module may be omitted if modulename is distinct from all built-in and function names.

ModulePath path
Specifies a colon separated list of directories in which to search for modules. To find a module, fvwm searches each directory in turn and uses the first file found. Directory names on the list do not need trailing slashes.

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

For example:

ModulePath ${HOME}/lib/fvwm/modules:+

The directory containing the standard modules is available via the environment variable $FVWM_MODULEDIR.

ModuleSynchronous [Expect string] [Timeout secs] modulename
The ModuleSynchronous command is very similar to Module. Fvwm stops processing any commands and user input until the module sends a string beginning with "NOP FINISHED STARTUP" back to fvwm. If the optional Timeout is given fvwm gives up if the module sent no input back to fvwm for secs seconds. If the Expect option is given, fvwm waits for the given string instead. ModuleSynchronous should only be used during fvwm startup to enforce the order in which modules are started. This command is intended for use with the FvwmTheme module since the configuration must be in place before any other modules are started.

Warning: It is quite easy to hang fvwm with this command, even if a timeout is given. Be extra careful choosing the string to wait for. Although all modules in the fvwm distribution send back the "NOP FINISHED STARTUP" string once they have properly started up, this may not be the case for third party modules. Moreover, you can try to escape from a locked ModuleSynchronous command by using the key sequence Ctrl-Alt-Escape (see the EscapeFunc).

ModuleTimeout timeout
Specifies how many seconds fvwm waits for a module to respond. If the module does not respond within the time limit then fvwm kills it. timeout must be greater than zero, or it is reset to the default value of 30 seconds.

SendToModule modulename string
Sends an arbitrary string (no quotes required) to all modules, whose alias or name matching modulename, which may contain wildcards. This only makes sense if the module is set up to understand and deal with these strings though. Can be used for module to module communication, or implementation of more complex commands in modules.

 

QUIT, RESTART AND SESSION MANAGEMENT COMMANDS

Quit
Exits fvwm, generally causing X to exit too.

QuitScreen
Causes fvwm to stop managing the screen on which the command was issued.

QuitSession
Causes a session manager (if any) to shutdown the session. This command does not work for xsm, it seems that xsm does not implement this functionality. Use Unix signals to manage xsm remotely.

Restart [window_manager [params]]
Causes fvwm to restart itself if window_manager is left blank, or to switch to an alternate window manager (or other fvwm version) if window_manager is specified. If the window manager is not in your default search path, then you should use the full path name for window_manager.

This command should not have a trailing ampersand. The command can have optional parameters with simple shell-like syntax. You can use ~ (is expanded to the user home directory) and environmental variables .IR $VAR " or " ${VAR} . Here are several examples:

Key F1 R N Restart
Key F1 R N Restart fvwm2 -s
Key F1 R N Restart ~/bin/fvwm2 -f $HOME/.fvwm/main
Key F1 R N Restart fvwm1 -s -f .fvwm1rc
Key F1 R N Restart xterm -n '"X console"' \
  -T \"X\ console\" -e fvwm1 -s

If you need a native restart, we suggest only to use Restart command without parameters unless there is a reason not to. If you use 'Restart fvwm2', all current command line arguments are lost, while on Restart without parameters or with --pass-args, they are preserved. Here are some cases when 'Restart fvwm2' causes troubles:

* running fvwm under a session manager
* running fvwm with multi headed displays
* having command line arguments, like -f themes-rc or -cmd
* if the first fvwm2 in the $PATH is a different one

This is why we are issuing a warning on an old usage. If you really want to restart to fvwm2 with no additional arguments, you may get rid of this warning by using "Restart fvwm2 -s" or "Restart /full/path/fvwm2".

Note, currently with multi headed displays, restart of fvwms on different screens works independently.

Restart --pass-args window_manager
The same as Restart without parameters but the name for the current window manager is replaced with the specified window_manager and original arguments are preserved.

This command is useful if you use initial arguments like

-cmd FvwmCpp

and want to switch to another fvwm version without losing the initial arguments.

Restart --dont-preserve-state [other-params]
The same as

Restart [other-params]

but it does not save any window states over the restart.

Without this option, Restart preserves most per-window state by writing it to a file named .fs-restart-$HOSTDISPLAY in the user's home directory.

SaveSession
Causes a session manager (if any) to save the session. This command does not work for xsm, it seems that xsm does not implement this functionality. Use Unix signals to manage xsm remotely.

SaveQuitSession
Causes a session manager (if any) to save and then shutdown the session. This command does not work for xsm, it seems that xsm does not implement this functionality. Use Unix signals to manage xsm remotely.

 

COLOR GRADIENTS

A color gradient is a background that changes its color gradually from one hue to a different one. Color gradients can be used by various commands and modules of fvwm. There are eight types of gradients: HGradient is a horizontal gradient, VGradient is vertical, DGradient is diagonal from top left to bottom right, BGradient is backwards diagonal from bottom left to top right, SGradient is concentric squares, CGradient is concentric circles, RGradient is a radar like pattern and YGradient is a Yin Yang style (but without the dots).

The color gradient syntax has two forms:

?Gradient colors start-color end-color
This form specifies a linear gradient. The arguments denote the total number of colors to allocate (between 2 and 1000), the initial color and the final color.

Example:

TitleStyle VGradient 20 rgb:b8/ce/bc rgb:5b/85/d0

?Gradient colors segments color length color [length color] ...
The second form specifies a nonlinear gradient. The arguments are: the total number of colors to allocate (between 2 and 1000), then the number of segments. For each segment, specify the starting color, a relative length, then the ending color. Each subsequent segment begins with the second color of the last segment. The lengths may be any non-negative integers. The length of one segment divided by the sum of all segment's lengths is the fraction of the colors that are used for the segment.

Examples:

MenuStyle * MenuFace DGradient \
  128 2 lightgrey 50 blue 50 white

# 20% gradient from red to blue,
# 30% from blue to black,
# 50% from black to grey
MenuStyle * DGradient 100 3 Red 20 Blue 30 \
  Black 50 Grey

# 50% from blue to green, then
# 50% from yellow to red
*FvwmTheme: Colorset 0 Blue Red HGradient \
  128 3 Blue 1000 Green 1 Yellow 1000 Red

 

ENVIRONMENT

DISPLAY
Fvwm starts on this display unless the -display option is given.
FVWM_MODULEDIR
Set by fvwm to the directory containing the standard fvwm modules.
FVWM_USERDIR
Used to determine the user's data directory for reading and sometimes writing personal files. If this variable is not already set, it is set by fvwm to $HOME/.fvwm, which is the default user's data directory.
SESSION_MANAGER
Fvwm tries to contact this session manager.
SESSION_MANAGER_NAME
This is used mainly to determine xsm running to work around its bug. If this variable is set to "xsm", DiscardCommand is set as xsm expects it and not as XSMP requires. If you run fvwm under xsm, you should set this variable to "xsm", otherwise old state files are not removed.
SM_SAVE_DIR
If this is set, fvwm saves its session data in this directory. Otherwise it uses $HOME. Note, the state files are named .fs-?????? and normally are removed automatically when not used anymore.

 

AUTHORS

Robert Nation with help from many people, based on twm code, which was written by Tom LaStrange. After Robert Nation came Charles Hines, followed by Brady Montz. Currently fvwm is developed by a number of people on the fvwm-workers mailing list.

 

COPYRIGHT

Fvwm and all the modules, scripts and other files coming with the distribution are subject to the GNU General Public License (GPL). Please refer to the COPYING file that came with fvwm for details.

 

BUGS

As of fvwm version 2.4.0 there were exactly 71.8 unidentified bugs. Since then 22.825 bugs have been fixed. Assuming that there are at least 10 unidentified bugs for every identified one, that leaves us with 71.8 - 22.825 + 10 * 22.825 = 277.225 unidentified bugs. If we follow this to its logical conclusion we will have an infinite number of unidentified bugs before the number of bugs can start to diminish, at which point the program will be bug-free. Since this is a computer program infinity = 3.4028e+38 if you don't insist on double-precision. At the current rate of bug discovery we should expect to achieve this point in 4.27e+27 years. I guess we better plan on passing this thing on to our children...

Known bugs can be found in the fvwm bug tracking system (accessible from the fvwm home page) and in the BUGS or TODO files in the distribution. These files are no longer maintained and may be out of date.

Bug reports can be sent to the fvwm-workers mailing list (see the FAQ) or reported through the bug tracking system.

The official fvwm homepage is http://www.fvwm.org/.


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
ANATOMY OF A WINDOW
THE VIRTUAL DESKTOP
USE ON MULTI-SCREEN DISPLAYS
XINERAMA SUPPORT
INITIALIZATION
COMPILATION OPTIONS
ICONS
MODULES
ICCCM COMPLIANCE
GNOME COMPLIANCE
MWM COMPATIBILITY
OPEN LOOK and XVIEW COMPATIBILITY
OPEN LOOK and XVIEW COMPATIBILITY
M4 PREPROCESSING
CPP PREPROCESSING
AUTO-RAISE
CONFIGURATION FILES
SUPPLIED CONFIGURATION
KEYBOARD SHORTCUTS
SESSION MANAGEMENT
BOOLEAN ARGUMENTS
BUILT IN KEY AND MOUSE BINDINGS
BUILT IN COMMANDS
QUOTING
COMMAND EXPANSION
THE LIST OF BUILTIN COMMANDS
COMMANDS FOR MENUS
MISCELLANEOUS COMMANDS
COMMANDS AFFECTING WINDOW MOVEMENT AND PLACEMENT
COMMANDS FOR FOCUS AND MOUSE MOVEMENT
COMMANDS CONTROLLING WINDOW STATE
COMMANDS FOR MOUSE, KEY AND STROKE BINDINGS
THE STYLE COMMAND (CONTROLLING WINDOW STYLES)
OTHER COMMANDS CONTROLLING WINDOW STYLES
COMMANDS CONTROLLING THE VIRTUAL DESKTOP
COMMANDS FOR USER FUNCTIONS AND SHELL COMMANDS
CONDITIONAL COMMANDS
MODULE COMMANDS
QUIT, RESTART AND SESSION MANAGEMENT COMMANDS
COLOR GRADIENTS
ENVIRONMENT
AUTHORS
COPYRIGHT
BUGS

This document was created by man2html, using the manual pages.
Time: 17:47:35 GMT, May 30, 2003

Last modified on April 11, 2014