Provided by: fvwm3_1.0.6a+ds-1_amd64 
NAME
fvwm3commands - fvwm built-in commands
LIST OF FVWM COMMANDS
The command descriptions below are grouped together in the following sections. The
sections are hopefully sorted in order of usefulness to the newcomer.
• Menu commands
• Miscellaneous commands
• Commands affecting window movement and placement
• Commands for focus and mouse movement
• Commands controlling window state
• Commands for mouse and key bindings
• The Style command (controlling window styles)
• Other commands controlling window styles
• Commands controlling the virtual desktop
• Commands for user functions and shell commands
• Conditional commands
• Module commands
• Quit, restart and session management commands
• Colorsets
• Color gradients
Miscellaneous Commands
BugOpts [option [bool]], ...
This command controls several workarounds for bugs in third party programs. The
individual options are separated by commas. The optional argument bool is a boolean
argument and controls if the bug workaround is enabled or not. It can either be "True"
or "False" to turn the option on or off, or "toggle" to switch is back and forth. If
bool is omitted, the default setting is restored.
DebugRandR activates monitor layout debug messages.
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 server’s host system. This is needed for some X servers running under
Windows, Windows NT or Mac OS X. 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. It is useful with
the Unmanaged style option too.
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.
QtDragnDropWorkaround suppresses the forwarding of unknown ClientEvent messages to
windows — usually this is harmless, but Qt has problems handling unrecognised
ClientEvent messages. Enabling this option might therefore help for Qt applications
using DragnDrop. This option is off by default.
EWMHIconicStateWorkaround is needed by EWMH compliant pagers or taskbars which
represent windows which are on a different desktops as iconified. These pagers and
taskbars use a version of the EWMH specification before version 1.2 (the current KDE 2
& 3 versions). These pagers and taskbars use the IconicState WM_STATE state to
determine if an application is iconified. This state, according to the ICCCM, does not
imply that a window is iconified (in the usual sense). Turning on this option forces
fvwm to establish an equivalence between the IconicState WM_STATE state and the
iconified window. This violates ICCCM compliance but should not cause big problems. By
default this option is off.
With the DisplayNewWindowNames enabled, fvwm prints the name, icon name (if
available), resource and class of new windows to the console. This can help in finding
the correct strings to use in the Style command.
When the ExplainWindowPlacement option is enabled, fvwm prints a message to the
console whenever a new window is placed or PlaceAgain, is used. The message explains
on which desk, page, screen and position it was placed and why. This option can be
used to figure out why a specific window does not appear where you think it should.
The DebugCRMotionMethod option enables some debugging code in the ConfigureRequest
handling routines of fvwm. It is not helpful for the user, but if you report a bug to
the fvwm team we may ask you to enable this option.
The TransliterateUtf8 option enables transliteration during conversions from utf-8
strings. By default fvwm will not transliterate during conversion, but will fall back
to alternate strings provided by the clients if conversion from utf-8 fails due to
characters which have no direct correspondence in the target charecter set. Some
clients however neglect to set non utf-8 properties correctly in which case this
option may help.
BusyCursor [Option bool], ...
This command controls the cursor during the execution of certain commands. Option can
be DynamicMenu, ModuleSynchronous, Read, Wait or *. An option must be followed by a
boolean argument bool. You can use commas to separate individual options. If you set
an option to "True", then when the corresponding command is run, fvwm displays the
cursor of the WAIT context of the CursorStyle command. "False" forces to not display
the cursor. The default is:
BusyCursor DynamicMenu False, ModuleSynchronous False, \
Read False, Wait False
The * option refers to all available options.
The Read option 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 ModuleSynchronous option affects the ModuleSynchronous command. If this option is
set to "False", then the busy cursor is not displayed while fvwm waits for a module
started by ModuleSynchronous to complete its startup.
The Wait option affects only the root cursor. During a wait pause the root cursor is
replaced by the busy cursor and fvwm is still fully functional (you can escape from
the pause, see the EscapeFunc command). If you want to use this option and if you do
not use the default root cursor, you must set your root cursor with the CursorStyle
command.
ClickTime [delay]
Specifies the maximum delay in milliseconds between a button press and a button
release for the Function command to consider the action a mouse click. The default
delay is 150 milliseconds. Omitting the delay value resets the ClickTime to the
default.
ClickTime also specifies the delay between two clicks to be interpreted as a
double-click.
ColorLimit limit
This command is obsolete. See the --color-limit option to fvwm.
ColormapFocus FollowsMouse | FollowsFocus
By default, fvwm installs the colormap of the window that the cursor is in. If you use
ColormapFocus FollowsFocus
then the installed colormap is the one for the window that currently has the keyboard
focus.
CursorStyle context [num | name | None | Tiny | file [x y] [fg bg]]
Defines a new cursor for the specified context. Note that this command can not control
the shapes an applications uses, for example, to indicate that it is busy. The various
contexts are:
POSITION (top_left_corner)
used when initially placing windows
TITLE (top_left_arrow)
used in a window title-bar
DEFAULT (top_left_arrow)
used in windows that do not 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 commands
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
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 argument is either the numeric value of the cursor as defined in the include
file X11/cursorfont.h or its name (without the XC_ prefix). Alternatively, the xpm file
name may be specified. The name can also be None (no cursor) or Tiny (a single pixel as
the cursor).
# make the kill cursor be XC_gumby (both forms work):
CursorStyle DESTROY 56
CursorStyle DESTROY gumby
Alternatively, the cursor can be loaded from an (XPM, PNG or SVG) image file. If fvwm is
compiled with Xcursor support, full ARGB is used, and (possibly animated) cursor files
made with the xcursorgen program can be loaded. Otherwise the cursor is converted to
monochrome.
The optional x and y arguments (following a file argument) specifies the hot-spot
coordinate with 0 0 as the top left corner of the image. Coordinates within the image
boundary are valid and overrides any hot-spot defined in the (XPM/Xcursor) image file. An
invalid or undefined hot-spot is placed in the center of the image.
CursorStyle ROOT cursor_image.png 0 0
The optional fg and bg arguments specify the foreground and background colors for the
cursor, defaulting to black and white (reverse video compared to the actual bitmap). These
colors are only used with monochrome cursors. Otherwise they are silently ignored.
CursorStyle ROOT nice_arrow.xpm yellow black
DefaultFont [fontname]
DefaultFont sets the default font to font fontname. The default font is used by fvwm
whenever no other font has been specified. To reset the default font to the built-in
default, omit the argument. The default font is used for menus, window titles, icon
titles as well as the geometry feedback windows during a move or resize operation. To
override the default font in a specific context, use the Style * Font, Style *
IconFont, or MenuStyle commands.
DefaultIcon filename
Sets the default icon which is used if a window has neither an client-supplied icon
nor an icon supplied via the Icon option of the Style command.
DefaultLayers bottom put top
Changes the layers that are used for the StaysOnBottom, StaysPut, StaysOnTop Style
options. Initially, the layers 2, 4 and 6 are used.
Deschedule [command_id]
Removes all commands that were scheduled with the id command_id with the Schedule
command from the list of commands to be executed unless they were already executed. If
the command_id is omitted, the value of the variable $[schedule.last] is used as the
id.
Emulate Fvwm | Mwm | Win
This command is a catch all for how miscellaneous things are done by fvwm. Right now
this command affects where the move/resize feedback window appears and how window
placement is aborted. To have more Mwm- or Win-like behavior you can call Emulate with
Mwm or Win as its argument. With Mwm resize and move feedback windows are in the
center of the screen, instead of the upper left corner. This also affects how manual
placement is aborted. See the ManualPlacement description.
EscapeFunc
By default the key sequence Ctrl-Alt-Escape allows for escaping from a Wait pause and
from a locked ModuleSynchronous command. The EscapeFunc command used with the Key
command allows for configuring this key sequence. An example:
Key Escape A MC -
Key Escape A S EscapeFunc
replaces the Ctrl-Alt-Escape key sequence with Shift-Escape for aborting a Wait pause
and ModuleSynchronous command. EscapeFunc used outside the Key command does nothing.
FakeClick [command value] ...
This command is mainly intended for debugging fvwm and no guarantees are made that it
works for you. FakeClick can simulate mouse button press and release events and pass
them to fvwm or the applications. The parameters are a list of commands which consist
of pairs of command tokens and integer values, The press and release commands are
followed by the appropriate mouse button number and generate a button press or release
event on the window below the pointer. The wait commands pauses fvwm for the given
number of milliseconds. The modifiers command simulates pressing or releasing modifier
keys. The values 1 to 5 are mapped to Mod1 to Mod5 while 6, 7 and 8 are mapped to
Shift, Lock and Control. The modifier is set for any further button events. To release
a modifier key, use the corresponding negative number. The depth command determines to
which window the button events are sent. With a depth of 1, all events go to the root
window, regardless of the pointer’s position. With 2, the event is passed to the top
level window under the pointer which is usually the frame window. With 3, events go to
the client window. Higher numbers go to successive sub windows. Zero (0) goes to the
smallest window that contains the pointer. Note that events propagate upward.
FakeClick depth 2 press 1 wait 250 release 1
This simulates a click with button 1 in the parent window (depth 2) with a delay of
250 milliseconds between the press and the release. Note: all command names can be
abbreviated with their first letter.
FakeKeypress [command value] ...
This command is mainly intended for debugging fvwm and no guarantees are made that it
works for you. FakeKeypress can simulate key press and release events and pass them to
fvwm or applications. The parameters are a list of commands which consist of pairs of
command tokens and values. The press and release commands are followed by a key name.
The key name is a standard X11 key name as defined in /usr/include/X11/keysymdef.h,
(without the XK_ prefix), or the keysym database /usr/X11R6/lib/X11/XKeysymDB. The
wait, modifiers and depth commands are the same as those used by FakeClick.
Save all GVim sessions with: "Esc:w\n"
All (gvim) FakeKeypress press Escape \
press colon \
press w \
press Return
Save & exit all GVim sessions with: "Esc:wq\n"
All (gvim) FakeKeypress press Escape \
press colon \
press w \
press q \
press Return
Send A to a specific window:
WindowId 0x3800002 FakeKeypress press A
Note: all command names can be abbreviated with their first letter.
HilightColor textcolor backgroundcolor
This command is obsoleted by the Style options HilightFore and HilightBack. Please use
Style * HilightFore textcolor, HilightBack backgroundcolor
instead.
HilightColorset [num]
This command is obsoleted by the Style option HilightColorset. Please use
Style * HilightColorset num
instead.
IconFont [fontname]
This command is obsoleted by the Style option IconFont. Please use
Style * IconFont fontname
instead.
IconPath path
This command is obsolete. Please use ImagePath instead.
ImagePath path
Specifies a colon separated list of directories in which to search for images (both
monochrome and pixmap). To find an image given by a relative pathname, fvwm looks into
each directory listed in turn, and uses the first file found.
If a directory is given in the form "/some/dir;.ext", this means all images in this
directory have the extension ".ext" that should be forced. The original image name
(that may contain another extension or no extension at all) is not probed, instead
".ext" is added or replaces the original extension. This is useful, for example, if a
user has some image directories with ".xpm" images and other image directories with
the same names, but ".png" images.
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 config 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).
LocalePath path
Specifies a colon separated list of "locale path" in which to search for string
translations. A locale path is constituted by a directory path and a text domain
separated by a semicolon (';'). As an example the default locale path is:
/install_prefix/share/locale;fvwm
where install_prefix is the fvwm installation directory. With such a locale path
translations are searched for in
/install_prefix/share/locale/lang/LC_MESSAGES/fvwm.mo
where lang depends on the locale. If no directory is given the default directory path
is assumed. If no text domain is given, fvwm is assumed. Without argument the default
locale path is restored.
As for the ImagePath command, path may contain environment variables and a '+' to
append or prepend the locale path easily.
For example, the fvwm-themes package uses
LocalePath ";fvwm-themes:+"
to add locale catalogs.
The default fvwm catalog contains a few strings used by the fvwm executable itself
(Desk and Geometry) and strings used in some default configuration files and FvwmForm
configuration. You can take a look at the po/ subdirectory of the fvwm source to get
the list of the strings with a possible translation in various languages. At present,
very few languages are supported.
The main use of locale catalogs is via the "$[gt.string]" parameter:
DestroyMenu MenuFvwmWindowOps
AddToMenu MenuFvwmWindowOps "$[gt.Window Ops]" Title
+ "$[gt.&Move]" Move
+ "$[gt.&Resize]" Resize
+ "$[gt.R&aise]" Raise
+ "$[gt.&Lower]" Lower
+ "$[gt.(De)&Iconify]" Iconify
+ "$[gt.(Un)&Stick]" Stick
+ "$[gt.(Un)Ma&ximize]" Maximize
+ "" Nop
+ "$[gt.&Close]" Close
+ "$[gt.&Destroy]" Destroy
gives a menu in the locale languages if translations are available.
Note that the FvwmScript module has a set of special instructions for string
translation. It is out of the scope of this discussion to explain how to build locale
catalogs. Please refer to the GNU gettext documentation.
PixmapPath path
This command is obsolete. Please use ImagePath instead.
PrintInfo subject [verbose]
Print information on subject to debug log file, which defaults to
$HOME/.fvwm/fvwm3-output.log . Environment variables $FVWM_USERDIR and $FVWM3_LOGFILE
can alter this default. For this logfile to be written, either fvwm3 has to be started
with -v option or SIGUSR2 signal can be used to toggle opening/closing debug log file.
An optional integer argument to debug log file, which defaults to
$HOME/.fvwm/fvwm3-output.log . Environment variables $FVWM_USERDIR and $FVWM3_LOGFILE
can alter this default. For this logfile to be written, either fvwm3 has to be started
with -v option or SIGUSR2 signal can be used to toggle opening/closing debug log file.
An optional integer argument verbose defines the level of information which is given.
The current valid subjects are:
Colors which prints information about the colors used by fvwm. This useful on screens
which can only display 256 (or less) colors at once. If verbose is one or greater the
palette used by fvwm is printed. If you have a limited color palette, and you run out
of colors, this command might be helpful.
ImageCache which prints information about the images loaded by fvwm. If verbose is one
or greater all images in the cache will be listed together with their respective
reuse.
Locale which prints information on your locale and the fonts that fvwm used. verbose
can be 1 or 2.
nls which prints information on the locale catalogs that fvwm used
style which prints information on fvwm styles. verbose can be 1.
bindings which prints information on all the bindings fvwm has: key and mouse
bindings. verbose has no effect with this option.
infostore which prints information on all entries in the infostore, listing the key
and its value. verbose has no effect with this option.
Schedule [Periodic] delay_ms [command_id] command
The command is executed after about delay_ms milliseconds. This may be useful in
some tricky setups. The command is executed in the same context window as the Schedule
command. An optional integer argument command_id may be given in decimal, hexadecimal
or octal format. This id can be used with the Deschedule command to remove the
scheduled command before it is executed. If no id is given, fvwm uses negative id
numbers, starting with -1 and decreasing by one with each use of the Schedule command.
Note that the Schedule command and its arguments undergo the usual command line
expansion, and, when command is finally executed, it is expanded again. It may
therefore be necessary to quote the parts of the command that must not be expanded
twice.
Note: A window’s id as it is returned with $[w.id] can be used as the command_id.
Example:
Current Schedule 1000 $[w.id] WindowShade
The Schedule command also supports the optional keyword Periodic which indicates that
the command should be executed every delay_ms. Example:
Schedule Periodic 10000 PipeRead '[ -N "$MAIL" ] && echo \
Echo You have mail'
Use the Deschedule command to stop periodic commands.
State state [bool]
Sets, clears or toggles one of the 32 user defined states which are associated with
each window. The state is a number ranging from 0 to 31. The states have no meaning in
fvwm, but they can be checked in conditional commands like Next with the State
condition. The optional argument bool is a boolean argument. "True" sets the given
state, while "False" clears it. Using "toggle" switches to the opposite state. If the
bool argument is not given, the state is toggled.
WindowFont [fontname]
This command is obsoleted by the Style option Font. Please use
Style * Font fontname
instead.
WindowList [(conditions)] [position] [options] [double-click-action]
Generates a pop-up menu (and pops it up) in which the title and geometry of each of
the windows currently on the desktop are shown.
The format of the geometry part is: desk(layer): x-geometry sticky, where desk and
layer are the corresponding numbers and sticky is empty or a capital S. The geometry
of iconified windows is shown in parentheses. Selecting an item from the window list
pop-up menu causes the interpreted function "WindowListFunc" to be run with the window
id of that window passed in as $0. The default "WindowListFunc" looks like this:
AddToFunc WindowListFunc
+ I Iconify off
+ I FlipFocus
+ I Raise
+ I WarpToWindow 5p 5p
You can destroy the built-in "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. See the default
# WindowListFunc definition earlier in this
# man page.
AddToFunc SwitchToWindow
+ I WindowListFunc
Key Tab A M WindowList "Prev SwitchToWindow"
Hitting Alt-Tab once it brings up the window list, if you hit it twice the focus is
flipped between the current and the last focused window. With the proper
SelectOnRelease menu style (see example above) a window is selected as soon as you
release the Alt key.
The options passed to WindowList are separated by commas and can be Geometry /
NoGeometry / NoGeometryWithInfo, NoDeskNum, NoLayer, NoNumInDeskTitle,
NoCurrentDeskTitle, MaxLabelWidth width, TitleForAllDesks, Function funcname, Desk
desknum, CurrentDesk, NoIcons / Icons / OnlyIcons, NoNormal / Normal / OnlyNormal,
NoSticky / Sticky / OnlySticky, NoStickyAcrossPages / StickyAcrossPages /
OnlyStickyAcrossPages, NoStickyAcrossDesks / StickyAcrossDesks /
OnlyStickyAcrossDesks, NoOnTop / OnTop / OnlyOnTop, NoOnBottom / OnBottom /
OnlyOnBottom, Layer m [n], UseSkipList / OnlySkipList, NoDeskSort, ReverseOrder,
CurrentAtEnd, IconifiedAtEnd, UseIconName, Alphabetic / NotAlphabetic, SortByResource,
SortByClass, NoHotkeys, SelectOnRelease.
(Note - normal means not iconic, sticky, or on top)
With the SortByResource option windows are alphabetically sorted first by resource
class, then by resource name and then by window name (or icon name if UseIconName is
specified). ReverseOrder also works in the expected manner.
With the SortByClass option windows are sorted just like with SortByResource, but the
resource name is not taken into account, only the resource class.
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
key. To switch it off, use SelectOnRelease without a key name.
If you pass in a function via Function funcname, it is called within a window context
of the selected window:
AddToFunc IFunc I Iconify toggle
WindowList Function IFunc, NoSticky, CurrentDesk, NoIcons
If you use the Layer m [n] option, only windows in layers between m and n are
displayed. n defaults to m. With the ReverseOrder option the order of the windows in
the list is reversed.
With the CurrentAtEnd option the currently focused window (if any) is shown at the
bottom of the list. This is mostly intended for simulating the Alt-Tab behavior in
another GUI.
IconifiedAtEnd makes iconified windows be moved to the end of the list. This is also
from another GUI.
The NoGeometry option causes fvwm to not display the geometries as well as the
separators which indicate the different desktops. NoGeometryWithInfo removes the
geometries, but keep the desktop information and indicates iconic windows. NoDeskNum
causes fvwm to not display the desktop number in the geometry or before the window
title with the NoGeometryWithInfo option. NoNumInDeskTitle is only useful if a desktop
name is defined with the DesktopName command. It causes fvwm to not display the
desktop number before the desktop name. By default, the WindowList menu have a title
which indicates the current desk or the selected desktop if the Desk condition is
used. The NoCurrentDeskTitle option removes this title. TitleForAllDesks causes fvwm
to add a menu title with the desk name and/or number before each group of windows on
the same desk. With NoLayer, the layer of the window is not displayed. The options
ShowPage, ShowPageX and ShowPageY enable displaying the page of the window rounded
multiples of the display size. With ShowScreen, the window’s screen name is displayed.
The MaxLabelWidth option takes the number of characters to print as its argument. No
more than that many characters of the window name are visible.
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.)
XSync
When XSync is called, the X function with the same name is used to send all pending X
requests to the server. This command is intended for debugging only.
XSynchronize [bool]
The XSynchronize command controls whether X requests are sent to the X server
immediately or not. Normally, requests are sent in larger batches to save unnecessary
communication. To send requests immediately, use "True" as the argument, to disable
this use "False" or to toggle between both methods use "Toggle" or omit the bool
argument. Fvwm defaults to synchronized requests when started with the --debug option.
This command is intended for debugging only.
+
Used to continue adding to the last specified decor, function or menu. See the
discussion for AddToDecor, AddToFunc, and AddToMenu.
Window Movement and Placement
AnimatedMove x y [Warp]
Move a window in an animated fashion. Similar to Move command. The options are the
same, except they are required, since it doesn’t make sense to have a user move the
window interactively and animatedly. If the optional argument Warp is specified the
pointer is warped with the window.
GeometryWindow Hide | Show | Colorset n | Position x y | Screen S
Configures the position or size window that is usually shown when a window is moved or
resized interactively. This can be used to hide, show, change the colorset, change the
location, or change the screen of the geometry window. Multiple options can be set at
once separated by spaces. Details of each option are described below.
GeometryWindow Hide [Never | Move | Resize]
Hides or switches off the geometry window. If the optional parameters Move or Resize
are given, it will only hide the geometry window during the respective operation. The
parameter Never will switch the geometry back on again (equivalent to Show).
GeometryWindow Show [Never | Move | Resize]
Shows or switches on the geometry window (equivalent to Hide Never). If the optional
parameters Move or Resize are given, it will only show the geometry window during the
respective operation. The parameter Never will switch the geometry window off
(equivalent to Hide).
GeometryWindow Colorset cset
Sets colorset of the gometry window to cset. Use the literal option default for cset
to use the default colorset.
GeometryWindow Position [+|-]x[p] [+|-]y[p]
Configures the position the geometry window appears. x and y are the relative
coordinates as a percentage of the screen size. If a leading '-' is provided the
coordinates are computed from the left/bottom of the screen respectively. If the
coordinates are appended with a 'p', they are interpreted as the number of pixels from
the respective screen edge. If no position arguments are given, the geometry window’s
position will return to its default state of the upper left corner or the center if
emulating MWM.
GeometryWindow Screen RANDRNAME
Configure which screen the geometry window is shown on. By default the geometry window
is shown on the current screen. If a valid RANDRNAME is provided, the geometry window
will always be shown on that screen. Use current as the RANDRNAME to return the
default.
Examples:
# Position the geometry window in the center of the screen
GeometryWindow Position 50 50
# Position the geometry window next to the RightPanel
GeometryWindow Position -120p 0
# Use colorset 2 for the geometry window
GeometryWindow Colorset 2
# Only show the geometry window on the primary monitor
GeometryWindow Screen $[monitor.primary]
# Hide the geometry window
GeometryWindow Hide
HideGeometryWindow [Never | Move | Resize]
This command has been depreciated and is now obsolete. Use GeometryWindow Hide
instead.
Layer [arg1 arg2] | [default]
Puts the current window in a new layer. If arg1 is non zero then the next layer is the
current layer number plus arg1. If arg1 is zero then the new layer is arg2.
As a special case, default puts the window in its default layer, i.e. the layer it was
initially in. The same happens if no or invalid arguments are specified.
Lower
Allows the user to lower a window. Note that this lowers a window only in its layer.
To bring a window to the absolute bottom, use
AddToFunc lower-to-bottom
+ I Layer 0 0
+ I Lower
Move [options]
Allows the user to move a window. If called from somewhere in a window or its border,
then that window is moved. If called from the root window, then the user is allowed to
select the target window. Move can be called with various options to either start an
interactive move, specify the position to move, or a direction.
Move without options starts an interactive move. The window may snap to other windows
and screen boundaries, configurable with the SnapAttraction style. Moving a window to
the edge of the screen can be used to drag the window to other pages. (See EdgeScroll,
and the EdgeMoveDelay style for more information.)
Holding down Alt disables snapping and allows one to switch pages without any delay.
Interactive movement can be aborted with the Escape key or any mouse button not set to
place the window. By default mouse button 2 is set to cancel the move operation. To
change this you may use the Mouse command with special context 'P' for Placement.
The window condition PlacedByButton can be used to check if a specific button was
pressed to place the window (see Current command).
If the single argument pointer is given, the top left corner of the window is moved to
the pointer position before starting an interactive move; this is mainly intended for
internal use by modules like FvwmPager.
Move pointer
To move a window in a given direction until it hits another window, icon, or screen
boundary use:
Move shuffle [Warp] [ewmhiwa] [snap type] [layers min max] direction(s)
The direction can be North/N/Up/U, East/E/Right/R, South/S/Down/D, or West/W/Left/L.
The window will move in the given direction until it hits another window or the
EwmhBaseStruts/screen boundary. When a window is at the EwmhBaseStruts/screen
boundary, it will move to the next monitor in the given direction, if it exists. If a
window is outside of the current working area (partly off screen), it will move to the
edge of the working area. Windows will honor the EWMH working area and stop at the
EwmhBaseStruts unless the literal option ewmhiwa is given. If multiple direction(s)
are given, the window will move the directions in the order of the sequence stated.
The literal option Warp will warp the mouse pointer to the window. If the literal
option snap followed by a snap type of windows, icons, or same is given, then the
window will only stop if it hits another window, icon, or the same type. If the
literal option layers followed by a min layer and max layer is given, then only
windows on the layers between min and max layers will stop the window. For example:
# Shuffle the window Right.
Move shuffle Right
# Shuffle Up, only consider windows on Layer 3.
Move shuffle layers 3 3 Up
# Shuffle Left then Up
Move shuffle Left Up
# Shuffle Up then Left (may not be same position as above)
Move shuffle Up Left
Move can be used to moved a window to a specified position:
Move [screen S] [w | m]x[p | w] [w | m]y[p | w] [Warp] [ewmhiwa]
This will move the window to the x and y position (see below). By default, the EWMH
working area is honoured. If he trailing option ewmhiwa is given, then the window
position will ignore the working area (such as ignoring any values set via
EwmhBaseStruts). If the option Warp is given then the pointer is warped to the window.
If the literal option screen followed by a RandR screen name S is specified, the
coordinates are interpreted as relative to the given screen. The width and height of
the screen are used for the calculations instead of the display dimensions. The screen
is interpreted as in the MoveToScreen command.
The positional arguments x and y 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, while a trailing 'w' means percent of the window
width/height. 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.
For advanced uses, the arguments x and y can be used multiple times, but without the
prefix 'm' or 'w'. (See complex examples below).
Simple Examples:
# Interactive move
Mouse 1 T A Move
# Move window to 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 so top left corner is 10 pixels
# off the top left screen edge
Move +-10 +-10
# 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
# Move window to center of screen (50% of screen
# position minus 50% of widow size).
Move 50-50w 50-50w
See also the AnimatedMove command.
MoveToDesk [prev | arg1 [arg2] [min max]]
Moves the selected window to another desktop. The arguments are the same as for the
GotoDesk command. Without any arguments, the window is moved to the current desk.
MoveToDesk is a replacement for the obsolete WindowsDesk command, which can no longer
be used.
MoveThreshold [pixels]
When the user presses a mouse button upon an object fvwm waits to see if the action is
a click or a drag. If the mouse moves by more than pixels pixels it is assumed to be a
drag.
Previous versions of fvwm hardwired pixels to 3, which is now the default value. If
pixels is negative or omitted the default value (which might be increased when
16000x9000 pixel displays become affordable) is restored.
MoveToPage [options] [x[p | w] y[p | w]] | [prev]
Moves the selected window to another page (x,y). The upper left page is (0,0), the
upper right is (M,0), where M is one less than the current number of horizontal pages
specified in the DesktopSize command. Similarly the lower left page is (0,N), and the
lower right page is (M,N). Negative page numbers refer to pages from the
rightmost/lowest page. If x and y are not given, the window is moved to the current
page (a window that has the focus but is off-screen can be retrieved with this).
Moving windows to a page relative to the current page can be achieved by adding a
trailing 'p' after any or both numerical arguments. To move the window relative to its
current location, add a trailing 'w'. To move a window to the previous page use prev
as the single argument.
Windows are usually not moved beyond desk boundaries.
Possible options are wrapx and wrapy to wrap around the x or y coordinate when the
window is moved beyond the border of the desktop. For example, with wrapx, when the
window moves past the right edge of the desktop, it reappears on the left edge. The
options nodesklimitx and nodesklimity allow moving windows beyond the desk boundaries
in x and y direction (disabling the wrapx and wrapy options).
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, wrap at desk boundaries
MoveToPage wrapx wrapy +2p -1p
MoveToScreen [screen]
Moves the selected window to another screen. The screen argument must be a valid RandR
name.
OpaqueMoveSize [percentage]
Tells fvwm the maximum size window with which opaque window movement should be used.
The percentage is percent of the total screen area (may be greater than 100). With
OpaqueMoveSize 0
all windows are moved using the traditional rubber-band outline. With
OpaqueMoveSize unlimited
or if a negative percentage is given all windows are moved as solid windows. The
default is
OpaqueMoveSize 5
which allows small windows to be moved in an opaque manner but large windows are moved
as rubber-bands. If percentage is omitted or invalid the default value is set. To
resize windows in an opaque manner you can use the ResizeOpaque style. See the Style
command.
PlaceAgain [Anim] [Icon]
Causes the current window’s position to be re-computed using the initial window
placement logic. The window is moved to where it would have been if it were a new
window that had just appeared. Most useful with Smart or Clever (ReallySmart)
placement. With the optional argument Anim an animated move is used to place the
window in its new position. With the additional option Icon, the icon is placed again
instead.
Raise
Allows the user to raise a window. Note that this raises a window only in its layer.
To bring a window to the absolute top, use
AddToFunc raise-to-top
+ I Layer 0 ontop
+ I Raise
where ontop is the highest layer used in your setup.
RaiseLower
Alternately raises and lowers a window. The window is raised if it is obscured by any
window (except for its own transients when RaiseTransient style is used; see the Style
command) otherwise it is lowered.
Resize [[frame] [direction dir] [warptoborder automatic] [fixeddirection] width[p | c | wa
| da] height[p | c]]
Allows for resizing a window. If called from somewhere in a window or its border, then
that window is resized. If called from the root window then the user is allowed to
select the target window.
Resize without options starts an interactive resize.
If the EdgeResizeDelay style is set or the Alt key is held down, the window can be
resized across the edge of the screen.
The operation can be aborted with the Escape key 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. With the suffix 'wa' the value is a
percentage of the width or height size of the EWMH working area, and with the suffix
'da' it is a percentage of the width or height of the EWMH dynamic working area. So
you can say
Resize 80c 24c
to make a terminal window just big enough for 80x24 characters.
If the width or height is prefixed with the letter 'w' the size is not taken as an
absolute value but added to the current size of the window. Example:
# Enlarge window by one line
Resize keep w+1c
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. The new size is the size of the client window, thus
Resize 100 100
may make the window bigger than the screen. To base the new size on the size of the
whole fvwm window, add the frame option after the command. The options fixeddirection,
direction and warptoborder are only used in interactive move operations. With
fixeddirection the same border is moved even if the pointer moves past the opposite
border. The direction option must be followed by a direction name such as "NorthWest",
"South" or "East" (you get the idea). Resizing is started immediately, even if the
pointer is not on a border. If the special option automatic is given as a direction
argument, then the direction to resize is calculated based on the position of the
pointer in the window. If the pointer is in the middle of the window, then no
direction is calculated. The warptoborder option can be used to warp the pointer to
the direction indicated. As with the automatic option for direction, the border to
warp to is calculated based on the pointer’s proximity to a given border. Also, if
resizing is started by clicking on the window border, the pointer is warped to the
outer edge of the border.
AddToFunc ResizeSE I Resize Direction SE
Mouse 3 A M ResizeSE
Resize [bottomright | br x y]
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. Actually, any of the options accepted by the Move
command can be used.
ResizeMaximize [resize-arguments]
Combines the effects of Resize and Maximize in a single command. When used on a
maximized window, the window is resized and is still in the maximized state
afterwards. When used on an unmaximized window, the window is resized and put into the
maximized state afterwards. This is useful if the user wants to resize the window
temporarily and then return to the original geometry. The resize-arguments are the
same as for the Resize command.
ResizeMove resize-arguments move-arguments
This command does the same as the Resize and Move commands, but in a single call which
is less visually disturbing. The resize-arguments are exactly the same arguments as
for the Resize command and the move-arguments are exactly the same arguments as for
the Move command except the pointer option which is not supported by the ResizeMove
command.
Examples:
# Move window to top left corner and cover
# most of the screen
ResizeMove -10p -20p 0 0
# Grow the focused window towards the top of screen
Current Resize keep w+$[w.y]p keep 0
Note: Fvwm may not be able to parse the command properly if the option bottomright of
the Resize command is used.
ResizeMoveMaximize resize-arguments move-arguments
Combines the effects of ResizeMove and Maximize in a single command. When used on a
maximized window, the window is resized and moved and is still in the maximized state
afterwards. When used on an unmaximized window, the window is resized and put into the
maximized state afterwards. This is useful if the user wants to resize the window
temporarily and then return to the original geometry. The resize-arguments and
move-arguments are the same as for the ResizeMove command.
RestackTransients
This command regroups the transients of a window close to it in the stacking order as
if the window had just been lowered and then raised. The position of the window itself
is not altered. Only windows that use either the RaiseTransient or LowerTransient
style are affected at all. When RestackTransients is used on a transient window with
the StackTransientParent style set, it is redirected to the parent window.
SetAnimation milliseconds-delay [fractions-to-move-list]
Sets the time between frames and the list of fractional offsets to customize the
animated moves of the AnimatedMove command and the animation of menus (if the menu
style is set to animated; see MenuStyle command). If the fractions-to-move-list is
omitted, only the time between frames is altered. The fractions-to-move-list specifies
how far the window should be offset at each successive frame as a fraction of the
difference between the starting location and the ending location. e.g.:
SetAnimation 10 -.01 0 .01 .03 .08 .18 .3 \
.45 .6 .75 .85 .90 .94 .97 .99 1.0
Sets the delay between frames to 10 milliseconds, and sets the positions of the 16
frames of the animation motion. Negative values are allowed, and in particular can be
used to make the motion appear more cartoonish, by briefly moving slightly in the
opposite direction of the main motion. The above settings are the default.
SnapAttraction [proximity [behaviour] [Screen]]
The SnapAttraction command is obsolete. It has been replaced by the Style command
option SnapAttraction.
SnapGrid [x-grid-size y-grid-size]
The SnapGrid command is obsolete. It has been replaced by the Style command option
SnapGrid.
WindowsDesk arg1 [arg2]
Moves the selected window to another desktop.
This command has been removed and must be replaced by MoveToDesk, the arguments for
which are the same as for the GotoDesk command.
+
*Important*
You cannot simply change the name of the command: the syntax has changed. If you used:
WindowsDesk n
to move a window to desk n, you have to change it to:
MoveToDesk 0 n
XorPixmap [pixmap]
Selects the pixmap with which bits are xor’ed when doing rubber-band window moving or
resizing. This has a better chance of making the rubber-band visible if XorValue does
not give good results. An example pixmap resize.rainbow.xpm is provided with the icon
distribution. To turn the XorPixmap off again use the XorValue command or omit the
pixmap argument.
XorValue [number]
Changes the value with which bits are xor’ed when doing rubber-band window moving or
resizing. Valid values range from zero to the maximum value of an unsigned long
integer on your system. Setting this value is a trial-and-error process. The default
value 0 tries to find a value that gives a good contrast to black and white. The
default value is used if the given number is omitted or invalid.
Focus & Mouse Movement
CursorMove horizontal[p] vertical[p]
Moves the mouse pointer by horizontal pages in the X direction and vertical pages in
the Y direction. Either or both entries may be negative. CursorMove can only move the
mouse cursor to a relative position. To move the mouse cursor to an absolute position,
see WarpToWindow. Both horizontal and vertical values are expressed in percent of
pages, so
CursorMove 100 100
means to move down and right by one full page.
CursorMove 50 25
means to move right half a page and down a quarter of a page. Alternatively, the
distance can be specified in pixels by appending a 'p' to the horizontal and/or
vertical specification. For example
CursorMove -10p -10p
means move ten pixels up and ten pixels left. The CursorMove function should not be
called from pop-up menus.
FlipFocus [NoWarp]
Executes a Focus command as if the user had used the pointer to select the window.
This command alters the order of the WindowList in the same way as clicking in a
window to focus, i.e. the target window is removed from the WindowList and placed at
the start. This command is recommended for use with the Direction command and in the
function invoked from WindowList.
Focus [NoWarp]
Sets the keyboard focus to the selected window. If the NoWarp argument is given, this
is all it does. Otherwise it also moves the viewport or window as needed to make the
selected window visible. This command does not automatically raise the window. Does
not warp the pointer into the selected window (see WarpToWindow function). Does not
de-iconify. This command does not alter the order of the WindowList, it rotates the
WindowList around so that the target window is at the start.
When the NoWarp argument is given, Focus cannot transfer the keyboard focus to windows
on other desks.
To raise and/or warp a pointer to a window together with Focus or FlipFocus, use a
function, like:
AddToFunc SelectWindow
+ I Focus
+ I Iconify false
+ I Raise
+ I WarpToWindow 50 8p
WarpToWindow [!raise | raise] x[p] y[p]
Warps the cursor to the associated window and raises it (unless the option !raise is
present). The parameters x and y default to percentage of window down and in from the
upper left hand corner (or number of pixels down and in if 'p' is appended to the
numbers). If a number is negative the opposite edge is used and the direction
reversed. This command works also with windows that are not managed by fvwm. In this
case fvwm does not bring the window onto the screen if it is not visible. For example
it is possible to warp the pointer to the center of the root window on screen 1:
WindowId root 1 WarpToWindow 50 50
Window State
Close
If the window accepts the delete window protocol a message is sent to the window
asking it to gracefully remove itself. If the window does not understand the delete
window protocol then the window is destroyed as with the Destroy command. Note: if the
window accepts the delete window protocol but does not close itself in response, the
window is not deleted.
Delete
Sends a message to a window asking that it remove itself, frequently causing the
application to exit.
Destroy
Destroys an application window, which usually causes the application to crash and
burn.
Iconify [bool]
Iconifies a window if it is not already iconified or de-iconifies it if it is already
iconified. The optional argument bool is a boolean argument. "True" means only
iconification is allowed, while "False" forces de-iconification. Using "toggle"
switches between iconified and de-iconified states.
There are a number of Style options which influence the appearance and behavior of
icons (e.g. StickyIcon, NoIcon).
For backward compatibility, the optional argument may also be a positive number
instead of "True", or a negative number instead of "False". Note that this syntax is
obsolete, and will be removed in the future.
Maximize [flags] [bool | forget] [horizontal[p]] [vertical[p]]
Without its optional arguments (or if the bool bit has the value "toggle") Maximize
causes the window to alternately switch from a full-screen size to its normal size. To
force a window into maximized (normal) state you can use a "True" or "False" value for
the bool argument.
With just the parameter "forget" a maximized window reverts back into normal state but
keeps its current maximized size. This can be useful in conjunction with the commands
ResizeMaximize and ResizeMoveMaximize. If the window is not maximized, nothing
happens.
With the optional arguments horizontal and vertical, which are expressed as percentage
of a full screen, the user can control the new size of the window. An optional suffix
'p' can be used to indicate pixels instead of percents of the screen size. If
horizontal is greater than 0 then the horizontal dimension of the window is set to
horizontal*screen_width/100. If the value is smaller than 0 the size is subtracted
from the screen width, i.e. -25 is the same as 75. If horizontal is "grow", it is
maximized to current available space until finding any obstacle. The vertical resizing
is similar. If both horizontal and vertical values are "grow", it expands vertically
first, then horizontally to find space. Instead of the horizontal "grow" argument,
"growleft" or "growright" can be used respectively "growup" and "growdown". The
optional flags argument is a space separated list containing the following key words:
fullscreen, ewmhiwa, growonwindowlayer, growonlayers and screen. fullscreen causes the
window to become fullscreened if the appropriate EWMH hint is set. ewmhiwa causes fvwm
to ignore the EWMH working area. growonwindowlayer causes the various grow methods to
ignore windows with a layer other than the current layer of the window which is
maximized. The growonlayers option must have two integer arguments. The first one is
the minimum layer and the second one the maximum layer to use. Windows that are
outside of this range of layers are ignored by the grow methods. A negative value as
the first or second argument means to assume no minimum or maximum layer. screen must
have an argument which specifies the screen on which to operate.
Here are some examples. The following adds a title-bar button to switch a window to
the full vertical size of the screen:
Mouse 0 4 A Maximize 0 100
The following causes windows to be stretched to the full width:
Mouse 0 4 A Maximize 100 0
This makes a window that is half the screen size in each direction:
Mouse 0 4 A Maximize 50 50
To expand a window horizontally until any other window is found:
Mouse 0 4 A Maximize 0 grow
To expand a window until any other window on the same or a higher layer is hit.
Mouse 0 4 A Maximize growonlayers $[w.layer] -1 grow grow
To expand a window but leave the lower 60 pixels of the screen unoccupied:
Mouse 0 4 A Maximize 100 -60p
Values larger than 100 can be used with caution.
Refresh
Causes all windows on the screen to redraw themselves. All pending updates of all
windows' styles and looks are applied immediately. E.g. if Style or TitleStyle
commands were issued inside a fvwm function.
RefreshWindow
Causes the chosen window to redraw itself. All pending updates of the window’s style
and look are applied immediately. E.g. if Style or TitleStyle commands were issued
inside a fvwm function.
Stick [bool]
If the bool argument is empty or "toggle", the Stick command makes a window sticky if
it is not already sticky, or non-sticky if it is already sticky. To make a window
sticky regardless of its current state the bool argument must be "True". To make it
non-sticky use "False".
StickAcrossPages [bool]
Works like Stick but only sticks a window across pages, not across desks.
StickAcrossDesks [bool]
Works like Stick but only sticks a window across desks, not across pages.
WindowShade [bool] | [[ShadeAgain] direction]
Toggles the window shade feature for titled windows. Windows in the shaded state only
display a title-bar. If bool is not given or "toggle", the window shade state is
toggled. If bool is "True", the window is forced to the shaded state. If bool is
"False", then the window is forced to the non-shaded state. To force shading in a
certain direction, the direction argument can be used. Any of the strings "North",
"South", "West", "East", "NorthWest", "NorthEast", "SouthWest", "SouthEast" or "Last"
can be given. The direction can be abbreviated with the usual one or two letters "N",
"NW", etc. Using a direction on a window that was already shaded unshades the window.
To shade it in a different direction, use the ShadeAgain option. The direction Last
shades the window in the direction it last was shaded. If the window has never been
shaded before it is shaded as if no direction had been given. Windows without titles
can be shaded too. Please refer also to the options WindowShadeSteps,
WindowShadeShrinks, WindowShadeScrolls, WindowShadeLazy, WindowShadeAlwaysLazy and
WindowShadeBusy options of the Style command. Examples:
Style * WindowShadeShrinks, WindowShadeSteps 20, \
WindowShadeLazy
Mouse 1 - S WindowShade North
Mouse 1 [ S WindowShade West
Mouse 1 ] S WindowShade E
Mouse 1 _ S WindowShade S
Note: When a window that has been shaded with a direction argument changes the
direction of the window title (see TitleAtTop Style option), the shading direction
does not change. This may look very strange. Windows that were shaded without a
direction argument stay shaded in the direction of the title bar.
For backward compatibility, the optional argument may also be 1 to signify "on", and 2
to signify "off". Note that this syntax is obsolete, and will be removed in the
future.
WindowShadeAnimate [steps [p]]
This command is obsolete. Please use the WindowShadeSteps option of the Style command
instead.
Mouse & Key Bindings
IgnoreModifiers [Modifiers]
Tells fvwm which modifiers to ignore when matching Mouse or Key bindings.
IgnoreModifiers affects the ClickToFocus style too. This command belongs into your
config. If you issue it when your fvwm session is already up and running the results
are unpredictable. The should appear before any applications or modules are started in
your config file (e.g. with the Exec command).
Modifiers has the same syntax as in the Mouse or Key bindings, with the addition of
'L' meaning the caps lock key. The default is "L". Modifiers can be omitted, meaning
no modifiers are ignored. This command comes in handy if the num-lock and scroll-lock
keys interfere with your shortcuts. With XFree86 '2' usually is the num-lock modifier
and '5' refers to the scroll-lock key. To turn all these pesky modifiers off you can
use this command:
IgnoreModifiers L25
If the Modifiers argument is the string "default", fvwm reverts back to the default
value "L".
Important This command creates a lot of extra network traffic, depending on your CPU,
network connection, the number of Key or Mouse commands in your configuration file and
the number of modifiers you want to ignore. If you do not have a lightning fast
machine or very few bindings you should not ignore more than two modifiers. I.e. do
not ignore
if you have no problem with it. In the FAQ you can find a better solution of this
problem.
EdgeCommand [screen RANDRNAME] [direction [Function]]
Binds a specified fvwm command Function to an edge of the screen. Direction may be one
of "North", "Top", "West", "Left", "South", "Bottom", "Right" and "East". If Function
is omitted the binding for this edge is removed. If EdgeCommand is called without any
arguments all edge bindings are removed. If the literal option screen followed by a
RandR screen name RANDRNAME is given, the command is set only for the given monitor.
Function is executed when the mouse pointer enters the invisible pan frames that
surround the visible screen. The binding works only if EdgeThickness is set to a value
greater than 0. If a function is bound to an edge, scrolling specified by EdgeScroll
is disabled for this edge. It is possible to bind a function only to some edges and
use the other edges for scrolling. This command is intended to raise or lower certain
windows when the mouse pointer enters an edge. FvwmAuto can be used get a delay when
raising or lowering windows. The following example raises FvwmButtons if the mouse
pointer enters the top edge of the screen.
# Disable EdgeScrolling but make it possible
# to move windows over the screen edge
EdgeResistance -1
Style * EdgeMoveDelay 250
Style * EdgeMoveResistance 20
# Set thickness of the edge of the screen to 1
EdgeThickness 1
# Give focus to FvwmButtons if the mouse
# hits top edge
EdgeCommand Top Next (FvwmButtons) Focus
# Make sure the Next command matches the window
Style FvwmButtons CirculateHit
Module FvwmButtons
Module FvwmAuto 100 "Silent AutoRaiseFunction" \
"Silent AutoLowerFunction"
# If any window except FvwmButtons has
# focus when calling this function
# FvwmButtons are lowered
DestroyFunc AutoLowerFunction
AddToFunc AutoLowerFunction
+ I Current (!FvwmButtons) All (FvwmButtons) Lower
# If FvwmButtons has focus when calling this function raise it
DestroyFunc AutoRaiseFunction
AddToFunc AutoRaiseFunction
+ I Current (FvwmButtons) Raise
Normally, the invisible pan frames are only on the screen edges that border virtual
pages. If a screen edge has a command bound to it, the pan frame is always created on
that edge.
EdgeLeaveCommand [screen RANDRNAME] [direction [Function]]
Binds a specified fvwm command Function to an edge of the screen. Direction may be one
of "North", "Top", "West", "Left", "South", "Bottom", "Right" and "East". If Function
is omitted the binding for this edge is removed. If EdgeLeaveCommand is called without
any arguments all edge bindings are removed. If the literal option screen followed by
a RandR screen name RANDRNAME is given, the command is set only for the given monitor.
Function is executed when the mouse pointer leaves the invisible pan frames that
surround the visible screen. The binding works only if EdgeThickness is set to a value
greater than 0. If a function is bound to an edge, scrolling specified by EdgeScroll
is disabled for this edge. It is possible to bind a function only to some edges and
use the other edges for scrolling. This command is intended to raise or lower certain
windows when the mouse pointer leaves an edge. FvwmAuto can be used get a delay when
raising or lowering windows. See example for EdgeCommand
Normally, the invisible pan frames are only on the screen edges that border virtual
pages. If a screen edge has a command bound to it, the pan frame is always created on
that edge.
Key [(window)] Keyname Context Modifiers Function
Binds a keyboard key to a specified fvwm command, or removes the binding if Function
is '-'. The syntax is the same as for a Mouse binding except that the mouse button
number is replaced with a Keyname. Normally, the key binding is activated when the key
is pressed. Keyname is a standard X11 key name as defined in
/usr/include/X11/keysymdef.h, (without the XK_ prefix), or the keysym database
/usr/X11R6/lib/X11/XKeysymDB. Only key names that are generated with no modifier keys
or with just the
key held are guaranteed to work. The Context and Modifiers fields are defined as in
the Mouse binding. However, when you press a key the context window is the window that
has the keyboard focus. That is not necessarily the same as the window the pointer is
over (with SloppyFocus or ClickToFocus). Note that key bindings with the 'R' (root
window) context do not work properly with SloppyFocus and ClickToFocus. If you
encounter problems, use the PointerKey command instead. If you want to bind keys to a
window with SloppyFocus or ClickToFocus that are supposed to work when the pointer is
not over the window, fvwm assumes the pointer is over the client window (i.e. you have
to use the 'W' context).
The special context 'M' for menus can be used to (re)define the menu controls. It be
used alone or together with 'T', 'S', 'I', '[', ']', '-' and '_'. See the Menu
Bindings section for details.
The following example binds the built-in window list to pop up when
is hit, no matter where the mouse pointer is:
Key F11 A SCM WindowList
Binding a key to a title-bar button causes that button to appear. Please refer to the
Mouse command for details.
Mouse [(window)] Button Context Modifiers Function
Defines a mouse binding, or removes the binding if Function is '-'. Button is the
mouse button number. If Button is zero then any button performs the specified
function. Note that only mouse buttons 1 to 5 are fully supported by X11. Any number
above this works only partially. Complex functions can not be used with these buttons
and neither any operation that requires dragging the pointer with the button held.
This is due to limitations of X11. By default, the highest allowed button number is 9.
Context describes where the binding applies. Valid contexts are 'R' for the root
window, 'W' for an application window, 'D' for a desktop application (as kdesktop or
Nautilus desktop), 'T' for a window title-bar, 'S' for a window side, top, or bottom
bar, '[', ']', '-' and '_' for the left, right, top or bottom side only, 'F' for a
window frame (the corners), '<', '^', '>' and 'v' for the top left, top right, bottom
right or bottom left corner, 'I' for an icon window, or '0' through '9' for title-bar
buttons, or any combination of these letters. 'A' is for any context. For instance, a
context of "FST" applies when the mouse is anywhere in a window’s border except the
title-bar buttons. Only 'S' and 'W' are valid for an undecorated window.
The special context 'M' for menus can be used to (re)define the menu controls. It can
be used alone or together with 'T', 'S', 'I', '[', ']', '-' and '_'. See the Menu
Bindings section for details.
The special context 'P' controls what buttons that can be used to place a window. When
using this context no modifiers are allowed (Modifiers must be N), no window is
allowed, and the Function must be one of PlaceWindow, PlaceWindowDrag,
PlaceWindowInteractive, CancelPlacement, CancelPlacementDrag,
CancelPlacementInteractive or -.
PlaceWindow makes Button usable for window placement, both for interactive and drag
move. CancelPlacement does the inverse. That is makes Button to cancel move for both
interactive and drag move. It may however not override how new windows are resized
after being placed. This is controlled by the Emulate command. Also a window being
dragged can always be placed by releasing the button hold while dragging, regardless
of if it is set to PlaceWindow or not.
PlaceWindowDrag and PlaceWindowInteractive/CancelPlacementDrag and
CancelPlacementInteractive work as PlaceWindow/CancelPlacement with the exception that
they only affect either windows dragged / placed interactively.
- is equivalent to CancelPlacement.
The following example makes all buttons but button 3 usable for interactive placement
and makes drag moves started by other buttons than one cancel if button 1 is pressed
before finishing the move:
Mouse 0 P N PlaceWindow
Mouse 3 P N CancelPlacement
Mouse 1 P N CancelPlacementDrag
By default, the binding applies to all windows. You can specify that a binding only
applies to specific windows by specifying the window name in brackets. The window name
is a wildcard pattern specifying the class, resource or name of the window you want
the binding to apply to.
The following example shows how the same key-binding can be used to perform different
functions depending on the window that is focused:
Key (rxvt) V A C Echo ctrl-V-in-RXVT
Key (*term) V A C Echo ctrl-V-in-Term
Key (*vim) V A C --
Key V A C Echo ctrl-V-elsewhere
A '--' action indicates that the event should be propagated to the specified window to
handle. This is only a valid action for window-specific bindings.
This example shows how to display the WindowList when Button 3 is pressed on an rxvt
window:
Mouse (rxvt) 3 A A WindowList
Note that Fvwm actually intercepts all events for a window-specific binding and (if
the focused window doesn’t match any of the bindings) sends a synthetic copy of the
event to the window. This should be transparent to most applications, however (for
security reasons) some programs ignore these synthetic events by default - xterm is
one of them. To enable handling of these events, add the following line to your
~/.Xdefaults file:
XTerm*allowSendEvents: true
Modifiers is any combination of 'N' for no modifiers, 'C' for control, 'S' for shift,
'M' for Meta, 'L' for Caps-Lock or 'A' for any modifier. For example, a modifier of
"SM" applies when both the
and
keys are down. X11 modifiers mod1 through mod5 are represented as the digits '1'
through '5'. The modifier 'L' is ignored by default. To turn it on, use the
IgnoreModifiers command.
Function is one of fvwm’s commands.
The title-bar buttons are numbered with odd numbered buttons on the left side of the
title-bar and even numbers on the right. Smaller-numbered buttons are displayed toward
the outside of the window while larger-numbered buttons appear toward the middle of
the window (0 is short for 10). In summary, the buttons are numbered:
1 3 5 7 9 0 8 6 4 2
The highest odd numbered button which has an action bound to it determines the number
of buttons drawn on the left side of the title bar. The highest even number determines
the number of right side buttons which are drawn. Actions can be bound to either mouse
buttons or keyboard keys.
PointerKey [(window)] Keyname Context Modifiers Function
This command works exactly like the Key command. The only difference is that the
binding operates on the window under the pointer. Normal key bindings operate on the
focused window instead. The PointerKey command can for example be used to bind keys to
the root window if you are using SloppyFocus or ClickToFocus. However, some
applications (xterm is one example) are unable to handle this key anymore, even if the
pointer is over the xterm window. It is recommended to use the PointerKey command only
for key combinations that are not needed in any application window.
Example:
Style * SloppyFocus
PointerKey f1 a m Menu MainMenu
Controlling the Virtual Desktop
Desk arg1 [arg2] [min max]
This command has been renamed. Please see GotoDesk command.
DesktopName desk name
Defines the name of the desktop number desk to name. This name is used in the
WindowList command and in the FvwmPager where it override the Label configuration
option. Moreover, if consecutive names starting from desktop 0 are defined, then these
names can be used by any EWMH compliant application (as a pager).
DesktopConfiguration global | per-monitor | shared
This command controls the behaviour of how desktops should be managed by FVWM. By
default, for all screens detected by FVWM through RandR support, the option of global
means that all windows on the same desk across monitors is treated as one — hence,
when a change of desktop/page happens, the same change occurs across all monitors.
With per-monitor , each RandR monitor has a separate copy of desktops, and hence
function independently of one another when switching desks/pages.
When shared is set, the desktops are shared amongst all monitors. So for example, with
the following number of desktops defined with two monitors ([] is monitor1, and <> is
monitor2):
[0] 1 2 <3> 4
Moving between desktops would still honor the monitor the desktop is being requested
on. If monitor1 wanted to switch to desktop 3, then that desktop is exchanged with
monitor2 such that the following showed the active desktop on both monitors:
<0> 1 2 [3] 4
This concept is similar to how spectrwm or xmonad handles desktops.
Note: these each DesktopConfiguration mode can be changed on-the-fly.
DesktopSize Horizontalx_Vertical_
Defines the virtual desktop size in units of the physical screen size.
EdgeResistance delayEdgeResistance scrolling moving [screen-scrolling]
Tells how hard it should be to change the desktop viewport by moving the mouse over
the edge of the screen. The parameter tells how many milliseconds the pointer must
spend on the screen edge before fvwm moves the viewport. This is intended for people
who use
EdgeScroll 100 100
but find themselves accidentally flipping pages when they do not want to. If -1 is
given as the delay, scrolling is disabled completely.
The second form of invocation with two or three arguments is obsolete and should be
replaced with the following three commands as needed:
EdgeResistance scrolling
Style * EdgeMoveDelay scrolling
Style * EdgeMoveResistance moving
or
Style * EdgeMoveResistance moving screen-scrolling
Fvwm does this substitution automatically and prints a warning.
EdgeScroll horizontal[p] vertical[p] [wrap | wrapx | wrapy]
Specifies the percentage of a page to scroll when the cursor hits the edge of a page.
A trailing 'p' changes the interpretation to mean pixels. If you do not want any
paging or scrolling when you hit the edge of a page include
EdgeScroll 0 0
in your config file, or possibly better, set the EdgeThickness to zero. See the
EdgeThickness command. If you want whole pages, use
EdgeScroll 100 100
Both horizontal and vertical should be positive numbers.
If the horizontal and vertical percentages are multiplied by 1000 or one of the
keywords wrap, wrapx and wrapy is given then scrolling wraps around at the edge of the
desktop. If
EdgeScroll 100000 100000
is used fvwm scrolls by whole pages, wrapping around at the edge of the desktop.
EdgeThickness 0 | 1 | 2
This is the width or height of the invisible window that fvwm creates on the edges of
the screen that are used for the edge scrolling feature.
In order to enable page scrolling via the mouse, four windows called the "pan frames"
are placed at the very edge of the screen. This is how fvwm detects the mouse’s
presence at the window edge. Because of the way this works, they need to be at the top
of the stack and eat mouse events, so if you have any kind of error along the lines
of: "mouse clicks at the edge of the screen do the wrong thing" you’re having trouble
with the pan frames and (assuming you do not use the mouse to flip between pages)
should set the EdgeThickness to 0.
A value of 0 completely disables mouse edge scrolling, even while dragging a window. 1
gives the smallest pan frames, which seem to work best except on some servers.
2 is the default.
Pan frames of 1 or 2 pixels can sometimes be confusing, for example, if you drag a
window over the edge of the screen, so that it straddles a pan frame, clicks on the
window, near the edge of the screen are treated as clicks on the root window.
EwmhBaseStruts screen RANDRNAME left right top bottom
Where left, right, top and bottom are positive or null integers which define bands at
the edge of the screen. If screen is given, followed by the RANDRNAME of a given
display, then the EwmhBaseStruts are defined for just RANDRNAME. left defines a band
on the left of your screen of width left, right defines a band on the right of your
screen of width right, top defines a band on the top of your screen of height top and
bottom defines a band on the bottom of your screen of height bottom. The unit is the
pixel and the default is 0 0 0 0. These areas define additional reserved space to the
reserved space defined by some ewmh compliant applications. This is used to compute
the Working Area. See the Extended Window Manager Hints section for a definition of
the Working Area.
EwmhNumberOfDesktops num [max]
This command is useful only for an ewmh compliant pager or taskbar (as kpager or
kicker taskbar) and not for fvwm modules ( FvwmPager or FvwmIconMan). It causes a
compliant application to consider at least num desktops (desktop 0 to desktop num-1).
The optional argument max causes a compliant application to never consider more than
max desktops. If max is 0 (the default) there is no limitation. The actual number of
desktops is determined dynamically. It is at least num, but it can be d if there is a
window on desktop d-1 (or if the current desktop is desktop d-1) and d is less or
equal to max or max is null. Moreover, a compliant pager can ask to change num itself.
This is accepted by fvwm only if this number is less than or equal to max or if max is
null. Note that negative desktops are not supported by the ewmh specification. The
default is 4 0.
GotoDesk [prev | arg1 [arg2] [min max]]
Switches the current viewport to another desktop (workspace, room).
The command takes 1, 2, 3, or 4 arguments. A single argument is interpreted as a
relative desk number. Two arguments are understood as a relative and an absolute desk
number. Three arguments specify a relative desk and the minimum and maximum of the
allowable range. Four arguments specify the relative, absolute, minimum and maximum
values. (Desktop numbers can be negative). If a literal prev is given as the single
argument, the last visited desk number is used.
If arg1 is non zero then the next desktop number is the current desktop number plus
arg1.
If arg1 is zero then the new desktop number is arg2. (If arg2 is not present, then the
command has no effect.)
If min and max are given, the new desktop number is no smaller than min and no bigger
than max. Values out of this range are truncated (if you gave an absolute desk number)
or wrapped around (if you gave a relative desk number).
The syntax is the same as for MoveToDesk, which moves a window to a different desktop.
The number of active desktops is determined dynamically. Only desktops which contain
windows or are currently being displayed are active. Desktop numbers must be between
2147483647 and -2147483648 (is that enough?).
GotoDeskAndPage screen | prev | desk xpage ypage
Switches the current viewport to another desktop and page, similar to the GotoDesk and
GotoPage commands. The new desk is desk and the new page is (xpage,ypage).
GotoPage screen | prev | [options] x[p] y[p]
Moves the desktop viewport to page (x,y). The upper left page is (0,0), the upper
right is (M,0), where M is one less than the current number of horizontal pages
specified in the DesktopSize command. The lower left page is (0,N), and the lower
right page is (M,N), where N is the desktop’s vertical size as specified in the
DesktopSize command. To switch to a page relative to the current one add a trailing
'p' after any or both numerical arguments.
Possible options are wrapx and wrapy to wrap around the x or y coordinate when the
viewport is moved beyond the border of the desktop.
The name of the RandR screen.
To go to the last visited page use prev as the first argument. The GotoPage function
should not be used in a pop-up menu.
Examples:
# Go to page (2,3)
GotoPage 2 3
# Go to lowest and rightmost page
GotoPage -1 -1
# Go to last page visited
GotoPage prev
# Go two pages to the right and one page up
GotoPage +2p -1p
Scroll [screen RANDRNAME] [horizonal[p] vertical[p] | reverse]
Scrolls the virtual desktop’s viewport by horizontal pages in the x-direction and
vertical pages in the y-direction or starts interactive scrolling of the viewport.
Either or both entries may be negative. Both horizontal and vertical values are
expressed in percent of pages, so
Scroll 100 100
means to scroll down and right by one full page.
Scroll 50 25
means to scroll right half a page and down a quarter of a page. The Scroll function
should not be called from pop-up menus. Normally, scrolling stops at the edge of the
desktop.
If the horizontal and vertical percentages are 100 or more and are multiplied by 1000
then scrolling wraps around at the edge of the desktop. If
Scroll 100000 0
is executed over and over fvwm moves to the next desktop page on each execution and
wraps around at the edge of the desktop, so that every page is hit in turn.
If the letter 'p' is appended to each coordinate (horizontal and/or vertical), then
the scroll amount is measured in pixels.
Without arguments or if the option reverse is given interactive scrolling takes place.
The viewport scrolls as the mouse is moved. With the reverse option scrolling is done
in opposite direction of the mouse movement, and without it scrolling in the same
direction as the mouse.
The binding
Mouse 1 A CM Scroll reverse
gives an effect of grabbing and dragging the viewport with button 1 if Control and
Meta is pressed.
If screen is given, followed by the RANDRNAME of a given display, then the specified
screen is scrolled. This is only useful if using per-monitor or shared
DesktopConfiguration and wanting to scroll a monitor other than the current monitor.
Interactive scrolling always scrolls the current monitor.
User Functions and Shell Commands
AddToFunc [name [I | J | M | C | H | D action]]
Begins or adds to a function definition. Here is an example:
AddToFunc Move-or-Raise I Raise
+ M Move
+ D Lower
The function name is "Move-or-Raise", and it could be invoked from a menu or a mouse
binding or key binding:
Mouse 1 TS A Move-or-Raise
The name must not contain embedded whitespace. No guarantees are made whether function
names with embedded whitespace work or not. This behavior may also change in the
future without further notice. The letter before the action tells what kind of action
triggers the command which follows it. 'I' stands for "Immediate", and is executed as
soon as the function is invoked. 'J' is similar to "Immediate" but is delayed until a
button is pressed or released or the pointer is moved, or the function completes. It
is always executed before the other function actions. 'M' stands for "Motion", i.e. if
the user starts moving the mouse. 'C' stands for "Click", i.e., if the user presses
and releases the mouse button. 'H' stands for "Hold", i.e. if the user presses a mouse
button and holds it down for more than ClickTime milliseconds. 'D' stands for
"Double-click". The action 'I' causes an action to be performed on the button-press,
if the function is invoked with prior knowledge of which window to act on.
There is a number of predefined symbols that are replaced by certain values if they
appear on the command line. Please refer to the Command Expansion section for details.
Warning Please read the comments on executing complex functions in the section
Scripting and Complex Functions.
Examples:
If you call
Key F10 R A Function MailFunction xmh "-font fixed"
and "MailFunction" is
AddToFunc MailFunction
+ I Next ($0) Iconify off
+ I Next (AcceptsFocus, $0) Focus
+ I None ($0) Exec exec $0 $1
Then the last line of the function becomes
+ I None (xmh) Exec exec xmh -font fixed
The expansion is performed as the function is executed, so you can use the same
function with all sorts of different arguments. You could use
Key F11 R A Function MailFunction zmail "-bg pink"
in the same config, if you wanted. An example of using "$[w.id]" is:
AddToFunc PrintFunction
+ I Raise
+ I Exec xdpr -id $[w.id]
Note that "$$" is expanded to '$'.
Another example: bind right mouse button within the window button number 6 (this is a
minimize button for the win95 theme) to iconify all windows of the same resource:
AddToFunc FuncIconifySameResource "I" All ($0) Iconify on
Mouse 3 6 A FuncIconifySameResource $[w.resource]
Beep
As might be expected, this makes the terminal beep.
DestroyFunc function
Deletes a function, so that subsequent references to it are no longer valid. You can
use this to change the contents of a function during a fvwm session. The function can
be rebuilt using AddToFunc.
DestroyFunc PrintFunction
Echo string
Prints a message to the debug log file, which requires logging to be enabled. See the
-v option or PrintInfo for more information on both enabling debug logging and the log
file location. Potentially useful for debugging things in your config or getting the
value of variables.
Echo Beginning style definitions...
Echo Current desk $[desk.n].
EchoFuncDefinition function
The EchoFuncDefinition is similar to the Echo command but prints the definition for
the given function to the debug log file. It is useful to find out how fvwm handles
quoting and for debugging functions.
Exec command
Executes command. You should not use an ampersand '&' at the end of the command. You
probably want to use an additional "exec" at the beginning of command. Without that,
the shell that fvwm invokes to run your command stays until the command exits. In
effect, you’ll have twice as many processes running as you need. Note that some shells
are smart enough to avoid this, but it never hurts to include the "exec" anyway.
The following example binds function key
in the root window, with no modifiers, to the exec function. The program rxvt is
started with an assortment of options.
Key F1 R N Exec exec rxvt -fg yellow -bg blue \
-e /bin/tcsh
Note that this function doesn’t wait for command to complete, so things like:
Exec "echo AddToMenu ... > /tmp/file"
Read /tmp/file
do not work reliably (see the PipeRead command).
ExecUseShell [shell]
Makes the Exec command use the specified shell, or the value of the $SHELL environment
variable if no shell is specified, instead of the default Bourne shell (/bin/sh).
ExecUseShell
ExecUseShell /usr/local/bin/tcsh
Function FunctionName
Used to bind a previously defined function to a key or mouse button. The following
example binds mouse button 1 to a function called "Move-or-Raise", whose definition
was provided as an example earlier in this man page. After performing this binding
fvwm executes the "move-or-raise" function whenever button 1 is pressed in a window’s
title-bar.
Mouse 1 T A Function Move-or-Raise
The keyword Function may be omitted if FunctionName does not coincide with an fvwm
command.
Warning: Please read the comments on executing complex functions in the section
Scripting and Complex Functions.
InfoStoreAdd key value
Stores the value at the given key. This is useful to store generic information used in
the lifetime of an fvwm config file. For example storing program preferences for
opening video files.
The purpose of this command is to store internal information to fvwm which can be used
bu fvwm functions, or when opening programs of a certain type. Previous to this
command the only way to do this was via SetEnv but this is discouraged because it
places such information in the environment, which pollutes it and makes the
information global to other processes started by fvwm which may then modify them which
might not be what’s wanted. Hence the point of InfoStoreAdd is to still allow for such
information to be stored, but kept internal to fvwm.
In this way, one can build up as many key/value pairs as needed. Recalling the value
of a given key happens through fvwm’s usual expansion mechanism. See the Command
Expansion section for more details. For example:
InfoStoreAdd teddybearprog xteddy
# Echo the value of teddybearprog
Echo $[infostore.teddybearprog]
Removing an entry from the InfoStore is done with the InfoStoreRemove command.
InfoStoreRemove key
Removes an entry at the given key from the InfoStore. Example:
InfoStoreRemove teddybearprog
Nop
Does nothing. This is used to insert a blank line or separator in a menu. If the menu
item specification is
AddToMenu MyMenu " " Nop
then a blank line is inserted. If it looks like
+ "" Nop
then a separator line is inserted. Can also be used as the double-click action for
Menu or Popup.
PipeRead command [quiet]
Causes fvwm to read commands from the output of the command. This command is executed
by /bin/sh as if you typed it on the command line. If the command consists of more
than one word it must be quoted. Useful for building up dynamic menu entries based on
a directories contents, for example. If the keyword Quiet follows the command no
message is produced if the command is not found.
Example:
AddToMenu HomeDirMenu
PipeRead 'for i in $HOME/*; \
do echo "+ $i Exec xterm -e vi $i"; done'
Note: The PipeRead changes the pointer to a watch cursor by default during execution.
However, some commands, for example xwd, need to take control of the pointer
themselves and do not work. To disable the watch cursor, use the command prior to
PipeRead
BusyCursor Read off
The PipeRead command executes synchronously. If you want to Exec something, but need
the command to run synchronously, you might do something like:
PipeRead 'command 1>&2'
The redirection causes any output from the program to go to stderr instead of being
read as a sequence of commands by fvwm. PipeRead returns 1 if the given command could
be executed or -1 if not (see the section Conditional Commands for the meaning of
return codes).
Read filename [quiet]
Causes fvwm to read commands from the file named filename. If the keyword Quiet
follows the command no message is produced if the file is not found. If the file name
does not begin with a slash ('/'), fvwm looks in the user’s data directory, then the
system data directory. The user’s data directory is by default $HOME/.fvwm. It can be
overridden by exporting FVWM_USERDIR set to any other directory. The Read command
returns 1 if the given file could be read or -1 if not (see the section Conditional
Commands for the meaning of return codes).
SetEnv variable value
Set an environment variable to a new value, similar to the shell’s export or setenv
command. The variable and its value are inherited by processes started directly by
fvwm. This can be especially useful in conjunction with the FvwmM4 module. For
example:
SetEnv height HEIGHT
makes the FvwmM4 set variable HEIGHT usable by processes started by fvwm as the
environment variable $height. If value includes whitespace, you should enclose it in
quotes. If no value is given, the variable is deleted.
Silent command
A number of commands require a window to operate on. If no window was selected when
such a function is invoked the user is asked to select a window. Sometimes this
behavior is unwanted, for example if the function was called by a module and the
window that was selected at first does not exist anymore. You can prevent this by
putting Silent in front of the fvwm command. If a function that needs a window is
called with Silent without a window selected, it simply returns without doing
anything. If Silent is used on a user defined function it affects all function and sub
function calls until the original function exits.
Another usage of Silent is with binding commands Key, PointerKey and Mouse, this
disables error messages.
Silent also disables the error message for non-existent commands. Note: This command
is treated as a prefix to its command. Expansion of the command line is done as if
Silent was not there.
Examples:
Silent Move 0 0
Silent User_defined_function
# do not complain on keyboards without "Help" key
Silent Key Help R A Popup HelpMenu
UnsetEnv [variable]
Unset an environment variable, similar to shell’s export or unsetenv command. The
variable then is removed from the environment array inherited by processes started
directly by fvwm.
Wait window
This command is intended to be used in fvwm functions only. It causes execution of a
function to pause until a new window matching window appears. This can be a window’s
name, class, or resource string. It may contain the wildcards '*' and '?', which are
matched in the usual Unix filename manner. This is particularly useful in the
"InitFunction" if you are trying to start windows on specific desktops:
AddToFunc InitFunction
+ I Exec exec xterm -geometry 80x64+0+0
+ I Wait xterm
+ I GotoDesk 0 2
+ I Exec exec xmh -font fixed -geometry \
507x750+0+0
+ I Wait xmh
+ I GotoDesk 0 0
The above function starts an xterm on the current desk, waits for it to map itself,
then switches to desk 2 and starts an xmh. After the xmh window appears control moves
to desk 0.
Fvwm remains partially functional during a wait, but any input from the modules is
queued up and processed only after the window appears or the command is aborted. For
example, windows can not be focused with FvwmIconMan or FvwmPager during a wait.
You can escape from a Wait pause by pressing Ctrl-Alt-Escape (where Alt is the first
modifier). To redefine this key sequence see the EscapeFunc command.
Status On | Off
Turns status either On or Off. This sends information in JSON format down a named pipe
(set via FVWM_STATUS_PIPE env var) about the current desks and number of windows, etc.
This is meant to provide a fast means of supplying third-party tools information about
what’s happening in Fvwm. For example, the JSON could be manipulated and sent to tools
such as lemonbar, polybar, etc.
The format of the JSON blob looks like this:
{
"version": 1,
"current_screen": "HDMI2",
"screens": {
"HDMI2": {
"current_client": "n6tadam@shuttle: ~",
"desktops": {
"0": {
"number": 0,
"is_urgent": false,
"is_current": true,
"number_of_clients": 5
},
},
},
},
}
These sections repeat for all screens/groups/etc, depending on how many there are of
each.
Conditional Commands
Conditional commands are commands that are only executed if certain conditions are met.
Most conditional commands work on windows, like Next, ThisWindow or All. There is one
conditional command, Test, that works on global conditions unrelated to windows. The
syntax of the conditions is described below. For readability, the list of conditions is
located at the end of this section.
Return Codes
All commands in this section (unless specifically stated for the command) also have a
return code that can be 1 (if the condition was met) or 0 (if the condition was not
met). Some commands may return -1 which means that an error occurred and the return
code is useless. The Break command returns -2. Additionally, the return codes of
commands run in a complex functions are passed to the invoking complex function. The
return code is used by the TestRc command. Please refer to the commands' description
for examples. The return code can also be accessed through the variable $[cond.rc].
Non conditional commands do not modify the return code of the last conditional
command. Important note: return codes are only defined inside functions created with
the AddToFunc command and are not inherited by sub functions. To run a command without
altering the return code, the KeepRc command can be used.
The Ring of Windows
Fvwm stores windows in a ring internally. Think of the focused window as a cursor on
the current position in the ring. The Next command and many other commands search
forwards through the ring for a matching window, and Prev searches backwards. The
windows in the ring are either ordered by creation time (if the
!FPSortWindowlistByFocus, NeverFocus or MouseFocus styles are used) or by the last
time they had the focus.
List of Conditional Commands
All [options] [(conditions)] command
Execute command on all windows meeting the conditions. It returns 1 if any window
matches the condition and 0 otherwise. The execution starts at the top of the
window ring and continues towards the bottom. The options can be any combination
of Reverse and UseStack. If the option Reverse is given the execution order is
reversed. The option UseStack makes All use the stacking order instead of the
window ring when walking through windows. See the Conditions section for a list of
conditions.
This command implies the conditions CirculateHit, CirculateHitIcon and
CirculateHitShaded. They can be turned off by specifying !CirculateHit etc.
explicitly.
Any [(conditions)] command
Performs command if any window which satisfies all conditions exists. The command
is run in the context of the root window. See the Conditions section for a list of
conditions.
Break [levels]
If the break command is used in a function, function execution is terminated
immediately. Further commands of the function are not processed. Normally, all
nested invocations of complex functions are left. An optional integer number
levels may be given to break out of the given number of nested functions and
continue execution of a higher level function. The Break command always has the
return code -2. Example:
AddToFunc PickWindowRaiseAndDeiconify
+ I Pick
+ I TestRc (Error) Break
+ I Raise
+ I Iconify off
Current [(conditions)] command
Performs command on the currently focused window if it satisfies all conditions.
See the Conditions section for a list of conditions.
This command implies the conditions CirculateHit, CirculateHitIcon and
CirculateHitShaded. They can be turned off by specifying !CirculateHit etc.
explicitly.
Direction [FromPointer] direction [(conditions)] command
Performs command (typically Focus) on a window in the given direction which
satisfies all conditions. Normally, the center of the currently focused window or
the context window in which the command was invoked is taken as the starting
point. Lacking such a window, or when the FromPointer option is given, the current
position of the pointer is taken as the starting point. The direction may be one
of "North", "Northeast", "East", "Southeast", "South", "Southwest", "West",
"Northwest" and "Center". Which window Direction selects depends on angle and
distance between the center points of the windows. Closer windows are considered a
better match than those farther away. The Center direction simply selects the
window closest to the starting point. Returns -1 if an invalid direction was
given. See the Conditions section for a list of conditions.
KeepRc command
Runs the command but does not alter the return code of the previous command. Note:
KeepRc is treated as a prefix to its command. Expansion of the command line is
done as if KeepRc was not there.
Next [(conditions)] command
Performs command (typically Focus) on the next window which satisfies all
conditions. If the command is running in a window context, it starts looking for a
matching window from there. Otherwise it starts at the focused window. See
Conditions section for a list of conditions.
None [(conditions)] command
Performs command if no window which satisfies all conditions exists. The command
is run in the context of the root window. Returns 1 if no window matches the
conditions and 0 otherwise. See Conditions section for a list of conditions.
This command implies the conditions CirculateHit, CirculateHitIcon and
CirculateHitShaded. They can be turned off by specifying !CirculateHit etc.
explicitly.
NoWindow command
Performs command, but removes the window context if any. This is not really a
conditional command, but a prefix that may be useful in menu items that should
operate without a window even if such menu is bound to window decorations.
Pick [(conditions)] command
Pick works like Function if invoked in the context of a window. If invoked in the
root window, it first asks the user to pick a window and then executes the command
in the context of that window. This avoids annoying multiple selections with
complex functions. The command is executed only if the given conditions are met.
Returns -1 if no window was selected. See Conditions section for a list of
conditions.
This command implies the conditions CirculateHit, CirculateHitIcon and
CirculateHitShaded. They can be turned off by specifying !CirculateHit etc.
explicitly.
PointerWindow [(conditions)] command
Performs command if the window under the pointer satisfies all conditions. Returns
-1 if there is no window under the pointer. See Conditions section for a list of
conditions.
This command implies the conditions CirculateHit, CirculateHitIcon and
CirculateHitShaded. They can be turned off by specifying !CirculateHit etc.
explicitly.
Prev [(conditions)] command
Performs command (typically Focus) on the previous window which satisfies all
conditions. If the command is running in a window context, it starts looking for a
matching window from there. Otherwise it starts at the focused window. See
Conditions section for a list of conditions.
ScanForWindow [FromPointer] dir1 dir2 [(conditions)] command
Performs command (typically Focus) on a window in the given direction which
satisfies all conditions. Normally, the center of the currently focused window or
the context window in which the command was invoked is taken as the starting
point. Lacking such a window, or when the FromPointer option is given, the current
position of the pointer is taken as the starting point. The direction dir1 may be
one of "North", "NorthEast", "East", "SouthEast", "South", "SouthWest", "West",
and "NorthWest". Which window ScanForWindow selects depends first on the position
along the primary axis given by dir1. If any windows have the exact same
coordinate along the primary axis, the secondary direction is used to order the
windows. The direction dir2 may be one of the same set of values as dir1. If dir2
is not perfectly perpendicular to dir1, ScanForWindow returns a failure. When
using ScanForWindow repeatedly with the same arguments, it is guaranteed that all
windows matching the conditions will eventually be found. If the focus reaches a
limit along the primary axis, it will wrap around to the opposite side. Returns -1
if an invalid direction was given. See Conditions section for a list of
conditions.
Test [(test-conditions)] command
Performs command if all test-conditions are satisfied. The test-conditions are
keywords with possible arguments from the list below and are separated by commas
or whitespace. They include: Version operator x.y.z, EnvIsSet varname, EnvMatch
varname pattern, EdgeHasPointer direction, EdgeIsActive direction, Start, Init,
Restart, Exit, Quit, ToRestart, True, False, F, R, W, X and I. A test-condition
prefixed with "!" is negated.
The Version operator x.y.z test-condition is fulfilled if the logical condition of
the expression is true. Valid operator values are: >=, >, ⇐, <, == and !=.
Example:
Test (Version >= 2.5.11) Echo 2.5.11 or later.
The EnvIsSet varname test-condition is true if the given environment variable is
set. The EnvMatch varname pattern test-condition is true if pattern matches the
given environment or infostore variable value. (See InfoStoreAdd). The pattern may
contain special "*" and "?" chars. The "varname" is coded without the leading
dollar sign ($).
The EdgeHasPointer [direction] test-condition is true if the edge in the given
direction currently contains the pointer. The EdgeIsActive [direction]
test-condition is true if the edge in the given direction currently is active. An
edge is active, and can contain a pointer if either a command is bound to it or
edge scroll is available in that direction. The direction may be one of * Any,
North, Top, Up, West, Left, South, Bottom, Down, Right* and * East. If no
direction is specified Any* is assumed.
The Start test-condition is the same as either Init or Restart. It is only true on
startup or restart prior and during StartFunction execution. The Exit
test-condition is the same as either Quit or ToRestart. It is only valid on
shutdown during ExitFunction function execution.
The True and False test-conditions are unconditionally true and false.
Additionally, if a test-condition name is not recognized, the Error return code is
set and the command is not executed.
The F file, R file, W file, X file and I file test-conditions test for existence
of the given [F]ile (possibly with [R]ead/[W]rite permissions), e[X]ecutable (in
$PATH), or the [I]mage (in ImagePath).
Example:
AddToFunc StartFunction I Test (Init) Exec exec xterm
AddToFunc VerifyVersion
+ I Test (Version 2.5.*) Echo 2.5.x detected
+ I TestRc (NoMatch) \
Test (!Version 2.6.*) Echo Future version
+ I TestRc (NoMatch) \
Echo 2.6.x is detected
Test (F $[FVWM_USERDIR]/local-config) Read local-config
Test (X xterm-utf16) Exec exec xterm-utf16
TestRc [([!]returncode)] command
Performs command if the last conditional command returned the value returncode.
Instead of the numeric values 0 (no match), 1 (match), -1 (error), and -2 (break)
the symbolic names "NoMatch", "Match", "Error" and "Break" can be used. If no
returncode is given, the default 0 is assumed. If the return code is prefixed with
'!', the command is executed if returncode does not match the value returned by
the conditional command. The TestRc command can only be used inside functions. If
the command is another conditional command, the previous return code is replaced
by the new one. Example:
AddToFunc ToggleXterm
+ I All (my_xtermwindow) Close
+ I TestRc (NoMatch) Exec xterm -T my_xtermwindow
ThisWindow [(conditions)] command
ThisWindow executes the specified command in the context of the current operand
window. If there is no operand window (it is invoked in the root window), the
command is ignored. ThisWindow is never interactive. The command is executed only
if the given conditions are met. It returns -1 if used outside a window context.
See Conditions section for a list of conditions.
This command implies the conditions CirculateHit, CirculateHitIcon and
CirculateHitShaded. They can be turned off by specifying "!CirculateHit" etc.
explicitly.
WindowId [id] [(conditions)] | [root [screen]] command
The WindowId command looks for a specific window id and runs the specified command
on it. The second form of syntax retrieves the window id of the root window of the
given screen. If no screen is given, the current screen is assumed. The window
indicated by id may belong to a window not managed by fvwm or even a window on a
different screen. Although most commands can not operate on such windows, there
are some exceptions, for example the WarpToWindow command. Returns -1 if no window
with the given id exists. See Conditions section for a list of conditions.
This command implies the conditions CirculateHit, CirculateHitIcon and
CirculateHitShaded. They can be turned off by specifying !CirculateHit etc.
explicitly.
Examples:
WindowId 0x34567890 Raise
WindowId root 1 WarpToWindow 50 50
WindowId $0 (Silly_Popup) Delete
In the past this command was mostly useful for functions used with the WindowList
command, or for selective processing of FvwmEvent calls (as in the last example),
but currently these handler functions are called within a window context, so this
command is not really needed in these cases. Still it may be useful if, for
example, the window id should be stored in the environment variable for a further
proceeding.
Pick SetEnv BOOKMARKED_WINDOW $[w.id]
WindowId $[BOOKMARKED_WINDOW] WarpToWindow
Conditions
The conditions that may be given as an argument to any conditional command are a list
of keywords separated by commas, enclosed in parentheses. Unless stated otherwise,
conditional commands accept all the conditions listed below. Note that earlier
versions of fvwm required the conditions to be separated by whitespace instead of
commas and enclosed in brackets instead of parentheses (this is still supported for
backward compatibility).
In addition, the conditions may include one or more window names to match to. If more
than one window name is given, all of them must match. The window name, icon name,
class, and resource are considered when attempting to find a match. Each name may
include the wildcards '*' and '?', and may consist of two or more alternatives,
separated by the character '|', which acts as an OR operator. (If OR operators are
used, they must not be separated by spaces from the names.) Each window name can begin
with '!', which prevents command if any of the window name, icon name, class or
resource match. However, '!' must not be applied to individual names in a group
separated by OR operators; it may only be applied to the beginning of the group, and
then it operates on the whole group.
Examples:
Next ("Netscape|konqueror|Mozilla*") WarpToWindow 99 90
This goes to the next web browser window, no matter which of the three named web
browsers is being used.
Next ("Mozilla*", "Bookmark*") WarpToWindow 99 90
This goes to Mozilla’s bookmark manager window, ignoring other Mozilla windows and
other browsers' bookmark windows.
All ("XTerm|rxvt", !console) Iconify
This iconifies all the xterm and rxvt windows on the current page, except that the one
named "console" (with the -name option to xterm) is excluded.
Next (!"FvwmPager|FvwmForm*|FvwmButtons") Raise
Next (!FvwmPager, !FvwmForm*, !FvwmButtons) Raise
These two commands are equivalent; either one raises the next window which is not one
of the named fvwm modules.
Any condition can be negated by using a an exclamation mark ('!') directly in front of
its name.
AcceptsFocus, AnyScreen, CirculateHit, CirculateHitIcon, CirculateHitShaded, Closable,
CurrentDesk, CurrentGlobalPage, CurrentGlobalPageAnyDesk, CurrentPage,
CurrentPageAnyDesk, CurrentScreen, Desk, FixedPosition, FixedSize, Focused,
HasBorders, HasHandles, HasPointer, HasTitle, TitleAtTop, TitleAtBottom, TitleAtLeft,
TitleAtRight, Iconic, Iconifiable, Layer [n], Maximizable, Maximized, Overlapped,
PlacedByButton n, PlacedByButton3, PlacedByFvwm, Raised, Shaded, State n, Sticky,
StickyAcrossDesks, StickyAcrossPages, StickyIcon, StickyAcrossDesksIcon,
StickyAcrossPagesIcon, Transient, Visible.
The AcceptsFocus condition excludes all windows that do not want the input focus (the
application has set the "Input hints" for the window to False) and do not use the
Lenience option of the Style command. Also, all windows using the NeverFocus style are
ignored. Note: !Lenience is equivalent to the deprecated option NoLenience.
With the AnyScreen condition used together with any of the Current... conditions,
windows that do not intersect the screen containing the mouse pointer are considered
for a match too. For example:
# Focus next window on current page,
# regardless of screen
Next (CurrentPage, AnyScreen) Focus
The CirculateHit and CirculateHitIcon options override the CirculateSkip and
CirculateSkipIcon Style attributes for normal or iconic windows. The
CirculateHitShaded option overrides the CirculateSkipShaded Style. All three options
are turned on by default for the Current command. They can be turned off by specifying
!CirculateHit etc. explicitly. Note: Do not confuse these conditions with the style
options of the same name. Specifically,
Style foo CirculateSkip
Next (foo, CirculateHit) ...
is not the same as
Style foo CirculateHit ...
Next (foo)
The prior selects windows with the name foo only in the Next command. In the second
example, these windows are always matched in all conditional commands.
The Closable condition matches only windows that are allowed to be closed.
The CurrentDesk condition matches only windows that are on the current desk.
The CurrentGlobalPage condition matches only windows that are on the current page of
the current desk, regardless of which screen the window is on. This condition
implicitly activates the CurrentDesk condition.
The CurrentGlobalPageAnyDesk condition matches only windows that are on the current
page of any desk, regardless of RandR screen .
The CurrentPage condition matches only windows that are on the current page of the
current desk. This condition implicitly activates the CurrentDesk condition.
The CurrentPageAnyDesk and CurrentScreen conditions matches only windows that are on
the current page of any desk.
The Screen [name] condition matches only windows which are on the specified screen.
The Desk [n] condition matches only windows which are on the specified desk.
The FixedPosition condition excludes all windows that do not have a fixed position,
either set through WM hints or the Style option FixedPosition. Example:
DestroyFunc ToggleFixedGeometry
AddToFunc ToggleFixedGeometry
+ I Pick (FixedPosition) \
WindowStyle VariablePosition, VariableSize
+ I TestRc (NoMatch) WindowStyle FixedPosition, FixedSize
The FixedSize condition excludes all windows that do not have a fixed size, either set
through WM hints or the Style option FixedSize.
The Focused matches on the window that currently has the keyboard focus. This is not
useful for the Current command but can be used with the other conditional commands.
The HasBorders condition excludes all windows that do not have borders.
The HasHandles condition excludes all windows that do not have resize handles.
The HasPointer condition excludes all windows that do not contain the pointer.
The HasTitle condition excludes all windows that do not have a titlebar.
The TitleAtTop, TitleAtBottom, TitleAtLeft, TitleAtRight conditions test for the
titlebar at that window location.
The Iconic condition matches only iconic windows.
The Iconifiable condition matches only windows that are allowed to be iconified.
The Layer [n] condition matches only windows on the specified layer. The optional
argument of the Layer condition defaults to the layer of the focused window. The
negation !Layer switches off the Layer condition.
The Maximizable condition matches only windows that are allowed to be maximized.
The Maximized condition matches only maximized windows.
The Overlapped condition matches only windows that are overlapped by other windows on
the same layer (or unmanaged windows if the option RaiseOverUnmanaged of the BugOpts
command is used). Note that this condition can be slow if you have many windows or if
RaiseOverUnmanaged is used and the connection to the X server is slow.
The PlacedByButton n condition is fulfilled if the last interactive motion of the
window (with the Move command or as ManualPlacement) was ended by pressing mouse
button n. Example:
Mouse 1 T A Function MoveWindow
DestroyFunc MoveWindow
AddToFunc MoveWindow
+ C Move
+ C ThisWindow (PlacedByButton 5) WindowShade off
+ C TestRc (Match) Maximize on 0 100
+ C ThisWindow (PlacedByButton 4) WindowShade on
The PlacedByButton3 condition has the same meaning as PlacedByButton 3. It remains
only for backward compatibility.
The PlacedByFvwm condition excludes all windows that have been placed manually or by
using the user or program position hint.
The Raised conditions matches only windows that are fully visible on the current
viewport and not overlapped by any other window.
The Shaded conditions matches only shaded windows (see WindowShade command).
The State n or !State n conditions match only windows with the specified integer state
set (or unset). See the State command for details. The argument may range from 0 to
31.
The Sticky, StickyAcrossDesks and StickyAcrossPages match only windows that are
currently sticky, sticky across all desks or sticky across all pages. Please refer to
the Style options with the same name and the commands Stick, StickAcrossDesks and
StickAcrossPages for details.
The StickyIcon, StickyAcrossDesksIcon and StickyAcrossPagesIcon match only windows
that become sticky, sticky across all desks or sticky across all pages when they are
in iconified state.
The Transient condition matches only windows that have the "transient" property set by
the application. This it usually the case for application popup menus and dialogs. The
FvwmIdent module can be used to find out whether a specific window is transient.
The Visible condition matches only windows that are at least partially visible on the
current viewport and not completely overlapped by other windows.
Module Commands
Fvwm maintains a database of module configuration lines in a form
*<ModuleName>: <Config-Resource>
where <ModuleName> is either a real module name or an alias.
This database is initially filled from config file (or from output of -cmd config
command), and can be later modified either by user (via FvwmCommand) or by modules.
When modules are run, they read appropriate portion of database. (The concept of this
database is similar to one used in X resource database).
Commands for manipulating module configuration database are described below.
* module_config_line
Defines a module configuration. module_config_line consists of a module name (or a
module alias) and a module resource line. The new syntax allows a delimiter, a colon
and optional spaces, between the module name and the rest of the line, this is
recommended to avoid conflicts.
*FvwmPager: WindowBorderWidth 1
*FvwmButtons-TopRight: Geometry 100x100-0+0
*FvwmButtons-Bottom: Geometry +0-0
DestroyModuleConfig module_config
Deletes module configuration entries, so that new configuration lines may be entered
instead. This also sometimes the only way to turn back some module settings,
previously defined. This changes the way a module runs during a fvwm session without
restarting. Wildcards can be used for portions of the name as well.
The new non-conflicting syntax allows a delimiter, a colon and optional spaces between
the module name and the rest of the line. In this case a module name (or alias) can’t
have wildcards.
DestroyModuleConfig FvwmButtons*
DestroyModuleConfig FvwmForm: Fore
DestroyModuleConfig FvwmIconMan: Tips*
KillModule modulename [modulealias]
Causes the module which was invoked with name modulename to be killed. The name may
include wildcards. If modulealias is given, only modules started with the given alias
are killed.
# kill all pagers
KillModule FvwmPager
Module FvwmEvent SoundEvent
KillModule FvwmEvent SoundEvent
Module modulename [moduleparams]
Specifies a module with its optional parameters which should be spawned. Currently
several modules, including FvwmButtons, FvwmEvent, FvwmForm, FvwmPager, FvwmScript
support aliases. Aliases are useful if more than one instance of the module should be
spawned. Aliases may be configured separately using * syntax. To start a module
FvwmForm using an alias MyForm, the following syntax may be used:
Module FvwmForm MyForm
At the current time the available modules (included with fvwm) are FvwmAnimate
(produces animation effects when a window is iconified or de-iconified), FvwmAuto (an
auto raise module), FvwmBacker (to change the background when you change desktops),
FvwmBanner (to display a spiffy XBM, XPM, PNG or SVG), FvwmButtons (brings up a
customizable tool bar), FvwmCommandS (a command server to use with shell’s FvwmCommand
client), FvwmConsole (to execute fvwm commands directly), FvwmCpp (to preprocess your
config with cpp), FvwmEvent (trigger various actions by events), FvwmForm (to bring up
dialogs), FvwmIconMan (a flexible icon manager), FvwmIdent (to get window info),
FvwmM4 (to preprocess your config with m4), FvwmPager (a mini version of the desktop),
FvwmPerl (a Perl manipulator and preprocessor), FvwmProxy (to locate and control
obscured windows by using small proxy windows), FvwmRearrange (to rearrange windows),
FvwmScript (another powerful dialog toolkit), These modules have their own man pages.
There may be other modules out on there as well.
Modules can be short lived transient programs or, like FvwmButtons , can remain for
the duration of the X session. Modules are terminated by the window manager prior to
restarts and quits, if possible. See the introductory section on modules. The keyword
Module may be omitted if modulename is distinct from all fvwm commands.
ModuleListenOnly modulename [moduleparams]
This command works like the Module command, but fvwm never sends any messages to the
module. This may be handy to write a module as a shell script that is triggered by
external events without the burden to answer packets sent by fvwm. For example, a
module written as a shell script may change labels of the FvwmButtons module to
implement a simple clock.
ModulePath path
Specifies a colon separated list of directories in which to search for modules. To
find a module, fvwm searches each directory in turn and uses the first file found.
Directory names on the list do not need trailing slashes.
The ModulePath may contain environment variables such as $HOME (or ${HOME}). Further,
a '+' in the path is expanded to the previous value of the path, allowing easy
appending or prepending to the path.
For example:
ModulePath ${HOME}/lib/fvwm/modules:+
The directory containing the standard modules is available via the environment
variable $FVWM_MODULEDIR.
ModuleSynchronous [Expect string] [Timeout secs] modulename
The ModuleSynchronous command is very similar to Module. Fvwm stops processing any
commands and user input until the module sends a string beginning with "NOP FINISHED
STARTUP" back to fvwm. If the optional Timeout is given fvwm gives up if the module
sent no input back to fvwm for secs seconds. If the Expect option is given, fvwm waits
for the given string instead. ModuleSynchronous should only be used during fvwm
startup to enforce the order in which modules are started. This command is intended
for use with the (currently hypothetical) module that should be in place before other
modules are started.
Warning: It is quite easy to hang fvwm with this command, even if a timeout is given.
Be extra careful choosing the string to wait for. Although all modules in the fvwm
distribution send back the "NOP FINISHED STARTUP" string once they have properly
started up, this may not be the case for third party modules. Moreover, you can try to
escape from a locked ModuleSynchronous command by using the key sequence
(see the EscapeFunc).
ModuleTimeout timeout
Specifies how many seconds fvwm waits for a module to respond. If the module does not
respond within the time limit then fvwm kills it. timeout must be greater than zero,
or it is reset to the default value of 30 seconds.
SendToModule modulename string
Sends an arbitrary string (no quotes required) to all modules, whose alias or name
matching modulename, which may contain wildcards. This only makes sense if the module
is set up to understand and deal with these strings though. Can be used for module to
module communication, or implementation of more complex commands in modules.
Session Management Commands
Quit
Exits fvwm, generally causing X to exit too.
QuitScreen
Causes fvwm to stop managing the screen on which the command was issued.
Restart [window_manager [params]]
Causes fvwm to restart itself if window_manager is left blank, or to switch to an
alternate window manager (or other fvwm version) if window_manager is specified. If
the window manager is not in your default search path, then you should use the full
path name for window_manager.
This command should not have a trailing ampersand. The command can have optional
parameters with simple shell-like syntax. You can use ~ (is expanded to the user’s
home directory) and environmental variables $VAR or ${VAR}. Here are several examples:
Key F1 R N Restart
Key F1 R N Restart fvwm -s
Key F1 R N Restart fvwm1 -s -f .fvwmrc
Key F1 R N Restart xterm -n '"X console"' -T \"X\ console\" -e fvwm -s
Note, currently with multi headed displays, restart of fvwms on different screens
works independently.
Restart --pass-args window_manager
The same as Restart without parameters but the name for the current window manager is
replaced with the specified window_manager and original arguments are preserved.
Restart --dont-preserve-state [other-params]
The same as
Restart [other-params]
but it does not save any window states over the restart.
Without this option, Restart preserves most per-window state by writing it to a file
named .fs-restart-$HOSTDISPLAY in the user’s home directory.
SaveSession
Causes a session manager (if any) to save the session. This command does not work for
xsm, it seems that xsm does not implement this functionality. Use Unix signals to
manage xsm remotely.
SaveQuitSession
Causes a session manager (if any) to save and then shutdown the session. This command
does not work for xsm, it seems that xsm does not implement this functionality. Use
Unix signals to manage xsm remotely.
Colorsets
Colorsets are a powerful method to control colors. Colorsets create appearance resources
that are shared by fvwm and its modules. When a colorset is modified all parts of fvwm
react to that change. A colorset includes a foreground color, background color, shadow and
highlight color (often based on the background color), background face (this includes
images and all kinds of gradients). There is a way to render background face and specify
other color operations.
Colorset num [options]
Creates or modifies colorset num. Colorsets are identified by this number. The number
can start at zero and can be a very large number.
Warning: The highest colorset number used determines memory consumption. Thus, if you
define 'Colorset 100000', the memory for 100001 colorsets is used. Keep your colorset
numbers as small as possible.
By convention, colorsets are numbered like this:
# 0 = Default colors
# 1 = Inactive windows
# 2 = Active windows
# 3 = Inactive menu entry and menu background
# 4 = Active menu entry
# 5 = greyed out menu entry (only bg used)
# 6 = module foreground and background
# 7 = hilight colors
If you need to have more colors and do not want to reinvent the wheel, you may use the
convention used in fvwm-themes, it defines the meaning of the first 40 colorsets for
nearly all purposes:
http://fvwm-themes.sourceforge.net/doc/colorsets
Each colorset has four colors, an optional pixmap and an optional shape mask. The four
colors are used by modules as the foreground, background, highlight and shadow colors.
When a colorset is created it defaults to a foreground of black and background of
gray. The background and foreground are marked as "average" and "contrast" (see later)
so that just specifying a pixmap or gradient gives sensible results.
options is a comma separated list containing some of the keywords: fg, Fore,
Foreground, bg, Back, Background, hi, Hilite, Hilight, sh, Shade, Shadow, fgsh,
Pixmap, TiledPixmap, AspectPixmap, Transparent, RootTransparent, Shape, TiledShape,
AspectShape, NoShape, ?Gradient, Tint, fgTint, bgTint, Alpha, fgAlpha, Dither,
NoDither, IconTint, IconAlpha, Plain.
fg, Fore and Foreground take a color name as an argument and set the foreground color.
The special name Contrast may be used to select a color that contrasts well with the
background color. To reset the foreground color to the default value you can simply
omit the color name.
bg, Back and Background take a color name as an argument and set the background color.
It also sets the highlight and shadow colors to values that give a 3d effect unless
these have been explicitly set with the options below. The special name Average may be
used to select a color that is the average color of the pixmap. If the pixmap is
tinted with the Tint option, the tint is not taken in account in the computation of
the average color. You should use the bgTint option to get the "real" average color.
The background color is reset to the default value if the color name is omitted.
hi, Hilite and Hilight take a color name as an argument and set the highlight color.
If the highlight color is not explicitly set, the default is to calculate it from the
background color. To switch back to the default behavior the color name can be
omitted.
sh, Shade and Shadow take a color name as an argument and set the shadow color. If the
shadow color is not explicitly set, the default is to calculate it from the background
color. To switch back to the default behavior the color name can be omitted.
fgsh takes a color name as an argument and sets the color used by the shadowing font
effect. See the Font Shadow Effects section of the fvwm man page. By default this
color is computed from the foreground and background colors. To switch back to the
default the color name can be omitted.
Pixmap, TiledPixmap and AspectPixmap take a file name as an argument, search the
ImagePath and use it as the background pixmap. Any transparent parts are filled with
the background color. Not specifying a file name removes any existing image from the
colorset. TiledPixmap produces repeated copies of the image with no scaling, Pixmap
causes the image to be stretched to fit whatever object the colorset is applied to and
AspectPixmap stretches to fit but retains the image aspect ratio.
Transparent creates a transparent background pixmap. The pixmap is used as a window
background to achieve root transparency. For this you should use the
ParentalRelativity option to the Style command. A subsequent root background change
may be detected or not, this depends on the program used to set the background. If you
use fvwm-root, xsetbg (xli), FvwmBacker with solid or colorset colors or a recent
version of Esetroot (>= 9.2) a background change is detected. If background changes
are not detected (e.g., if you use xv or xsetroot) you can force detection by using
the -d option of fvwm-root:
xv -root -quit mybg.png; fvwm-root -d
Due to the way X implements transparency no guarantees can be made that the desired
effect can be achieved. The application may even crash. If you experience any problems
with this option, do not use it.
Using outline move and resize (see the OpaqueMoveSize command and the ResizeOpaque
Style option) as well as setting the WindowShadeShrinks style may help. The
transparency achieved with Transparent depends on whether the colorset is applied to
the foreground or the background of a window. In the second case the transparency is
relative to the parent window of the window on which the colorset is defined. For
example:
Colorset 12 VGradient 200 grey30 grey60
Colorset 17 Transparent
*FvwmIconMan: Colorset 12
*FvwmIconMan: PlainColorset 17
gives an IconMan with a vertical grey gradient background and the buttons use the
background (by transparency). To obtain a (root) transparent IconMan:
Colorset 12 Transparent
Colorset 17 Transparent
Colorset 18 Transparent
Colorset 19 Transparent
*FvwmIconMan: Colorset 12
*FvwmIconMan: PlainColorset 17
*FvwmIconMan: FocusColorset 18
*FvwmIconMan: IconColorset 19
The Colorset IconMan option defines the IconMan window background, but the
PlainColorset and the FocusColorset are drawn on the foreground. So, the transparency
of the IconMan buttons is achieved by drawing nothing. Now if this IconMan is
swallowed in an FvwmButtons as:
FvwmButtons:(Colorset 10, Swallow "FvwmIconMan" 'FvwmIconMan')
then, FvwmIconMan becomes a child of FvwmButtons and it is transparent relative to
FvwmButtons. So, in this case FvwmIconMan uses Colorset 10 as background. If you want
root transparency use the RootTransparent option. FvwmButtons FvwmIconMan, and
FvwmIdent, are relatively simple. There is one main colorset option which defines the
background of the window and the other colorsets (if any) are drawn on the foreground.
The case of FvwmProxy is simpler, the two colorsets refer to the window backgrounds.
FvwmPager is more complicated as almost everything in the pager are windows with some
parental relations (the mini windows are the child and the desktops are the parents
and all this is complicated by the hilighted page). So, the colorsets apply to the
background of these windows. You should experiment. For FvwmForm and FvwmScript the
situation is similar. There is a main window (a child of the root window) which
corresponds to the main colorset and most of the widgets are windows which are
children of the main window. Tint may work or not with the Transparent option. When
the colorset is drawn on the foreground Tint should work. In some cases, tinting may
be very slow. Tinting may work with fvwm menu (without animation). Tinting may work
better if your X server has backing store enabled (try xdpyinfo to see if this the
case). There is a chance that the backing store support of your X server does not work
well with the terrible hack used to Tint the ParentRelative Pixmap. So, to get tinted
root transparency it is more safe to use the RootTransparent option.
RootTransparent [ buffer ] creates a root transparent background. To make this option
work, you must use an Esetroot compatible program, fvwm-root with the --retain-pixmap
option or FvwmBacker with the RetainPixmap option (and colorset or solid backgrounds).
The buffer keyword is useful only when the Tint option is used too. This speeds up
creation of windows which use the colorset (useful for fvwm menus) at the cost of
memory usage. It also speeds up opaque move and resize which can be unacceptably slow
without buffer. However, this option may add a lot of memory to your X server
(depending on the size of the image used to set the background). In summary, using
outline move and resize for modules which use such a colorset may be a good idea.
Shape, TiledShape and AspectShape take a file name as an argument, search the
ImagePath and use it as the shape bitmap. TiledShape produces repeated copies of the
bitmap with no scaling, Shape causes the bitmap to be stretched to fit whatever object
the colorset is applied to and AspectShape stretches to fit but retains the bitmap
aspect ratio. If the file is a pixmap in xpm format the shape mask (all opaque pixels)
of the pixmap is used. For png and svg images, the shape mask is equivalent to all not
completely transparent pixels (alpha > 0).
Warning Due to the way X11 implements shapes you cannot take back making windows
shaped. You may have to restart fvwm or the shaped application.
?Gradient ... creates a pixmap and stretches it to fit the window. ?Gradient may be
one of HGradient, VGradient, DGradient, BGradient, SGradient, CGradient, RGradient or
YGradient. The gradient types are as follows: H is horizontal; V is vertical; D is
diagonal from top left to bottom right; B is a backwards diagonal from bottom left to
top right; S is concentric squares; C is concentric circles; R is a radar like pattern
and Y is a Yin Yang style (but without the dots). Please refer to the Color Gradients
section for the syntax of gradients.
Tint takes 2 arguments, a color and a percentage between 0 and 100. It causes the
image defined using ?Pixmap or ?Gradient to be tinted with the specified color using
the percentage. If the image is transparent Tint tints only the image part.
Unfortunately, a colorset background specified using the Transparent option can give
strange results. See the Transparent option for details. With no arguments this option
removes the tint.
fgTint takes 2 arguments, a color and a percentage between 0 and 100. It causes the
color defined using fg to be tinted with the specified color using the percentage.
With no arguments this option removes the tint.
bgTint takes 2 arguments, a color and a percentage between 0 and 100. It causes the
color defined using bg to be tinted with the specified color using the percentage. If
the sh and hi colors are not specified, they are recomputed from the tinted bg color.
With no arguments this option removes the tint.
Alpha takes a percentage between 0 and 100 as an argument. It causes fvwm to merge the
image defined using ?Pixmap or ?Gradient with the bg color using the percentage. If
the percentage is 0 the image is hidden and if it is 100 the image is displayed as
usual (no merge). The default is 100 and it is restored if no argument is given.
fgAlpha takes a percentage between 0 and 100 as an argument. It causes fvwm to merge
the text and the colorset background using the percentage. If the percentage is 0 the
text is hidden and if it is 100 the text is displayed as usual (no merge). This option
has an effect only with fonts loaded by Xft, see the Font Names and Font Loading
section. The default is 100 and it is restored if no argument is given.
Dither causes fvwm to dither the image defined using ?Pixmap or ?Gradient. This is
useful only with displays with depth less than or equal to 16 (i.e., on displays which
can only display less than 65537 colors at once). The dithering effect lets you
simulate having more colors available that you actually have. NoDither causes fvwm to
do not dither the images. Dither is the default if the depth is less than or equal to
8 (a screen with 256 colors or less). In depth 15 (32768 colors) and 16 (65536
colors), the default is NoDither, however this effect can be useful with images which
contain a lot of close colors. For example a fine gradient looks more smooth.
IconTint takes 2 arguments, a color and a percentage between 0 and 100. It causes fvwm
or a module to tint the "icons" which are rendered into the colorset background with
the specified color using a percentage. Here "icons" means, fvwm Icons, fvwm menu
icons, MiniIcons which represent applications in various modules, images loaded by
modules (e.g., images specified by the Icon FvwmButtons button option) ...etc. With no
arguments this option removes the icon tint.
IconAlpha takes a percentage between 0 and 100 as an argument. It causes fvwm to merge the
"icons" which are rendered into the colorset background using this percentage. The default
is 100 and it is restored if no argument is given.
Note: It is equivalent to use "Tint a_color rate" and "Alpha a" if a = 100 and the bg
color is a_color. This equivalence does not hold for IconAlpha and IconTint as the
background can be an image or a gradient (and not a uniform color background). However, in
some cases you can achieve (almost) the same effect by using IconTint in the place of
IconAlpha. This is preferable as, in general, IconAlpha generates more redrawing than
IconTint.
NoShape removes the shape mask from the colorset while Plain removes the background pixmap
or gradient.
Examples
Colorset 3 fg tan, bg navy
If necessary this creates colorsets 0, 1, 2 and 3 and then changes colorset 3 to have a
foreground of tan, a background of navy.
Colorset 3 bg "navy blue"
changes the background color of colorset 3 to navy blue. The foreground and pixmap are
unchanged.
Colorset 3 AspectPixmap large_murky_dungeon.xpm
causes depression.
Colorset 3 bg Average
Sets the background color and the relief colors to match the background pixmap. This is
the default setting but it must be used if a background color was specified and is now not
required.
Colorset 3 YGradient 200 3 blue 1000 navy 1 blue 1000 navy
Adds a Yin Yang gradient background pixmap to colorset 3. If the background is set to
average it is recomputed along with the foreground if that is set to contrast.
#!/bin/sh
FvwmCommand "Colorset 7 fg navy, bg gray"
while true
do
FvwmCommand "Colorset 7 fg gray"
sleep 1
FvwmCommand "Colorset 7 fg navy"
sleep 1
done
Makes colorset 7 blink.
The color names used in colorsets are saved as fvwm variables which can be substituted in
any fvwm command. For example:
AddToFunc InitFunction
+ I Exec exec xterm -fg $[fg.cs0] -bg $[bg.cs0]
Where $[fg.cs0] is the foreground color of colorset zero. Please refer to the Command
Expansion section for more information.
CleanupColorsets
Resets a definition of all colorsets.
Color Gradients
A color gradient is a background that changes its color gradually from one hue to a
different one. Color gradients can be used by various commands and modules of fvwm.
There are eight types of gradients: HGradient is a horizontal gradient, VGradient is
vertical, DGradient is diagonal from top left to bottom right, BGradient is backwards
diagonal from bottom left to top right, SGradient is concentric squares, CGradient is
concentric circles, RGradient is a radar like pattern and YGradient is a Yin Yang
style (but without the dots).
The color gradient syntax has two forms:
?Gradient colors start-color end-color
This form specifies a linear gradient. The arguments denote the total number of colors
to allocate (between 2 and 1000), the initial color and the final color.
Example:
TitleStyle VGradient 20 rgb:b8/ce/bc rgb:5b/85/d0
?Gradient colors segments color length color [length color] ...
The second form specifies a nonlinear gradient. The arguments are: the total number of
colors to allocate (between 2 and 1000), then the number of segments. For each
segment, specify the starting color, a relative length, then the ending color. Each
subsequent segment begins with the second color of the last segment. The lengths may
be any non-negative integers. The length of one segment divided by the sum of all
segments lengths is the fraction of the colors that are used for the segment.
Examples:
Colorset 0 DGradient 128 2 lightgrey 50 blue 50 white
# 20% gradient from red to blue,
# 30% from blue to black,
# 50% from black to grey
Colorset 0 DGradient 100 3 Red 20 Blue 30 Black 50 Grey
# 50% from blue to green, then
# 50% from yellow to red
Colorset 0 HGradient 128 3 Blue 1000 Green 1 Yellow 1000 Red
Note: Some gradient styles 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, !HilightBack
+ Make sure sub menus do not overlap the parent menu. This can prevent menus being redrawn
every time a sub menu pops up or down.
+
MenuStyle <style> PopupOffset 1 100
+ Run your X server with backing storage. If your X Server is started with the -bs option,
turn it off. If not try the -wm and +bs options:
+
startx -- -wm +bs
+ You may have to adapt this example to your system (e.g. if you use xinit to start X).
2023-01-17 FVWM3COMMANDS(1)