fvwm2 - F(?) Virtual Window Manager (version 2) for X11
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]
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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
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.
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.
Style * OLDecor
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 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".
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.
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 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.
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.
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 ( Ctrl-n, Ctrl-p, Ctrl-f, Ctrl-b, and Ctrl-j, Ctrl-k, Ctrl-h, Ctrl-l ) 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, 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.
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:
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 -
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.
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.
Whenever a fvwm command line is executed, fvwm performs parameter expansion. A parameter is a '$' followed by a single letter or a word enclosed in brackets ($[...]). 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 "$$". Note that module configuration lines (i.e. lines beginning with '*') are not fully expanded; for backward compatibility single alphabetic-letter parameters (like "$d" or "$n") are not expanded in these lines.
The general idea is to expand single letter parameters as soon as possible. So a "$d" is expanded immediately when read by the parser, but "$3" is only expanded in the context of a complex function with at least four parameters. Otherwise it is left untouched. Similarly, "$c" is only expanded in the context of a window.
Parameter expansion in the + command is different than in normal commands. If the command is adding to a function, single letter parameters are expanded normally which is often not what was intended. To suppress expansion the '$' has to be doubled. Parameters enclosed in brackets are protected from parameter expansion in these commands so the '$' must not be doubled.
Example:
# Print the current desk number, horizontal # page and the window's class. Echo $d $[page.nx] $c # But a function that prints $d needs $$, # but not before $[page.nx] or $c: AddToFunc PrintDeskNumber + I Echo $$d $[page.nx] $c
Note: If this funtion is called outside a window context, it will print "$c" 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 $d $[page.nx] $c
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.
$d The current desk number.
$n The window's name or "$n" if no window is associated with the command.
$r The window's resource name or "$r" if no window is associated with the command.
$v The first line printed by the -version command line option.
$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.
$x The x coordinate of the current viewport.
$y The y coordinate of the current viewport.
$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".
$[vp.x] $[vp.y] $[vp.width] $[vp.height] Either coordinate or the width or height of the current viewport.
$[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.
$[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.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.
$[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 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
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
+ 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 pixmap1 \ ScreenSaverMenu ScreenLockMenu
DestroyMenu Utilities
DestroyMenuStyle pixamp1
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 sub-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.
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 you 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 a gap as large as one respectively eight spaces are with the font used in the menu items. 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.
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.
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.
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 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.
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 FollowsFocus
then the installed colormap is the one for the window that currently has the keyboard focus.
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.
DefaultColorset -1
or any variant of the DefaultColors command.
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 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 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
Style * HilightFore textcolor, \
HilightBack backgroundcolor
instead.
Style * HilightColorset num
instead.
Style * IconFont fontname
instead.
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).
Style * Font fontname
instead.
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 WindowId $0 Iconify off + I WindowId $0 FlipFocus + I WindowId $0 Raise + I WindowId $0 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 $w 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, 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, $0 is the window id:
AddToFunc IFunc I WindowId $0 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.
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.)
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.
AddToFunc lower-to-bottom + I Layer 0 0 + I Lower
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.
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.
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
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.
AddToFunc raise-to-top + I Layer 0 ontop + I Raise
where ontop is the highest layer used in your setup.
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.
Example:
# Move the window to the top left corner ResizeMove w+0 -10p 0 -20p
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.
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.
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
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.
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