fvwm3 manual page

fvwm3 - F? Virtual Window Manager for X11

fvwm3 [-c config-command] [-d displayname] [-f config-file] [-o logfile] [-v]

Fvwm is a window manager for X11 optimised for speed.

Fvwm is intended to have a small memory footprint and is extremely customizable and extendible. A large virtual desktop and multiple disjoint desktops can be used separately or together. The virtual desktop pretends that the video screen is really quite large, and you can scroll around within the desktop. The multiple disjoint desktops pretend there are really several screens to work at, but each screen is completely unrelated to the others.

Fvwm provides keyboard accelerators that allow one to perform practically all window manager functions, including moving and resizing windows and operating the menus, using keyboard shortcuts.

Fvwm does not distinguish between configuration and action commands. Configuration commands typically set fonts, colors, menu contents, and key and mouse function bindings, while action commands do things like raising and lowering windows. Fvwm makes no such distinction and allows anything to be changed at any time.

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

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

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

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

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

The (m by n) size (i.e. number of pages) of the virtual desktops can be changed any time, by using the DesktopSize command. All virtual desktops must be (are) the same size. The total number of distinct desktops does not need to be specified, but is limited to approximately 4 billion total. All windows on a range of desktops can be viewed in the FvwmPager, a miniature view of the desktops. The pager is an accessory program, called a module, which is not essential for the window manager to operate. Windows may also be listed using the WindowList command or the FvwmIconMan module.

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

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

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

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:

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:

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 is a fvwm-specific extension to geometry strings which can also enforce the geometry is relative to the given screen. For example:

Where 'n' can be one of a RandR monitor name, or an assigned monitor number. For more details, see the RANDR SUPPORT section.

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

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

Some applications that understand standard Xt command line arguments and X resources, like xterm and xfontsel, allow the user to specify the start-up desk or page on the command line:

starts an xterm on desk number 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:

or

Fvwm best supports multiple screens using the RandR X11 protocol. If fvwm isn’t built with the RandR protocol then the multi screen support is very limited, and it is suggested to rebuild with RandR. It is also recommended to use 'EdgeScroll 0 0' on multi-screen displays to avoid changing pages when moving the mouse between screens.

If Fvwm has been compiled with RandR support then it tracks the outputs (displays) which it finds. These outputs are stored by name, which can be found by running using the xrandr(1) command.

When Fvwm detects monitors, it adds them to a tree with a defined order, and each monitor is assigned a number. That order is top-down, left-to-right, so for example, the following diagram illustrates a monitor layout and their assigned number.

Hence it is possible to then refer to the 2nd monitor and print its name via expansion variables as:

Which would print the name, B.

In doing so, Fvwm tracks events from RandR, such as when a given output changes size, or has been added or removed.

In addition to specific FvwmEvent conditions which can be used to track a monitor’s change, there is a function called RandRFunc which the user can define to be run when a screen event occurs (such as enabling/disabling/resolution change):

Because Fvwm has the capability to track outputs, Fvwm can be told how to handle those. This is controlled via the DesktopConfiguration command. By default, Fvwm treats all outputs it finds as one large screen, although Fvwm can be told to treat screens independently of each other.

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

This looks for file config in $FVWM_USERDIR and $FVWM_DATADIR directories, as described in Read. If this fails more files are queried for backward compatibility. Here is the complete list of all file locations queried in the default installation (only the first found file is used):

Please note, the last 5 locations are not guaranteed to be supported in the future.

If a configuration file is not found, the left mouse button, or

or

keys on the root window bring up menus and forms that can create a starting configuration file.

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

If you want to start some applications or modules with fvwm, you can simply put

or

into your config, but it is not recommended; do this only if you know what you are doing. It is usually important to start applications or modules after the entire config is read, because it contains styles or module configurations which can affect window appearance and functionality.

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

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

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

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

You do not need to define all special functions if some are empty. Also note, all these special functions may be emulated now using StartFunction and ExitFunction, like this:

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.

Fvwm can load .xbm, .xpm, .png and .svg images. XBM images are monochrome. Fvwm can always display XBM files. XPM and PNG formats are color images. SVG is a vector graphics image format. Compile-time options determine whether fvwm can display XPM, PNG or SVG icons and images. See the INSTALL.fvwm file for more information.

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

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

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

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

Modules simply transmit commands to the fvwm command engine. Commands are formatted just as in the case of a mouse binding in the config setup file. Certain auxiliary information is also transmitted, as in the sample module FvwmButtons.

Please refer to the Module Commands section for details.

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

The ICCCM states that windows possessing the property

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

resembles the Restart command. It is not exactly the same, since killing the previously running wm may terminate your X session, if the wm was started as the last client in your .Xclients or .Xsession file.

Further additions are support for client-side colormap installation (see the ICCCM for details) and the urgency hint. Clients can set this hint in the WM_HINTS property of their window and expect the window manager to attract the user’s attention to the window. Fvwm has two re-definable functions for this purpose, "UrgencyFunc" and "UrgencyDoneFunc", which are executed when the flag is set/cleared. Their default definitions are:

Fvwm attempts to respect the extended window manager hints (ewmh or EWMH for short) specification: https://specifications.freedesktop.org/wm-spec/wm-spec-1.3.html and some extensions of this specification.

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

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

When a compliant taskbar asks fvwm to activate a window (typically when you click on a button which represents a window in such a taskbar), then fvwm calls the complex function EWMHActivateWindowFunc which by default is Iconify Off, Focus and Raise. You can redefine this function. For example:

additionally warps the pointer to the center of the window.

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

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

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

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

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

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

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.

The following commands are built-in to fvwm:

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 Alt key (same as the 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:

Quotes are required only when needed to make fvwm consider two or more words to be a single argument. Unnecessary quoting is allowed. If you want a quote character in your text, you must escape it by using the backslash character. For example, if you have a pop-up menu called "Window-Ops", then you do not need quotes:

but if you replace the dash with a space, then you need quotes:

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.

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

If a command is prefixed with a '-' parameter expansion isn’t performed. This applies to the command immediately following the '-', in which the expansion normally would have taken place. When uesed together with other prefix commands it must be added before the other prefix.

Example:

opens an xmessage dialog with "$[w.name]" unexpanded.

The longer variables may contain additional variables inside the name, which are expanded before the outer variable.

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

Example:

Note: If the command is called outside a window context, it prints "$[w.class]" instead of the class name. It is usually not enough to have the pointer over a window to have a context window. To force using the window with the focus, the Current command can be used:

The parameters known by fvwm are:

$[monitor.<n>.x], $[monitor.<n>.y], $[monitor.<n>.width], $[monitor.<n>.height], $[monitor.<n>.desk], $[monitor.<n>.pagex], $[monitor.<n>.pagey] $[monitor.primary], $[monitor.prev_primary], $[monitor.current], $[monitor.prev] $[monitor.output], $[monitor.number] $[monitor.count], $[monitor.<n>.prev_desk], $[monitor.<n>.prev_pagex], $[monitor.<n>.prev_pagey]:: Returns information about the selected monitor. These can be nested, for example: $[monitor.$[monitor.primary].width]

+ <n> should be a valid xrandr(1) output name.

+ "x" returns the monitor’s x position; "y" returns the monitor’s y position; "width" returns the monitor’s width (in pixels); "height" returns the monitor’s height (in pixels)

+ "number" returns the monitor’s position within the tree. See RANDR SUPPORT.

+ "current" is the same as the deprecated $[screen.pointer] variable; the monitor which has the mouse pointer.

+ "prev" returns the previously focused monitor, or the empty string if there isn’t one.

+ "count" returns the number of active monitors.

+ "desk" returns the current desk displayed on the referenced monitor.

+ "pagex" returns the X page on the referenced monitor.

+ "pagey" returns the Y page of the referenced monitor.

+ "primary" is the name of the output set as primary via xrandr(1).

+ "prev_primary" is the name of the output which was the previous primary monitor.

+ "prev_desk" returns the previous desk on the referenced monitor.

+ "prev_pagex" returns the previous X page on the referenced monitor.

+ "prev_pagey" returns the previous Y page on the referenced monitor.

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

Please refer to the fvwm3menus man page.

Please refer to the fvwm3commands and fvwm3styles man pages.

The environment variables that have an effect on how fvwm operates are the following:

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.

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.

Bug reports can be sent to the fvwm-workers mailing list at <fvwm-workers@fvwm.org>

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