with zero or a
positive integer). For example "$[fg.cs3]" is expanded to the name of
the foreground color of colorset 3 (in rgb:rrrr/gggg/bbbb form).
.sp
If .lighten or .darken
is appended to the parameters, they are
instead replaced with a color that is lighter or darker than the one
defined in colorset by a percentage value (between 0 and 100).
For example "$[bg.cs3.lighten15]" is expanded to the background color of
colorset 3 and then lightened 15% (in rgb:rrrr/gggg/bbbb form).
.sp
If .hash is appened to the end the color output will use #rrggbb form
(instead of rgb:rrrr/gggg/bbbb). For example, $[bg.cs3.hash] or
$[bg.cs3.lighten15.hash].
.sp
Please refer to the \fBColorsets\fP section for details about colorsets.
.RE
.sp
$[schedule.last]
.RS 4
This is replaced by the id of the last command that was scheduled with
the \fBSchedule\fP command, even if this command was already executed.
.RE
.sp
$[schedule.next]
.RS 4
This is replaced by the id the next command used with \fBSchedule\fP will
get (unless a different id is specified explicitly).
.RE
.sp
$[cond.rc]
.RS 4
The return code of the last conditional command. This variable is only
valid inside a function and can not be used in a conditional command.
Please refer to the section \fBConditional Commands\fP in the command list.
.RE
.sp
$[func.context]
.RS 4
The context character of the running command as used in the \fBMouse\fP,
\fBKey\fP or \fBPointerKey\fP command. This is useful for example with:
.sp
.if n .RS 4
.nf
.fam C
Mouse 3 FS N WindowShade $$[func.context]
.fam
.fi
.if n .RE
.RE
.sp
$[debuglog.state]
.RS 4
Either \fI0\fP (debug log closed) or \fI1\fP. Indicates the current state of
debugging and logging facility.
.RE
.sp
$[gt.\fIstr\fP]
.RS 4
return the translation of \fIstr\fP by looking in the current locale
catalogs. If no translation is found \fIstr\fP is returned as is. See the
\fBLocalePath\fP command.
.RE
.sp
$[infostore.\fIkey\fP]
.RS 4
Return the value of the item stored in the InfoStore at the given \fIkey\fP.
If no key is present, the unexpanded string is returned.
.RE
.sp
$[...]
.RS 4
If the string within the braces is neither of the above, fvwm tries to
find an environment variable with this name and replaces its value if
one is found (e.g. "$[PAGER]" could be replaced by "more"). Otherwise
the string is left as is.
.sp
Some examples can be found in the description of the \fBAddToFunc\fP
command.
.RE
.SH "SCRIPTING AND COMPLEX FUNCTIONS"
.sp
To achieve the more complex effects, fvwm has a number of commands that
improve its scripting abilities. Scripts can be read from a file with
\fBRead\fP, from the output of a command with \fBPipeRead\fP or written as a
complex function with the \fBAddToFunc\fP command. For the curious, section
7 of the fvwm FAQ shows some real life applications of scripting. Please
refer to the sections \fBUser Functions and Shell Commands\fP and
\fBConditional Commands\fP for details. A word of warning: during execution
of complex functions, fvwm needs to take all input from the mouse
pointer (the pointer is "grabbed" in the slang of X). No other programs
can receive any input from the pointer while a function is run. This can
confuse some programs. For example, the xwd program refuses to make
screen shots when run from a complex function. To achieve the same
functionality you can use the \fBRead\fP or \fBPipeRead\fP command instead.
.SH "MENUS"
.sp
Before a menu can be opened, it has to be populated with menu items
using the \fBAddToMenu\fP command and bound to a key or mouse button with
the \fBKey\fP, \fBPointerKey\fP or \fBMouse\fP command (there are many other ways to
invoke a menu too). This is usually done in the configuration file.
.sp
Fvwm menus are extremely configurable in look and feel. Even the
slightest nuances can be changed to the user\(cqs liking, including the
menu item fonts, the background, delays before popping up sub menus,
generating menus dynamically and many other features. Please refer to
the \fBMenuStyle\fP command to learn more.
.sp
\fBTypes of Menus\fP
.RS 4
There are four slightly different types of menus:
.sp
Popup menus can appear everywhere on the screen on their own or
attached to a part of a window. The \fBPopup\fP command opens popup menus.
If the popup menu was invoked with a mouse button held down, it is
closed when the button is released. The item under the pointer is then
activated and the associated action is executed.
.sp
Normal menus are very similar command, but slightly transient.
When invoked by clicking a mouse button, they stay open
and can be navigated with no button held. But if invoked by a
button press followed by mouse motion, it behaves exactly like a popup
menu. The \fBMenu\fP command creates normal menus.
.sp
"Sub menus" are menus inside other menus. When a menu item that has the
\fBPopup\fP command as its action is selected, the named menu is opened as
a sub menu to the parent. Any type of menu can have sub menus.
.sp
"Tear off menus" are menus that have been "torn off" their original
context on the desktop like a normal window. They are created from
other menus by certain key presses or mouse sequences or with the
\fBTearMenuOff\fP command from inside a menu.
.RE
.sp
\fBMenu Anatomy\fP
.RS 4
Menus consist of any number of titles which are inactive menu items
that usually appear at the top of the menu, normal items triggering
various actions when selected, separator lines between the items, tear
off bars (a horizontal broken line) that tear off the menu when
selected, and sub menu items indicated with a triangle pointing left
or right, depending on the direction in which the sub menu appears.
All the above menu items are optional.
.sp
Additionally, if the menu is too long to fit on the screen, the excess
menu items are put in a continuation menu and a sub menu with the
string "More..." is placed at the bottom of the menu. The "More..."
string honors the locale settings.
.sp
Finally, there may be a picture running up either side of the menu (a
"side bar").
.RE
.sp
\fBMenu Navigation\fP
.RS 4
Menus are navigated with the keyboard and the mouse.
Many people prefer to use the mouse, but it can be tedious.
Keyboard navigation can be much faster.
While fvwm displays a menu, it can do nothing else. For example, new
windows do not appear before the menu is closed. However, this is not
exactly true for tear off menus. See the \fBTear Off Menus\fP section for
details.
.RE
.sp
\fBMouse Navigation\fP
.RS 4
Moving the pointer over a menu selects the item below it. Normally
this is indicated by a 3d border around the item, but not all parts of
a menu can be selected. Pressing any mouse button while a menu is open
by default activates the item below it. Items of a popup menu are also
activated by releasing a held mouse button. In case of an item that
hides a sub menu, the sub menu is displayed if the pointer hovers over
the item long enough or moves close to the triangle indicating the sub
menu. This behaviour can be tuned with menu styles.
.sp
Scrolling a mouse wheel over a menu either wraps the pointer along the
menu (default), scrolls the menu under the pointer or act as if the
menu was clicked depending on the \fIMouseWheel\fP menu style.
.sp
Clicking on a selected item activates it \- what happens exactly
depends on the type of the item.
.sp
Clicking on a title, a separator, the side bar, or outside the menu
closes the menu (exception: tear off menus can not be closed this
way). Pressing mouse button 2 over a menu title or activating a tear
off bar creates a tear off menu from the current menu. Clicking on a
normal menu item invokes the command that is bound to it, and clicking
on a sub menu item either closes all open menus and replaces them with
the sub menu or posts the menu (default).
.sp
Posting menus is meant to ease mouse navigation. Once a sub menu is
posted, only items from that sub menu can be selected. This can be
very useful to navigate the menu if the pointer tends to stray off the
menu. To unpost the menu and revert back to normal operation, either
click on the same sub menu item or press any key.
.RE
.sp
\fBKeyboard Navigation\fP
.RS 4
Just like with mouse navigation, the item below the pointer is
selected. This is achieved by warping the pointer to the menu items
when necessary. While a menu is open, all key presses are intercepted
by the menu. No other application can get keyboard input (although
this is not the case for tear off menus).
.sp
Items can be selected directly by pressing a hotkey that can be
configured individually for each menu item. The hotkey is indicated by
underlining it in the menu item label. With the \fIAutomaticHotkeys\fP
menu style fvwm automatically assigns hotkeys to all menu items.
.sp
The most basic keys to navigate through menus are the cursor keys
(move up or down one item, enter or leave a sub menu),
.sp
(activate item) and
.sp
(close menu). Numerous other keys can be used to navigate through
menus by default:
.sp
\fIEnter\fP, \fIReturn\fP, \fISpace\fP activate the current item.
.sp
\fIEscape\fP, \fIDelete\fP, \fICtrl\-G\fP exit the current sequence of menus or
destroy a tear off menu.
.sp
\fIJ\fP, \fIN\fP, \fICursor\-Down\fP, \fITab\fP, \fIMeta\-Tab\fP, \fICtrl\-F\fP, move to the next
item.
.sp
\fIK\fP, \fIP\fP, \fICursor\-Up\fP, \fIShift\-Tab\fP, \fIShift\-Meta\-Tab\fP, \fICtrl\-B\fP, move
to the prior item.
.sp
\fIL\fP, \fICursor\-Right\fP, \fIF\fP enter a sub menu.
.sp
\fIH\fP, \fICursor\-Left\fP, \fIB\fP return to the prior menu.
.sp
\fICtrl\-Cursor\-Up\fP, \fICtrl\-K\fP \fICtrl\-P\fP, \fIShift\-Ctrl\-Meta\-Tab\fP, \fIPage\-Up\fP
move up five items.
.sp
\fICtrl\-Cursor\-Down\fP, \fICtrl\-J\fP \fICtrl\-N\fP, \fICtrl\-Meta\-Tab\fP \fIPage\-Down\fP
move down five items.
.sp
\fIShift\-P\fP, \fIHome\fP, \fIShift\-Cursor\-Up\fP, \fICtrl\-A\fP move to the first item.
.sp
\fIShift\-N\fP, \fIEnd\fP, \fIShift\-Cursor\-Down\fP, \fICtrl\-E\fP move to the last item.
.sp
\fIMeta\-P\fP, \fIMeta\-Cursor\-Up\fP, \fICtrl\-Cursor\-Left\fP, \fIShift\-Ctrl\-Tab\fP, move
up just below the next separator.
.sp
\fIMeta\-N\fP, \fIMeta\-Cursor\-Down\fP, \fICtrl\-Cursor\-Right\fP, \fICtrl\-Tab\fP, move
down just below the next separator.
.sp
\fIInsert\fP opens the "More..." sub menu if any.
.sp
\fIBackspace\fP tears off the menu.
.RE
.sp
\fBMenu Bindings\fP
.RS 4
The keys and mouse buttons used to navigate the menu can be configured
using the \fBKey\fP and \fBMouse\fP commands with the special context \*(AqM\*(Aq,
possible combined with \*(AqT\*(Aq for the menu title, \*(AqI\*(Aq for other menu
items, \*(AqS\*(Aq for any border or sidepic, \*(Aq[\*(Aq for left border including a
left sidepic, \*(Aq]\*(Aq for right border including a right sidepic, \*(Aq\-\*(Aq for
top border, \*(Aq\fI\*(Aq for bottom border. The menu context uses its own set
of actions that can be bound to keys and mouse buttons. These are
_MenuClose\fP, \fIMenuCloseAndExec\fP, \fIMenuEnterContinuation\fP,
\fIMenuEnterSubmenu\fP, \fIMenuLeaveSubmenu\fP, \fIMenuMoveCursor\fP,
\fIMenuCursorLeft\fP, \fIMenuCursorRight\fP, \fIMenuSelectItem\fP, \fIMenuScroll\fP
and \fIMenuTearOff\fP.
.sp
It is not possible to override the key Escape with no modifiers for
closing the menu. Neither is it possible to undefine mouse button 1,
the arrow keys or the enter key for minimal navigation.
.sp
\fBMenuClose\fP exits from the current sequence of menus or destroys a
tear off menu.
.sp
\fBMenuCloseAndExec\fP exits from the current sequence of menus or
destroys a tear off menu and executes the rest of the line as a
command.
.sp
\fBMenuEnterContinuation\fP opens the "More..." sub menu if any.
.sp
\fBMenuEnterSubmenu\fP enters a sub menu.
.sp
\fBMenuLeaveSubmenu\fP returns to the prior menu.
.sp
\fBMenuMoveCursor\fP \fIn\fP [\fIm\fP] moves the selection to another item. If the
first argument is zero the second argument specifies an absolute item
in the menu to move the pointer to. Negative items are counted from
the end of the menu. If the first argument is non\-zero, the second
argument must be omitted, and the first argument specifies a relative
change in the selected item. The positions may be suffixed with a \*(Aqs\*(Aq
to indicate that the items should refer only to the first items after
separators.
.sp
\fBMenuCursorLeft\fP enters a sub menu with the \fISubmenusLeft\fP menu style,
and returns to the prior menu with the \fISubmenusRight\fP menu style.
.sp
\fBMenuCursorRight\fP enters a sub menu with the \fISubmenusRight\fP menu
style, and returns to the prior menu with the \fISubmenusLeft\fP menu
style.
.sp
\fBMenuSelectItem\fP triggers the action for the menu item.
.sp
\fBMenuScroll \fP\fIn\fP performs menu scrolling according to the
\fIMouseWheel\fP menu style with \fIn\fP items. The distance can be suffixed
with an \*(Aqs\*(Aq to indicate the items should refer only to the first items
after separators.
.sp
\fBMenuTearOff\fP turns a normal menu into a "torn off" menu. See \fBTear
Off Menus\fP for details.
.RE
.sp
\fBTear Off Menus\fP
.RS 4
A tear off menu is any menu that has been "torn off" the window it was
attached to and pinned to the root window. There are three ways to
tear off a menu: click on the menu title with mouse button 2, press
.sp
in the menu or activate its tear off bar (a horizontal bar with a
broken line). Tear off bars must be added to the menu as any other
item by assigning them the command \fBTearMenuOff\fP.
.sp
The builtin tear off actions can be overridden by undefining the
builtin menu actions bound to tear off. To remove the builtin mouse
button 2 binding, use:
.sp
.if n .RS 4
.nf
.fam C
Mouse 2 MT A \-
.fam
.fi
.if n .RE
.sp
and to remove the builtin backspace binding, use:
.sp
.if n .RS 4
.nf
.fam C
Key Backspace M A \-
.fam
.fi
.if n .RE
.sp
See the section \fBMenu Bindings\fP for details on how to assign other
bindings for tear off.
.sp
Note that prior to fvwm 2.5.20 the tear off mouse bindings were
redefined in different way, which no longer work.
.sp
The window containing the menu is placed as any other window would be.
If you find it confusing to have your tear off menus appear at random
positions on the screen, put this line in your configuration file:
.sp
.if n .RS 4
.nf
.fam C
Style fvwm_menu UsePPosition
.fam
.fi
.if n .RE
.sp
To remove borders and buttons from a tear\-off menu but keep the menu
title, you can use
.sp
.if n .RS 4
.nf
.fam C
Style fvwm_menu !Button 0, !Button 1
Style fvwm_menu !Button 2, !Button 3
Style fvwm_menu !Button 4, !Button 5
Style fvwm_menu !Button 6, !Button 7
Style fvwm_menu !Button 8, !Button 9
Style fvwm_menu Title, HandleWidth 0
.fam
.fi
.if n .RE
.sp
A tear off menu is a cross breeding between a window and a menu. The
menu is swallowed by a window and its title is stripped off and
displayed in the window title. The main advantage is that the menu
becomes permanent \- activating an item does not close the menu.
Therefore, it can be used multiple times without reopening it. To
destroy such a menu, close its window or press the Escape key.
.sp
Tear off menus behave somewhat differently than normal menus and
windows. They do not take the keyboard focus, but while the pointer is
over one of them, all key presses are sent to the menu. Other fvwm key
bindings are disabled as long as the pointer is inside the tear off
menu or one of its sub menus. When the pointer leaves this area, all
sub menus are closed immediately. Note that the window containing a
tear off menu is never hilighted as if it had the focus.
.sp
A tear off menu is an independent copy of the menu it originated from.
As such, it is not affected by adding items to that menu or changing
its menu style.
.sp
To create a tear off menu without opening the normal menu first, the
option \fITearOffImmediately\fP can be added to the \fBMenu\fP or \fBPopup\fP
command.
.RE
.SS "Building menu contents"
.sp
\fBAddToMenu\fP \fImenu\-name\fP [\fImenu\-label\fP \fIaction\fP]
.RS 4
Begins or adds to a menu definition. Typically a menu definition looks
like this:
.sp
.if n .RS 4
.nf
.fam C
AddToMenu Utilities Utilities Title
+ Xterm Exec exec xterm \-e tcsh
+ Rxvt Exec exec rxvt
+ "Remote Logins" Popup Remote\-Logins
+ Top Exec exec rxvt \-T Top \-n Top \-e top
+ Calculator Exec exec xcalc
+ Xman Exec exec xman
+ Xmag Exec exec xmag
+ emacs Exec exec xemacs
+ Mail MailFunction xmh "\-font fixed"
+ "" Nop
+ Modules Popup Module\-Popup
+ "" Nop
+ Exit Fvwm Popup Quit\-Verify
.fam
.fi
.if n .RE
.sp
The menu could be invoked via
.sp
.if n .RS 4
.nf
.fam C
Mouse 1 R A Menu Utilities Nop
.fam
.fi
.if n .RE
.sp
or
.sp
.if n .RS 4
.nf
.fam C
Mouse 1 R A Popup Utilities
.fam
.fi
.if n .RE
.sp
There is no end\-of\-menu symbol. Menus do not have to be defined in a
contiguous region of the \fIconfig\fP file. The quoted (or first word)
portion in the above examples is the menu label, which appears in the
menu when the user pops it up. The remaining portion is an fvwm
command which is executed if the user selects that menu item. An empty
menu\-label ("") and the \fBNop\fP function are used to insert a separator
into the menu.
.sp
The keywords \fIDynamicPopUpAction\fP and \fIDynamicPopDownAction\fP have a
special meaning when used as the name of a menu item. The action
following the keyword is executed whenever the menu is popped up or
down. This way you can implement dynamic menus. It is even possible to
destroy itself with \fBDestroyMenu\fP and the rebuild from scratch. When
the menu has been destroyed (unless you used the \fIrecreate\fP option
when destroying the menu), do not forget to add the dynamic action
again.
.sp
Note: Do not trigger actions that require user interaction. They may
fail and may screw up your menus. See the \fBSilent\fP command.
.sp
\fBWarning\fP Do not issue \fBMenuStyle\fP commands as dynamic menu actions.
Chances are good that this crashes fvwm.
.sp
The keyword \fIGreyed\fP will still render the menu item, but will grey it out
making the option unselectable.
.sp
There are several configurable scripts installed together with fvwm
for automatic menu generation. They have their own man pages. Some of
them, specifically \fBfvwm\-menu\-directory\fP and \fBfvwm\-menu\-desktop\fP, may
be used with \fIDynamicPopupAction\fP to create a directory listing or
GNOME/KDE application listing.
.sp
Example (File browser):
.sp
.if n .RS 4
.nf
.fam C
# You can find the shell script fvwm_make_browse_menu.sh
# in the utils/ directory of the distribution.
AddToMenu BrowseMenu
+ DynamicPopupAction PipeRead \(rs
\*(Aqfvwm_make_browse_menu.sh BrowseMenu\*(Aq
.fam
.fi
.if n .RE
.sp
Example (Picture menu):
.sp
.if n .RS 4
.nf
.fam C
# Build a menu of all .jpg files in
# $HOME/Pictures
AddToMenu JpgMenu foo title
+ DynamicPopupAction Function MakeJpgMenu
AddToFunc MakeJpgMenu
+ I DestroyMenu recreate JpgMenu
+ I AddToMenu JpgMenu Pictures Title
+ I PipeRead \*(Aqfor i in $HOME/Pictures/*.jpg; \(rs
do echo AddToMenu JpgMenu "`basename $i`" Exec xv $i; done\*(Aq
.fam
.fi
.if n .RE
.sp
The keyword \fIMissingSubmenuFunction\fP has a similar meaning. It is
executed whenever you try to pop up a sub menu that does not exist.
With this function you can define and destroy menus on the fly. You
can use any command after the keyword, but if the name of an item
(that is a submenu) defined with \fBAddToFunc\fP follows it, fvwm executes
this command:
.sp
.if n .RS 4
.nf
.fam C
Function
.fam
.fi
.if n .RE
.sp
i.e. the name is passed to the function as its first argument and can
be referred to with "$0".
.sp
The \fBfvwm\-menu\-directory\fP script mentioned above may be used with
\fIMissingSubmenuFunction\fP to create an up to date recursive directory
listing.
.sp
Example:
.sp
.if n .RS 4
.nf
.fam C
# There is another shell script fvwm_make_directory_menu.sh
# in the utils/ directory of the distribution. To use it,
# define this function in your configuration file:
DestroyFunc MakeMissingDirectoryMenu
AddToFunc MakeMissingDirectoryMenu
+ I PipeRead fvwm_make_directory_menu.sh $0
DestroyMenu SomeMenu
AddToMenu SomeMenu
+ MissingSubmenuFunction MakeMissingDirectoryMenu
+ "Root directory" Popup /
.fam
.fi
.if n .RE
.sp
This is another implementation of the file browser that uses sub menus
for subdirectories.
.sp
Titles can be used within the menu. If you add the option \fItop\fP behind
the keyword \fBTitle\fP, the title is added to the top of the menu. If
there was a title already, it is overwritten.
.sp
.if n .RS 4
.nf
.fam C
AddToMenu Utilities Tools Title top
.fam
.fi
.if n .RE
.sp
All text up to the first Tab in the menu label is aligned to the left side of
t the menu, all text right of the first is aligned to the left in a second
column and all text thereafter is placed right aligned in the third column.
All other s are replaced by spaces. Note that you can change this format with
the \fIItemFormat\fP option of the \fBMenuStyle\fP command.
.sp
If the menu\-label contains an ampersand (\*(Aq&\*(Aq), the next character is
taken as a hot\-key for the menu item. Hot\-keys are underlined in the
label. To get a literal \*(Aq&\*(Aq, insert "&&". Pressing the hot\-key moves
through the list of menu items with this hot\-key or selects an item
that is the only one with this hot\-key.
.sp
If the menu\-label contains a sub\-string which is set off by stars,
then the text between the stars is expected to be the name of an image
file to insert in the menu. To get a literal \*(Aq\fB\*(Aq, insert "\fP*". For
example
.sp
.if n .RS 4
.nf
.fam C
+ Calculator*xcalc.xpm* Exec exec xcalc
.fam
.fi
.if n .RE
.sp
inserts a menu item labeled "Calculator" with a picture of a
calculator above it. The following:
.sp
.if n .RS 4
.nf
.fam C
+ *xcalc.xpm* Exec exec xcalc
.fam
.fi
.if n .RE
.sp
Omits the "Calculator" label, but leaves the picture.
.sp
If the menu\-label contains a sub\-string which is set off by percent
signs, then the text between the percent signs is expected to be the
name of image file (a so called mini icon to insert to the left of the
menu label. A second mini icon that is drawn at the right side of the
menu can be given in the same way. To get a literal \*(Aq%\*(Aq, insert "%%".
For example
.sp
.if n .RS 4
.nf
.fam C
+ Calculator%xcalc.xpm% Exec exec xcalc
.fam
.fi
.if n .RE
.sp
inserts a menu item labeled "Calculator" with a picture of a
calculator to the left. The following:
.sp
.if n .RS 4
.nf
.fam C
+ %xcalc.xpm% Exec exec xcalc
.fam
.fi
.if n .RE
.sp
Omits the "Calculator" label, but leaves the picture. The pictures
used with this feature should be small (perhaps 16x16).
.sp
If the menu\-name (not the label) contains a sub\-string which is set
off by at signs (\*(Aq@\*(Aq), then the text between them is expected to be
the name of an image file to draw along the left side of the menu (a
side pixmap). You may want to use the \fISidePic\fP option of the
\fBMenuStyle\fP command instead. To get a literal \*(Aq@\*(Aq, insert "@@". For
example
.sp
.if n .RS 4
.nf
.fam C
AddToMenu StartMenu@linux\-menu.xpm@
.fam
.fi
.if n .RE
.sp
creates a menu with a picture in its bottom left corner.
.sp
If the menu\-name also contains a sub\-string surrounded by \*(Aq^\*(Aqs, then
the text between \*(Aq^\*(Aqs is expected to be the name of an X11 color and
the column containing the side picture is colored with that color. You
can set this color for a menu style using the \fISideColor\fP option of
the \fBMenuStyle\fP command. To get a literal \*(Aq^\*(Aq, insert "^^". Example:
.sp
.if n .RS 4
.nf
.fam C
AddToMenu StartMenu@linux\-menu.xpm@^blue^
.fam
.fi
.if n .RE
.sp
creates a menu with a picture in its bottom left corner and colors
with blue the region of the menu containing the picture.
.sp
In all the above cases, the name of the resulting menu is name
specified, stripped of the substrings between the various delimiters.
.RE
.sp
\fBDestroyMenu\fP [recreate] \fImenu\fP
.RS 4
Deletes a menu, so that subsequent references to it are no longer
valid. You can use this to change the contents of a menu during an
fvwm session. The menu can be rebuilt using \fBAddToMenu\fP. The optional
parameter \fIrecreate\fP tells fvwm not to throw away the menu completely
but to throw away all the menu items (including the title).
.sp
.if n .RS 4
.nf
.fam C
DestroyMenu Utilities
.fam
.fi
.if n .RE
.RE
.sp
\fBTitle\fP
.RS 4
Does nothing. It is used to insert a title line in a popup or menu.
.RE
.SS "Commands that open menus"
.sp
\fBMenu\fP \fImenu\-name\fP [\fIposition\fP] [\fIdouble\-click\-action\fP]
.RS 4
Causes a previously defined menu to be popped up in a sticky manner.
That is, if the user invokes the menu with a click action instead of a
drag action, the menu stays up. The command \fIdouble\-click\-action\fP is
invoked if the user double\-clicks a button (or hits the key rapidly
twice if the menu is bound to a key) when bringing up the menu. If the
double click action is not specified, double clicking on the menu does
nothing. However, if the menu begins with a menu item (i.e. not with a
title or a separator) and the double click action is not given, double
clicking invokes the first item of the menu (but only if the pointer
really was over the item).
.sp
The pointer is warped to where it was when the menu was invoked if it
was both invoked and closed with a keystroke.
.sp
The \fIposition\fP arguments allow placement of the menu somewhere on the
screen, for example centered on the visible screen or above a title
bar. Basically it works like this: you specify a \fIcontext\-rectangle\fP
and an offset to this rectangle by which the upper left corner of the
menu is moved from the upper left corner of the rectangle. The
\fIposition\fP arguments consist of several parts:
.sp
[\fIcontext\-rectangle\fP] \fIx\fP \fIy\fP [\fIspecial options\fP]
.sp
The \fIcontext\-rectangle\fP can be one of:
.sp
\fIRoot\fP
.RS 4
the root window of the current screen.
.RE
.sp
\fIMonitor\fP
.RS 4
the area of the current RandR screen.
.RE
.sp
\fIMouse\fP
.RS 4
a 1x1 rectangle at the mouse position.
.RE
.sp
\fIWindow\fP
.RS 4
the frame of the context window.
.RE
.sp
\fIInterior\fP
.RS 4
the inside of the context window.
.RE
.sp
\fITitle\fP
.RS 4
the title of the context window or icon.
.RE
.sp
\fIButton\fP
.RS 4
button of the context window.
.RE
.sp
\fIIcon\fP
.RS 4
the icon of the context window.
.RE
.sp
\fIMenu\fP
.RS 4
the current menu.
.RE
.sp
\fIItem\fP
.RS 4
the current menu item.
.RE
.sp
\fIContext\fP
.RS 4
the current window, menu or icon.
.RE
.sp
\fIThis\fP
.RS 4
whatever widget the pointer is on (e.g. a corner of a window or the
root window).
.RE
.sp
\fIRectangle\fP <_geometry_>
.RS 4
the rectangle defined by <_geometry_> in X geometry format. Width
and height default to 1 if omitted.
.sp
If the context\-rectangle is omitted or invalid (e.g. "item" on a
window), "Mouse" is the default. Note that not all of these make sense
under all circumstances (e.g. "Icon" if the pointer is on a menu).
.sp
The offset values \fIx\fP and \fIy\fP specify how far the menu is moved from
its default position. By default, the numeric value given is
interpreted as a percentage of the context rectangle\(cqs width (height),
but with a trailing \*(Aq\fIm\fP\*(Aq the menu\(cqs width (height) is used instead.
Furthermore a trailing \*(Aq\fIp\fP\*(Aq changes the interpretation to mean
pixels.
.sp
Instead of a single value you can use a list of values. All additional
numbers after the first one are separated from their predecessor by
their sign. Do not use any other separators.
.sp
If \fIx\fP or \fIy\fP are prefixed with "\*(Aq\fIo\fP" where is an
integer, the menu and the rectangle are moved to overlap at the
specified position before any other offsets are applied. The menu and
the rectangle are placed so that the pixel at percent of the
rectangle\(cqs width/height is right over the pixel at percent
of the menu\(cqs width/height. So "o0" means that the top/left borders of
the menu and the rectangle overlap, with "o100" it\(cqs the bottom/right
borders and if you use "o50" they are centered upon each other (try it
and you will see it is much simpler than this description). The
default is "o0". The prefix "o" is an abbreviation for
"+\-m".
.sp
A prefix of \*(Aq\fIc\fP\*(Aq is equivalent to "o50". Examples:
.sp
.if n .RS 4
.nf
.fam C
# window list in the middle of the screen
WindowList Root c c
# menu to the left of a window
Menu name window \-100m c+0
# popup menu 8 pixels above the mouse pointer
Popup name mouse c \-100m\-8p
# somewhere on the screen
Menu name rectangle 512x384+1+1 +0 +0
# centered vertically around a menu item
AddToMenu foobar\-menu
+ "first item" Nop
+ "special item" Popup "another menu" item +100 c
+ "last item" Nop
# above the first menu item
AddToMenu foobar\-menu
+ "first item" Popup "another menu" item +0 \-100m
.fam
.fi
.if n .RE
.sp
Note that you can put a sub menu far off the current menu so you could
not reach it with the mouse without leaving the menu. If the pointer
leaves the current menu in the general direction of the sub menu the
menu stays up.
.RE
.sp
\fISpecial options\fP
.RS 4
.sp
To create a tear off menu without opening the normal menu, add the
option \fITearOffImmediately\fP. Normally the menu opens in normal state
for a split second before being torn off. As tearing off places the
menu like any other window, a position should be specified explicitly:
.sp
.if n .RS 4
.nf
.fam C
# Forbid fvwm to place the menu window
Style UsePPosition
# Menu at top left corner of screen
Menu Root 0p 0p TearOffImmediately
.fam
.fi
.if n .RE
.sp
The \fIAnimated\fP and \fIMwm\fP or \fIWin\fP menu styles may move a menu
somewhere else on the screen. If you do not want this you can add
\fIFixed\fP as an option. This might happen for example if you want the
menu always in the top right corner of the screen.
.sp
Where do you want a menu to appear when you click on its menu item?
The default is to place the title under the cursor, but if you want it
where the position arguments say, use the \fISelectInPlace\fP option. If
you want the pointer on the title of the menu, use \fISelectWarp\fP too.
Note that these options apply only if the \fIPopupAsRootMenu\fP
\fBMenuStyle\fP option is used.
.sp
The pointer is warped to the title of a sub menu whenever the pointer
would be on an item when the sub menu is popped up (\fIfvwm\fP menu style)
or never warped to the title at all (\fIMwm\fP or \fIWin\fP menu styles). You
can force (forbid) warping whenever the sub menu is opened with the
\fIWarpTitle\fP (\fINoWarp\fP) option.
.sp
Note that the \fIspecial\-options\fP do work with a normal menu that has no
other position arguments.
.RE
.RE
.sp
\fBPopup\fP \fIPopupName\fP [\fIposition\fP] [\fIdefault\-action\fP]
.RS 4
This command has two purposes: to bind a menu to a key or mouse
button, and to bind a sub menu into a menu. The formats for the two
purposes differ slightly. The \fIposition\fP arguments are the same as for
\fBMenu\fP. The command \fIdefault\-action\fP is invoked if the user clicks a
button to invoke the menu and releases it immediately again (or hits
the key rapidly twice if the menu is bound to a key). If the default
action is not specified, double clicking on the menu does nothing.
However, if the menu begins with a menu item (i.e. not with a title or
a separator) and the default action is not given, double clicking
invokes the first item of the menu (but only if the pointer really was
over the item).
.sp
To bind a previously defined pop\-up menu to a key or mouse button:
.sp
The following example binds mouse buttons 2 and 3 to a pop\-up called
"Window Ops". The menu pops up if the buttons 2 or 3 are pressed in
the window frame, side\-bar, or title\-bar, with no modifiers (none of
shift, control, or meta).
.sp
.if n .RS 4
.nf
.fam C
Mouse 2 FST N Popup "Window Ops"
Mouse 3 FST N Popup "Window Ops"
.fam
.fi
.if n .RE
.sp
Pop\-ups can be bound to keys through the use of the \fBKey\fP command.
Pop\-ups can be operated without using the mouse by binding to keys and
operating via the up arrow, down arrow, and enter keys.
.sp
To bind a previously defined pop\-up menu to another menu, for use as a
sub menu:
.sp
The following example defines a sub menu "Quit\-Verify" and binds it
into a main menu, called "RootMenu":
.sp
.if n .RS 4
.nf
.fam C
AddToMenu Quit\-Verify
+ "Really Quit Fvwm?" Title
+ "Yes, Really Quit" Quit
+ "Restart Fvwm" Restart
+ "Restart Fvwm 1.xx" Restart fvwm1 \-s
+ "" Nop
+ "No, Don\*(Aqt Quit" Nop
AddToMenu RootMenu "Root Menu" Title
+ "Open XTerm Window" Popup NewWindowMenu
+ "Login as Root" Exec exec xterm \-T Root \-n Root \-e su \-
+ "Login as Anyone" Popup AnyoneMenu
+ "Remote Hosts" Popup HostMenu
+ "" Nop
+ "X utilities" Popup Xutils
+ "" Nop
+ "Fvwm Modules" Popup Module\-Popup
+ "Fvwm Window Ops" Popup Window\-Ops
+ "" Nop
+ "Previous Focus" Prev (AcceptsFocus) Focus
+ "Next Focus" Next (AcceptsFocus) Focus
+ "" Nop
+ "Refresh screen" Refresh
+ "" Nop
+ "Reset X defaults" Exec xrdb \-load \(rs
$HOME/.Xdefaults
+ "" Nop
+ "" Nop
+ Quit Popup Quit\-Verify
.fam
.fi
.if n .RE
.sp
Popup differs from \fBMenu\fP in that pop\-ups do not stay up if the user
simply clicks. These are popup\-menus, which are a little hard on the
wrist. \fBMenu\fP menus stay up on a click action. See the \fBMenu\fP command
for an explanation of the interactive behavior of menus. A menu can be
open up to ten times at once, so a menu may even use itself or any of
its predecessors as a sub menu.
.RE
.sp
\fBTearMenuOff\fP
.RS 4
When assigned to a menu item, it inserts a tear off bar into the menu
(a horizontal broken line). Activating that item tears off the menu.
If the menu item has a label, it is shown instead of the broken line.
If used outside menus, this command does nothing. Examples:
.sp
.if n .RS 4
.nf
.fam C
AddToMenu WindowMenu
+ I "" TearMenuOff
AddToMenu RootMenu
+ I "click here to tear me off" TearMenuOff
.fam
.fi
.if n .RE
.RE
.SS "Menu style commands"
.sp
Menu styles describe the looks and behaviour like normal styles do
for windows. Menu styles are assigned to individual or all menus,
and changing the menu style immediately affects all menus that use
it. (If a menu style is used from within a menu, the changes are
applied the next time an affected menu is opened.)
.sp
\fBChangeMenuStyle\fP \fImenustyle\fP \fImenu\fP ...
.RS 4
Changes the menu style of \fImenu\fP to \fImenustyle\fP. You may specify more
than one menu in each call of \fBChangeMenuStyle\fP.
.RE
.sp
\fBCopyMenuStyle\fP \fIorig\-menustyle\fP \fIdest\-menustyle\fP
.RS 4
Copy \fIorig\-menustyle\fP to \fIdest\-menustyle\fP, where \fIorig\-menustyle\fP is
an existing menu style. If the menu style \fIdest_menustyle\fP does not
exist, then it is created.
.RE
.sp
\fBDestroyMenuStyle\fP \fImenustyle\fP
.RS 4
Deletes the menu style named \fImenustyle\fP and changes all menus using
this style to the default style, you cannot destroy the default menu
style.
.sp
.if n .RS 4
.nf
.fam C
DestroyMenuStyle pixmap1
.fam
.fi
.if n .RE
.RE
.sp
\fBMenuStyle\fP \fIstylename\fP [\fIoptions\fP]
.RS 4
Sets a new menu style or changes a previously defined style. The
\fIstylename\fP is the style name; if it contains spaces or tabs it has to
be quoted. The name "\fB" is reserved for the default menu style. The
default menu style is used for every menu\-like object (e.g. the window
created by the *WindowList\fP command) that had not be assigned a style
using the \fBChangeMenuStyle\fP. See also \fBDestroyMenuStyle\fP. When using
monochrome color options are ignored.
.sp
\fIoptions\fP is a comma separated list containing some of the keywords
Fvwm / Mwm / Win, BorderWidth, HilightBack / !HilightBack, HilightTitleBack,
ActiveFore / !ActiveFore, MenuColorset, ActiveColorset, GreyedColorset,
TitleColorset, Hilight3DThick / Hilight3DThin / Hilight3DOff,
Hilight3DThickness, Animation / !Animation, Font, TitleFont,
PopupDelay, PopupOffset, TitleWarp / !TitleWarp, TitleUnderlines0 /
TitleUnderlines1 / TitleUnderlines2, SeparatorsLong / SeparatorsShort,
TrianglesSolid / TrianglesRelief, PopupImmediately / PopupDelayed,
PopdownImmediately / PopdownDelayed, PopupActiveArea, DoubleClickTime,
SidePic, SideColor, PopupAsRootMenu / PopupAsSubmenu / PopupIgnore /
PopupClose, RemoveSubmenus / HoldSubmenus, SubmenusRight /
SubmenusLeft, SelectOnRelease, ItemFormat, VerticalItemSpacing,
VerticalMargins, VerticalTitleSpacing, AutomaticHotkeys /
!AutomaticHotkeys, UniqueHotkeyActivatesImmediate /
!UniqueHotkeyActivatesImmediate, MouseWheel, ScrollOffPage /
!ScrollOffPage, TrianglesUseFore / !TrianglesUseFore,
Translucent / !Translucent.
.sp
In the above list some options are listed as option pairs or triples
with a \*(Aq/\*(Aq in between. These options exclude each other. All paired
options can be negated to have the effect of the counterpart option by
prefixing ! to the option.
.sp
\fIFvwm\fP, \fIMwm\fP, \fIWin\fP reset all options to the style with the same name
in former versions of fvwm. The default for new menu styles is \fIFvwm\fP
style. These options override all others except \fIHilightBack\fP, \fIActiveFore\fP
and \fIPopupDelay\fP, so they should be used only as the first option specified
for a menu style or to reset the style to defined behavior. The same effect
can be created by setting all the other options one by one.
.sp
\fIMwm\fP and \fIWin\fP style menus popup sub menus automatically. \fIWin\fP menus
indicate the current menu item by changing the background to dark.
\fIFvwm\fP sub menus overlap the parent menu, \fIMwm\fP and \fIWin\fP style menus
never overlap the parent menu.
.sp
\fIFvwm\fP style is equivalent to !HilightBack, Hilight3DThin,
!ActiveFore, !Animation, Font, PopupOffset 0 67, TitleWarp,
TitleUnderlines1, SeparatorsShort, TrianglesRelief, PopupDelayed,
PopdownDelayed, PopupDelay 150, PopdownDelay 150, PopupAsSubmenu,
HoldSubmenus, SubmenusRight, BorderWidth 2, !AutomaticHotkeys,
UniqueHotkeyActivatesImmediate, PopupActiveArea 75.
.sp
\fIMwm\fP style is equivalent to !HilightBack, Hilight3DThick,
!ActiveFore, !Animation, Font, PopupOffset \-3 100,
!TitleWarp, TitleUnderlines2, SeparatorsLong, TrianglesRelief,
PopupImmediately, PopdownDelayed, PopdownDelay 150, PopupAsSubmenu,
HoldSubmenus, SubmenusRight, BorderWidth 2,
UniqueHotkeyActivatesImmediate, !AutomaticHotkeys, PopupActiveArea 75.
.sp
\fIWin\fP style is equivalent to HilightBack, Hilight3DOff, ActiveFore,
!Animation, Font, PopupOffset \-5 100, !TitleWarp,
TitleUnderlines1, SeparatorsShort, TrianglesSolid, PopupImmediately,
PopdownDelayed, PopdownDelay 150, PopupAsSubmenu, RemoveSubmenus,
SubmenusRight, BorderWidth 2, UniqueHotkeyActivatesImmediate,
!AutomaticHotkeys, PopupActiveArea 75.
.sp
\fIBorderWidth\fP takes the thickness of the border around the menus in
pixels. It may be zero to 50 pixels. The default is 2. Using an
invalid value reverts the border width to the default.
.sp
\fIHilightBack\fP and \fI!HilightBack\fP switch hilighting the background of
the selected menu item on and off. The \fIActiveColorset\fP background
color is used for the hilighting.
.sp
\fIHilightTitleBack\fP switches hilighting the background of menu titles
on. The \fITitleColorset\fP background color is used for the hilighting.
.sp
\fIActiveFore\fP and \fI!ActiveFore\fP switch hilighting the foreground of the
selected menu item on and off. The \fIActiveColorset\fP foreground color
is used for the hilighting.
.sp
\fIMenuColorset\fP controls the colorset used to color the menu. If the
colorset has a pixmap or gradient defined, this is used as the background
of the menu. The shape mask from the colorset is used to shape the
menu. Please refer to the \fBColorsets\fP section for details about
colorsets.
.sp
\fIActiveColorset\fP controls the color of the active menu item, provided
the \fIHilightBack\fP or \fIActiveFore\fP menu styles are used. If specified,
the hilight and shadow colors from the colorset are used too. The
pixmap and shape mask from the colorset are not used. Hilighting the
background or foreground can be turned off individually with the
\fI!ActiveFore\fP or \fI!HilightBack\fP menu styles.
.sp
\fIGreyedColorset\fP works exactly like \fIMenuColorset\fP, but the foreground
from the colorset replaces the color given with the \fIGreyed\fP menu
style. No other parts of the colorset are used.
.sp
\fITitleColorset\fP works exactly like \fIMenuColorset\fP, but is used only
for menu titles.
.sp
\fITranslucent\fP controls a pseudo transparent effect that uses a image
of the desktop under the menu as its background image. This option
takes one value that is a number between 0 (fully translucent)
and 100 (not translucent), which is the percent of the translucency.
Use \fI!Translucent\fP (or no additional value) to turn the effect off.
The translucent effect only applies to normal menus and does not
apply to "torn off" menus. Note, only the menu background is
translucent, the \fIHilightBack\fP of the active item and
\fIHilightTitleBack\fP of the title are not. To have a fully translucent
menu use the following.
.sp
.if n .RS 4
.nf
.fam C
MenuStyle * Translucent 60, !HilightBack, !HilightTitleBack, ActiveFore
.fam
.fi
.if n .RE
.sp
\fIHilight3DThick\fP, \fIHilight3DThin\fP and \fIHilight3DOff\fP determine if the
selected menu item is hilighted with a 3D relief. Thick reliefs are
two pixels wide, thin reliefs are one pixel wide.
.sp
\fIHilight3DThickness\fP takes one numeric argument that may be between
\-50 and +50 pixels. With negative values the menu item gets a pressed
in look. The above three commands are equivalent to a thickness of 2,
1 and 0.
.sp
\fIAnimation\fP and \fI!Animation\fP turn menu animation on or off. When
animation is on, sub menus that do not fit on the screen cause the
parent menu to be shifted to the left so the sub menu can be seen.
.sp
\fIFont\fP and \fITitleFont\fP take a font name as an argument. If a font by
this name exists it is used for the text of all menu items. If it does
not exist or if the name is left blank the built\-in default is used.
If a \fITitleFont\fP is given, it is used for all menu titles instead of
the normal font.
.sp
\fIPopupDelay\fP requires one numeric argument. This value is the delay in
milliseconds before a sub menu is popped up when the pointer moves
over a menu item that has a sub menu. If the value is zero no
automatic pop up is done. If the argument is omitted the built\-in
default is used. Note that the popup delay has no effect if the
\fIPopupImmediately\fP option is used since sub menus pop up immediately
then.
.sp
\fIPopupImmediately\fP makes menu items with sub menus pop up it up as
soon as the pointer enters the item. The \fIPopupDelay option\fP is
ignored then. If \fIPopupDelayed\fP is used fvwm looks at the \fIPopupDelay\fP
option if or when this automatic popup happens.
.sp
\fIPopdownDelay\fP works exactly like \fIPopupDelay\fP but determines the
timeout of the \fIPopupDelayed\fP style.
.sp
\fIPopdownImmediately\fP makes sub menus vanish as soon as the pointer
leaves the sub menu and the correspondent item in the parent menu.
With the opposite option \fIPopdownDelayed\fP the sub menu only pops down
after the time specified with the \fIPopdownDelay\fP option. This comes
handy when the pointer often strays off the menu item when trying to
move into the sub menu. Whenever there is a conflict between the
\fIPopupImmediately\fP, \fIPopupDelayed\fP, \fIPopupDelay\fP styles and the
\fIPopdownImmediately\fP, \fIPopdownDelayed\fP, \fIPopdownDelay\fP styles, the
\fIPopup...\fP styles win when using mouse navigation and the \fIPopdown...\fP
styles win when navigating with the keyboard.
.sp
\fIPopupOffset\fP requires two integer arguments. Both values affect where
sub menus are placed relative to the parent menu. If both values are
zero, the left edge of the sub menu overlaps the left edge of the
parent menu. If the first value is non\-zero the sub menu is shifted
that many pixels to the right (or left if negative). If the second
value is non\-zero the menu is moved by that many percent of the parent
menu\(cqs width to the right or left.
.sp
\fIPopupActiveArea\fP requires an integer value between 51 and 100.
Normally, when the pointer is over a menu item with a sub menu and the
pointer enters the area that starts at 75% of the menu width, the sub
menu is shown immediately. This percentage can be changed with
\fIPopupActiveArea\fP. Setting this value to 100 disables this kind of
automatic popups altogether. The default value is restored if no or an
invalid value is given.
.sp
\fITitleWarp\fP and \fI!TitleWarp\fP affect if the pointer warps to the menu
title when a sub menu is opened or not. Note that regardless of this
setting the pointer is not warped if the menu does not pop up under
the pointer.
.sp
\fITitleUnderlines0\fP, \fITitleUnderlines1\fP and \fITitleUnderlines2\fP specify
how many lines are drawn below a menu title.
.sp
\fISeparatorsLong\fP and \fISeparatorsShort\fP set the length of menu
separators. Long separators run from the left edge all the way to the
right edge. Short separators leave a few pixels to the edges of the
menu.
.sp
\fITrianglesSolid\fP and \fITrianglesRelief\fP affect how the small triangles
for sub menus is drawn. Solid triangles are filled with a color while
relief triangles are hollow.
.sp
\fIDoubleClickTime\fP requires one numeric argument. This value is the
time in milliseconds between two mouse clicks in a menu to be
considered as a double click. The default is 450 milliseconds. If the
argument is omitted the double click time is reset to this default.
.sp
\fISidePic\fP takes the name of an image file as an argument. The picture
is drawn along the left side of the menu. The \fISidePic\fP option can be
overridden by a menu specific side pixmap (see \fBAddToMenu\fP). If the
file name is omitted an existing side pixmap is removed from the menu
style.
.sp
\fISideColor\fP takes the name of an X11 color as an argument. This color
is used to color the column containing the side picture (see above).
The SideColor option can be overridden by a menu specific side color
(see \fBAddToMenu\fP). If the color name is omitted the side color option
is switched off.
.sp
\fIPopupAsRootMenu\fP, \fIPopupAsSubmenu\fP, \fIPopupIgnore\fP and \fIPopupClose\fP
change the behavior when you click on a menu item that opens a sub
menu. With \fIPopupAsRootMenu\fP the original menu is closed before the
sub menu appears, with \fIPopupAsSubmenu\fP it is not, so you can navigate
back into the parent menu. Furthermore, with \fIPopupAsSubmenu\fP the sub
menu is held open (posted) regardless of where you move the mouse.
Depending on your menu style this may simplify navigating through the
menu. \fBAny\fP keystroke while a menu is posted reverts the menu back to
the normal behavior. With \fIPopupClose\fP the menu is closed when a sub
menu item is activated, and the menu stays open if \fIPopupIgnore\fP is
used (even if the menu was invoked with the \fBPopup\fP command).
\fIPopupAsSubmenu\fP is the default.
.sp
\fIRemoveSubmenus\fP instructs fvwm to remove sub menu when you move back
into the parent menu. With \fIHoldSubmenus\fP the sub menu remains
visible. You probably want to use \fIHoldSubmenus\fP if you are using the
\fIPopupDelayed\fP style. \fIRemoveSubmenus\fP affects menu navigation with
the keyboard.
.sp
\fISelectOnRelease\fP takes an optional key name as an argument. If the
given key is released in a menu using this style, the current menu
item is selected. This is intended for
\fBWindowList\fP navigation. The key name is a standard X11 key name as
defined in \fI/usr/include/X11/keysymdef.h\fP, (without the \fIXK_\fP prefix),
or the keysym database \fI/usr/X11R6/lib/X11/XKeysymDB\fP. To disable this
behavior, omit the key name.
.sp
Note: Some X servers do not support KeyRelease events.
\fISelectOnRelease\fP does not work on such a machine.
.sp
\fIItemFormat\fP takes a special string as its argument that determines
the layout of the menu items. Think of the format string as if it were
a menu item. All you have to do is tell fvwm where to place the
different parts of the menu item (i.e. the labels, the triangle
denoting a sub menu, the mini icons and the side pic) in the blank
area. The string consists of spaces,
.sp
characters and formatting directives beginning with \*(Aq%\*(Aq. Any invalid
characters and formatting directives are silently ignored:
.sp
\fB%l\fP, \fB%c\fP and \fB%r\fP
.RS 4
Insert the next item label. Up to three labels can be used. The item
column is left\-aligned (\fB%l\fP), centered (\fB%c\fP) or right\-aligned
(\fB%r\fP).
.RE
.sp
\fB%i\fP
.RS 4
Inserts the mini icon.
.RE
.sp
\fB%>\fP and \fB%<\fP
.RS 4
Insert the sub menu triangle pointing either to the right (\fB%>\fP) or to
the left (\fB%<\fP).
.RE
.sp
\fB%|\fP
.RS 4
The first \fB%|\fP denotes the beginning of the area that is highlighted
either with a background color or a relief (or both). The second \fB%|\fP
marks the end of this area. \fB%|\fP can be used up to twice in the
string. If you do not add one or both of them, fvwm sets the margins
to the margins of the whole item (not counting the side picture).
.RE
.sp
\fB%s\fP
.RS 4
Places the side picture either at the beginning or the end of the
menu. This directive may be used only once and only as the first or
last in the format string. If the \fB%s\fP is not at the beginning of the
string, menus are not drawn properly.
.RE
.sp
\fBSpace\fP, \fBTab\fP, \fB%Space\fP and \fB%Tab\fP
.RS 4
Add gap of one space, or a tab, using the width of the menu font. When
using a tab, the size of the gap can be one to 8 spaces since the tab
position is a multiple of 8 from the edge of the menu. The whole
string must be quoted if spaces or tabs are used.
.RE
.sp
\fB%p\fP
.RS 4
Like Space and Tab \fB%p\fP inserts an empty area into the item, but with
better control of its size (see below).
.RE
.sp
You can define an additional space before and after each of the
objects like this
.sp
.if n .RS 4
.nf
.fam C
%left.rightp
.fam
.fi
.if n .RE
.sp
This means: if the object is defined in the menu (e.g. if it is \fB%s\fP
and you use a side picture, or it is \fB%l\fP for the third column and
there are items defined that actually have a third column), then add
\fIleft\fP pixels before the object and \fIright\fP pixels after it. You may
leave out the \fIleft\fP or the \fI.right\fP parts if you do not need them.
All values up to the screen width are allowed. Even negative values
can be used with care. The \fBp\fP may be replaced with any other
formatting directives described above.
.sp
Note: Only items defined in the format string are visible in the
menus. So if you do not put a \fB%s\fP in there you do not see a side
picture, even if one is specified.
.sp
Note: The \fISubmenusLeft\fP style changes the default \fIItemFormat\fP
string, but if it was set manually it is not modified.
.sp
Note: If any unformatted title of the menu is wider than the widest
menu item, the spaces between the different parts of the menu items
are enlarged to match the width of the title. Leading left aligned
objects in the format string (\fB%l\fP, \fB%i\fP, \fB%<\fP, first \fB%|\fP) stick to
the left edge of the menu and trailing right aligned objects (\fB%r\fP,
\fB%i\fP, \fB%>\fP, second \fB%|\fP) stick to the right edge. The gaps between the
remaining items are enlarged equally.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
MenuStyle * ItemFormat "%.4s%.1|%.5i%.5l%.5l%.5r%.5i%2.3>%1|"
.fam
.fi
.if n .RE
.sp
Is the default string used by fvwm: (side picture + 4 pixels gap)
(beginning of the hilighted area + 1 pixel gap) (mini icon + 5p)
(first column left aligned + 5p) (second column left aligned + 5p)
(third column right aligned + 5p) (second mini icon + 5p) (2p + sub
menu triangle + 3p) (1p + end of hilighted area).
.sp
.if n .RS 4
.nf
.fam C
MenuStyle * ItemFormat "%.1|%3.2<%5i%5l%5l%5r%5i%1|%4s"
.fam
.fi
.if n .RE
.sp
Is used by fvwm with the \fISubmenusLeft\fP option below.
.sp
\fIVerticalItemSpacing\fP and \fIVerticalTitleSpacing\fP control the vertical
spacing of menu items and titles like \fIItemFormat\fP controls the
horizontal spacing. Both take two numeric arguments that may range
from \-100 to +100. The first is the gap in pixels above a normal menu
item (or a menu title), the second is the gap in pixels below it.
Negative numbers do not make much sense and may screw up the menu
completely. If no arguments are given or the given arguments are
invalid, the built\-in defaults are used: one pixel above the item or
title and two below.
.sp
\fIVerticalMargins\fP can be used to add some padding at the top and
bottom of menus. It takes two numeric arguments that must be positive
integers (or zero). If the number of arguments or its values are
incorrect, fvwm defaults both to 0, which means no padding at all. If
the values are correct, the first one is used for the top margin, and
the second one is used for the bottom margin.
.sp
\fISubmenusLeft\fP mirrors the menu layout and behavior. Sub menus pop up
to the left, the sub menu triangle is drawn left and the mini icon and
side picture are drawn at the right side of the menu. The default is
\fISubmenusRight\fP. The position hints of a menu are also affected by
this setting, i.e. position hints using \fIitem\fP or \fImenu\fP as context
rectangle and position hints using \fIm\fP offsets.
.sp
\fIAutomaticHotkeys\fP and \fI!AutomaticHotkeys\fP control the menu\(cqs ability
to automatically provide hot\-keys on the first character of each menu
item\(cqs label. This behavior is always overridden if an explicit
hot\-key is assigned in the \fBAddToMenu\fP command.
.sp
\fIUniqueHotkeyActivatesImmediate\fP and \fI!UniqueHotkeyActivatesImmediate\fP
controls how menu items are invoked when used with hotkeys. By
default, if a given menu entry only has one completeable match for a
given hotkey, the action for that menu entry is invoked and the menu
is closed. This is due to the \fIUniqueHotkeyActivatesImmediate\fP option.
However, the menu can be told to remain open, waiting for the user to
invoke the selected item instead when there is only one matched item
for a given hotkey, by using the \fI!UniqueHotkeyActivatesImmediate\fP
option.
.sp
\fIMouseWheel\fP controls the ability to scroll the menu using a mouse
wheel. It takes one argument, that can be one of ScrollsPointer,
ScrollsMenu, ScrollsMenuBackwards or ActivatesItem. ScrollsPointer
makes the mouse wheel scroll the pointer over a menu. This is the
default. ScrollsMenu and ScrollsMenuBackwards scroll the menu beneath
the pointer. ActivatesItem disables scrolling by mouse wheel and makes
the use of a mouse wheel act as if the menu was clicked. If no
argument is supplied the default setting is restored.
.sp
\fIScrollOffPage\fP allows a menu to be scrolled out of the visible area
if \fIMouseWheel\fP is set to ScrollsMenu or ScrollsMenuBackwards. This is
the default. The opposite, \fI!ScrollOffPage\fP disables this behaviour.
.sp
\fITrianglesUseFore\fP draws sub menu triangles with the foreground color
of the menu colorset (normally drawn with the hilight color).
\fI!TrianglesUseFore\fP disables this behaviour.
.RE
.SH "LIST OF FVWM COMMANDS"
.sp
The command descriptions below are grouped together in the following
sections. The sections are hopefully sorted in order of usefulness to
the newcomer.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBMenu commands\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBMiscellaneous commands\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBCommands affecting window movement and placement\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBCommands for focus and mouse movement\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBCommands controlling window state\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBCommands for mouse and key bindings\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBThe Style command (controlling window styles)\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBOther commands controlling window styles\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBCommands controlling the virtual desktop\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBCommands for user functions and shell commands\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBConditional commands\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBModule commands\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBQuit, restart and session management commands\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBColorsets\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fBColor gradients\fP
.RE
.SS "Miscellaneous Commands"
.sp
\fBBugOpts\fP [\fIoption\fP [\fIbool\fP]], ...
.RS 4
This command controls several workarounds for bugs in third party
programs. The individual options are separated by commas. The optional
argument \fIbool\fP 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
\fIbool\fP is omitted, the default setting is restored.
.sp
\fIDebugRandR\fP activates monitor layout debug messages.
.sp
\fIFlickeringMoveWorkaround\fP 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.
.sp
\fIMixedVisualWorkaround\fP makes fvwm install the root colormap before it
does some operations using the root window visuals. This is only
useful when the \fB\-visual\fP 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).
.sp
The \fIModalityIsEvil\fP 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.
.sp
\fIRaiseOverNativeWindows\fP makes fvwm try to raise the windows it
manages over native windows of the X server\(cqs 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.
.sp
\fIRaiseOverUnmanaged\fP 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 \fIUnmanaged\fP style option too.
.sp
\fIFlickeringQtDialogsWorkaround\fP 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.
.sp
\fIQtDragnDropWorkaround\fP suppresses the forwarding of unknown
ClientEvent messages to windows \(em 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.
.sp
\fIEWMHIconicStateWorkaround\fP 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.
.sp
With the \fIDisplayNewWindowNames\fP 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 \fBStyle\fP
command.
.sp
When the \fIExplainWindowPlacement\fP option is enabled, fvwm prints a
message to the console whenever a new window is placed or
\fBPlaceAgain\fP, 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.
.sp
The \fIDebugCRMotionMethod\fP 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.
.sp
The \fITransliterateUtf8\fP 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.
.RE
.sp
\fBBusyCursor\fP [\fIOption\fP \fIbool\fP], ...
.RS 4
This command controls the cursor during the execution of certain
commands. \fIOption\fP can be \fIDynamicMenu\fP, \fIModuleSynchronous\fP, \fIRead\fP,
\fIWait\fP or \fI*\fP. An option must be followed by a boolean argument
\fIbool\fP. 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 \fIWAIT\fP context of the \fBCursorStyle\fP
command. "False" forces to not display the cursor. The default is:
.sp
.if n .RS 4
.nf
.fam C
BusyCursor DynamicMenu False, ModuleSynchronous False, \(rs
Read False, Wait False
.fam
.fi
.if n .RE
.sp
The \fI*\fP option refers to all available options.
.sp
The \fIRead\fP option controls the \fBPipeRead\fP command.
.sp
The \fIDynamicMenu\fP option affects the \fIDynamicPopupAction\fP and
\fIMissingSubmenuFunction\fP options of the \fBAddToMenu\fP 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 \fBRead\fP or \fBPipeRead\fP
command and the \fIRead\fP option is set to "True".
.sp
The \fIModuleSynchronous\fP option affects the \fBModuleSynchronous\fP
command. If this option is set to "False", then the busy cursor is not
displayed while fvwm waits for a module started by \fBModuleSynchronous\fP
to complete its startup.
.sp
The \fIWait\fP 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 \fBEscapeFunc\fP
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
\fBCursorStyle\fP command.
.RE
.sp
\fBClickTime\fP [\fIdelay\fP]
.RS 4
Specifies the maximum delay in milliseconds between a button press and
a button release for the \fBFunction\fP command to consider the action a
mouse click. The default delay is 150 milliseconds. Omitting the delay
value resets the \fBClickTime\fP to the default.
.sp
ClickTime also specifies the delay between two clicks to be interpreted as a
double\-click.
.RE
.sp
\fBColorLimit\fP \fIlimit\fP
.RS 4
This command is obsolete. See the \fB\-\-color\-limit\fP option to fvwm.
.RE
.sp
\fBColormapFocus\fP FollowsMouse | FollowsFocus
.RS 4
By default, fvwm installs the colormap of the window that the cursor
is in. If you use
.sp
.if n .RS 4
.nf
.fam C
ColormapFocus FollowsFocus
.fam
.fi
.if n .RE
.sp
then the installed colormap is the one for the window that currently
has the keyboard focus.
.RE
.sp
\fBCursorStyle\fP \fIcontext\fP [\fInum\fP | \fIname\fP | None | Tiny | \fIfile\fP [\fIx\fP \fIy\fP] [\fIfg\fP \fIbg\fP]]
.RS 4
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:
.sp
\fIPOSITION\fP (top_left_corner)
.RS 4
used when initially placing windows
.RE
.sp
\fITITLE\fP (top_left_arrow)
.RS 4
used in a window title\-bar
.RE
.sp
\fIDEFAULT\fP (top_left_arrow)
.RS 4
used in windows that do not set their cursor
.RE
.sp
\fISYS\fP (hand2)
.RS 4
used in one of the title\-bar buttons
.RE
.sp
\fIMOVE\fP (fleur)
.RS 4
used when moving or resizing windows
.RE
.sp
\fIRESIZE\fP (sizing)
.RS 4
used when moving or resizing windows
.RE
.sp
\fIWAIT\fP (watch)
.RS 4
used during certain fvwm commands (see \fBBusyCursor\fP for details)
.RE
.sp
\fIMENU\fP (top_left_arrow)
.RS 4
used in menus
.RE
.sp
\fISELECT\fP (crosshair)
.RS 4
used when the user is required to select a window
.RE
.sp
\fIDESTROY\fP (pirate)
.RS 4
used for \fBDestroy\fP, \fBClose\fP, and \fBDelete\fP commands
.RE
.sp
\fITOP\fP (top_side)
.RS 4
used in the top side\-bar of a window
.RE
.sp
\fIRIGHT\fP (right_side)
.RS 4
used in the right side\-bar of a window
.RE
.sp
\fIBOTTOM\fP (bottom_side)
.RS 4
used in the bottom side\-bar of a window
.RE
.sp
\fILEFT\fP (left_side)
.RS 4
used in the left side\-bar of a window
.RE
.sp
\fITOP_LEFT\fP (top_left_corner)
.RS 4
used in the top left corner of a window
.RE
.sp
\fITOP_RIGHT\fP (top_right_corner)
.RS 4
used in the top right corner of a window
.RE
.sp
\fIBOTTOM_LEFT\fP (bottom_left_corner)
.RS 4
used in the bottom left corner of a window
.RE
.sp
\fIBOTTOM_RIGHT\fP (bottom_right_corner)
.RS 4
used in the bottom right corner of a window
.RE
.sp
\fITOP_EDGE\fP (top_side)
.RS 4
used at the top edge of the screen
.RE
.sp
\fIRIGHT_EDGE\fP (right_side)
.RS 4
used at the right edge of the screen
.RE
.sp
\fIBOTTOM_EDGE\fP (bottom_side)
.RS 4
used at the bottom edge of the screen
.RE
.sp
\fILEFT_EDGE\fP (left_side)
.RS 4
used at the left edge of the screen
.RE
.sp
\fIROOT\fP (left_ptr)
.RS 4
used as the root cursor
.RE
.RE
.sp
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.
.sp
The second argument is either the numeric value of the cursor as
defined in the include file \fIX11/cursorfont.h\fP or its name (without
the XC_ prefix). Alternatively, the xpm file name may be specified.
The name can also be \fINone\fP (no cursor) or \fITiny\fP (a single pixel as
the cursor).
.sp
.if n .RS 4
.nf
.fam C
# make the kill cursor be XC_gumby (both forms work):
CursorStyle DESTROY 56
CursorStyle DESTROY gumby
.fam
.fi
.if n .RE
.sp
Alternatively, the cursor can be loaded from an (XPM, PNG or SVG)
image \fIfile\fP. If fvwm is compiled with Xcursor support, full ARGB is
used, and (possibly animated) cursor files made with the \fBxcursorgen\fP
program can be loaded. Otherwise the cursor is converted to
monochrome.
.sp
The optional \fIx\fP and \fIy\fP arguments (following a \fIfile\fP 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.
.sp
.if n .RS 4
.nf
.fam C
CursorStyle ROOT cursor_image.png 0 0
.fam
.fi
.if n .RE
.sp
The optional \fIfg\fP and \fIbg\fP 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.
.sp
.if n .RS 4
.nf
.fam C
CursorStyle ROOT nice_arrow.xpm yellow black
.fam
.fi
.if n .RE
.sp
\fBDefaultFont\fP [\fIfontname\fP]
.RS 4
\fBDefaultFont\fP sets the default font to font \fIfontname\fP. 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 \fBStyle\fP *
\fIFont\fP, \fBStyle\fP * \fIIconFont\fP, or \fBMenuStyle\fP commands.
.RE
.sp
\fBDefaultIcon\fP \fIfilename\fP
.RS 4
Sets the default icon which is used if a window has neither an
client\-supplied icon nor an icon supplied via the \fIIcon\fP option of the
\fBStyle\fP command.
.RE
.sp
\fBDefaultLayers\fP \fIbottom\fP \fIput\fP \fItop\fP
.RS 4
Changes the layers that are used for the \fIStaysOnBottom\fP, \fIStaysPut\fP,
\fIStaysOnTop\fP \fBStyle\fP options. Initially, the layers 2, 4 and 6 are
used.
.RE
.sp
\fBDeschedule\fP [\fIcommand_id\fP]
.RS 4
Removes all commands that were scheduled with the id \fIcommand_id\fP with
the \fBSchedule\fP command from the list of commands to be executed unless
they were already executed. If the \fIcommand_id\fP is omitted, the value
of the variable $[schedule.last] is used as the id.
.RE
.sp
\fBEmulate\fP Fvwm | Mwm | Win
.RS 4
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 \fBEmulate\fP with \fIMwm\fP or \fIWin\fP 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 \fIManualPlacement\fP description.
.RE
.sp
\fBEscapeFunc\fP
.RS 4
By default the key sequence Ctrl\-Alt\-Escape allows for escaping from a
\fBWait\fP pause and from a locked \fBModuleSynchronous\fP command. The
\fBEscapeFunc\fP command used with the \fBKey\fP command allows for
configuring this key sequence. An example:
.sp
.if n .RS 4
.nf
.fam C
Key Escape A MC \-
Key Escape A S EscapeFunc
.fam
.fi
.if n .RE
.sp
replaces the Ctrl\-Alt\-Escape key sequence with Shift\-Escape for aborting a
\fBWait\fP pause and \fBModuleSynchronous\fP command. \fBEscapeFunc\fP used outside the
\fBKey\fP command does nothing.
.RE
.sp
\fBFakeClick\fP [\fIcommand\fP \fIvalue\fP] ...
.RS 4
This command is mainly intended for debugging fvwm and no guarantees
are made that it works for you. \fIFakeClick\fP 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
\fIcommand\fP tokens and integer \fIvalues\fP, The \fIpress\fP and \fIrelease\fP
commands are followed by the appropriate mouse button number and
generate a button press or release event on the window below the
pointer. The \fIwait\fP commands pauses fvwm for the given number of
milliseconds. The \fImodifiers\fP 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 \fIdepth\fP 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\(cqs 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.
.sp
.if n .RS 4
.nf
.fam C
FakeClick depth 2 press 1 wait 250 release 1
.fam
.fi
.if n .RE
.sp
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.
.RE
.sp
\fBFakeKeypress\fP [\fIcommand\fP \fIvalue\fP] ...
.RS 4
This command is mainly intended for debugging fvwm and no guarantees
are made that it works for you. \fBFakeKeypress\fP 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 \fIpress\fP and \fIrelease\fP commands are followed by
a key name. The key name is a standard X11 key name as defined in
\fI/usr/include/X11/keysymdef.h\fP, (without the \fIXK_\fP prefix), or the
keysym database \fI/usr/X11R6/lib/X11/XKeysymDB\fP. The \fIwait\fP,
\fImodifiers\fP and \fIdepth\fP commands are the same as those used by
\fBFakeClick\fP.
.sp
Save all GVim sessions with: "Esc:w\(rsn"
.sp
.if n .RS 4
.nf
.fam C
All (gvim) FakeKeypress press Escape \(rs
press colon \(rs
press w \(rs
press Return
.fam
.fi
.if n .RE
.sp
Save & exit all GVim sessions with: "Esc:wq\(rsn"
.sp
.if n .RS 4
.nf
.fam C
All (gvim) FakeKeypress press Escape \(rs
press colon \(rs
press w \(rs
press q \(rs
press Return
.fam
.fi
.if n .RE
.sp
Send A to a specific window:
.sp
.if n .RS 4
.nf
.fam C
WindowId 0x3800002 FakeKeypress press A
.fam
.fi
.if n .RE
.sp
Note: all command names can be abbreviated with their first letter.
.RE
.sp
\fBHilightColor\fP \fItextcolor\fP \fIbackgroundcolor\fP
.RS 4
This command is obsoleted by the \fBStyle\fP options \fIHilightFore\fP and
\fIHilightBack\fP. Please use
.sp
.if n .RS 4
.nf
.fam C
Style * HilightFore textcolor, HilightBack backgroundcolor
.fam
.fi
.if n .RE
.sp
instead.
.RE
.sp
\fBHilightColorset\fP [\fInum\fP]
.RS 4
This command is obsoleted by the \fBStyle\fP option \fIHilightColorset\fP.
Please use
.sp
.if n .RS 4
.nf
.fam C
Style * HilightColorset num
.fam
.fi
.if n .RE
.sp
instead.
.RE
.sp
\fBIconFont\fP [\fIfontname\fP]
.RS 4
This command is obsoleted by the \fBStyle\fP option \fIIconFont\fP. Please use
.sp
.if n .RS 4
.nf
.fam C
Style * IconFont fontname
.fam
.fi
.if n .RE
.sp
instead.
.RE
.sp
\fBIconPath\fP \fIpath\fP
.RS 4
This command is obsolete. Please use \fBImagePath\fP instead.
.RE
.sp
\fBImagePath\fP \fIpath\fP
.RS 4
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.
.sp
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.
.sp
The \fIpath\fP may contain environment variables such as \fI$HOME\fP (or
\fI${HOME}\fP). Further, a \*(Aq+\*(Aq in the \fIpath\fP is expanded to the previous
value of the path, allowing appending or prepending to the path
easily.
.sp
For example:
.sp
.if n .RS 4
.nf
.fam C
ImagePath $HOME/icons:+:/usr/include/X11/bitmaps
.fam
.fi
.if n .RE
.sp
Note: if the \fBFvwmM4\fP module is used to parse your \fIconfig\fP files,
then m4 may want to mangle the word "include" which frequently shows
up in the \fBImagePath\fP command. To fix this one may add
.sp
.if n .RS 4
.nf
.fam C
undefine(`include\*(Aq)
.fam
.fi
.if n .RE
.sp
prior to the \fBImagePath\fP command, or better: use the \fB\-m4\-prefix\fP
option to force all \fBm4\fP directives to have a prefix of "m4_" (see the
\fBFvwmM4\fP man page).
.RE
.sp
\fBLocalePath\fP \fIpath\fP
.RS 4
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 (\*(Aq;\*(Aq). As an example
the default locale path is:
.sp
.if n .RS 4
.nf
.fam C
/install_prefix/share/locale;fvwm
.fam
.fi
.if n .RE
.sp
where install_prefix is the fvwm installation directory. With such a
locale path translations are searched for in
.sp
.if n .RS 4
.nf
.fam C
/install_prefix/share/locale/lang/LC_MESSAGES/fvwm.mo
.fam
.fi
.if n .RE
.sp
where \fIlang\fP depends on the locale. If no directory is given the
default directory path is assumed. If no text domain is given, \fBfvwm\fP
is assumed. Without argument the default locale path is restored.
.sp
As for the \fBImagePath\fP command, \fIpath\fP may contain environment
variables and a \*(Aq+\*(Aq to append or prepend the locale path easily.
.sp
For example, the fvwm\-themes package uses
.sp
.if n .RS 4
.nf
.fam C
LocalePath ";fvwm\-themes:+"
.fam
.fi
.if n .RE
.sp
to add locale catalogs.
.sp
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 \fBFvwmForm\fP 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.
.sp
The main use of locale catalogs is via the "$[gt.string]" parameter:
.sp
.if n .RS 4
.nf
.fam C
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
.fam
.fi
.if n .RE
.sp
gives a menu in the locale languages if translations are available.
.sp
Note that the \fBFvwmScript\fP 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.
.RE
.sp
\fBPixmapPath\fP \fIpath\fP
.RS 4
This command is obsolete. Please use \fBImagePath\fP instead.
.RE
.sp
\fBPrintInfo\fP \fIsubject\fP [\fIverbose\fP]
.RS 4
Print information on \fIsubject\fP to debug log file, which defaults to
\fI$HOME/.fvwm/fvwm3\-output.log\fP . Environment variables \fI$FVWM_USERDIR\fP
and \fI$FVWM3_LOGFILE\fP can alter this default. For this logfile to be
written, either fvwm3 has to be started with \fB\-v\fP option or \fBSIGUSR2\fP
signal can be used to toggle opening/closing debug log file.
.sp
An optional integer argument to debug log file, which defaults to
\fI$HOME/.fvwm/fvwm3\-output.log\fP . Environment variables \fI$FVWM_USERDIR\fP
and \fI$FVWM3_LOGFILE\fP can alter this default. For this logfile to be
written, either fvwm3 has to be started with \fB\-v\fP option or \fBSIGUSR2\fP
signal can be used to toggle opening/closing debug log file.
.sp
An optional integer argument \fIverbose\fP defines the level of
information which is given. The current valid subjects are:
.sp
\fIColors\fP which prints information about the colors used by fvwm. This
useful on screens which can only display 256 (or less) colors at once.
If \fIverbose\fP 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.
.sp
\fIImageCache\fP which prints information about the images loaded by fvwm.
If \fIverbose\fP is one or greater all images in the cache will be listed
together with their respective reuse.
.sp
\fILocale\fP which prints information on your locale and the fonts that
fvwm used. \fIverbose\fP can be 1 or 2.
.sp
\fInls\fP which prints information on the locale catalogs that fvwm used
.sp
\fIstyle\fP which prints information on fvwm styles. \fIverbose\fP can be 1.
.sp
\fIbindings\fP which prints information on all the bindings fvwm has: key
and mouse bindings. \fIverbose\fP has no effect with this option.
.sp
\fIinfostore\fP which prints information on all entries in the infostore,
listing the key and its value. \fIverbose\fP has no effect with this
option.
.RE
.sp
\fBSchedule\fP [Periodic] \fIdelay_ms\fP [\fIcommand_id\fP] \fIcommand\fP
.RS 4
The \fIcommand\fP is executed after about \fIdelay_ms\fP milliseconds. This
may be useful in some tricky setups. The \fIcommand\fP is executed in the
same context window as the \fBSchedule\fP command. An optional integer
argument \fIcommand_id\fP may be given in decimal, hexadecimal or octal
format. This id can be used with the \fBDeschedule\fP 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 \fBSchedule\fP command. Note that the \fBSchedule\fP command
and its arguments undergo the usual command line expansion, and, when
\fIcommand\fP 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.
.sp
Note: A window\(cqs id as it is returned with $[w.id] can be used as the
\fIcommand_id\fP. Example:
.sp
.if n .RS 4
.nf
.fam C
Current Schedule 1000 $[w.id] WindowShade
.fam
.fi
.if n .RE
.sp
The \fBSchedule\fP command also supports the optional keyword \fIPeriodic\fP
which indicates that the \fIcommand\fP should be executed every
\fIdelay_ms\fP. Example:
.sp
.if n .RS 4
.nf
.fam C
Schedule Periodic 10000 PipeRead \*(Aq[ \-N "$MAIL" ] && echo \(rs
Echo You have mail\*(Aq
.fam
.fi
.if n .RE
.sp
Use the \fBDeschedule\fP command to stop periodic commands.
.RE
.sp
\fBState\fP \fIstate\fP [\fIbool\fP]
.RS 4
Sets, clears or toggles one of the 32 user defined states which are associated
with each window. The \fIstate\fP is a number ranging from 0 to 31. The states
have no meaning in fvwm, but they can be checked in conditional commands like
\fBNext\fP with the \fIState\fP condition. The optional argument \fIbool\fP is a boolean
argument. "True" sets the given state, while "False" clears it. Using "toggle"
switches to the opposite state. If the \fIbool\fP argument is not given, the state
is toggled.
.RE
.sp
\fBWindowFont\fP [\fIfontname\fP]
.RS 4
This command is obsoleted by the \fBStyle\fP option \fIFont\fP. Please use
.sp
.if n .RS 4
.nf
.fam C
Style * Font fontname
.fam
.fi
.if n .RE
.sp
instead.
.RE
.sp
\fBWindowList\fP [(\fIconditions\fP)] [\fIposition\fP] [\fIoptions\fP] [\fIdouble\-click\-action\fP]
.RS 4
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.
.sp
The format of the geometry part is: \fIdesk\fP(\fIlayer\fP): \fIx\-geometry\fP
\fIsticky\fP, where \fIdesk\fP and \fIlayer\fP are the corresponding numbers and
\fIsticky\fP 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:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc WindowListFunc
+ I Iconify off
+ I FlipFocus
+ I Raise
+ I WarpToWindow 5p 5p
.fam
.fi
.if n .RE
.sp
You can destroy the built\-in "WindowListFunc" and create your own if
these defaults do not suit you.
.sp
The window list menu uses the "WindowList" menu style if it is defined
(see \fBMenuStyle\fP command). Otherwise the default menu style is used.
To switch back to the default menu style, issue the command
.sp
.if n .RS 4
.nf
.fam C
DestroyMenuStyle WindowList
.fam
.fi
.if n .RE
.sp
Example:
.sp
.if n .RS 4
.nf
.fam C
MenuStyle WindowList SelectOnRelease Meta_L
.fam
.fi
.if n .RE
.sp
The \fIconditions\fP can be used to exclude certain windows from the
window list. Please refer to the \fBCurrent\fP command for details. Only
windows that match the given conditions are displayed in the window
list. The \fIoptions\fP below work vice versa: windows that would
otherwise not be included in the window list can be selected with
them. The \fIconditions\fP always override the \fIoptions\fP.
.sp
The \fIposition\fP arguments are the same as for \fBMenu\fP. The command
\fIdouble\-click\-action\fP 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 \fIdouble\-click\-action\fP must be quoted if it consists
of more than one word.
.sp
The \fIdouble\-click\-action\fP is useful to define a default window if you
have bound the window list to a key (or button) like this:
.sp
.if n .RS 4
.nf
.fam C
# 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"
.fam
.fi
.if n .RE
.sp
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 \fISelectOnRelease\fP menu style (see example above) a window is selected
as soon as you release the Alt key.
.sp
The \fIoptions\fP passed to WindowList are separated by commas and can be
\fIGeometry\fP / \fINoGeometry\fP / \fINoGeometryWithInfo\fP, \fINoDeskNum,\fP
\fINoLayer,\fP \fINoNumInDeskTitle\fP, \fINoCurrentDeskTitle\fP, \fIMaxLabelWidth
width\fP, \fITitleForAllDesks\fP, \fIFunction funcname\fP, \fIDesk desknum\fP,
\fICurrentDesk\fP, \fINoIcons\fP / \fIIcons\fP / \fIOnlyIcons\fP, \fINoNormal\fP /
\fINormal\fP / \fIOnlyNormal\fP, \fINoSticky\fP / \fISticky\fP / \fIOnlySticky\fP,
\fINoStickyAcrossPages\fP / \fIStickyAcrossPages\fP / \fIOnlyStickyAcrossPages\fP,
\fINoStickyAcrossDesks\fP / \fIStickyAcrossDesks\fP / \fIOnlyStickyAcrossDesks\fP,
\fINoOnTop\fP / \fIOnTop\fP / \fIOnlyOnTop\fP, \fINoOnBottom\fP / \fIOnBottom\fP /
\fIOnlyOnBottom\fP, \fILayer m [n]\fP, \fIUseSkipList\fP / \fIOnlySkipList\fP,
\fINoDeskSort\fP, \fIReverseOrder\fP, \fICurrentAtEnd\fP, \fIIconifiedAtEnd\fP,
\fIUseIconName\fP, \fIAlphabetic\fP / \fINotAlphabetic\fP, \fISortByResource\fP,
\fISortByClass\fP, \fINoHotkeys\fP, \fISelectOnRelease\fP.
.sp
(Note \- normal means not iconic, sticky, or on top)
.sp
With the \fISortByResource\fP option windows are alphabetically sorted
first by resource class, then by resource name and then by window name
(or icon name if \fIUseIconName\fP is specified). \fIReverseOrder\fP also
works in the expected manner.
.sp
With the \fISortByClass\fP option windows are sorted just like with
\fISortByResource\fP, but the resource name is not taken into account,
only the resource class.
.sp
The \fISelectOnRelease\fP option works exactly like the \fBMenuStyle\fP option
with the same name, but overrides the option given in a menu style. By
default, this option is set to the left
.sp
key. To switch it off, use \fISelectOnRelease\fP without a key name.
.sp
If you pass in a function via \fBFunction\fP funcname, it is called within
a window context of the selected window:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc IFunc I Iconify toggle
WindowList Function IFunc, NoSticky, CurrentDesk, NoIcons
.fam
.fi
.if n .RE
.sp
If you use the \fILayer\fP \fIm\fP [\fIn\fP] option, only windows in layers
between m and n are displayed. n defaults to m. With the
\fIReverseOrder\fP option the order of the windows in the list is
reversed.
.sp
With the \fICurrentAtEnd\fP 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.
.sp
\fIIconifiedAtEnd\fP makes iconified windows be moved to the end of the
list. This is also from another GUI.
.sp
The \fINoGeometry\fP option causes fvwm to not display the geometries as
well as the separators which indicate the different desktops.
\fINoGeometryWithInfo\fP removes the geometries, but keep the desktop
information and indicates iconic windows. \fINoDeskNum\fP causes fvwm to
not display the desktop number in the geometry or before the window
title with the \fINoGeometryWithInfo\fP option. \fINoNumInDeskTitle\fP is only
useful if a desktop name is defined with the \fBDesktopName\fP 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 \fIDesk\fP condition is used.
The \fINoCurrentDeskTitle\fP option removes this title. \fITitleForAllDesks\fP
causes fvwm to add a menu title with the desk name and/or number
before each group of windows on the same desk. With \fINoLayer\fP, the
layer of the window is not displayed. The options \fIShowPage\fP,
\fIShowPageX\fP and \fIShowPageY\fP enable displaying the page of the window
rounded multiples of the display size. With \fIShowScreen\fP, the window\(cqs
screen name is displayed.
.sp
The \fIMaxLabelWidth\fP option takes the number of characters to print as
its argument. No more than that many characters of the window name are
visible.
.sp
If you wanted to use the \fBWindowList\fP as an icon manager, you could
invoke the following:
.sp
.if n .RS 4
.nf
.fam C
WindowList OnlyIcons, Sticky, OnTop, Geometry
.fam
.fi
.if n .RE
.sp
(Note \- the \fIOnly\fP options essentially wipe out all other ones... but
the \fIOnlyListSkip\fP option which just causes \fBWindowList\fP to only
consider the windows with \fIWindowListSkip\fP style.)
.RE
.sp
\fBXSync\fP
.RS 4
When \fBXSync\fP 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.
.RE
.sp
\fBXSynchronize\fP [bool]
.RS 4
The \fBXSynchronize\fP 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 \fBbool\fP
argument. Fvwm defaults to synchronized requests when started with the
\fB\-\-debug\fP option. This command is intended for debugging only.
.RE
.sp
\fB+\fP
.RS 4
Used to continue adding to the last specified decor, function or menu.
See the discussion for \fBAddToDecor\fP, \fBAddToFunc\fP, and \fBAddToMenu\fP.
.RE
.SS "Window Movement and Placement"
.sp
\fBAnimatedMove\fP \fIx\fP \fIy\fP [Warp]
.RS 4
Move a window in an animated fashion. Similar to \fBMove\fP command. The
options are the same, except they are required, since it doesn\(cqt make
sense to have a user move the window interactively and animatedly. If
the optional argument \fIWarp\fP is specified the pointer is warped with
the window.
.RE
.sp
\fBGeometryWindow\fP Hide | Show | Colorset \fIn\fP | Position \fIx\fP \fIy\fP | Screen \fIS\fP
.RS 4
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.
.RS 3
.ll -.6i
.sp
\fBGeometryWindow\fP Hide [Never | Move | Resize]
.br
.RE
.ll
.sp
Hides or switches off the geometry window. If the optional parameters \fIMove\fP
or \fIResize\fP are given, it will only hide the geometry window during the
respective operation. The parameter \fINever\fP will switch the geometry back on
again (equivalent to \fIShow\fP).
.RS 3
.ll -.6i
.sp
\fBGeometryWindow\fP Show [Never | Move | Resize]
.br
.RE
.ll
.sp
Shows or switches on the geometry window (equivalent to \fIHide Never\fP). If
the optional parameters \fIMove\fP or \fIResize\fP are given, it will only show the
geometry window during the respective operation. The parameter \fINever\fP will
switch the geometry window off (equivalent to \fIHide\fP).
.RS 3
.ll -.6i
.sp
\fBGeometryWindow\fP Colorset \fIcset\fP
.br
.RE
.ll
.sp
Sets colorset of the gometry window to \fIcset\fP. Use the literal option
\fIdefault\fP for \fIcset\fP to use the default colorset.
.RS 3
.ll -.6i
.sp
\fBGeometryWindow\fP Position [+|\-]\fIx\fP[p] [+|\-]\fIy\fP[p]
.br
.RE
.ll
.sp
Configures the position the geometry window appears. \fIx\fP and \fIy\fP are the
relative coordinates as a percentage of the screen size. If a leading \*(Aq\-\*(Aq
is provided the coordinates are computed from the left/bottom of the screen
respectively. If the coordinates are appended with a \*(Aqp\*(Aq, they are interpreted
as the number of pixels from the respective screen edge. If no position
arguments are given, the geometry window\(cqs position will return to its default
state of the upper left corner or the center if emulating MWM.
.RS 3
.ll -.6i
.sp
\fBGeometryWindow\fP Screen \fIRANDRNAME\fP
.br
.RE
.ll
.sp
Configure which screen the geometry window is shown on. By default the
geometry window is shown on the current screen. If a valid \fIRANDRNAME\fP
is provided, the geometry window will always be shown on that screen.
Use \fIcurrent\fP as the \fIRANDRNAME\fP to return the default.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
# 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
.fam
.fi
.if n .RE
.RE
.sp
\fBHideGeometryWindow\fP [Never | Move | Resize]
.RS 4
This command has been depreciated and is now obsolete. Use
\fBGeometryWindow Hide\fP instead.
.RE
.sp
\fBLayer\fP [\fIarg1\fP \fIarg2\fP] | [default]
.RS 4
Puts the current window in a new layer. If \fIarg1\fP is non zero then the
next layer is the current layer number plus \fIarg1\fP. If \fIarg1\fP is zero
then the new layer is \fIarg2\fP.
.sp
As a special case, \fIdefault\fP 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.
.RE
.sp
\fBLower\fP
.RS 4
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
.sp
.if n .RS 4
.nf
.fam C
AddToFunc lower\-to\-bottom
+ I Layer 0 0
+ I Lower
.fam
.fi
.if n .RE
.RE
.sp
\fBMove\fP [\fIoptions\fP]
.RS 4
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.
.sp
\fBMove\fP without options starts an interactive move. The window may snap to
other windows and screen boundaries, configurable with the \fBSnapAttraction\fP
style. Moving a window to the edge of the screen can be used to drag the
window to other pages. (See \fBEdgeScroll\fP, and the \fIEdgeMoveDelay\fP style for
more information.)
.sp
Holding down \fIAlt\fP disables snapping and allows one to switch pages
without any delay. Interactive movement can be aborted with the
\fIEscape\fP 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 \fBMouse\fP command with special context \*(AqP\*(Aq for Placement.
.sp
The window condition \fIPlacedByButton\fP can be used to check if a
specific button was pressed to place the window (see \fBCurrent\fP
command).
.sp
If the single argument \fIpointer\fP 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 \fBFvwmPager\fP.
.RS 3
.ll -.6i
.sp
\fBMove\fP pointer
.br
.RE
.ll
.sp
To move a window in a given direction until it hits another window, icon,
or screen boundary use:
.RS 3
.ll -.6i
.sp
\fBMove\fP shuffle [Warp] [ewmhiwa] [snap \fItype\fP] [layers \fImin\fP \fImax\fP] \fIdirection\fP(s)
.br
.RE
.ll
.sp
The \fIdirection\fP can be \fINorth\fP/\fIN\fP/\fIUp\fP/\fIU\fP, \fIEast\fP/\fIE\fP/\fIRight\fP/\fIR\fP,
\fISouth\fP/\fIS\fP/\fIDown\fP/\fID\fP, or \fIWest\fP/\fIW\fP/\fILeft\fP/\fIL\fP. The window will move
in the given direction until it hits another window or the
\fBEwmhBaseStruts\fP/screen boundary. When a window is at the
\fBEwmhBaseStruts\fP/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 \fBEwmhBaseStruts\fP unless the literal option \fIewmhiwa\fP is given. If
multiple \fIdirection\fP(s) are given, the window will move the directions
in the order of the sequence stated.
.sp
The literal option \fIWarp\fP will warp the mouse pointer to the window.
If the literal option \fIsnap\fP followed by a snap \fItype\fP of \fIwindows\fP,
\fIicons\fP, or \fIsame\fP is given, then the window will only stop if it hits
another window, icon, or the same type. If the literal option \fIlayers\fP
followed by a \fImin\fP layer and \fImax\fP layer is given, then only windows on
the layers between \fImin\fP and \fImax\fP layers will stop the window. For example:
.sp
.if n .RS 4
.nf
.fam C
# 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
.fam
.fi
.if n .RE
.sp
\fBMove\fP can be used to moved a window to a specified position:
.RS 3
.ll -.6i
.sp
\fBMove\fP [screen \fIS\fP] [w | m]\fIx\fP[p | w] [w | m]\fIy\fP[p | w] [Warp] [ewmhiwa]
.br
.RE
.ll
.sp
This will move the window to the \fIx\fP and \fIy\fP position (see below).
By default, the EWMH working area is honoured. If he trailing option
\fIewmhiwa\fP is given, then the window position will ignore the working
area (such as ignoring any values set via \fBEwmhBaseStruts\fP). If the
option \fIWarp\fP is given then the pointer is warped to the window.
.sp
If the literal option \fIscreen\fP followed by a RandR screen name \fIS\fP 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 \fIscreen\fP is
interpreted as in the \fBMoveToScreen\fP command.
.sp
The positional arguments \fIx\fP and \fIy\fP 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 \*(Aq\fIp\fP\*(Aq changes the interpretation to mean pixels,
while a trailing \*(Aq\fIw\fP\*(Aq means percent of the window width/height. To move the
window relative to its current position, add the \*(Aq\fIw\fP\*(Aq (for "window") prefix
before the \fIx\fP and/or \fIy\fP value. To move the window to a position relative to
the current location of the pointer, add the \*(Aq\fIm\fP\*(Aq (for "mouse") prefix. To
leave either coordinate unchanged, "\fIkeep\fP" can be specified in place of
\fIx\fP or \fIy\fP.
.sp
For advanced uses, the arguments \fIx\fP and \fIy\fP can be used multiple
times, but without the prefix \*(Aq\fIm\fP\*(Aq or \*(Aq\fIw\fP\*(Aq. (See complex examples
below).
.sp
Simple Examples:
.sp
.if n .RS 4
.nf
.fam C
# 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
.fam
.fi
.if n .RE
.sp
More complex examples (these can be bound as actions to keystrokes,
etc.; only the command is shown, though):
.sp
.if n .RS 4
.nf
.fam C
# 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
.fam
.fi
.if n .RE
.sp
See also the \fBAnimatedMove\fP command.
.RE
.sp
\fBMoveToDesk\fP [prev | \fIarg1\fP [\fIarg2\fP] [\fImin\fP \fImax\fP]]
.RS 4
Moves the selected window to another desktop. The arguments are the
same as for the \fBGotoDesk\fP command. Without any arguments, the window
is moved to the current desk. \fBMoveToDesk\fP is a replacement for the
obsolete \fBWindowsDesk\fP command, which can no longer be used.
.RE
.sp
\fBMoveThreshold\fP [\fIpixels\fP]
.RS 4
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
\fIpixels\fP pixels it is assumed to be a drag.
.sp
Previous versions of fvwm hardwired \fIpixels\fP to 3, which is now the
default value. If \fIpixels\fP is negative or omitted the default value
(which might be increased when 16000x9000 pixel displays become
affordable) is restored.
.RE
.sp
\fBMoveToPage\fP [\fIoptions\fP] [\fIx\fP[p | w] \fIy\fP[p | w]] | [prev]
.RS 4
Moves the selected window to another page (\fIx\fP,\fIy\fP). 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 \fBDesktopSize\fP
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 \fIx\fP and \fIy\fP 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
\*(Aq\fIp\fP\*(Aq after any or both numerical arguments. To move the window
relative to its current location, add a trailing \*(Aq\fIw\fP\*(Aq. To move a
window to the previous page use \fIprev\fP as the single argument.
.sp
Windows are usually not moved beyond desk boundaries.
.sp
Possible \fIoptions\fP are \fIwrapx\fP and \fIwrapy\fP to wrap around the x or y
coordinate when the window is moved beyond the border of the desktop.
For example, with \fIwrapx\fP, when the window moves past the right edge
of the desktop, it reappears on the left edge. The options
\fInodesklimitx\fP and \fInodesklimity\fP allow moving windows beyond the desk
boundaries in x and y direction (disabling the \fIwrapx\fP and \fIwrapy\fP
options).
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
# 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
.fam
.fi
.if n .RE
.RE
.sp
\fBMoveToScreen\fP [\fIscreen\fP]
.RS 4
Moves the selected window to another screen. The \fIscreen\fP argument
must be a valid RandR name.
.RE
.sp
\fBOpaqueMoveSize\fP [\fIpercentage\fP]
.RS 4
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
.sp
.if n .RS 4
.nf
.fam C
OpaqueMoveSize 0
.fam
.fi
.if n .RE
.sp
all windows are moved using the traditional rubber\-band outline. With
.sp
.if n .RS 4
.nf
.fam C
OpaqueMoveSize unlimited
.fam
.fi
.if n .RE
.sp
or if a negative percentage is given all windows are moved as solid
windows. The default is
.sp
.if n .RS 4
.nf
.fam C
OpaqueMoveSize 5
.fam
.fi
.if n .RE
.sp
which allows small windows to be moved in an opaque manner but large
windows are moved as rubber\-bands. If \fIpercentage\fP is omitted or
invalid the default value is set. To resize windows in an opaque
manner you can use the \fIResizeOpaque\fP style. See the \fBStyle\fP command.
.RE
.sp
\fBPlaceAgain\fP [Anim] [Icon]
.RS 4
Causes the current window\(cqs 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 \fISmart\fP or \fIClever\fP (\fIReallySmart\fP) placement. With the optional
argument \fIAnim\fP an animated move is used to place the window in its
new position. With the additional option \fIIcon\fP, the icon is placed
again instead.
.RE
.sp
\fBRaise\fP
.RS 4
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
.sp
.if n .RS 4
.nf
.fam C
AddToFunc raise\-to\-top
+ I Layer 0 ontop
+ I Raise
.fam
.fi
.if n .RE
.sp
where ontop is the highest layer used in your setup.
.RE
.sp
\fBRaiseLower\fP
.RS 4
Alternately raises and lowers a window. The window is raised if it is
obscured by any window (except for its own transients when
\fIRaiseTransient\fP style is used; see the \fBStyle\fP command) otherwise it
is lowered.
.RE
.sp
\fBResize\fP [[frame] [direction \fIdir\fP] [warptoborder \fIautomatic\fP] [fixeddirection] \fIwidth\fP[p | c | wa | da] \fIheight\fP[p | c]]
.RS 4
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.
.sp
\fBResize\fP without options starts an interactive resize.
.sp
If the \fIEdgeResizeDelay\fP style is set or the \fIAlt\fP key is held down,
the window can be resized across the edge of the screen.
.sp
The operation can be aborted with the \fIEscape\fP key or by pressing
any mouse button (except button 1 which confirms it).
.sp
If the optional arguments \fIwidth\fP and \fIheight\fP are provided, then the
window is resized so that its dimensions are \fIwidth\fP by \fIheight\fP. The
units of \fIwidth\fP and \fIheight\fP are percent\-of\-screen, unless a letter
\*(Aq\fIp\fP\*(Aq is appended to one or both coordinates, in which case the
location is specified in pixels. With a \*(Aq\fIc\fP\*(Aq suffix the unit defined
by the client application (hence the c) is used. With the suffix
\*(Aq\fIwa\fP\*(Aq the value is a percentage of the width or height size of the
EWMH working area, and with the suffix \*(Aq\fIda\fP\*(Aq it is a percentage of
the width or height of the EWMH dynamic working area. So you can say
.sp
.if n .RS 4
.nf
.fam C
Resize 80c 24c
.fam
.fi
.if n .RE
.sp
to make a terminal window just big enough for 80x24 characters.
.sp
If the \fIwidth\fP or \fIheight\fP is prefixed with the letter \*(Aq\fIw\fP\*(Aq the size
is not taken as an absolute value but added to the current size of the
window. Example:
.sp
.if n .RS 4
.nf
.fam C
# Enlarge window by one line
Resize keep w+1c
.fam
.fi
.if n .RE
.sp
Both, \fIwidth\fP and \fIheight\fP can be negative. In this case the new size
is the screen size minus the given value. If either value is "\fIkeep\fP",
the corresponding dimension of the window is left untouched. The new
size is the size of the client window, thus
.sp
.if n .RS 4
.nf
.fam C
Resize 100 100
.fam
.fi
.if n .RE
.sp
may make the window bigger than the screen. To base the new size on
the size of the whole fvwm window, add the \fIframe\fP option after the
command. The options \fIfixeddirection\fP, \fIdirection\fP and \fIwarptoborder\fP
are only used in interactive move operations. With \fIfixeddirection\fP
the same border is moved even if the pointer moves past the opposite
border. The \fIdirection\fP 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 \fIautomatic\fP 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 \fIwarptoborder\fP option can be used to warp
the pointer to the direction indicated. As with the \fIautomatic\fP option
for \fIdirection\fP, the border to warp to is calculated based on the
pointer\(cqs 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.
.sp
.if n .RS 4
.nf
.fam C
AddToFunc ResizeSE I Resize Direction SE
Mouse 3 A M ResizeSE
.fam
.fi
.if n .RE
.RE
.sp
\fBResize\fP [bottomright | br \fIx\fP \fIy\fP]
.RS 4
An alternate syntax is used if the keyword \fIbottomright\fP or in short
\fIbr\fP follows the command name. In this case, the arguments \fIx\fP and \fIy\fP
specify the desired position of the bottom right corner of the window.
They are interpreted exactly like the \fIx\fP and \fIy\fP arguments of the \fBMove\fP
command. Actually, any of the options accepted by the \fBMove\fP command can
be used.
.RE
.sp
\fBResizeMaximize\fP [\fIresize\-arguments\fP]
.RS 4
Combines the effects of \fBResize\fP and \fBMaximize\fP 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 \fIresize\-arguments\fP are the
same as for the \fBResize\fP command.
.RE
.sp
\fBResizeMove\fP \fIresize\-arguments\fP \fImove\-arguments\fP
.RS 4
This command does the same as the \fBResize\fP and \fBMove\fP commands, but in
a single call which is less visually disturbing. The
\fIresize\-arguments\fP are exactly the same arguments as for the \fBResize\fP
command and the \fImove\-arguments\fP are exactly the same arguments as for
the \fBMove\fP command except the \fIpointer\fP option which is not supported
by the \fBResizeMove\fP command.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
# 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
.fam
.fi
.if n .RE
.sp
Note: Fvwm may not be able to parse the command properly if the option
\fIbottomright\fP of the \fBResize\fP command is used.
.RE
.sp
\fBResizeMoveMaximize\fP \fIresize\-arguments\fP \fImove\-arguments\fP
.RS 4
Combines the effects of \fBResizeMove\fP and \fBMaximize\fP 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
\fIresize\-arguments\fP and \fImove\-arguments\fP are the same as for the
\fBResizeMove\fP command.
.RE
.sp
\fBRestackTransients\fP
.RS 4
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 \fIRaiseTransient\fP or \fILowerTransient\fP style are affected
at all. When \fBRestackTransients\fP is used on a transient window with
the \fIStackTransientParent\fP style set, it is redirected to the parent
window.
.RE
.sp
\fBSetAnimation\fP \fImilliseconds\-delay\fP [\fIfractions\-to\-move\-list\fP]
.RS 4
Sets the time between frames and the list of fractional offsets to
customize the animated moves of the \fBAnimatedMove\fP command and the
animation of menus (if the menu style is set to animated; see
\fBMenuStyle\fP command). If the \fIfractions\-to\-move\-list\fP is omitted, only
the time between frames is altered. The \fIfractions\-to\-move\-list\fP
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.:
.sp
.if n .RS 4
.nf
.fam C
SetAnimation 10 \-.01 0 .01 .03 .08 .18 .3 \(rs
\&.45 .6 .75 .85 .90 .94 .97 .99 1.0
.fam
.fi
.if n .RE
.sp
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.
.RE
.sp
\fBSnapAttraction\fP [\fIproximity\fP [\fIbehaviour\fP] [Screen]]
.RS 4
The \fBSnapAttraction\fP command is obsolete. It has been replaced by the
\fBStyle\fP command option \fISnapAttraction\fP.
.RE
.sp
\fBSnapGrid\fP [\fIx\-grid\-size\fP \fIy\-grid\-size\fP]
.RS 4
The \fBSnapGrid\fP command is obsolete. It has been replaced by the
\fBStyle\fP command option \fISnapGrid\fP.
.RE
.sp
\fBWindowsDesk\fP \fIarg1\fP [\fIarg2\fP]
.RS 4
Moves the selected window to another desktop.
.sp
This command has been removed and must be replaced by \fBMoveToDesk\fP,
the arguments for which are the same as for the \fBGotoDesk\fP command.
.sp
.if n .RS 4
.nf
.fam C
+
*Important*
.fam
.fi
.if n .RE
.sp
You cannot simply change the name of the command: the syntax has
changed. If you used:
.sp
.if n .RS 4
.nf
.fam C
WindowsDesk n
.fam
.fi
.if n .RE
.sp
to move a window to desk n, you have to change it to:
.sp
.if n .RS 4
.nf
.fam C
MoveToDesk 0 n
.fam
.fi
.if n .RE
.RE
.sp
\fBXorPixmap\fP [\fIpixmap\fP]
.RS 4
Selects the pixmap with which bits are xor\(cqed when doing rubber\-band
window moving or resizing. This has a better chance of making the
rubber\-band visible if \fBXorValue\fP does not give good results. An
example pixmap \fIresize.rainbow.xpm\fP is provided with the icon
distribution. To turn the \fIXorPixmap\fP off again use the \fBXorValue\fP
command or omit the \fIpixmap\fP argument.
.RE
.sp
\fBXorValue\fP [\fInumber\fP]
.RS 4
Changes the value with which bits are xor\(cqed 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 \fInumber\fP is omitted or invalid.
.RE
.SS "Focus & Mouse Movement"
.sp
\fBCursorMove\fP \fIhorizontal\fP[p] \fIvertical\fP[p]
.RS 4
Moves the mouse pointer by \fIhorizontal\fP pages in the X direction and
\fIvertical\fP 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
\fBWarpToWindow\fP. Both horizontal and vertical values are expressed in
percent of pages, so
.sp
.if n .RS 4
.nf
.fam C
CursorMove 100 100
.fam
.fi
.if n .RE
.sp
means to move down and right by one full page.
.sp
.if n .RS 4
.nf
.fam C
CursorMove 50 25
.fam
.fi
.if n .RE
.sp
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
\*(Aq\fIp\fP\*(Aq to the horizontal and/or vertical specification. For example
.sp
.if n .RS 4
.nf
.fam C
CursorMove \-10p \-10p
.fam
.fi
.if n .RE
.sp
means move ten pixels up and ten pixels left. The CursorMove function
should not be called from pop\-up menus.
.RE
.sp
\fBFlipFocus\fP [NoWarp]
.RS 4
Executes a \fBFocus\fP 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 \fBWindowList\fP and placed at the start. This command
is recommended for use with the \fBDirection\fP command and in the
function invoked from \fBWindowList\fP.
.RE
.sp
\fBFocus\fP [NoWarp]
.RS 4
Sets the keyboard focus to the selected window. If the \fINoWarp\fP
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 \fBWarpToWindow\fP function). Does
not de\-iconify. This command does not alter the order of the
\fBWindowList\fP, it rotates the \fBWindowList\fP around so that the target
window is at the start.
.sp
When the \fINoWarp\fP argument is given, Focus cannot transfer the
keyboard focus to windows on other desks.
.sp
To raise and/or warp a pointer to a window together with \fBFocus\fP or
\fBFlipFocus\fP, use a function, like:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc SelectWindow
+ I Focus
+ I Iconify false
+ I Raise
+ I WarpToWindow 50 8p
.fam
.fi
.if n .RE
.RE
.sp
\fBWarpToWindow\fP [!raise | raise] \fIx\fP[p] \fIy\fP[p]
.RS 4
Warps the cursor to the associated window and raises it (unless the
option \fI!raise\fP is present). The parameters \fIx\fP and \fIy\fP default to
percentage of window down and in from the upper left hand corner (or
number of pixels down and in if \*(Aq\fIp\fP\*(Aq 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:
.sp
.if n .RS 4
.nf
.fam C
WindowId root 1 WarpToWindow 50 50
.fam
.fi
.if n .RE
.RE
.SS "Window State"
.sp
\fBClose\fP
.RS 4
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 \fBDestroy\fP command. Note: if the window accepts the delete
window protocol but does not close itself in response, the window is
not deleted.
.RE
.sp
\fBDelete\fP
.RS 4
Sends a message to a window asking that it remove itself, frequently
causing the application to exit.
.RE
.sp
\fBDestroy\fP
.RS 4
Destroys an application window, which usually causes the application
to crash and burn.
.RE
.sp
\fBIconify\fP [\fIbool\fP]
.RS 4
Iconifies a window if it is not already iconified or de\-iconifies it
if it is already iconified. The optional argument \fIbool\fP is a boolean
argument. "\fITrue\fP" means only iconification is allowed, while
"\fIFalse\fP" forces de\-iconification. Using "\fItoggle\fP" switches between
iconified and de\-iconified states.
.sp
There are a number of \fBStyle\fP options which influence the appearance
and behavior of icons (e.g. \fIStickyIcon\fP, \fINoIcon\fP).
.sp
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.
.RE
.sp
\fBMaximize\fP [\fIflags\fP] [\fIbool | forget\fP] [\fIhorizontal\fP[p]] [\fIvertical\fP[p]]
.RS 4
Without its optional arguments (or if the \fIbool\fP bit has the value
"\fItoggle\fP") \fBMaximize\fP 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 "\fITrue\fP" or "\fIFalse\fP" value for the
\fIbool\fP argument.
.sp
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 \fBResizeMaximize\fP and
\fBResizeMoveMaximize\fP. If the window is not maximized, nothing happens.
.sp
With the optional arguments \fIhorizontal\fP and \fIvertical\fP, which are
expressed as percentage of a full screen, the user can control the new
size of the window. An optional suffix \*(Aq\fIp\fP\*(Aq 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
\fIhorizontal\fP*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
\fIhorizontal\fP is "\fIgrow\fP", 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, "\fIgrowleft\fP" or "\fIgrowright\fP" can be used
respectively "\fIgrowup\fP" and "\fIgrowdown\fP". The optional \fIflags\fP
argument is a space separated list containing the following key words:
\fIfullscreen\fP, \fIewmhiwa\fP, \fIgrowonwindowlayer\fP, \fIgrowonlayers\fP and
\fIscreen\fP. \fIfullscreen\fP causes the window to become fullscreened if the
appropriate EWMH hint is set. \fIewmhiwa\fP causes fvwm to ignore the EWMH
working area. \fIgrowonwindowlayer\fP causes the various grow methods to
ignore windows with a layer other than the current layer of the window
which is maximized. The \fIgrowonlayers\fP 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. \fIscreen\fP
must have an argument which specifies the screen on which to operate.
.sp
Here are some examples. The following adds a title\-bar button to
switch a window to the full vertical size of the screen:
.sp
.if n .RS 4
.nf
.fam C
Mouse 0 4 A Maximize 0 100
.fam
.fi
.if n .RE
.sp
The following causes windows to be stretched to the full width:
.sp
.if n .RS 4
.nf
.fam C
Mouse 0 4 A Maximize 100 0
.fam
.fi
.if n .RE
.sp
This makes a window that is half the screen size in each direction:
.sp
.if n .RS 4
.nf
.fam C
Mouse 0 4 A Maximize 50 50
.fam
.fi
.if n .RE
.sp
To expand a window horizontally until any other window is found:
.sp
.if n .RS 4
.nf
.fam C
Mouse 0 4 A Maximize 0 grow
.fam
.fi
.if n .RE
.sp
To expand a window until any other window on the same or a higher
layer is hit.
.sp
.if n .RS 4
.nf
.fam C
Mouse 0 4 A Maximize growonlayers $[w.layer] \-1 grow grow
.fam
.fi
.if n .RE
.sp
To expand a window but leave the lower 60 pixels of the screen
unoccupied:
.sp
.if n .RS 4
.nf
.fam C
Mouse 0 4 A Maximize 100 \-60p
.fam
.fi
.if n .RE
.sp
Values larger than 100 can be used with caution.
.RE
.sp
\fBRefresh\fP
.RS 4
Causes all windows on the screen to redraw themselves. All pending
updates of all windows\*(Aq styles and looks are applied immediately. E.g.
if \fBStyle\fP or \fBTitleStyle\fP commands were issued inside a fvwm
function.
.RE
.sp
\fBRefreshWindow\fP
.RS 4
Causes the chosen window to redraw itself. All pending updates of the
window\(cqs style and look are applied immediately. E.g. if \fBStyle\fP or
\fBTitleStyle\fP commands were issued inside a fvwm function.
.RE
.sp
\fBStick\fP [\fIbool\fP]
.RS 4
If the \fIbool\fP argument is empty or "\fItoggle\fP", the \fBStick\fP 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 \fIbool\fP argument must be "True". To make it non\-sticky use
"False".
.RE
.sp
\fBStickAcrossPages\fP [\fIbool\fP]
.RS 4
Works like \fBStick\fP but only sticks a window across pages, not across desks.
.RE
.sp
\fBStickAcrossDesks\fP [\fIbool\fP]
.RS 4
Works like \fBStick\fP but only sticks a window across desks, not across
pages.
.RE
.sp
\fBWindowShade\fP [bool] | [[ShadeAgain] \fIdirection\fP]
.RS 4
Toggles the window shade feature for titled windows. Windows in the
shaded state only display a title\-bar. If \fIbool\fP is not given or
"\fItoggle\fP", the window shade state is toggled. If \fIbool\fP is "True",
the window is forced to the shaded state. If \fIbool\fP is "False", then
the window is forced to the non\-shaded state. To force shading in a
certain direction, the \fIdirection\fP argument can be used. Any of the
strings "\fINorth\fP", "\fISouth\fP", "\fIWest\fP", "\fIEast\fP", "\fINorthWest\fP",
"\fINorthEast\fP", "\fISouthWest\fP", "\fISouthEast\fP" or "\fILast\fP" can be given.
The direction can be abbreviated with the usual one or two letters
"\fIN\fP", "\fINW\fP", etc. Using a direction on a window that was already
shaded unshades the window. To shade it in a different direction, use
the \fIShadeAgain\fP option. The direction \fILast\fP 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
\fIWindowShadeSteps\fP, \fIWindowShadeShrinks\fP, \fIWindowShadeScrolls\fP,
\fIWindowShadeLazy\fP, \fIWindowShadeAlwaysLazy\fP and \fIWindowShadeBusy\fP
options of the \fBStyle\fP command. Examples:
.sp
.if n .RS 4
.nf
.fam C
Style * WindowShadeShrinks, WindowShadeSteps 20, \(rs
WindowShadeLazy
Mouse 1 \- S WindowShade North
Mouse 1 [ S WindowShade West
Mouse 1 ] S WindowShade E
Mouse 1 _ S WindowShade S
.fam
.fi
.if n .RE
.sp
Note: When a window that has been shaded with a \fIdirection\fP argument
changes the direction of the window title (see \fITitleAtTop\fP \fBStyle\fP
option), the shading direction does not change. This may look very
strange. Windows that were shaded without a \fIdirection\fP argument stay
shaded in the direction of the title bar.
.sp
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.
.RE
.sp
\fBWindowShadeAnimate\fP [\fIsteps\fP [p]]
.RS 4
This command is obsolete. Please use the \fIWindowShadeSteps\fP option of
the \fBStyle\fP command instead.
.RE
.SS "Mouse & Key Bindings"
.sp
\fBIgnoreModifiers\fP [\fIModifiers\fP]
.RS 4
Tells fvwm which modifiers to ignore when matching Mouse or Key
bindings. \fBIgnoreModifiers\fP affects the \fIClickToFocus\fP style too. This
command belongs into your \fIconfig\fP. 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
\fIconfig\fP file (e.g. with the \fBExec\fP command).
.sp
\fIModifiers\fP has the same syntax as in the \fBMouse\fP or \fBKey\fP bindings, with the
addition of \*(AqL\*(Aq meaning the caps lock key. The default is "L". \fIModifiers\fP
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 \*(Aq2\*(Aq usually is the num\-lock modifier and \*(Aq5\*(Aq refers to the
scroll\-lock key. To turn all these pesky modifiers off you can use this command:
.sp
.if n .RS 4
.nf
.fam C
IgnoreModifiers L25
.fam
.fi
.if n .RE
.sp
If the \fIModifiers\fP argument is the string "\fIdefault\fP", fvwm reverts
back to the default value "L".
.sp
\fBImportant\fP This command creates a lot of extra network traffic,
depending on your CPU, network connection, the number of \fBKey\fP or
\fBMouse\fP 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
.sp
if you have no problem with it. In the \fIFAQ\fP you can find a better
solution of this problem.
.RE
.sp
\fBEdgeCommand\fP [screen \fIRANDRNAME\fP] [\fIdirection\fP [\fIFunction\fP]]
.RS 4
Binds a specified fvwm command \fIFunction\fP to an edge of the screen.
Direction may be one of "\fINorth\fP", "\fITop\fP", "\fIWest\fP", "\fILeft\fP",
"\fISouth\fP", "\fIBottom\fP", "\fIRight\fP" and "\fIEast\fP". If \fIFunction\fP 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 \fIscreen\fP followed by a RandR screen name \fIRANDRNAME\fP is given,
the command is set only for the given monitor.
.sp
\fIFunction\fP is executed when the mouse pointer enters the invisible pan
frames that surround the visible screen. The binding works only if
\fBEdgeThickness\fP is set to a value greater than 0. If a function is
bound to an edge, scrolling specified by \fBEdgeScroll\fP 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.
\fBFvwmAuto\fP can be used get a delay when raising or lowering windows.
The following example raises \fBFvwmButtons\fP if the mouse pointer enters
the top edge of the screen.
.sp
.if n .RS 4
.nf
.fam C
# 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" \(rs
"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
.fam
.fi
.if n .RE
.sp
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.
.RE
.sp
\fBEdgeLeaveCommand\fP [screen \fIRANDRNAME\fP] [\fIdirection\fP [\fIFunction\fP]]
.RS 4
Binds a specified fvwm command \fIFunction\fP to an edge of the screen.
Direction may be one of "\fINorth\fP", "\fITop\fP", "\fIWest\fP", "\fILeft\fP",
"\fISouth\fP", "\fIBottom\fP", "\fIRight\fP" and "\fIEast\fP". If \fIFunction\fP 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 \fIscreen\fP followed by a RandR screen name \fIRANDRNAME\fP
is given, the command is set only for the given monitor.
.sp
\fIFunction\fP is executed when the mouse pointer leaves the invisible pan
frames that surround the visible screen. The binding works only if
\fBEdgeThickness\fP is set to a value greater than 0. If a function is
bound to an edge, scrolling specified by \fBEdgeScroll\fP 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.
\fBFvwmAuto\fP can be used get a delay when raising or lowering windows.
See example for \fBEdgeCommand\fP
.sp
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.
.RE
.sp
\fBKey\fP [(\fIwindow\fP)] \fIKeyname\fP \fIContext\fP \fIModifiers\fP \fIFunction\fP
.RS 4
Binds a keyboard key to a specified fvwm command, or removes the
binding if \fIFunction\fP is \*(Aq\-\*(Aq. The syntax is the same as for a \fBMouse\fP
binding except that the mouse button number is replaced with a
\fIKeyname\fP. Normally, the key binding is activated when the key is
pressed. \fIKeyname\fP is a standard X11 key name as defined in
\fI/usr/include/X11/keysymdef.h\fP, (without the \fIXK_\fP prefix), or the
keysym database \fI/usr/X11R6/lib/X11/XKeysymDB\fP. Only key names that
are generated with no modifier keys or with just the
.sp
key held are guaranteed to work. The \fIContext\fP and \fIModifiers\fP fields
are defined as in the \fBMouse\fP 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
\fISloppyFocus\fP or \fIClickToFocus\fP). Note that key bindings with the
\*(Aq\fIR\fP\*(Aq (root window) context do not work properly with \fISloppyFocus\fP
and \fIClickToFocus\fP. If you encounter problems, use the \fBPointerKey\fP
command instead. If you want to bind keys to a window with
\fISloppyFocus\fP or \fIClickToFocus\fP 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 \*(AqW\*(Aq context).
.sp
The special context \*(Aq\fIM\fP\*(Aq for menus can be used to (re)define the menu
controls. It be used alone or together with \*(AqT\*(Aq, \*(AqS\*(Aq, \*(AqI\*(Aq, \*(Aq[\*(Aq, \*(Aq]\*(Aq,
\*(Aq\-\*(Aq and \*(Aq_\*(Aq. See the \fBMenu Bindings\fP section for details.
.sp
The following example binds the built\-in window list to pop up when
.sp
is hit, no matter where the mouse pointer is:
.sp
.if n .RS 4
.nf
.fam C
Key F11 A SCM WindowList
.fam
.fi
.if n .RE
.sp
Binding a key to a title\-bar button causes that button to appear.
Please refer to the \fBMouse\fP command for details.
.RE
.sp
\fBMouse\fP [(\fIwindow\fP)] \fIButton\fP \fIContext\fP \fIModifiers\fP \fIFunction\fP
.RS 4
Defines a mouse binding, or removes the binding if \fIFunction\fP is \*(Aq\-\*(Aq.
\fIButton\fP is the mouse button number. If \fIButton\fP 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.
.sp
\fIContext\fP describes where the binding applies. Valid contexts are
\*(Aq\fIR\fP\*(Aq for the root window, \*(Aq\fIW\fP\*(Aq for an application window, \*(Aq\fID\fP\*(Aq for
a desktop application (as kdesktop or Nautilus desktop), \*(Aq\fIT\fP\*(Aq for a
window title\-bar, \*(Aq\fIS\fP\*(Aq for a window side, top, or bottom bar, \*(Aq\fI[\fP\*(Aq,
\*(Aq\fI]\fP\*(Aq, \*(Aq\fI\-\fP\*(Aq and \*(Aq\fI_\fP\*(Aq for the left, right, top or bottom side only,
\*(Aq\fIF\fP\*(Aq for a window frame (the corners), \*(Aq<\*(Aq, \*(Aq^\*(Aq, \*(Aq>\*(Aq and \*(Aq\fIv\fP\*(Aq for
the top left, top right, bottom right or bottom left corner, \*(Aq\fII\fP\*(Aq for
an icon window, or \*(Aq\fI0\fP\*(Aq through \*(Aq\fI9\fP\*(Aq for title\-bar buttons, or any
combination of these letters. \*(Aq\fIA\fP\*(Aq is for any context. For instance,
a context of "FST" applies when the mouse is anywhere in a window\(cqs
border except the title\-bar buttons. Only \*(AqS\*(Aq and \*(AqW\*(Aq are valid for an
undecorated window.
.sp
The special context \*(Aq\fIM\fP\*(Aq for menus can be used to (re)define the menu
controls. It can be used alone or together with \*(AqT\*(Aq, \*(AqS\*(Aq, \*(AqI\*(Aq, \*(Aq[\*(Aq,
\*(Aq]\*(Aq, \*(Aq\-\*(Aq and \*(Aq_\*(Aq. See the \fBMenu Bindings\fP section for details.
.sp
The special context \*(Aq\fIP\fP\*(Aq controls what buttons that can be used to
place a window. When using this context no modifiers are allowed
(\fIModifiers\fP must be N), no \fIwindow\fP is allowed, and the \fIFunction\fP
must be one of \fIPlaceWindow\fP, \fIPlaceWindowDrag\fP,
\fIPlaceWindowInteractive\fP, \fICancelPlacement\fP, \fICancelPlacementDrag\fP,
\fICancelPlacementInteractive\fP or \fI\-\fP.
.sp
\fIPlaceWindow\fP makes \fIButton\fP usable for window placement, both for
interactive and drag move. \fICancelPlacement\fP does the inverse. That is
makes \fIButton\fP 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 \fBEmulate\fP command. Also a window
being dragged can always be placed by releasing the button hold while
dragging, regardless of if it is set to \fIPlaceWindow\fP or not.
.sp
\fIPlaceWindowDrag\fP and \fIPlaceWindowInteractive\fP/\fICancelPlacementDrag\fP
and \fICancelPlacementInteractive\fP work as
\fIPlaceWindow\fP/\fICancelPlacement\fP with the exception that they only
affect either windows dragged / placed interactively.
.sp
\fI\-\fP is equivalent to \fICancelPlacement\fP.
.sp
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:
.sp
.if n .RS 4
.nf
.fam C
Mouse 0 P N PlaceWindow
Mouse 3 P N CancelPlacement
Mouse 1 P N CancelPlacementDrag
.fam
.fi
.if n .RE
.sp
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.
.sp
The following example shows how the same key\-binding can be used to
perform different functions depending on the window that is focused:
.sp
.if n .RS 4
.nf
.fam C
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
.fam
.fi
.if n .RE
.sp
A \*(Aq\fI\-\-\fP\*(Aq action indicates that the event should be propagated to the
specified window to handle. This is only a valid action for
window\-specific bindings.
.sp
This example shows how to display the WindowList when Button 3 is
pressed on an rxvt window:
.sp
.if n .RS 4
.nf
.fam C
Mouse (rxvt) 3 A A WindowList
.fam
.fi
.if n .RE
.sp
Note that Fvwm actually intercepts all events for a window\-specific
binding and (if the focused window doesn\(cqt 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 \fI~/.Xdefaults\fP file:
.sp
.if n .RS 4
.nf
.fam C
XTerm*allowSendEvents: true
.fam
.fi
.if n .RE
.sp
\fIModifiers\fP is any combination of \*(Aq\fIN\fP\*(Aq for no modifiers, \*(Aq\fIC\fP\*(Aq for
control, \*(Aq\fIS\fP\*(Aq for shift, \*(Aq\fIM\fP\*(Aq for Meta, \*(Aq\fIL\fP\*(Aq for Caps\-Lock or \*(Aq\fIA\fP\*(Aq
for any modifier. For example, a modifier of "SM" applies when both
the
.sp
and
.sp
keys are down. X11 modifiers mod1 through mod5 are represented as the
digits \*(Aq1\*(Aq through \*(Aq5\*(Aq. The modifier \*(AqL\*(Aq is ignored by default. To
turn it on, use the \fBIgnoreModifiers\fP command.
.sp
\fIFunction\fP is one of fvwm\(cqs commands.
.sp
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:
.sp
.if n .RS 4
.nf
.fam C
1 3 5 7 9 0 8 6 4 2
.fam
.fi
.if n .RE
.sp
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.
.RE
.sp
\fBPointerKey\fP [(\fIwindow\fP)] \fIKeyname\fP \fIContext\fP \fIModifiers\fP \fIFunction\fP
.RS 4
This command works exactly like the \fBKey\fP 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 \fBPointerKey\fP
command can for example be used to bind keys to the root window if you
are using \fISloppyFocus\fP or \fIClickToFocus\fP. 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
\fBPointerKey\fP command only for key combinations that are not needed in
any application window.
.sp
Example:
.sp
.if n .RS 4
.nf
.fam C
Style * SloppyFocus
PointerKey f1 a m Menu MainMenu
.fam
.fi
.if n .RE
.RE
.SS "Controlling Window Styles"
.sp
For readability, the commands in this section are not sorted
alphabetically. The description of the \fBStyle\fP command can be found at
the end of this section.
.sp
\fBFocusStyle\fP \fIstylename\fP \fIoptions\fP
.RS 4
works exactly like the \fBStyle\fP command, but accepts only the focus
policy related styles beginning with "FP". The prefix can be removed,
but at the cost of a little bit of time. \fBFocusStyle\fP is meant to make
the configuration file more readable. Example:
.sp
.if n .RS 4
.nf
.fam C
FocusStyle * EnterToFocus, !LeaveToUnfocus
.fam
.fi
.if n .RE
.sp
is equivalent to
.sp
.if n .RS 4
.nf
.fam C
Style * FPEnterToFocus, !FPLeaveToUnfocus
.fam
.fi
.if n .RE
.RE
.sp
\fBDestroyStyle\fP \fIstyle\fP
.RS 4
deletes the style named \fIstyle\fP. The changes take effect immediately.
Note that \fIstyle\fP is not a wild\-carded search string, but rather a
case\-sensitive string that should exactly match the original \fBStyle\fP
command.
.sp
Destroying style "*" can be done, but isn\(cqt really to be recommended.
For example:
.sp
.if n .RS 4
.nf
.fam C
DestroyStyle Application*
.fam
.fi
.if n .RE
.sp
This removes all settings for the style named "Application*", NOT all
styles starting with "Application".
.RE
.sp
\fBDestroyWindowStyle\fP
.RS 4
deletes the styles set by the \fBWindowStyle\fP command on the selected
window. The changes take effect immediately.
.RE
.sp
\fBUpdateStyles\fP
.RS 4
All pending updates of all windows\*(Aq styles and looks are applied
immediately. E.g. if \fBStyle\fP, \fIWindowStyle\fP or \fITitleStyle\fP commands
were issued inside a fvwm function.
.RE
.sp
\fBStyle\fP \fIstylename\fP \fIoptions\fP ...
.RS 4
The \fBStyle\fP command is used to set attributes of a window to values
other than the default or to set the window manager default styles.
.sp
\fIstylename\fP can be a window\(cqs name, class, visible name, or resource
string. It may contain the wildcards \*(Aq\fB\*(Aq and \*(Aq?\*(Aq, which are matched in
the usual Unix filename manner. Multiple style options in a single
*Style\fP command are read from left to right as if they were issued one
after each other in separate commands. A given style always overrides
all conflicting styles that have been issued earlier (or further left
on the same style line).
.sp
Note: windows that have no name (WM_NAME) are given a name of
"Untitled", and windows that do not have a class (WM_CLASS, res_class)
are given class "NoClass" and those that do not have a resource
(WM_CLASS, res_name) are given resource "NoResource".
.sp
If a window has the resource "fvwmstyle" set, the value of that
resource is used in addition to any window names when selecting the
style.
.sp
\fIoptions\fP is a comma separated list containing one or more of the
following keywords. Each group of style names is separated by slashes
(\*(Aq/\*(Aq). The last style in these groups is the default. \fIBorderWidth\fP,
\fIHandleWidth\fP, \fI!Icon\fP / \fIIcon\fP, \fIMiniIcon\fP, \fIIconBox\fP, \fIIconGrid\fP,
\fIIconFill\fP, \fIIconSize\fP, \fI!Title\fP / \fITitle\fP, \fITitleAtBottom\fP /
\fITitleAtLeft\fP / \fITitleAtRight\fP / \fITitleAtTop\fP, \fILeftTitleRotatedCW\fP /
\fILeftTitleRotatedCCW\fP, \fIRightTitleRotatedCCW\fP / \fIRightTitleRotatedCW\fP,
\fITopTitleRotated\fP / \fITopTitleNotRotated\fP, \fIBottomTitleRotated\fP /
\fIBottomTitleNotRotated\fP, \fI!UseTitleDecorRotation\fP /
\fIUseTitleDecorRotation\fP, \fIStippledTitle\fP / \fI!StippledTitle\fP,
\fIStippledIconTitle\fP / \fI!StippledIconTitle\fP, \fIIndexedWindowName\fP /
\fIExactWindowName\fP, \fIIndexedIconName\fP / \fIExactIconName\fP, \fITitleFormat\fP
/ \fIIconTitleFormat\fP / \fI!Borders\fP / \fIBorders\fP, \fI!Handles\fP / \fIHandles\fP,
\fIWindowListSkip\fP / \fIWindowListHit\fP, \fICirculateSkip\fP / \fICirculateHit\fP,
\fICirculateSkipShaded\fP / \fICirculateHitShaded\fP, \fICirculateSkipIcon\fP /
\fICirculateHitIcon\fP, \fILayer\fP, \fIStaysOnTop\fP / \fIStaysOnBottom\fP /
\fIStaysPut\fP, \fISticky\fP / \fISlippery\fP, \fIStickyAcrossPages\fP /
\fI!StickyAcrossPages\fP, \fIStickyAcrossDesks\fP / \fI!StickyAcrossDesks\fP,
\fI!StickyStippledTitle\fP / \fIStickyStippledTitle\fP,
\fI!StickyStippledIconTitle\fP / \fIStickyStippledIconTitle\fP, \fIStartIconic\fP
/ \fIStartNormal\fP, \fIColorset\fP, \fIHilightColorset\fP, \fIBorderColorset\fP,
\fIHilightBorderColorset\fP, \fIIconTitleColorset\fP,
\fIHilightIconTitleColorset\fP, \fIIconBackgroundColorset\fP,
\fIIconTitleRelief\fP, \fIIconBackgroundRelief\fP, \fIIconBackgroundPadding\fP,
\fIFont\fP, \fIIconFont\fP, \fIStartsOnDesk\fP / \fIStartsOnPage\fP /
\fIStartsAnyWhere\fP, \fIStartsOnScreen\fP, \fIStartShaded\fP / \fI!StartShaded\fP,
\fIManualPlacementHonorsStartsOnPage\fP /
\fIManualPlacementIgnoresStartsOnPage\fP, \fICaptureHonorsStartsOnPage\fP /
\fICaptureIgnoresStartsOnPage\fP, \fIRecaptureHonorsStartsOnPage\fP /
\fIRecaptureIgnoresStartsOnPage\fP, \fIStartsOnPageIncludesTransients\fP /
\fIStartsOnPageIgnoresTransients\fP, \fIIconTitle\fP / \fI!IconTitle\fP,
\fIMwmButtons\fP / \fIFvwmButtons\fP, \fIMwmBorder\fP / \fIFvwmBorder\fP, \fIMwmDecor\fP /
\fI!MwmDecor\fP, \fIMwmFunctions\fP / \fI!MwmFunctions\fP, \fIHintOverride\fP /
\fI!HintOverride\fP, \fI!Button\fP / \fIButton\fP, \fIResizeHintOverride\fP /
\fI!ResizeHintOverride\fP, \fIOLDecor\fP / \fI!OLDecor\fP, \fIStickyIcon\fP / \fISlipperyIcon\fP,
\fIStickyAcrossPagesIcon\fP / \fI!StickyAcrossPagesIcon\fP,
\fIStickyAcrossDesksIcon\fP / \fI!StickyAcrossDesksIcon\fP, \fIManualPlacement\fP
/ \fICascadePlacement\fP / \fIMinOverlapPlacement\fP /
\fIMinOverlapPercentPlacement\fP / \fITileManualPlacement\fP /
\fITileCascadePlacement\fP / \fIPositionPlacement\fP,
\fIMinOverlapPlacementPenalties\fP, \fIMinOverlapPercentPlacementPenalties\fP,
\fIDecorateTransient\fP / \fINakedTransient\fP, \fIDontRaiseTransient\fP /
\fIRaiseTransient\fP, \fIDontLowerTransient\fP / \fILowerTransient\fP,
\fIDontStackTransientParent\fP / \fIStackTransientParent\fP, \fISkipMapping\fP /
\fIShowMapping\fP, \fIScatterWindowGroups\fP / \fIKeepWindowGroupsOnDesk\fP,
\fIUseDecor\fP, \fIUseStyle\fP, \fI!UsePPosition\fP / \fINoPPosition\fP /
\fIUsePPosition\fP, \fI!UseUSPosition\fP, \fINoUSPosition\fP / \fIUseUSPosition\fP,
\fI!UseTransientPPosition\fP, \fINoTransientPPosition\fP /
\fIUseTransientPPosition\fP, \fI!UseTransientUSPosition\fP /
\fINoTransientUSPosition\fP / \fIUseTransientUSPosition\fP, \fI!UseIconPosition\fP
/ \fINoIconPosition\fP / \fIUseIconPosition\fP, \fILenience\fP / \fI!Lenience\fP,
\fIClickToFocus\fP / \fISloppyFocus\fP / \fIMouseFocus\fP|\fIFocusFollowsMouse\fP /
\fINeverFocus\fP, \fIClickToFocusPassesClickOff\fP /
\fIClickToFocusPassesClick\fP, \fIClickToFocusRaisesOff\fP /
\fIClickToFocusRaises\fP, \fIMouseFocusClickRaises\fP /
\fIMouseFocusClickRaisesOff\fP, \fIGrabFocus\fP / \fIGrabFocusOff\fP,
\fIGrabFocusTransientOff\fP / \fIGrabFocusTransient\fP, \fIFPFocusClickButtons\fP,
\fIFPFocusClickModifiers\fP, \fI!FPSortWindowlistByFocus\fP /
\fIFPSortWindowlistByFocus\fP, \fIFPClickRaisesFocused\fP /
\fI!FPClickRaisesFocused\fP, \fIFPClickDecorRaisesFocused\fP /
\fI!FPClickDecorRaisesFocused\fP, \fIFPClickIconRaisesFocused\fP /
\fI!FPClickIconRaisesFocused\fP, \fI!FPClickRaisesUnfocused\fP /
\fIFPClickRaisesUnfocused\fP, \fIFPClickDecorRaisesUnfocused\fP /
\fI!FPClickDecorRaisesUnfocused\fP, \fIFPClickIconRaisesUnfocused\fP /
\fI!FPClickIconRaisesUnfocused\fP, \fIFPClickToFocus\fP / \fI!FPClickToFocus\fP,
\fIFPClickDecorToFocus\fP / \fI!FPClickDecorToFocus\fP, \fIFPClickIconToFocus\fP /
\fI!FPClickIconToFocus\fP, \fI!FPEnterToFocus\fP / \fIFPEnterToFocus\fP,
\fI!FPLeaveToUnfocus\fP / \fIFPLeaveToUnfocus\fP, \fI!FPFocusByProgram\fP /
\fIFPFocusByProgram\fP, \fI!FPFocusByFunction\fP / \fIFPFocusByFunction\fP,
\fIFPFocusByFunctionWarpPointer\fP / \fI!FPFocusByFunctionWarpPointer\fP,
\fIFPLenient\fP / \fI!FPLenient\fP, \fI!FPPassFocusClick\fP / \fIFPPassFocusClick\fP,
\fI!FPPassRaiseClick\fP / \fIFPPassRaiseClick\fP, \fIFPIgnoreFocusClickMotion\fP /
\fI!FPIgnoreFocusClickMotion\fP, \fIFPIgnoreRaiseClickMotion\fP /
\fI!FPIgnoreRaiseClickMotion\fP, \fI!FPAllowFocusClickFunction\fP /
\fIFPAllowFocusClickFunction\fP, \fI!FPAllowRaiseClickFunction\fP /
\fIFPAllowRaiseClickFunction\fP, \fIFPGrabFocus\fP / \fI!FPGrabFocus\fP,
\fI!FPGrabFocusTransient\fP / \fIFPGrabFocusTransient\fP,
\fIFPOverrideGrabFocus\fP / \fI!FPOverrideGrabFocus\fP, \fIFPReleaseFocus\fP /
\fI!FPReleaseFocus\fP, \fI!FPReleaseFocusTransient\fP /
\fIFPReleaseFocusTransient\fP, \fIFPOverrideReleaseFocus\fP /
\fI!FPOverrideReleaseFocus\fP, \fIStartsLowered\fP / \fIStartsRaised\fP,
\fIIgnoreRestack\fP / \fIAllowRestack\fP, \fIFixedPosition\fP /
\fIVariablePosition\fP, \fIFixedUSPosition\fP / \fIVariableUSPosition\fP,
\fIFixedPPosition\fP / \fIVariablePPosition\fP, \fIFixedSize\fP / \fIVariableSize\fP,
\fIFixedUSSize\fP / \fIVariableUSSize\fP, \fIFixedPSize\fP / \fIVariablePSize\fP,
\fI!Closable\fP / \fIClosable\fP, \fI!Iconifiable\fP / \fIIconifiable\fP,
\fI!Maximizable\fP / \fIMaximizable\fP, \fI!AllowMaximizeFixedSize\fP /
\fIAllowMaximizeFixedSize\fP, \fIIconOverride\fP / \fINoIconOverride\fP /
\fINoActiveIconOverride\fP, \fIDepressableBorder\fP / \fIFirmBorder\fP,
\fIMinWindowSize\fP, \fIMaxWindowSize\fP, \fIIconifyWindowGroups\fP /
\fIIconifyWindowGroupsOff\fP, \fIResizeOpaque\fP / \fIResizeOutline\fP,
\fIBackingStore\fP / \fIBackingStoreOff\fP / \fIBackingStoreWindowDefault\fP,
\fIOpacity\fP / \fIParentalRelativity\fP, \fISaveUnder\fP / \fISaveUnderOff\fP,
\fIWindowShadeShrinks\fP / \fIWindowShadeScrolls\fP, \fIWindowShadeSteps\fP,
\fIWindowShadeAlwaysLazy\fP / \fIWindowShadeBusy\fP / \fIWindowShadeLazy,\fP
\fIEWMHDonateIcon\fP / \fIEWMHDontDonateIcon\fP, \fIEWMHDonateMiniIcon\fP /
\fIEWMHDontDonateMiniIcon\fP, \fIEWMHMiniIconOverride\fP /
\fIEWMHNoMiniIconOverride\fP, \fIEWMHUseStackingOrderHints\fP /
\fIEWMHIgnoreStackingOrderHints\fP, \fIEWMHIgnoreStateHints\fP /
\fIEWMHUseStateHints\fP, \fIEWMHIgnoreStrutHints\fP / \fIEWMHUseStrutHints\fP,
\fIEWMHIgnoreWindowType\fP / \fI!EWMHIgnoreWindowType\fP,
\fIEWMHMaximizeIgnoreWorkingArea\fP / \fIEWMHMaximizeUseWorkingArea\fP /
\fIEWMHMaximizeUseDynamicWorkingArea\fP, \fIEWMHPlacementIgnoreWorkingArea\fP
/ \fIEWMHPlacementUseWorkingArea\fP /
\fIEWMHPlacementUseDynamicWorkingArea\fP, \fIMoveByProgramMethod\fP,
\fIUnmanaged\fP, \fIState\fP, \fISnapGrid\fP, \fISnapAttraction\fP, \fIEdgeMoveDelay\fP,
\fIEdgeResizeDelay\fP. \fIEdgeMoveResistance\fP, \fIInitialMapCommand\fP
.sp
In the above list some options are listed as
style\-option/opposite\-style\-option. The opposite\-style\-option for
entries that have them describes the fvwm default behavior and can be
used if you want to change the fvwm default behavior.
.sp
\fBFocus policy\fP
.RS 4
\fIClickToFocus\fP instructs fvwm to give the focus to a window when it
is clicked in. The default \fIMouseFocus\fP (or its alias
\fIFocusFollowsMouse\fP) tells fvwm to give a window the focus as soon
as the pointer enters the window, and take it away when the pointer
leaves the window. \fISloppyFocus\fP is similar, but doesn\(cqt give up the
focus if the pointer leaves the window to pass over the root window
or a ClickToFocus window (unless you click on it, that is), which
makes it possible to move the mouse out of the way without losing
focus. A window with the style \fINeverFocus\fP never receives the
focus. This is useful for modules like \fBFvwmButtons\fP. for example.
Note: Once any of the "FP..." styles has been used, the defaults
that come with the basic focus policies are not restored when the
latter are used again. For example, once !FPGrabFocus has been used,
using ClickToFocus does not restore FPGrabFocus.
.sp
The focus model can be augmented with several additional options. In
fvwm\-2.5.3 and later, there are a large number of advanced options
beginning with "FP" or "!FP". These options shall replace the older
options one day and are described first. Using any of these new
options may limit compatibility with older releases. In general,
options beginning with "FP" turn a feature on, while those beginning
with "!FP" turn it off.
.RE
.sp
\fBFocusing the window\fP
.RS 4
With \fIFPEnterToFocus\fP, when the pointer enters a window it receives
focus.
.sp
With \fIFPLeaveToUnfocus\fP a window loses focus when the pointer leaves
it.
.sp
With \fIFPClickToFocus\fP, \fIFPClickDecorToFocus\fP or
\fIFPClickIconToFocus\fP, a window receives focus when the inside of the
window or the decorations or its icon is clicked.
.sp
The \fIFPFocusByProgram\fP style allows windows to take the focus
themselves.
.sp
The !\fIFPFocusByFunction\fP style forbids that a window receives the
focus via the \fBFocus\fP and \fBFlipFocus\fP commands.
.sp
The \fIFPFocusByFunctionWarpPointer\fP style controls if the pointer is
warped to a selected window when the \fBFocus\fP command is used.
.sp
\fIFPLenient\fP allows focus on windows that do not want it, like
\fBFvwmPager\fP or xclock.
.sp
The \fIFPFocusClickButtons\fP style takes a list of mouse buttons that
can be clicked to focus or raise a window when the appropriate style
is used. The default is to use the first three buttons ("123").
.sp
The \fIFPFocusClickModifiers\fP style takes a list of modifier keys just
like the \fBKey\fP command. The exact combination of modifier keys must
be pressed for the click to focus or raise a window to work. The
default is to use no modifiers ("N").
.sp
With the \fIFPPassFocusClick\fP style, the click that was used to focus
a window is passed to the application.
.sp
With the \fIFPAllowFocusClickFunction\fP style, the click that was used
to focus a window can also trigger a normal action that was bound to
the window with the \fBMouse\fP command).
.sp
If the \fIFPIgnoreFocusClickMotion\fP style is used, clicking in a
window and then dragging the pointer with the button held down does
not count as the click to focus the window. Instead, the application
processes these events normally. This is useful to select text in a
terminal window with the mouse without raising the window. However,
mouse bindings on the client window are not guaranteed to work
anymore (see \fBMouse\fP command). This style forces the initial click
to be passed to the application. The distance that the pointer must
be moved to trigger this is controlled by the \fBMoveThreshold\fP
command.
.sp
The \fIFPSortWindowlistByFocus\fP and !\fIFPSortWindowlistByFocus\fP styles
control whether the internal window list is sorted in the order the
windows were focused or in the order they were created. The latter
is the default for \fIClickToFocus\fP and \fISloppyFocus\fP.
.sp
\fBClicking the window to raise\fP
.sp
The styles \fIFPClickRaisesFocused\fP, \fIFPClickDecorRaisesFocused\fP and
\fIFPClickIconRaisesFocused\fP allow one to raise the window when the
interior or the decorations or the icon of the window is clicked
while the window is already focused.
.sp
The styles \fIFPClickRaisesUnfocused\fP, \fIFPClickDecorRaisesUnfocused\fP
and \fIFPClickIconRaisesUnfocused\fP allow one to raise the window when
the interior or the decorations or the icon of the window is clicked
while the window is not yet focused.
.sp
With the \fIFPPassRaiseClick\fP style, the click that was used to raise
the window is passed to the application.
.sp
With the \fIFPAllowRaiseClickFunction\fP style, the click that was used
to raise the window can also trigger a normal action that was bound
to the window with the \fBMouse\fP command.
.sp
If the \fIFPIgnoreRaiseClickMotion\fP style is used, clicking in a
window and then dragging the pointer with the button held down does
not count as the click to raise the window. Instead, the application
processes these events normally. This is useful to select text in a
terminal window with the mouse without raising the window. However,
mouse bindings on the client window are not guaranteed to work
anymore (see \fBMouse\fP command. Note that this style forces that the
initial click is passed to the application. The distance that the
pointer must be moved to trigger this is controlled by the
\fBMoveThreshold\fP command.
.sp
\fBGrabbing the focus when a new window is created\fP
.sp
New normal or transient windows with the \fIFPGrabFocus\fP or
\fIFPGrabFocusTransient\fP style automatically receive the focus when
they are created. \fIFPGrabFocus\fP is the default for windows with the
\fIClickToFocus\fP style. Note that even if these styles are disabled,
the application may take the focus itself. Fvwm can not prevent
this.
.sp
The \fIOverrideGrabFocus\fP style instructs fvwm to never take away the
focus from such a window via the \fIGrabFocus\fP or \fIGrabFocusTransient\fP
styles. This can be useful if you like to have transient windows
receive the focus immediately, for example in a web browser, but not
while you are working in a terminal window or a text processor.
.sp
The above three styles are accompanied by \fIFPReleaseFocus\fP,
\fIFPReleaseFocusTransient\fP and \fIFPOverrideReleaseFocus\fP. These
control if the focus is returned to another window when the window
is closed. Otherwise no window or the window under the pointer
receives the focus.
.sp
\fIClickToFocusPassesClickOff\fP and \fIClickToFocusPassesClick\fP controls
whether a mouse click to focus a window is sent to the application
or not. Similarly,
\fIClickToFocusRaisesOff\fP/\fIMouseFocusClickRaisesOff\fP and
\fIClickToFocusRaises\fP/\fIMouseFocusClickRaises\fP control if the window
is raised (but depending on the focus model).
.sp
Note: in fvwm versions prior to 2.5.3, the "Click..." options
applied only to windows with \fIClickToFocus\fP while the "Mouse..."
options applied to windows with a different focus policy. This is no
longer the case.
.sp
The old \fIGrabFocus\fP style is equivalent to using \fIFPGrabFocus\fP
.br
\fIFPReleaseFocus\fP.
.sp
The old \fIGrabFocusTransient\fP style is equivalent to using
\fIFPGrabFocusTransient\fP + \fIFPReleaseFocusTransient\fP.
.sp
\fILenience\fP is equivalent to the new style \fIFPLenient\fP.
.RE
.RE
.sp
\fBWindow title\fP
.RS 4
The \fITitle\fP and !Title options determine whether the window is
decorated with a title\-bar. By default all windows have a title\-bar.
\fINoTitle\fP is equivalent to \fI!Title\fP but is deprecated.
.sp
Windows with the \fITitleAtBottom\fP, \fITitleAtLeft\fP or \fITitleAtRight\fP
style have a title\-bar below, to the left or to the right of the
window instead of above as usual. The \fITitleAtTop\fP style restores
the default placement. Even if the window has the \fI!Title\fP style
set, this affects the \fBWindowShade\fP command. Please check the
\fBWindowShade\fP command for interactions between that command and
these styles. Titles on the left or right side of the windows are
augmented by the following styles:
.sp
Normally, the text in titles on the left side of a window is rotated
counterclockwise by 90 degrees from the normal upright position and
90 degrees clockwise for titles on the right side. It can also be
rotated in the opposite directions with \fILeftTitleRotatedCW\fP if
\fITitleAtLeft\fP is used, and with \fIRightTitleRotatedCCW\fP if
\fITitleAtRight\fP is used. The defaults can be restored with
\fILeftTitleRotatedCCW\fP and \fIRightTitleRotatedCW\fP. A normal horizontal
text may be rotated as well with \fITopTitleRotated\fP if \fITitleAtTop\fP
is used, and with \fIBottomTitleRotated\fP if \fITitleAtBottom\fP is used.
The defaults can be restored with \fITopTitleNotRotated\fP and
\fIBottomTitleNotRotated\fP.
.sp
By default the title bar decoration defined using the \fBTitleStyle\fP
command is rotated following the title text rotation (see the
previous paragraph). This can be disabled by using the
!\fIUseTitleDecorRotation\fP style. \fIUseTitleDecorRotation\fP reverts back
to the default.
.sp
With the \fIStippledTitle\fP style, titles are drawn with the same
effect that is usually reserved for windows with the \fISticky\fP,
\fIStickyAcrossPages\fP or \fIStickyAcrossDesks\fP style. \fI!StippledTitle\fP
reverts back to normal titles. \fIStippledTitleOff\fP is equivalent to
\fI!StippledTitle\fP but is deprecated.
.sp
\fBColorset\fP takes the colorset number as its sole argument and
overrides the colors set by \fIColor\fP. Instead, the corresponding
colors from the given colorset are used. Note that all other
features of a colorset are not used. Use the \fBColorset\fP decoration
style in the \fBTitleStyle\fP and \fIButtonStyle\fP command for that. To
stop using the colorset, the colorset number is omitted.
.sp
\fIBorderColorset\fP takes eight positive integers as its arguments and will
apply the given colorsets to the eight individual components of the window
border.
.sp
For backwards compatibility, if one integer is supplied, that is applied to
all window border components.
.sp
The border is split up into the following definitions, and is the same order as
the colorsets which will be applied to the border.
.sp
.if n .RS 4
.nf
.fam C
North, North East, East, South East, South, South West, West, North West
.fam
.fi
.if n .RE
.sp
\fINorth\fP, \fIEast\fP, \fISouth\fP, and \fIWest\fP refer to the top, left, bottom, and right
sides of the window border.
.sp
\fINE\fP, \fISE\fP, \fISW\fP, and \fINW\fP refer to the window handles.
.sp
\fBNOTE\fP: due to how window handles are rendered, there is no way to make one
complete edge of a window the same color as defined by either \fINorth\fP, \fISouth\fP,
\fIEast\fP, or \fIWest\fP.
.sp
The \fIHilightBorderColorset\fP style option works the same as
\fIBorderColorset\fP but is used when the window has the focus.
.sp
!\fIIconTitle\fP disables displaying icon labels while the opposite
style \fIIconTitle\fP enables icon labels (default behaviour).
\fINoIconTitle\fP is equivalent to \fI!IconTitle\fP but is deprecated.
.sp
\fIIconTitleColorset\fP takes the colorset number as its sole argument
and overrides the colors set by \fIColor\fP or \fIColorset\fP. To stop using
this colorset, the argument is omitted.
.sp
\fIHilightIconTitleColorset\fP takes the colorset number as its sole
argument and overrides the colors set by \fBHilightColor\fP or
\fIHilightColorset\fP. To stop using this colorset, the argument is
omitted.
.sp
\fIIconBackgroundColorset\fP takes the colorset number as its sole
argument and uses it to set a background for the icon picture. By
default the icon picture is not drawn onto a background image. To
restore the default, the argument is omitted.
.sp
\fIIconTitleRelief\fP takes one numeric argument that may be between \-50
and +50 pixels and defines the thickness of the 3D relief drawn
around the icon title. With negative values the icon title gets a
pressed in look. The default is 2 and it is restored if the argument
is omitted.
.sp
\fIIconBackgroundRelief\fP takes one numeric argument that may be
between \-50 and +50 pixels and defines the thickness of the 3D
relief drawn around the icon picture background (if any). With
negative values the icon background gets a pressed in look. The
default is 2 and it is restored if the argument is omitted.
.sp
\fIIconBackgroundPadding\fP takes one numeric argument that may be
between 0 and 50 pixels and defines the amount of free space between
the relief of the icon background picture (if any) and the icon
picture. The default is 2 and it is restored if the argument is
omitted.
.sp
The \fIFont\fP and \fIIconFont\fP options take the name of a font as their
sole argument. This font is used in the window or icon title. By
default the font given in the \fBDefaultFont\fP command is used. To
revert back to the default, use the style without the name argument.
These styles replace the older \fBWindowFont\fP and \fIIconFont\fP commands.
.sp
The deprecated \fIIndexedWindowName\fP style causes fvwm to use window
titles in the form
.sp
.if n .RS 4
.nf
.fam C
name (i)
.fam
.fi
.if n .RE
.sp
where \fIname\fP is the exact window name and \fIi\fP is an integer which
represents the \fIi th\fP window with \fIname\fP as window name. This has
been replaced with:
.sp
.if n .RS 4
.nf
.fam C
TitleFormat %n (%t)
.fam
.fi
.if n .RE
.sp
\fIExactWindowName\fP restores the default which is to use the exact
window name. Deprecated in favour of:
.sp
.if n .RS 4
.nf
.fam C
TitleFormat %n
.fam
.fi
.if n .RE
.sp
\fIIndexedIconName\fP and \fIExactIconName\fP work the same as
\fIIndexedWindowName\fP and \fIExactWindowName\fP styles but for the icon
titles. Both are deprecated in favour of:
.sp
.if n .RS 4
.nf
.fam C
IconTitleFormat %n (%t)
IconTitleFormat %n
.fam
.fi
.if n .RE
.sp
\fITitleFormat\fP describes what the visible name of a window should
look like, with the following placeholders being valid:
.sp
\fB%n\fP
.RS 4
Insert the window\(cqs name.
.RE
.sp
\fB%i\fP
.RS 4
Insert the window\(cqs icon name.
.RE
.sp
\fB%c\fP
.RS 4
Insert the window\(cqs class name.
.RE
.sp
\fB%r\fP
.RS 4
Insert the window\(cqs resource name.
.RE
.sp
\fB%t\fP
.RS 4
Insert the window count.
.RE
.sp
\fB%I\fP
.RS 4
Insert the window ID.
.RE
.sp
\fB%%\fP
.RS 4
Insert a literal \*(Aq%\*(Aq character.
.sp
Any amount of whitespace may be used, along with other characters to
make up the string \(em but a valid \fITitleFormat\fP string must contain
at least one of the placeholders mentioned. No quote stripping is
performed on the string, so for example the following is printed
verbatim:
.sp
.if n .RS 4
.nf
.fam C
TitleFormat " %n " \-> [%t] \-> [%c]
.fam
.fi
.if n .RE
.sp
Note: It\(cqs perfectly possible to use a \fITitleFormat\fP which can
result in wiping out the visible title altogether. For example:
.sp
.if n .RS 4
.nf
.fam C
TitleFormat %z
.fam
.fi
.if n .RE
.RE
.sp
Simply because the placeholder \*(Aq%z\*(Aq isn\(cqt supported. This is not a
bug but rather a facet of how the formatting parser works.
.sp
+
\fIIconTitleFormat\fP describes what the visible icon name of a window
should look like, with the options being the same as \fITitleFormat\fP.
.RE
.sp
\fBTitle buttons\fP
.RS 4
\fIButton\fP and !\fIButton\fP take a numeric argument which is the number
of the title\-bar button which is to be shown or omitted. \fINoButton\fP
is equivalent to \fI!Button\fP but is deprecated.
.sp
\fIMwmButtons\fP makes the \fBMaximize\fP button look pressed\-in when the
window is maximized. See the \fIMwmDecorMax\fP flag in \fBButtonStyle\fP for
more information. To switch this style off again, use the
\fBFvwmButtons\fP style.
.RE
.sp
\fBBorders\fP
.RS 4
!\fIBorders\fP suppresses the window border (but not the title)
completely. The \fIBorders\fP style enables them again. Without borders,
all other styles affecting window borders are meaningless.
.sp
\fIMwmBorder\fP makes the 3D bevel more closely match Mwm\(cqs.
\fIFvwmBorder\fP turns off the previous option.
.sp
With the !\fIHandles\fP style, the window does not get the handles in
the window corners that are commonly used to resize it. With
\fI!Handles\fP, the width from the \fIBorderWidth\fP style is used. By
default, or if \fIHandles\fP is specified, the width from the
\fIHandleWidth\fP style is used. \fINoHandles\fP is equivalent to \fI!Handles\fP
but is deprecated.
.sp
\fIHandleWidth\fP takes a numeric argument which is the width of the
border to place the window if it does have resize\-handles. Using
HandleWidth without an argument restores the default.
.sp
\fIBorderWidth\fP takes a numeric argument which is the width of the
border to place the window if it does not have resize\-handles. It is
used only if the \fI!Handles\fP style is specified too. Using
BorderWidth without an argument restores the default.
.sp
\fIDepressableBorder\fP makes the border parts of the window decoration
look sunken in when a button is pressed over them. This can be
disabled again with the \fIFirmBorder\fP style.
.RE
.sp
\fBIcons, shading, maximizing, movement, resizing\fP
.RS 4
\fIIcon\fP takes an (optional) unquoted string argument which is the
icon bitmap or pixmap to use. Icons specified this way override
pixmap icons, but not icon windows or the ewmh icon, provided by the
client in the application (with the WM_HINTS property or with the
ewmh \fINET_WM_ICON property). The _IconOverride\fP style changes the
behavior to override any client\-provided icons; the \fINoIconOverride\fP
style changes the behavior to not override any client\-provided
icons; the default overriding behavior can be activated with the
\fINoActiveIconOverride\fP style. With this style, fvwm uses application
provided icons if the icon is changed but uses the icon provided in
the configuration file until then.
.sp
There is one exception to these rules, namely
.sp
.if n .RS 4
.nf
.fam C
Style * Icon unknown.xpm
.fam
.fi
.if n .RE
.sp
doesn\(cqt force the unknown.xpm icon on every window, it just sets the
default icon like the DefaultIcon command. If you really want all
windows to have the same icon, you can use
.sp
.if n .RS 4
.nf
.fam C
Style ** Icon unknown.xpm
.fam
.fi
.if n .RE
.sp
If the \fINoIcon\fP attribute is set then the specified window simply
disappears when it is iconified. The window can be recovered through
the window\-list. If \fIIcon\fP is set without an argument then the
\fINoIcon\fP attribute is cleared but no icon is specified. An example
which allows only the \fBFvwmPager\fP module icon to exist:
.sp
.if n .RS 4
.nf
.fam C
Style * NoIcon
Style FvwmPager Icon
.fam
.fi
.if n .RE
.sp
\fIIconBox\fP takes no argument, four numeric arguments (plus optionally
a screen specification), an X11 geometry string or the string
"none":
.sp
.if n .RS 4
.nf
.fam C
IconBox [screen scr\-spec] l t r b
.fam
.fi
.if n .RE
.sp
or
.sp
.if n .RS 4
.nf
.fam C
IconBox geometry
.fam
.fi
.if n .RE
.sp
Where \fIl\fP is the left coordinate, \fIt\fP is the top, \fIr\fP is right and
\fIb\fP is bottom. Negative coordinates indicate distance from the right
or bottom of the screen. If the first argument is the word \fIscreen\fP,
the \fIscr\-spec\fP argument specifies the RandR screen on which the
IconBox is defined ´or the additional \*(Aqw\*(Aq for the screen where the
window center is located. This is only useful with multiple screens.
The "l t r b" specification is more flexible than an X11 geometry.
For example:
.sp
.if n .RS 4
.nf
.fam C
IconBox \-80 240 \-1 \-1
.fam
.fi
.if n .RE
.sp
defines a box that is 80 pixels wide from the right edge, 240 pixels
down from the top, and continues to the bottom of the screen.
.sp
Perhaps it is easier to use is an X11 geometry string though:
.sp
.if n .RS 4
.nf
.fam C
IconBox 1000x70\-1\-1
.fam
.fi
.if n .RE
.sp
places an 1000 by 70 pixel icon box on the bottom of the screen
starting in the lower right hand corner of the screen. One way to
figure out a geometry like this is to use a window that resizes in
pixel increments, for example, xv. Then resize and place the xv
window where you want the iconbox. Then use FvwmIdent to read the
windows geometry. The icon box is a region of the screen where fvwm
attempts to put icons for any matching window, as long as they do
not overlap other icons. Multiple icon boxes can be defined as
overflow areas. When the first icon box is full, the second one is
filled. All the icon boxes for one style must be defined in one
\fBStyle\fP command. For example:
.sp
.if n .RS 4
.nf
.fam C
Style * IconBox \-80 240 \-1 \-1, \(rs
IconBox 1000x70\-1\-1
.fam
.fi
.if n .RE
.sp
A Style command with the IconBox option replaces any icon box
defined previously by another Style command for the same style.
That\(cqs why the backslash in the previous example is required.
.sp
Note: The geometry for the icon box command takes the additional
screen specifier "@w" in case RandR isused. This designates the
screen where the window center is located. The additional screen
specifier is not allowed anywhere else.
.sp
If you never define an icon box, or you fill all the icon boxes,
fvwm has a default icon box that covers the screen, it fills top to
bottom, then left to right, and has an 80x80 pixel grid. To disable
all but the default icon box you can use IconBox without arguments
in a separate \fBStyle\fP command. To disable all icon boxes including
the default icon box, the argument "none" can be specified.
.sp
Hint: You can auto arrange your icons in the icon box with a simple
fvwm function. Put the "DeiconifyAndRearrange" function below in
your configuration file:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc DeiconifyAndRearrange
+ C Iconify off
+ C All (CurrentPage, Iconic) PlaceAgain Icon
.fam
.fi
.if n .RE
.sp
And then replace all places where you call the \fBIconify\fP command to
de\-iconify an icon with a call to the new function. For example
replace
.sp
.if n .RS 4
.nf
.fam C
AddToFunc IconFunc
+ C Iconify off
+ M Raise
+ M Move
+ D Iconify off
Mouse 1 I A Iconify off
.fam
.fi
.if n .RE
.sp
with
.sp
.if n .RS 4
.nf
.fam C
AddToFunc IconFunc
+ C DeiconifyAndRearrange
+ M Raise
+ M Move
+ D DeiconifyAndRearrange
Mouse 1 I A DeiconifyAndRearrange
.fam
.fi
.if n .RE
.sp
\fIIconGrid\fP takes 2 numeric arguments greater than zero.
.sp
.if n .RS 4
.nf
.fam C
IconGrid x y
.fam
.fi
.if n .RE
.sp
Icons are placed in an icon box by stepping through the icon box
using the \fIx\fP and \fIy\fP values for the icon grid, looking for a free
space. The default grid is 3 by 3 pixels which gives a tightly
packed appearance. To get a more regular appearance use a grid
larger than your largest icon. Use the \fIIconSize\fP argument to clip
or stretch an icon to a maximum size. An \fIIconGrid\fP definition must
follow the \fBIconBox\fP definition that it applies to:
.sp
.if n .RS 4
.nf
.fam C
Style * IconBox \-80x240\-1\-1, IconGrid 90 90
.fam
.fi
.if n .RE
.sp
\fIIconFill\fP takes 2 arguments.
.sp
.if n .RS 4
.nf
.fam C
IconFill Bottom Right
.fam
.fi
.if n .RE
.sp
Icons are placed in an icon box by stepping through the icon box
using these arguments to control the direction the box is filled in.
By default the direction is left to right, then top to bottom. This
would be expressed as:
.sp
.if n .RS 4
.nf
.fam C
IconFill left top
.fam
.fi
.if n .RE
.sp
To fill an icon box in columns instead of rows, specify the vertical
direction (top or bottom) first. The directions can be abbreviated
or spelled out as follows: "t", "top", "b", "bot", "bottom", "l",
"lft", "left", "r", "rgt", "right". An \fBIconFill\fP definition must
follow the \fBIconBox\fP definition that it applies to:
.sp
.if n .RS 4
.nf
.fam C
Style * IconBox \-80x240\-1\-1, IconFill b r
.fam
.fi
.if n .RE
.sp
\fIIconSize\fP sets limits on the size of an icon image. Both
user\-provided and application\-provided icon images are affected.
.sp
.if n .RS 4
.nf
.fam C
IconSize [ width height [ maxwidth maxheight ] ]
.fam
.fi
.if n .RE
.sp
All arguments are measured in pixels. When all four arguments are
passed to \fIIconSize,\fP \fIwidth\fP and \fIheight\fP represent the minimum
size of an icon, and \fImaxwidth\fP and \fImaxheight\fP represent the
maximum size of an icon. Icon images that are smaller than the
minimum size are padded. Icon images that are bigger than the
maximum size are clipped.
.sp
If only two arguments are passed to \fIIconSize,\fP \fIwidth\fP and \fIheight\fP
represent the absolute size of an icon. Icons covered by this style
are padded or clipped to achieve the given size.
.sp
If no arguments are specified, the default values are used for each
dimension. This effectively places no limits on the size of an icon.
.sp
The value of "\-1" can be used in place of any of the arguments to
specify the default value for that dimension.
.sp
In addition to the numeric arguments, 1 additional argument can be
"Stretched", "Adjusted", or "Shrunk".
.sp
Note that module provided icon managers are not affected by this
style.
.sp
\fIMiniIcon\fP specifies a pixmap to use as the miniature icon for the
window. This miniature icon can be drawn in a title\-bar button (see
\fBButtonStyle\fP), and can be used by various fvwm modules (\fBFvwmIconMan\fP
and \fBFvwmPager\fP). It takes the name of a pixmap as an argument.
.sp
\fIWindowShadeShrinks\fP and \fIWindowShadeScrolls\fP control if the contents
of a window that is being shaded with the \fBWindowShade\fP command are
scrolled (default) or if they stay in place. The shrinking mode is a
bit faster
.sp
The \fIWindowShadeSteps\fP option selects the number of steps for
animation when shading a window with \fBWindowShade\fP. It takes one
number as its argument. If the number has a trailing \*(Aq\fIp\fP\*(Aq it sets the
number of pixels to use as the step size instead of a fixed number of
steps. 0 disables the animation. This happens too if the argument is
omitted or invalid.
.sp
The \fBWindowShade\fP command has two modes of operation: busy and lazy
shading. Busy shading can be 50% slower than lazy shading, but the
latter can look strange under some conditions, for example, if the
window borders, buttons or the title are filled with a tiled pixmap.
Also, the window handles are not drawn in lazy mode and the border
relief may only be drawn partially right before the window reaches the
shaded state or tight after leaves the unshaded state. By default,
fvwm uses lazy mode if there are no bad visual effects (not counting
the window handles) and busy mode otherwise. Use the
\fIWindowShadeAlwaysLazy or WindowShadeBusy\fP to force using the lazy or
busy mode. The default setting is restored with \fIWindowShadeLazy\fP.
.sp
\fIResizeOpaque\fP instructs fvwm to resize the corresponding windows with
their contents visible instead of using an outline. Since this causes
the application to redraw frequently it can be quite slow and make the
window flicker excessively, depending on the amount of graphics the
application redraws. The \fIResizeOutline\fP style (default) negates the
\fIResizeOpaque\fP style. Many applications do not like their windows
being resized opaque, e.g. XEmacs, Netscape or terminals with a pixmap
background. If you do not like the result, do not use the
\fIResizeOpaque\fP style for these windows. To exempt certain windows from
opaque resizing you could use these lines in your configuration file:
.sp
.if n .RS 4
.nf
.fam C
Style * ResizeOpaque
Style rxvt ResizeOutline
Style emacs ResizeOutline
.fam
.fi
.if n .RE
.sp
\fISticky\fP makes the window sticky, i.e. it is always visible on each
page and each desk. The opposite style, \fISlippery\fP reverts back to the
default.
.sp
\fIStickyIcon\fP makes the window sticky when it\(cqs iconified. It
de\-iconifies on top the active desktop. \fISlipperyIcon\fP reverts back to
the default.
.sp
\fIStickyAcrossPages\fP and \fIStickyAcrossPagesIcon\fP work like \fISticky\fP and
\fIStickyIcon\fP, but stick the window only across pages, not desks while
\fIStickyAcrossDesks and StickyAcrossDesksIcon\fP works the other way
round.
.sp
Windows that have been marked as \fISticky\fP or \fIStickyAcrossDesks\fP or
\fIStickyAcrossPages\fP will have stipples drawn on the titlebar. This can
be negated with the !\fIStickyStippledTitle\fP style. The style
\fIStickyStippledTitle\fP puts back the stipples where that window has
also been marked as \fISticky\fP. Note that this is the default style for
\fISticky\fP windows. Sticky icons will have stipples drawn on the icon
title. This can be disabled in the same way with the
!\fIStickyStippledIconTitle\fP style.
.sp
Windows with the \fIStartIconic\fP style are shown as icons initially.
Note that some applications counteract that by deiconifying
themselves. The default is to not iconify windows and can be set with
the \fIStartNormal\fP style.
.sp
\fIStickyIcon\fP makes the window sticky when it\(cqs iconified. It
de\-iconifies on top the active desktop. \fISlipperyIcon\fP reverts back to
the default.
.sp
\fIStickyIconPage\fP works like \fIStickyIcon\fP, but sticks the icon only
across pages, not desks while \fIStickyIconDesk\fP works the other way
round.
.sp
\fIStippledIconTitle\fP works like \fIStippledTitle\fP in that it draws
stipples on the titles of icons but doesn\(cqt make the icon sticky.
.sp
\fIIgnoreRestack\fP makes fvwm ignore attempts of clients to raise or
lower their own windows. By default, the opposite style,
\fIAllowRestack\fP is active.
.sp
\fIFixedPosition\fP and \fIFixedUSPosition\fP make fvwm ignore attempts of the
user to move the window. It is still possible to move the window by
resizing it. To allow the user to move windows, use the
\fIVariablePosition\fP or \fIVariableUSPosition\fP style.
.sp
\fIFixedSize\fP and \fIFixedUSSize\fP make fvwm ignore attempts of the user to
resize the window. To allow the user to resize windows, use the
\fIVariableSize\fP or \fIVariableUSSize\fP style.
.sp
\fIFixedPPosition\fP and \fIFixedPSize\fP make fvwm ignore attempts of the
program to move or resize its windows. To allow this kind of actions,
use the \fIVariablePPosition\fP or \fIVariablePSize\fP style. These styles may
sometimes affect the initial placement and dimensions of new windows
(depending on the application). If windows are created at strange
places, try either the \fIVariablePPosition\fP or \fI!UsePPosition\fP styles.
The \fIFixedPSize\fP style may screw up window dimensions for some
applications. Do Not use this style in this case.
.sp
\fIMoveByProgramMethod\fP affects how fvwm reacts to requests by the
application to move its windows. By default, fvwm tries to detect
which method to use, but it sometimes detects the wrong method. You
may come across a window that travels across the screen by a few
pixels when the application resizes it, moves to a screen border with
the frame decorations off screen, that remembers its position for the
next time it starts but appears in a slighly shifted position, or that
attepmts to become full screen but has the. Try out both options,
\fIUseGravity\fP and \fIIgnoreGravity\fP on the window (and that window only)
and see if that helps. By default, fvwm uses the \fIAutoDetect\fP method.
Once the method was detected, it is never changed again. As long as
fvwm can not detect the proper method, it uses \fIIgnoreGravity\fP. To
force fvwm to retry the detection, use one of the other two options
first and then use \fIAutoDetect\fP again.
.sp
Note: This option was introduced to alleviate a problem with the ICCCM
specification. The ICCCM clearly states that the \fIUseGravity\fP option
should be used, but traditionally applications ignored this rule.
.sp
\fIClosable\fP enables the functions \fBClose\fP, \fBDelete\fP and \fBDestroy\fP to be
performed on the windows. This is on by default. The opposite,
\fI!Closable\fP, inhibits the window to be closed.
.sp
\fIIconifiable\fP enables the function \fBIconify\fP to be performed on the
windows. This is on by default. The opposite, \fI!Iconifiable\fP, inhibits
the window from being iconified.
.sp
\fIMaximizable\fP enables the function \fBMaximize\fP to be performed on the
windows. This is on by default. The opposite, \fI!Maximizable\fP, inhibits
the window from being maximized.
.sp
\fIAllowMaximizeFixedSize\fP enables the function \fBMaximize\fP to be
performed on windows that are not resizable, unless maximization has
been disabled either using the style \fI!Maximizable\fP or through WM
hints. This is on by default. The opposite, \fI!AllowMaximizeFixedSize\fP,
inhibits all windows that are not resizable from being maximized.
.sp
\fIResizeHintOverride\fP instructs fvwm to ignore the program supplied
minimum and maximum size as well as the resize step size (the
character size in many applications). This can be handy for broken
applications that refuse to be resized. Do not use it if you do not
need it. The default (opposite) style is \fINoResizeOverride\fP.
.sp
\fIMinWindowSize [ width [ p | c ] height [ p | c ] ]\fP Tells fvwm the
minimum width and height of a window. The values are the percentage of
the total screen area. If the letter \*(Aq\fIp\fP\*(Aq is appended to either of the
values, the numbers are interpreted as pixels. If the letter \*(Aq\fIc\fP\*(Aq is
appended to either of the values, the numbers are in terms of the client
window\(cqs size hints, which can be useful for windows such as terminals to
specify the number of rows or columns. This command is useful to deal with
windows that freak out if their window becomes too small. If you omit the
parameters or their values are invalid, both limits are set to 0 pixels
(which is the default value).
.sp
\fIMaxWindowSize [ width [ p | c ] height [ p | c ] ]\fP Tells fvwm the
maximum width and height of a window. The values are the percentage of
the total screen area. If the letter \*(Aq\fIp\fP\*(Aq is appended to either of the
values, the numbers are interpreted as pixels. If the letter \*(Aq\fIc\fP\*(Aq is
appended to either of the values, the numbers are in terms of the client
window\(cqs size hints, which can be useful for windows such as terminals to
specify the number of rows or columns. This command is useful to force
large application windows to be fully visible. Neither \fIheight\fP nor \fIwidth\fP
may be less than 100 pixels. If you omit the parameters or their values
are invalid, both limits are set to 32767 pixels (which is the default).
.sp
With \fIIconifyWindowGroups\fP all windows in the same window group are
iconified and deiconified at once when any window in the group is
(de)iconified. The default is \fIIconifyWindowGroupsOff\fP, which disables
this behavior. Although a number of applications use the window group
hint, it is rarely used in a proper way, so it is probably best to use
\fIIconifyWindowGroups\fP only for selected applications.
.sp
The option \fISnapAttraction\fP affects interactive window movement: If
during an interactive move the window or icon comes within \fIproximity\fP
pixels of another the window or icon, it is moved to make the borders
adjoin. The default of 0 means that no snapping happens. Calling this
command without arguments turns off snap attraction and restores the
default behavior. Please refer also to the \fISnapGrid\fP option.
.sp
The second argument optional and may be set to one of
the five following values: With \fIAll\fP both icons and windows snap to
other windows and other icons. \fISameType\fP lets windows snap only to
windows, and icons snap only to icons. With \fIWindows\fP windows snap
only to other windows. Similarly with \fIIcons\fP icons snap only to other
icons. With \fINone\fP no snapping takes place. This option can be useful
in conjunction with the thirs argument if you only want to snap
against the screen edges. The default behavior is \fIAll\fP.
.sp
The third and last optional argument may be set to one of the four
following values:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
With \fIScreen\fP the already snapping icons or windows, which is
controlled by the second argument, will snap now also to the screen
edges.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fIScreenWindows\fP snaps only windows to the screen edges.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fIScreenIcons\fP snaps only icons to the screen edges.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
. sp -1
. IP \(bu 2.3
.\}
\fIScreenAll\fP snaps windows and icons to the screen edges.
.RE
.RE
.sp
The option \fISnapGrid\fP defines an invisible grid on the screen. During
an interactive move a window or icon is positioned such that its
location (top left corner) is coincident with the nearest grid point.
The default \fIx\-grid\-size\fP and \fIy\-grid\-size\fP setting are both 1, which
is effectively no grid all.
.sp
An interactive move with both \fISnapGrid\fP and \fISnapAttraction\fP results
in the window being moved to be adjacent to the nearest window border
(if within snap proximity) or grid position. The window moves the
shortest distance possible to satisfy both \fISnapGrid\fP and
\fISnapAttraction\fP. Note that the x and y coordinates are not coupled.
For example, a window may snap to another window on the x axis while
snapping to a grid point on the y axis. Using this style without
arguments reinstates the default settings.
.sp
The styles \fIEdgeMoveDelay\fP and \fIEdgeResizeDelay\fP define how hard it
is to change the desktop viewport by moving or resizing a
window 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. The command \fBEdgeScroll\fP determines how far the
viewport is scrolled. If \-1 is given as the delay, page flipping is
disabled completely. The defaults are no delay for moving (0) and no
flipping for resizing (\-1). Using these styles without any argument
restores the default settings. Note that, with
.sp
.if n .RS 4
.nf
.fam C
EdgeScroll 0 0
.fam
.fi
.if n .RE
.sp
it is still possible to move or resize windows across the edge of the
current screen. See also \fBEdgeThickness\fP.
.sp
The option \fIEdgeMoveResistance\fP makes it easier to place a window
directly adjacent to a RandR screen\(cqs edge. It takes one or two parameters.
The first parameter tells how many pixels over an outside edge of the
screen a window\(cqs edge must move before it actually moves partially off
the screen. The optional second parameter does the same as the first, but
for inside edges (shared edge between two RandR monitors). If omitted,
there is no resistance between inside edges. Note that the center of the
window being moved determines the screen on which the window should be
kept. Both values are 0 (no resistance) by default. To restore the defaults,
the option \fIEdgeMoveResistance\fP can be used without any parameters.
.sp
The option \fIInitialMapCommand\fP allows for any valid fvwm command or
function to run when the window is initially mapped by fvwm. Example:
.sp
.if n .RS 4
.nf
.fam C
Style MyWindow StartsOnPage 0 0, InitialMapCommand Iconify
.fam
.fi
.if n .RE
.sp
This would hence place the window called \fIMyWindow\fP on page 0 0 for
the current desk, and immediately run the \fBIconify\fP command on that
window.
.sp
Note that should \fIInitialMapCommand\fP be used as a global option for
all windows, but there is a need that some windows should not have
this command applied, then an action of \fBNop\fP can be used on those
windows, as in the following example:
.sp
.if n .RS 4
.nf
.fam C
Style * InitialMapCommand Iconify
Style XTeddy InitialMapCommand Nop
.fam
.fi
.if n .RE
.sp
\fBWindow Manager placement\fP
.RS 4
Applications can place windows at a particular spot on the screen
either by window manager hints or a geometry specification. When they
do neither, then the window manager steps in to find a place for the
window. Fvwm knows several ways to deal with this situation. The
default is \fITileCascadePlacement\fP.
.sp
\fIPositionPlacement\fP [\fICenter\fP|\fIUnderMouse\fP|\fImove\-arguments\fP] When
used without an argument, new windows are placed in the top left
corner of the display. With the argument \fICenter\fP, all new window
appear at the center of the screen, and with \fIUnderMouse\fP, windows are
centered under the mouse pointer where possible. If the window is
unable to fit on the screen because the pointer is at the edge of the
screen, then the window is forced on\-screen using this option. If any
other \fImove\-arguments\fP are given, they are interpreted exactly as the
\fBMove\fP command does (with the exception that references to the current
window position do not work as the window has not been placed yet).
.sp
\fICascadePlacement\fP automatically place new windows in a cascading
fashion.
.sp
\fITileCascadePlacement\fP automatically places new windows in a smart
location \- a location in which they do not overlap any other windows
on the screen. If no such position can be found \fICascadePlacement\fP is
used as a fall\-back method.
.sp
\fITileManualPlacement\fP This is the same as \fITileCascadePlacement\fP, but
uses \fIManualPlacement\fP as the fall\-back method.
.sp
\fIMinOverlapPlacement\fP automatically places new windows in a location
in which the overlapping area in pixels of other windows is minimized.
By default this placement policy tries to avoid overlapping icons and
windows on higher layers. This can be configured with the
\fIMinOverlapPlacementPenalties\fP style.
.sp
\fIMinOverlapPercentPlacement\fP is similar to \fIMinOverlapPlacement\fP but
tries to minimize the overlapped percentages of other windows instead
of the overlapped area in pixels. This placement policy tries to avoid
covering other windows completely and tries even harder not to cover
small windows. This can be configured with the
\fIMinOverlapPlacementPenalties\fP and
\fIMinOverlapPercentPlacementPenalties\fP styles.
.sp
\fIMinOverlapPlacementPenalties\fP takes at most 6 positive or null
decimal arguments:
.sp
.if n .RS 4
.nf
.fam C
normal ontop icon sticky below strut
.fam
.fi
.if n .RE
.sp
if trailing arguments are missing the default is used which is:
.sp
.if n .RS 4
.nf
.fam C
1 5 10 1 0.05 50
.fam
.fi
.if n .RE
.sp
To reset this style to the default values, prefix it with a \*(Aq!\*(Aq. This
style configures the \fIMinOverlapPlacement\fP and
\fIMinOverlapPercentPlacement\fP placement policy. The \fInormal\fP factor
affects normal windows, the \fIontop\fP factor affects windows with a
greater layer than the window being placed, the \fIicon\fP factor affects
icons, the \fIsticky\fP factor affects sticky windows, the \fIbelow\fP factor
affects windows with a smaller layer than the window being placed, the
\fIstrut\fP factor affects the complement of the EWMH working area if the
window being placed has the \fIEWMHPlacementUseWorkingArea\fP style and
windows with an EWMH strut hint (i.e., a "please do not cover me"
hint) if the window being placed has the
\fIEWMHPlacementUseDynamicWorkingArea\fP style. These factors represent
the amount of area that these types of windows (or area) are counted
as, when a new window is placed. For example, by default the area of
ontop windows is counted 5 times as much as normal windows. So
\fIMinOverlapPlacement\fP and \fIMinOverlapPercentPlacement\fP covers 5 times
as much area of another window before it will cover an ontop window.
To treat ontop windows the same as other windows, set this to 1. To
really, really avoid putting windows under ontop windows, set this to
a high value, say 1000. This style affects the window already mapped
and not the window which is currently placed. There is one exception
to this rule: in the case of the window being placed has the
\fIEWMHPlacementUseWorkingArea\fP style the \fIstrut\fP factor affects the
placed window.
.sp
\fIMinOverlapPercentPlacementPenalties\fP takes at most 4 positive or null
integer arguments:
.sp
.if n .RS 4
.nf
.fam C
cover_100 cover_95 cover_85 cover_75
.fam
.fi
.if n .RE
.sp
if trailing arguments are missing the defaults are used which are:
.sp
.if n .RS 4
.nf
.fam C
12 6 4 1
.fam
.fi
.if n .RE
.sp
To reset this style to the default values, prefix it with a \*(Aq!\*(Aq. This
style affects the \fIMinOverlapPercentPlacement\fP placement policy and is
similar to the \fIMinOverlapPlacementPenalties\fP style. The \fIcover_xx\fP
factor is used when the window being placed covers at least \fIxx\fP
percent of the window. This factor is added to the factor determined
by the \fIMinOverlapPlacementPenalties\fP style.
.sp
\fIManualPlacement\fP (aka active placement). The user is required to
place every new window manually. The window only shows as a rubber
band until a place is selected manually. The window is placed when a
mouse button or any key except \fIEscape\fP is pressed. Escape aborts
manual placement which places the window in the top left corner of the
screen. If mouse button 2 is pressed during the initial placement of a
window (respectively \fIShift\fP and mouse button 1 in case Mwm emulation
has been enabled with the \fBEmulate\fP command), the user is asked to
resize the window too.
.sp
It is possible to define buttons usable to place windows with the
\fBMove\fP command and the special context \*(AqP\*(Aq for placement (see \fBMove\fP
command). However, you can\(cqt redefine the way to also resize the
window other than the way it is affected by the \fBEmulate\fP command. The
button used for placing the window can be checked with the
\fIPlacedByButton\fP condition (see \fBCurrent\fP command).
.sp
Example:
.sp
.if n .RS 4
.nf
.fam C
Style * ManualPlacement
*FvwmEvent: PassID
*FvwmEvent: add_window GrowDownFunc
AddToFunc StartFunction
+ I FvwmEvent
AddToFunc GrowDownFunc
+ I windowid $0 (PlacedByButton 3) \(rs
Resize bottomright keep \-0p
.fam
.fi
.if n .RE
.sp
Now, whenever a window is created and the user presses button 3 to
finish initial placement, the window is automatically enlarged until
it hits the bottom screen border.
.sp
\fIOld placement styles\fP DumbPlacement / SmartPlacement /
SmartPlacementOff, CleverPlacement / CleverPlacementOff,
ActivePlacement / RandomPlacement, ActivePlacementsHonorsStartsOnPage
/ ActivePlacementsHonorsStartsOnPageOff are
still supported but will be removed in the future. The old and new
styles can be translated according to the following table:
.sp
.if n .RS 4
.nf
.fam C
Style * DumbPlacement, RandomPlacement
\-\->
Style * CascadePlacement
Style * DumbPlacement, ActivePlacement
\-\->
Style * ManualPlacement
Style * SmartPlacement, \(rs
RandomPlacement, CleverPlacementOff
\-\->
Style * TileCascadePlacement
Style * SmartPlacement, \(rs
ActivePlacement, CleverPlacementOff
\-\->
Style * TileManualPlacement
Style * SmartPlacement, CleverPlacement
\-\->
Style * MinOverlapPlacement
Style * SmartPlacement, \(rs
ActivePlacement, CleverPlacement
\-\->
Style * MinOverlapPercentPlacement
Style * ActivePlacementsHonorsStartsOnPage
\-\->
Style * ManualPlacementsHonorsStartsOnPage
Style * ActivePlacementsHonorsStartsOnPageOff
\-\->
Style * ManualPlacementsHonorsStartsOnPageOff
.fam
.fi
.if n .RE
.RE
.sp
\fBPlacement policy options and window stacking\fP
.RS 4
\fI!UsePPosition\fP instructs fvwm to ignore the program specified
position (PPosition hint) when adding new windows. Using PPosition is
required for some applications, but if you do not have one of those
it\(cqs a real headache. Many programs set PPosition to something
obnoxious like 0,0 (upper left corner). Note: \fI!UsePPosition\fP is
equivalent to the deprecated option \fI!UsePPosition\fP
.sp
\fI!UseUSPosition\fP works like \fI!UsePPosition\fP but applies suppresses
using the user specified position indicated by the program (USPosition
hint). It is generally a bad thing to override the user\(cqs choice, but
some applications misuse the USPosition hint to force their windows to
a certain spot on the screen without the user\(cqs consent. Note:
\fI!UseUSPosition\fP is equivalent to the deprecated option \fI!USPosition\fP
.sp
\fINoUseTransientPPosition\fP and \fIUseTransientPPosition\fP work like
\fI!UsePPosition\fP and \fIUsePPosition\fP but apply only to transient
windows. Note: \fI!UseTransientPPosition\fP is equivalent to the
deprecated option \fI!TransientPPosition\fP
.sp
\fINoUseIconPosition\fP instructs fvwm to ignore the program specified
icon position (IconPosition hint) when iconifying the window. Note:
\fI!UseIconPosition\fP is equivalent to the deprecated option
\fI!IconPosition\fP
.sp
\fIStartsOnDesk\fP takes a numeric argument which is the desktop number on
which the window should be initially placed. Note that standard Xt
programs can also specify this via a resource (e.g. "\-xrm \*(Aq*Desk:
1\*(Aq").
.sp
\fIStartsOnPage\fP takes 1, 2, or 3 numeric arguments. If one or three
arguments are given, the first (or only) argument is the desktop
number. If three arguments are given, the 2nd and 3rd arguments
identify the x,y page position on the virtual window. If two arguments
are given, they specify the page position, and indicate no desk
preference. If only one argument is given, \fIStartsOnPage\fP functions
exactly like \fIStartsOnDesk\fP. For those standard Xt programs which
understand this usage, the starting desk/page can also be specified
via a resource (e.g., "\-xrm \*(Aq*page: 1 0 2\*(Aq"). \fIStartsOnPage\fP in
conjunction with \fISkipMapping\fP is a useful technique when you want to
start an app on some other page and continue with what you were doing,
rather than waiting for it to appear.
.sp
\fIStartsOnScreen\fP takes one argument. It must be a valid RandR name. A
new window is placed on the specified screen. The default is to place
windows on the screen that contains the mouse pointer at the time the
window is created. However, those windows which are not placed by fvwm
(i.e., those with a USPosition hint from a user specified geometry)
are normally placed in a position relative to all identified screens.
.sp
\fIStartsOnPageIncludesTransients\fP causes the \fIStartsOnPage\fP style to be
applied even for transient windows. This is not usually useful, since
transients are usually pop ups that you want to appear in your visible
viewport; but occasionally an application uses a transient for
something like a startup window that needs to be coerced into place.
.sp
\fIManualPlacementIgnoresStartsOnPage\fP suppresses \fIStartsOnPage\fP or
\fIStartsOnDesk\fP placement in the event that both \fIManualPlacement\fP and
\fISkipMapping\fP are in effect when a window is created. This prevents
you from interactively placing a window and then wondering where it
disappeared to, because it got placed on a different desk or page.
\fIManualPlacementHonorsStartsOnPage\fP allows this to happen anyway. The
option has no effect if \fISkipMapping\fP is not in effect, because fvwm
switches to the proper desk/page to perform interactive placement. The
default is \fIManualPlacementIgnoresStartsOnPage\fP;
\fIManualPlacementHonorsStartsOnPage\fP matches the way the old
\fIStartsOnDesk\fP style used to handle the situation.
.sp
\fICaptureHonorsStartsOnPage\fP causes the initial capture (of an already
existing window) at startup to place the window according to the
\fIStartsOnPage\fP and \fIStartsOnScreen\fP desk, page and screen
specification. \fICaptureIgnoresStartsOnPage\fP causes fvwm to ignore
these settings (including \fIStartsOnDesk\fP) on initial capture. The
default is \fICaptureIgnoresStartsOnPage\fP.
.sp
\fIRecaptureHonorsStartsOnPage\fP causes a window to be placed according
to, or revert to, the \fIStartsOnPage\fP and \fIStartsOnScreen\fP desk, page
and screen specification on \fBRestart\fP. \fIRecaptureIgnoresStartsOnPage\fP
causes fvwm to respect the current window position on \fBRestart\fP. The
default is \fIRecaptureIgnoresStartsOnPage\fP.
.sp
\fILayer\fP accepts one optional argument: a non\-negative integer. This is
the layer the window is put in. If no argument is given, any
previously set value is deleted and the default layer is implied.
.sp
\fIStaysOnTop\fP puts the window in the top layer. This layer can be
changed by the command \fBDefaultLayers\fP; the default is 6.
.sp
\fIStaysPut\fP puts the window in the put layer. This layer can be changed
by the command \fBDefaultLayers\fP; the default is 4.
.sp
\fIStaysOnBottom\fP puts the window in the bottom layer. This layer can be
changed by the command \fBDefaultLayers\fP; the default is 2.
.sp
\fIStartsLowered\fP instructs fvwm to put the window initially at the
bottom of its layer rather than the default \fIStartsRaised\fP.
.sp
\fIStartShaded\fP tells fvwm to shade the window. An optional direction
argument may be given, which can be one of "\fINorth\fP", "\fISouth\fP",
"\fIWest\fP", "\fIEast\fP", "\fINorthWest\fP", "\fINorthEast\fP", "\fISouthWest\fP",
"\fISouthEast\fP" or if no direction is given, the default is to shade
north.
.sp
\fISkipMapping\fP tells fvwm not to switch to the desk the window is on
when it gets mapped initially (useful with \fIStartsOnDesk\fP or
\fIStartsOnPage\fP).
.sp
\fIKeepWindowGroupsOnDesk\fP makes new windows that have the window group
hint set appear on the same desk as the other windows of the same
group. Since this behavior may be confusing, the default setting is
\fIScatterWindowGroups\fP. The window group hint is ignored when placing
windows in this case.
.RE
.sp
\fBTransient windows\fP
.RS 4
\fIDecorateTransient\fP causes transient windows, which are normally left
undecorated, to be given the usual fvwm decorations (title bar,
buttons, etc.). Note that some pop\-up windows, such as the xterm
menus, are not managed by the window manager and still do not receive
decorations. \fINakedTransient\fP (the default) causes transient windows
not to be given the standard decorations. You can only bind keys or
mouse buttons to the sides and the client part of an undecorated
window (\*(AqS\*(Aq and ´W\*(Aq contexts in bindings, see \fBMouse\fP and \fIKey\fP
commands).
.sp
A window with the \fIRaiseTransient\fP style that has transient windows
raises all its transients when it is raised. The \fIDontRaiseTransient\fP
style disables this behavior. All windows are then treated as if they
had no transients.
.sp
A window with the \fILowerTransient\fP style that has transient windows
lowers all its transients when it is lowered. The \fIDontLowerTransient\fP
style disables this behavior. All windows are then treated as if they
had no transients.
.sp
The \fIStackTransientParent\fP style augments \fIRaiseTransient\fP and
\fILowerTransient\fP styles. Raising a window with \fIStackTransientParent\fP
style transfers the raise action to the main window if the window
being raised is a transient and its main window has \fIRaiseTransient\fP
style; this effect makes raise on a transient act just like raise on
its main \- the whole group is raised. Similar behavior holds for
lowering a whole group of transients when the main has
\fILowerTransient\fP style. \fIDontStackTransientParent\fP turns this behavior
off. \fI(Dont)StackTransientParent\fP has no effect if \fIRaiseTransient\fP
and \fILowerTransient\fP are not used.
.sp
A reasonable emulation of Motif raise/lower on transients is possible
like this
.sp
.if n .RS 4
.nf
.fam C
Style * RaiseTransient
Style * LowerTransient
Style * StackTransientParent
.fam
.fi
.if n .RE
.RE
.sp
\fBExtended Window Manager Hints styles\fP
.RS 4
To understand the used terminology in this sub section, please read
the \fBExtended Window Manager Hints\fP section.
.sp
\fIEWMHDonateIcon\fP instructs fvwm to set the application ewmh icon hint
with the icon that is used by fvwm if the application does not provide
such hint (and if the icon used by fvwm is not an icon window).
\fIEWMHDonateMiniIcon\fP does the same thing for mini icons. This allows
compliant pager, taskbar, iconbox ...etc to display the same (mini)
icons as fvwm. Note that on some hardware (e.g., 8\-bit displays) these
styles can slow down window mapping and that in general only one of
these styles is needed by a compliant application.
\fIEWMHDontDonateIcon\fP and \fIEWMHDontDonateMiniIcon\fP restore the defaults
which are to not set any ewmh (mini) icons hints.
.sp
By default, if an application provides an ewmh icon hint of small size
(i.e., height and width less than or equal to 22), then fvwm uses this
icon as its mini icon. \fIEWMHMiniIconOverride\fP instructs fvwm to ignore
ewmh icons and to use the mini icon provided by the \fIMiniIcon\fP style.
\fIEWMHNoMiniIconOverride\fP restores the default.
.sp
\fIEWMHUseStackingOrderHints\fP causes fvwm to use EWMH hints and respect
EWMH hints which change the window layer.
\fIEWMHIgnoreStackingOrderHints\fP causes fvwm to ignore EWMH layer hints.
.sp
An application can ask for some reserved space on the desktop by a
hint. In the EWMH terminology such a hint is called a strut and it is
used to compute the working area and may be used for window placement
and in the maximize command. \fIEWMHIgnoreStrutHints\fP causes fvwm to
ignore such hints, as \fIEWMHUseStrutHints\fP, causes fvwm to use it which
is the default.
.sp
\fIEWMHIgnoreStateHints\fP causes fvwm to ignore initial EWMH state hints
when a new window is mapped. The default \fIEWMHUseStateHints\fP causes
fvwm to accept such hints.
.sp
\fIEWMHIgnoreWindowType\fP causes fvwm to ignore EWMH window type
specification. The default \fI!EWMHIgnoreWindowType\fP causes fvwm to
style windows of specified types as such.
.sp
\fIEWMHMaximizeIgnoreWorkingArea\fP causes fvwm to ignore the EWMH working
area when it executes a \fBMaximize\fP command. With
\fIEWMHMaximizeUseWorkingArea\fP the EWMH working area is used as with
\fIEWMHMaximizeUseDynamicWorkingArea\fP the EWMH dynamic working area is
used (the default).
.sp
\fIEWMHPlacementIgnoreWorkingArea\fP causes fvwm to ignore the EWMH
working area when it places (or places again) a window. With
\fIEWMHPlacementUseWorkingArea\fP the EWMH working area is taken in
account as with \fIEWMHPlacementUseDynamicWorkingArea\fP the EWMH dynamic
working area is taken in account (the default). Note that with the
\fIMinOverlapPlacement\fP and \fIMinOverlapPercentPlacement\fP placement
policy, the way the EWMH (dynamic) working area is taken in account is
configurable with the \fIMinOverlapPlacementPenalties\fP style.
.RE
.sp
\fBMiscellaneous\fP
.RS 4
The \fIBackingStore\fP, \fIBackingStoreOff\fP and \fIBackingStoreWindowDefault\fP
determine if the X server uses backing store for the window or not.
\fIBackingStore\fP means that the X server tries to keep the obscured
parts of a window in memory. This is usually slower if the client runs
on the same machine as the X server, but can be much faster if the
connection is slow (see also \fISaveUnder\fP below). \fIBackingStoreOff\fP
disables backing store for the window. By default, fvwm does not
enable or disable backing store itself but leaves is as the window
requested it. To revert back to the application\(cqs choice, use the
\fIBackingStoreWindowDefault\fP style.
.sp
Note: This style is useless if the X server does not allow backing
store.
.sp
\fISaveUnder\fP enables the corresponding window attribute in the X
server. For a window using this style, the X server tries to store the
graphics below it in memory which is usually slower if the client runs
on the same machine as the X server. \fISaveUnder\fP may speed up fvwm if
the connection to the X server is slow (e.g. over a modem link). To
disable save under, use the \fISaveUnderOff\fP style. This is the default.
See also \fIBackingStore\fP above.
.sp
Note: This style is useless if the X server does not allow save under.
.sp
\fIParentalRelativity\fP enables clients that use a background pixmap of
type \fIParentRelative\fP to achieve transparency. Fvwm modules that
support transparent colorsets require this setting. \fIOpacity\fP is the
default and should be used for all non\-transparent clients for better
performance.
.sp
\fIMwmDecor\fP makes fvwm attempt to recognize and respect the mwm
decoration hints that applications occasionally use. To switch this
style off, use the \fINoDecorHint\fP style.
.sp
\fIMwmFunctions\fP makes fvwm attempt to recognize and respect the mwm
prohibited operations hints that applications occasionally use.
\fIHintOverride\fP makes fvwm shade out operations that mwm would
prohibit, but it lets you perform the operation anyway. \fINoFuncHint\fP
allows turns off the mwm hints completely.
.sp
\fIOLDecor\fP makes fvwm attempt to recognize and respect the olwm and
olvwm hints that many older XView and OLIT applications use. Switch
this option off with \fINoOLDecor\fP.
.sp
\fIUseDecor\fP This style is deprecated and will be removed in the future.
There are plans to replace it with a more flexible solution in
fvwm\-3.0.
.sp
\fIUseDecor\fP accepts one argument: the name of a decor created with
\fBAddToDecor\fP. If no decor name is specified, the "Default" decor is
used. Windows do not actually contain decors, but are always assigned
to one. If the decor is later modified with \fBAddToDecor\fP, the changes
are visible for all windows which are assigned to it. The decor for a
window can be reassigned with \fBChangeDecor\fP.
.sp
\fIUseStyle\fP This style is deprecated and will be removed in the future.
There are plans to replace it with a more flexible solution in
fvwm\-3.0.
.sp
\fIUseStyle\fP takes one arg, which is the name of another style. That way
you can have unrelated window names easily inherit similar traits
without retyping. For example:
.sp
.if n .RS 4
.nf
.fam C
Style rxvt UseStyle XTerm
.fam
.fi
.if n .RE
.sp
Warning: If a style is built from one or more parent styles and the
parent styles are changed, the derived style is not modified. To
achieve this you have to issue the \fIUseStyle\fP line again.
.sp
\fIUnmanaged\fP Windows with the \fIUnmanaged\fP style option are ignored by
fvwm. They are not decorated, can not be moved or resized, etc. You
probably want to use \fBBugopts RaiseOverUnmanaged\fP too. This option can
be turned off with the \fI!Unmanaged\fP style.
.sp
\fIState\fP sets the initial value of one of the 32 user defined states
which are associated with each window. The state number ranges from 0
to 31 and must be given as an argument. The states have no meaning in
fvwm, but they can be checked in conditional commands like \fBNext\fP with
the \fIState\fP condition and manipulated with the \fBState\fP command.
.sp
.if n .RS 4
.nf
.fam C
# turn on state 11 for xterms ...
Style xterm State 11
# ... but not for rxvts.
Style rxvt !State 11
.fam
.fi
.if n .RE
.sp
Windows with the \fIWindowListSkip\fP styles do not appear in the menu
that is created with the \fBWindowList\fP command or the lists shown in
modules like \fBFvwmIconMan\fP. In the modules, the style can usually be
ignored with an option. Please refer to the man page of the module in
question for further information. To disable this feature, use the
default style \fIWindowListHit\fP.
.sp
The styles \fICirculateSkip\fP and \fICirculateHit\fP control whether the
window is considered by conditional commands, for example \fBNext\fP,
\fIPrev\fP or \fIAll\fP. Windows with \fICirculateSkip\fP, are never selected by
conditional commands. However, the styles can be overridden explicitly
in the condition with the \fICirculateHit\fP, \fICirculateHitIcon\fP or
\fICirculateHitShaded\fP conditions, and some conditional commands,
e.g. \fBCurrent\fP and \fIAll\fP, do this by default. The styles
\fICirculateSkipIcon\fP, \fICirculateHitIcon\fP, \fICirculateSkipShaded\fP and
\fICirculateHitShaded\fP work like \fICirculateSkip\fP and \fICirculateHit\fP but
apply only to iconic or shaded windows. Note: if multiple ...Skip...
options are combined, windows are only selected if they match none of
the given conditions. So, with
.sp
.if n .RS 4
.nf
.fam C
Style * CirculateSkipIcon, CirculateSkipShaded
.fam
.fi
.if n .RE
.sp
only windows that are neither iconic nor shaded are selected. Note:
For historical reasons, the conditional commands understand the names
of these styles as condition names. Take care not to confuse them.
.RE
.sp
\fBExamples\fP
.RS 4
.RE
.sp
.if n .RS 4
.nf
.fam C
# Change default fvwm behavior to no title\-
# bars on windows! Also define a default icon.
Style * !Title, \(rs
Icon unknown1.xpm, \(rs
BorderWidth 4, \(rs
HandleWidth 5
# now, window specific changes:
Style Fvwm* !Handles, Sticky, \(rs
WindowListSkip, \(rs
BorderWidth 0
Style FvwmPager StaysOnTop, BorderWidth 0
Style *lock !Handles, Sticky, \(rs
StaysOnTop, WindowListSkip
Style xbiff Sticky, WindowListSkip
Style FvwmButtons !Handles, Sticky, \(rs
WindowListSkip
Style sxpm !Handles
# Put title\-bars back on xterms only!
Style xterm Title, Color black/grey
Style rxvt Icon term.xpm
Style xterm Icon rterm.xpm
Style xcalc Icon xcalc.xpm
Style xbiff Icon mail1.xpm
Style xmh Icon mail1.xpm, \(rs
StartsOnDesk 2
Style xman Icon xman.xpm
Style matlab Icon math4.xpm, \(rs
StartsOnDesk 3
Style xmag Icon magnifying_glass2.xpm
Style xgraph Icon graphs.xpm
Style FvwmButtons Icon toolbox.xpm
Style Maker StartsOnDesk 1
Style signal StartsOnDesk 3
# Fire up Netscape on the second desk, in the
# middle of my 3x3 virtual desktop, and do not
# bother me with it...
Style Netscape* SkipMapping, \(rs
StartsOnPage 1 1 1
.fam
.fi
.if n .RE
.sp
Note that all properties for a window are or\(cqed together. In the above
example "FvwmPager" gets the property \fIStaysOnTop\fP via an exact window
name match but also gets \fI!Handles\fP, \fISticky\fP and \fIWindowListSkip\fP by
a match to "Fvwm*". It gets \fI!Title\fP by virtue of a match to "*". If
conflicting styles are specified for a window, then the last style
specified is used.
.sp
\fBWindowStyle\fP \fIoptions\fP
.RS 4
sets attributes (styles) on the selected window. The \fIoptions\fP are
exactly the same as for the \fBStyle\fP command.
.RE
.SS "Window Styles"
.sp
\fBAddButtonStyle\fP button [\fIstate\fP] [\fIstyle\fP] [\-\- [!]\fIflag\fP ...]
.RS 4
Adds a button style to \fIbutton\fP. \fIbutton\fP can be a button number, or
one of "\fIAll\fP", "\fILeft\fP" or "\fIRight\fP". \fIstate\fP can be "\fIActiveUp\fP",
"\fIActiveDown\fP", "\fIInactiveUp\fP" or "\fIInactiveDown\fP", or "\fIActive\fP" (the
same as both "ActiveUp" and "ActiveDown") or "\fIInactive\fP" (the same as
both "InactiveUp" and "InactiveDown") or any of these 6 with
"\fIToggled\fP" prepended. The "Active" states apply to the focused
window, the "Inactive" ones apply to all other windows. The "Up"
states apply to the non pressed buttons, the "Down" ones apply to
pressed buttons. The "Toggled" prefix refers to maximized, shaded or
sticky windows that have the corresponding \fIMwmDecor...\fP button style
set. Additionally, the following shortcuts may be used: "\fIAllNormal\fP",
"\fIAllToggled\fP", "\fIAllActive\fP", "\fIAllInactive\fP", "\fIAllUp\fP",
"\fIAllDown\fP". They are actually different masks for 4 individual states
from 8 total. These are supported too: "\fIAllActiveUp\fP",
"\fIAllActiveDown\fP", "\fIAllInactiveUp\fP", "\fIAllInactiveDown\fP".
.sp
If \fIstate\fP is omitted, then the style is added to every state. If the
\fIstyle\fP and \fIflags\fP are enclosed in parentheses, then multiple \fIstate\fP
definitions can be placed on a single line. \fIFlags\fP for additional
button styles cannot be changed after definition.
.sp
Buttons are drawn in the order of definition, beginning with the most
recent button style, followed by those added with \fBAddButtonStyle\fP. To
clear the button style stack, change style flags, or for descriptions
of available styles and flags, see the \fBButtonStyle\fP command.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
**ButtonStyle** 1 Pixmap led.xpm \-\- Top Left
**ButtonStyle** 1 ActiveDown HGradient 8 grey black
**ButtonStyle All** \-\- UseTitleStyle
AddButtonStyle 1 \(rs
ActiveUp (Pixmap a.xpm) \(rs
ActiveDown (Pixmap b.xpm \-\- Top)
AddButtonStyle 1 Vector 4 50x30@1 70x70@0 30x70@0 50x30@1
.fam
.fi
.if n .RE
.sp
Initially for this example all button states are set to a pixmap. The
second line replaces the "ActiveDown" state with a gradient (it
overrides the pixmap assigned to it in the line before, which assigned
the same style to every state). Then, the \fIUseTitleStyle\fP flag is set
for all buttons, which causes fvwm to draw any styles set with
\fBTitleStyle\fP before drawing the buttons. Finally, \fBAddButtonStyle\fP is
used to place additional pixmaps for both "ActiveUp" and "ActiveDown"
states and a vector button style is drawn on top of all states.
.RE
.sp
\fBAddTitleStyle\fP [\fIstate\fP] [\fIstyle\fP] [\-\- [!]\fIflag\fP ...]
.RS 4
Adds a title style to the title\-bar. \fIstate\fP can be "\fIActiveUp\fP",
"\fIActiveDown\fP", "\fIInactiveUp\fP" or "\fIInactiveDown\fP", or "\fIActive\fP" (the
same as both "ActiveUp" and "ActiveDown") or "\fIInactive\fP" (the same as
both "InactiveUp" and "InactiveDown") or any of these 6 with "Toggled"
prepended. If \fIstate\fP is omitted, then the style is added to every
state. If the \fIstyle\fP and \fIflags\fP are enclosed in parentheses, then
multiple \fIstate\fP definitions can be placed on a single line. This
command is quite similar to the \fBAddButtonStyle\fP command.
.sp
Title\-bars are drawn in the order of definition, beginning with the
most recent \fBTitleStyle\fP, followed by those added with
\fBAddTitleStyle\fP. To clear the title style stack, change style flags,
or for the descriptions of available styles and flags, see the
\fBTitleStyle\fP and \fBButtonStyle\fP commands.
.RE
.sp
\fBAddToDecor\fP \fIdecor\fP
.RS 4
This command is deprecated and will be removed in the future. There
are plans to replace it with a more flexible solution in fvwm\-3.0.
.sp
Add or divert commands to the decor named \fIdecor\fP. A decor is a name
given to the set of commands which affect button styles, title\-bar
styles and border styles. If \fIdecor\fP does not exist it is created;
otherwise the existing \fIdecor\fP is modified. Note: Earlier versions
allowed to use the \fBHilightColor\fP, \fBHilightColorset\fP and \fBWindowFont\fP
commands in decors. This is no longer possible. Please use the \fBStyle\fP
command with the \fIHilight...\fP and \fIFont\fP options.
.sp
New decors start out exactly like the "default" decor without any
style definitions. A given decor may be applied to a set of windows
with the \fIUseDecor\fP option of the \fBStyle\fP command. Modifying an
existing decor affects all windows which are currently assigned to it.
.sp
\fBAddToDecor\fP is similar in usage to the \fBAddToMenu\fP and \fBAddToFunc\fP
commands, except that menus and functions are replaced by
\fBButtonStyle\fP, \fBAddButtonStyle\fP, \fBTitleStyle\fP, \fBAddTitleStyle\fP and
\fBBorderStyle\fP commands. Decors created with \fBAddToDecor\fP can be
manipulated with \fBChangeDecor\fP, \fBDestroyDecor\fP, \fBUpdateDecor\fP and the
\fBStyle\fP option.
.sp
The following example creates a decor "FlatDecor" and style
"FlatStyle". They are distinct entities:
.sp
.if n .RS 4
.nf
.fam C
AddToDecor FlatDecor
+ ButtonStyle All Active (\-\- flat) Inactive (\-\- flat)
+ TitleStyle \-\- flat
+ BorderStyle \-\- HiddenHandles NoInset
Style FlatStyle \(rs
UseDecor FlatDecor, HandleWidth 4, Colorset 0, HilightColorset 1
Style xterm UseStyle FlatStyle
.fam
.fi
.if n .RE
.sp
An existing window\(cqs decor may be reassigned with \fBChangeDecor\fP. A
decor can be destroyed with \fBDestroyDecor\fP.
.sp
.if n .RS 4
.nf
.fam C
DestroyDecor FlatDecor
AddToDecor FlatDecor ...
Style FlatStyle UseDecor FlatDecor
.fam
.fi
.if n .RE
.sp
and now apply the style again:
.sp
.if n .RS 4
.nf
.fam C
Style xterm UseStyle FlatStyle
.fam
.fi
.if n .RE
.RE
.sp
\fBBorderStyle\fP \fIstate\fP [\fIstyle\fP] [\-\- [!]\fIflag\fP ...]
.RS 4
Defines a border style for windows. \fIstate\fP can be either "\fIActive\fP"
or "\fIInactive\fP". If \fIstate\fP is omitted, then the style is set for both
states. If the \fIstyle\fP and \fIflags\fP are enclosed in parentheses, then
multiple \fIstate\fP definitions can be specified per line.
.sp
\fIstyle\fP is a subset of the available button styles, and can only be
\fITiledPixmap\fP (uniform pixmaps which match the bevel colors work best
this way) or \fIColorset\fP. If a \*(Aq!\*(Aq is prefixed to any \fIflag\fP, the
behavior is negated. If \fIstyle\fP is not specified, then one can change
flags without resetting the style.
.sp
The \fIHiddenHandles\fP flag hides the corner handle dividing lines on
windows with handles (this option has no effect for !\fIHandles\fP
windows). By default, \fIHiddenHandles\fP is disabled.
.sp
The \fINoInset\fP flag supplements \fIHiddenHandles\fP. If given, the inner
bevel around the window frame is not drawn. If \fIHiddenHandles\fP is not
specified, the frame looks a little strange.
.sp
\fIRaised\fP causes a raised relief pattern to be drawn (default). \fISunk\fP
causes a sunken relief pattern to be drawn. \fIFlat\fP inhibits the relief
pattern from being drawn.
.sp
To decorate the active and inactive window borders with a textured
pixmap, one might specify:
.sp
.if n .RS 4
.nf
.fam C
BorderStyle Active TiledPixmap marble.xpm
BorderStyle Inactive TiledPixmap granite.xpm
BorderStyle Active \-\- HiddenHandles NoInset
.fam
.fi
.if n .RE
.sp
To clear the style for both states:
.sp
.if n .RS 4
.nf
.fam C
BorderStyle Simple
.fam
.fi
.if n .RE
.sp
To clear for a single state:
.sp
.if n .RS 4
.nf
.fam C
BorderStyle Active Simple
.fam
.fi
.if n .RE
.sp
To unset a flag for a given state:
.sp
.if n .RS 4
.nf
.fam C
BorderStyle Inactive \-\- !NoInset
.fam
.fi
.if n .RE
.sp
title\-bar buttons can inherit the border style with the
\fIUseBorderStyle\fP flag (see \fBButtonStyle\fP).
.RE
.sp
\fBButtonState\fP [ActiveDown \fIbool\fP] [Inactive \fIbool\fP] [InactiveDown \fIbool\fP]
.RS 4
The \fBButtonState\fP command controls which states of the window titles
and title buttons are used. The default is to use all four states:
"ActiveUp", "ActiveDown", "InactiveUp" and "InactiveDown" (see
\fBButtonStyle\fP and \fBTitleStyle\fP commands). The \fIbool\fP argument after
the key word controls if the designated state is used ("True") or not
("False"). The \fIbool\fP flag is the same as other commands, and not
limited to just "True" or "False"; "Yes" and "No" may also be used.
The "ActiveUp" state cannot be deactivated. If no arguments are
provided or the given arguments are invalid, the default is restored.
.sp
If \fIActiveDown\fP argument is "False", no different button style for the
pressed down buttons used, instead "ActiveUp" state is used even when
button is pressed.
.sp
If \fIInactive\fP argument is "False", focused and unfocused windows look
similarly, the corresponding "Active" states are always used.
.sp
If \fIInactiveDown\fP argument is "False" (only applied when \fIInactive\fP is
"True"), the pressed titles and title buttons in non\-focused windows
are drawn using "InactiveUp" or "ActiveUp" states depending on the
values of the other key words.
.RE
.sp
\fBButtonStyle\fP button [\fIstate\fP] [\fIstyle\fP] [\-\- [!]\fIflag\fP ...]
.RS 4
Sets the button style for a title\-bar button. \fIbutton\fP is the
title\-bar button number between 0 and 9, or one of "\fIAll\fP", "\fILeft\fP",
"\fIRight\fP", or "\fIReset\fP". Button numbering is described in the \fBMouse\fP
command section. If the \fIstyle\fP and \fIflags\fP are enclosed in
parentheses, then multiple \fIstate\fP definitions can be specified per
line.
.sp
\fIstate\fP refers to which button state should be set. Button states are
defined as follows: "\fIActiveUp\fP" and "\fIActiveDown\fP" refer to the
un\-pressed and pressed states for buttons on active windows; while the
"\fIInactiveUp\fP" and "\fIInactiveDown\fP" states denote buttons on inactive
windows. The shortcut "\fIActive\fP" denotes both "ActiveUp" and
"ActiveDown" states. Shortcut "\fIInactive\fP" denotes both "InactiveUp"
and "InactiveDown" states. The similar state names like just
described, but with the "Toggled" prefix are used instead for title
buttons which have one of the \fIMwmDecorMax\fP, \fIMwmDecorShade\fP,
\fIMwmDecorStick\fP or \fIMwmDecorLayer\fP hints, if the window is maximized,
shaded, sticky or placed on specific layer, respectively.
.sp
.if n .RS 4
.nf
.fam C
AddToDecor Default
+ ButtonStyle 6 \(rs
Vector 4 50x25@1 85x75@0 15x75@0 50x25@1
+ ButtonStyle 6 ToggledActiveUp \(rs
Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
+ ButtonStyle 6 ToggledActiveDown \(rs
Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
+ ButtonStyle 6 ToggledInactive \(rs
Vector 4 50x75@0 85x25@1 15x25@0 50x75@0
+ ButtonStyle 6 \- MwmDecorShade
Mouse 0 6 N WindowShade
.fam
.fi
.if n .RE
.sp
Additionally, the following shortcuts may be used: "\fIAllNormal\fP",
"\fIAllToggled\fP", "\fIAllActive\fP", "\fIAllInactive\fP", "\fIAllUp\fP",
"\fIAllDown\fP". They are actually different masks for 4 individual states
from 8 total. These are supported too: "\fIAllActiveUp\fP",
"\fIAllActiveDown\fP", "\fIAllInactiveUp\fP", "\fIAllInactiveDown\fP".
.sp
If \fIstate\fP is specified, that particular button state is set. If
\fIstate\fP is omitted, every state is set. Specifying a style destroys
the current style (use \fBAddButtonStyle\fP to avoid this).
.sp
If \fIstyle\fP is omitted, then state\-dependent flags can be set for the
primary button style without destroying the current style. Examples
(each line should be considered independent):
.sp
.if n .RS 4
.nf
.fam C
ButtonStyle Left \-\- flat
ButtonStyle All ActiveUp (\-\- flat) Inactive (\-\- flat)
.fam
.fi
.if n .RE
.sp
The first line sets every state of the left buttons to flat, while the
second sets only the "ActiveUp" and "Inactive" states of every button
to flat (only flags are changed; the buttons\*(Aq individual styles are
not changed).
.sp
If you want to reset all buttons to their defaults:
.sp
.if n .RS 4
.nf
.fam C
ButtonStyle Reset
.fam
.fi
.if n .RE
.sp
To reset the "ActiveUp" button state of button 1 to the default:
.sp
.if n .RS 4
.nf
.fam C
ButtonStyle 1 ActiveUp Default
.fam
.fi
.if n .RE
.sp
To reset all button states of button 1 to the default of button number
2:
.sp
.if n .RS 4
.nf
.fam C
ButtonStyle 1 Default 2
.fam
.fi
.if n .RE
.sp
For any button, multiple \fIstate\fP definitions can be given on one line
by enclosing the \fIstyle\fP and \fIflags\fP in parentheses. If only one
definition per line is given the parentheses can be omitted.
.sp
\fIflags\fP affect the specified \fIstate\fP. If a \*(Aq!\*(Aq is prefixed to any
\fIflag\fP, its behavior is negated. The available state\-dependent flags
for all styles are described here (the \fBButtonStyle\fP entry deals with
state\-independent flags).
.sp
\fIRaised\fP causes a raised relief pattern to be drawn.
.sp
\fISunk\fP causes a sunken relief pattern to be drawn.
.sp
\fIFlat\fP inhibits the relief pattern from being drawn.
.sp
\fIUseTitleStyle\fP causes the given button state to render the current
title style before rendering the buttons\*(Aq own styles. The \fIRaised\fP,
\fIFlat\fP and \fISunk\fP \fBTitleStyle\fP flags are ignored since they are
redundant in this context.
.sp
\fIUseBorderStyle\fP causes the button to inherit the decorated
\fBBorderStyle\fP options.
.sp
\fIRaised\fP, \fISunk\fP and \fIFlat\fP are mutually exclusive, and can be
specified for the initial \fBButtonStyle\fP only. \fIUseTitleStyle\fP and
\fIUseBorderStyle\fP are also mutually exclusive (both can be off
however). The default is \fIRaised\fP with both \fIUseBorderStyle and
UseTitleStyle\fP left unset.
.sp
\fBImportant\fP
.sp
for the "ActiveDown" and "InactiveDown" states: When a button is
pressed, the relief is inverted. Because of this, to obtain the raised
look in "ActiveDown" or "InactiveDown" states you must specify the
opposite of the desired relief (i.e. \fISunk\fP for "ActiveDown" or
"InactiveDown"). This behavior is consistent, but may seem confusing
at first. The same applies to the "Toggled" states.
.sp
Button styles are classified as non\-destructive, partially
destructive, or fully destructive. Non\-destructive styles do not
affect the image. Partially destructive styles can obscure some or all
parts of the underlying image (i.e. \fIPixmap\fP). Fully destructive
styles obscure the entire underlying image (i.e. \fISolid\fP or one of the
\fIgradient\fP styles). Thus, if stacking styles with \fBAddButtonStyle\fP (or
\fBAddTitleStyle\fP for title\-bars), use care in sequencing styles to
minimize redraw.
.sp
The available styles are:
.sp
\fISimple\fP, \fIDefault\fP, \fISolid\fP, \fIColorset\fP, \fIVector\fP, \fI?Gradient\fP,
\fIPixmap\fP, \fIAdjustedPixmap\fP, \fIShrunkPixmap\fP, \fIStretchedPixmap\fP,
\fITiledPixmap\fP, \fIMiniIcon\fP
.sp
The description of these styles and their arguments follow:
.sp
The \fISimple\fP style does nothing. There are no arguments, and this
style is an example of a non\-destructive button style.
.sp
The \fIDefault\fP style conditionally accepts one argument: a number which
specifies the default button number to load. If the style command
given is \fBButtonStyle\fP or \fBAddButtonStyle\fP, the argument is optional
(if given, it overrides the current button). If a command other than
\fBButtonStyle\fP or \fBAddButtonStyle\fP is used, the number must be
specified.
.sp
The \fISolid\fP style fills the button with a solid color. The relief
border color is not affected. The color is specified as a single
argument. This style is fully destructive.
.sp
The \fIColorset\fP \fIcs\fP [\fIalpha\fP] style fills the button with the Colorset
\fIcs\fP. The optional \fIalpha\fP argument is a percentage between 0 and 100.
It causes fvwm to merge the colorset background onto the button using
this percentage. If the percentage is 0 the colorset background is
hidden and if it is 100 the colorset background is fully applied. The
default is 100. So, the destructiveness depends on the \fIalpha\fP
argument.
.sp
The \fIVector\fP \fInum\fP
\fIX\fP\fB[\fP\fIoffset\fP\fBp]x\fP\fIY\fP\fB[\fP\fIoffset\fP\fBp]@C ...\fP
style draws a line pattern. Since this is a standard button style, the
keyword \fIVector\fP is optional, \fInum\fP is a number of point
specifications of the form
\fIX\fP\fB[\fP\fIoffset\fP\fBp]x\fP\fIY\fP\fB[\fP\fIoffset\fP\fBp]@C ...\fP \fIX\fP
and \fIY\fP are point coordinates inside the button, given in percents
(from 0 to 100). An optional absolute \fIoffset\fP in pixels, can be given
as "+p" for a positive or "\-p" for a negative offset.
.sp
\fIC\fP specifies a line color (0 \- the shadow color, 1 \- the highlight
color, 2 \- the background color, 3 \- the foreground color, 4 \- only
move the point, do not draw). The first point color is not used. You
can use up to 10000 points in a line pattern. This style is partially
destructive.
.sp
The specification is a little cumbersome:
.sp
.if n .RS 4
.nf
.fam C
ButtonStyle 2 Vector 4 50x30@1 70x70@0 30x70@0 50x30@1
.fam
.fi
.if n .RE
.sp
then the button 2 decoration uses a 4\-point pattern consisting of a
line from (x=50,y=30) to (70,70) in the shadow color (@0), and then to
(30,70) in the shadow color, and finally to (50,30) in the highlight
color (@1). Is that too confusing? See the fvwm web pages for some
examples with screenshots.
.sp
A more complex example of \fIVector\fP:
.sp
.if n .RS 4
.nf
.fam C
ButtonStyle 8 Vector 10 45x65@2 45x75@3 \(rs
20x75@3 20x50@3 35x50@3 35x65@1 35x25@1 \(rs
75x25@1 75x65@0 35x65@0
ButtonStyle 0 Vector 10 45x65@2 45x75@0 \(rs
20x75@0 20x50@1 45x50@1 45x65@0 75x65@3 \(rs
75x25@3 35x25@3 35x47@3
.fam
.fi
.if n .RE
.sp
The \fIGradient\fP styles denote color gradients. Fill in the question
mark with any one of the defined gradient types. Please refer to the
\fBColor Gradients\fP section for a description of the gradient syntax.
The gradient styles are fully destructive.
.sp
The \fIPixmap\fP style displays a pixmap. A pixmap should be specified as
an argument. For example, the following would give button number 2 the
same pixmap for all 4 states (2 active and 2 inactive), and button
number 4 all different pixmaps.
.sp
.if n .RS 4
.nf
.fam C
ButtonStyle 2 Pixmap my_pixmap.xpm
ButtonStyle 4 \(rs
ActiveUp (Pixmap activeup.xpm) \(rs
ActiveDown (Pixmap activedown.xpm) \(rs
Inactive (Pixmap inactiveup.xpm)
ButtonStyle 4 \(rs
InactiveDown Pixmap inactivedown.xpm
.fam
.fi
.if n .RE
.sp
The pixmap specification can be given as an absolute or relative
pathname (see \fBImagePath\fP). If the pixmap cannot be found, the button
style reverts to \fISimple\fP. Flags specific to the \fIPixmap\fP style are
\fILeft\fP, \fIRight\fP, \fITop\fP, and \fIBottom\fP. These can be used to justify the
pixmap (default is centered for both directions). Pixmap transparency
is used for the color "None." This style is partially destructive.
.sp
The \fIAdjustedPixmap\fP style is similar to the \fIPixmap\fP style. But the
image is resized to exactly fit the button.
.sp
The \fIShrunkPixmap\fP style is similar to the \fIPixmap\fP style. But if the
image is bigger than the button the image is resized to fit into the
button.
.sp
The \fIStretchedPixmap\fP style is similar to the \fIPixmap\fP style. But if
the image is smaller than the button the image is resized to cover the
button.
.sp
The \fITiledPixmap\fP style accepts a pixmap to be tiled as the button
background. One pixmap is specified as an argument. Pixmap
transparency is not used. This style is fully destructive.
.sp
The \fIMiniIcon\fP style draws the window\(cqs miniature icon in the button,
which is specified with the \fIMiniIcon\fP option of the \fBStyle\fP command.
This button style accepts no arguments. Example:
.sp
.if n .RS 4
.nf
.fam C
Style * MiniIcon mini\-bx2.xpm
Style xterm MiniIcon mini\-term.xpm
Style Emacs MiniIcon mini\-doc.xpm
ButtonStyle 1 MiniIcon
.fam
.fi
.if n .RE
.RE
.sp
\fBButtonStyle\fP \fIbutton\fP \- [!]\fIflag\fP ...
.RS 4
Sets state\-independent flags for the specified \fIbutton\fP.
State\-independent flags affect button behavior. Each \fIflag\fP is
separated by a space. If a \*(Aq!\*(Aq is prefixed to the flag then the
behavior is negated. The special flag \fIClear\fP clears any existing
flags.
.sp
The following flags are usually used to tell fvwm which buttons should
be affected by mwm function hints (see \fIMwmFunctions\fP option of the
\fBStyle\fP command. This is not done automatically since you might have
buttons bound to complex functions, for instance.
.sp
\fIMwmDecorMenu\fP should be assigned to title\-bar buttons which display a
menu. The default assignment is the leftmost button. When a window
with the \fIMwmFunctions\fP \fBStyle\fP option requests not to show this
button, it is hidden.
.sp
\fIMwmDecorMin\fP should be assigned to title\-bar buttons which minimize
or iconify the window. The default assignment is the second button
over from the rightmost button. When a window with the \fIMwmFunctions\fP
\fBStyle\fP option requests not to show this button, it is hidden.
.sp
\fIMwmDecorMax\fP should be assigned to title\-bar buttons which maximize
the window. The default assignment is the rightmost button. When a
window with the \fIMwmFunctions\fP \fBStyle\fP option requests not to show
this button, it is hidden. When the window is maximized, the vector
pattern on the button looks pressed in.
.sp
\fIMwmDecorShade\fP should be assigned to title\-bar buttons which shade
the window (see \fBWindowShade\fP command). When the window is shaded, the
vector pattern on the button looks pressed in.
.sp
\fIMwmDecorStick\fP should be assigned to title\-bar buttons which make the
window sticky. When the window is sticky, the vector pattern on the
button looks pressed in.
.sp
The flag \fIMwmDecorLayer\fP \fIlayer\fP should be assigned to title\-bar
buttons which place the window in the layer numbered \fIlayer\fP. When the
window is on that specific layer, the vector pattern on the button
looks pressed in.
.RE
.sp
\fBChangeDecor\fP \fIdecor\fP
.RS 4
This command is deprecated and will be removed in the future. There
are plans to replace it with a more flexible solution in fvwm\-3.0.
.sp
Changes the decor of a window to \fIdecor\fP. \fIdecor\fP is "Default" or the
name of a decor defined with \fBAddToDecor\fP. If \fIdecor\fP is invalid,
nothing occurs. If called from somewhere in a window or its border,
then that window is affected. If called from the root window the user
is allowed to select the target window. \fBChangeDecor\fP only affects
attributes which can be set using the \fBAddToDecor\fP command.
.sp
.if n .RS 4
.nf
.fam C
ChangeDecor CustomDecor1
.fam
.fi
.if n .RE
.RE
.sp
\fBDestroyDecor\fP [recreate] \fIdecor\fP
.RS 4
This command is deprecated and will be removed in the future. There
are plans to replace it with a more flexible solution in fvwm\-3.0.
.sp
Deletes the \fIdecor\fP defined with \fBAddToDecor\fP, so that subsequent
references to it are no longer valid. Windows using this \fIdecor\fP
revert to the "Default" decor. The optional parameter \fIrecreate\fP tells
fvwm not to throw away the decor completely but to throw away only its
contents. If the decor is created again later, windows do not use it
before the \fIUseDecor\fP style is applied again unless the decor was
destroyed with the \fIrecreate\fP option. The decor named "Default" cannot
be destroyed.
.sp
.if n .RS 4
.nf
.fam C
DestroyDecor CustomDecor1
.fam
.fi
.if n .RE
.RE
.sp
\fBTitleStyle\fP [\fIjustification\fP] [Height [\fInum\fP]] [MinHeight [\fInum\fP]]
.RS 4
Sets attributes for the title\-bar. Justifications can be \fICentered\fP,
\fIRightJustified\fP or \fILeftJustified\fP. \fIHeight\fP sets the title bar\(cqs
height to an amount in pixels. \fIMinHeight\fP sets the minimal height in
pixels of the title bar. Defaults are \fICentered\fP, the window\(cqs font
height and no minimal height. To reset the font height to the default
value, omit the \fInum\fP argument after the \fIHeight\fP keyword. The
\fIMinHeight\fP height is reset by \fIHeight\fP or if given with no argument.
Example:
.sp
.if n .RS 4
.nf
.fam C
TitleStyle LeftJustified Height 24
.fam
.fi
.if n .RE
.RE
.sp
\fBTitleStyle\fP [\fIstate\fP] [\fIstyle\fP] [\-\- [!]\fIflag\fP ...]
.RS 4
Sets the style for the title\-bar. See also \fBAddTitleStyle\fP and
\fBButtonStyle\fP \fIstate\fP can be one of "\fIActiveUp\fP", "\fIActiveDown\fP",
"\fIInactiveUp\fP", or "\fIInactiveDown\fP". Shortcuts like "\fIActive\fP" and
"\fIInactive\fP" are allowed. The states with the "Toggled" prefix are
allowed too, the title itself does not use "Toggled" states, but these
states are used for the buttons with \fBButtonStyle\fP \fIUseTitleStyle\fP. If
\fIstate\fP is omitted, then the \fIstyle\fP is added to every state. If
parentheses are placed around the \fIstyle\fP and \fIflags\fP, then multiple
state definitions can be given per line. \fIstyle\fP can be omitted so
that flags can be set while not destroying the current style.
.sp
If a \*(Aq!\*(Aq is prefixed to any \fIflag\fP, its behavior is negated. Valid
flags for each state include \fIRaised\fP, \fIFlat\fP and \fISunk\fP (these are
mutually exclusive). The default is \fIRaised\fP. See the note in
\fBButtonStyle\fP regarding the "\fIActiveDown\fP" state. Examples:
.sp
.if n .RS 4
.nf
.fam C
TitleStyle ActiveUp HGradient 16 navy black
TitleStyle \(rs
ActiveDown (Solid red \-\- flat) \(rs
Inactive (TiledPixmap wood.xpm)
TitleStyle \(rs
ActiveUp (\-\- Flat) \(rs
ActiveDown (\-\- Raised) \(rs
InactiveUp (\-\- Flat) \(rs
InactiveDown (\-\- Sunk)
.fam
.fi
.if n .RE
.sp
This sets the "ActiveUp" state to a horizontal gradient, the
"ActiveDown" state to solid red, and the "Inactive" states to a tiled
wood pixmap. Finally, "ActiveUp" and "InactiveUp" are set to look
flat, while "ActiveDown" set to be sunk (the \fIRaised\fP flag for the
"ActiveDown" state causes it to appear sunk due to relief inversion),
and "InactiveDown" is set to look raised. An example which sets flags
for all states:
.sp
.if n .RS 4
.nf
.fam C
TitleStyle \-\- flat
.fam
.fi
.if n .RE
.sp
For a flattened look:
.sp
.if n .RS 4
.nf
.fam C
TitleStyle \-\- flat
ButtonStyle All Active (\-\- flat) Inactive (\-\- flat)
.fam
.fi
.if n .RE
.sp
\fBTitleStyle\fP accepts all the \fBButtonStyle\fP styles and arguments:
.sp
\fISimple\fP, \fIDefault\fP, \fISolid\fP, \fIColorset\fP, \fIVector\fP, \fI?Gradient\fP,
\fIPixmap\fP, \fIAdjustedPixmap\fP, \fIShrunkPixmap\fP, \fIStretchedPixmap\fP,
\fITiledPixmap\fP, \fIMiniIcon\fP.
.sp
See the \fBButtonStyle\fP command for a description of all these styles
and their arguments.
.sp
In addition to these styles \fBTitleStyle\fP accepts a powerful
\fIMultiPixmap\fP option. This allows you to specify different pixmaps,
colorsets or colors for different parts of the titlebar. Some of them
are tiled or stretched to fit a particular space; others are discrete
"transition" images. The definable \fIsections\fP are:
.sp
\fIMain\fP
.RS 4
The full titlebar
.RE
.sp
\fILeftMain\fP
.RS 4
Left of title text
.RE
.sp
\fIRightMain\fP
.RS 4
Right of title text
.RE
.sp
\fIUnderText\fP
.RS 4
Underneath title text
.RE
.sp
\fILeftOfText\fP
.RS 4
just to the left of the title text
.RE
.sp
\fIRightOfText\fP
.RS 4
just to the right of the title text
.RE
.sp
\fILeftEnd\fP
.RS 4
at the far left end of the titlebar (just after left buttons if any)
.RE
.sp
\fIRightEnd\fP
.RS 4
at the far right end of the titlebar (just before right buttons if any)
.RE
.sp
\fIButtons\fP
.RS 4
under buttons in case of \fIUseTitleStyle\fP
.RE
.sp
\fILeftButtons\fP
.RS 4
under left buttons in case of \fIUseTitleStyle\fP
.RE
.sp
\fIRightButtons\fP
.RS 4
under right buttons in case of \fIUseTitleStyle\fP
.RE
.RE
.sp
None of these are mandatory except for \fIMain\fP (or, if you do not
define \fIMain\fP you must define both \fILeftMain\fP and \fIRightMain\fP). If no
\fIButtons\fP pixmaps are defined and \fIUseTitleStyle\fP is specified for one
or more buttons, \fIMain\fP, \fILeftMain\fP or \fIRightMain\fP are used as
appropriate.
.sp
The syntax for this style type is:
.sp
.if n .RS 4
.nf
.fam C
MultiPixmap section style arg, ...
.fam
.fi
.if n .RE
.sp
continuing for whatever you want to define. The \fIstyle\fP can be either
\fITiledPixmap\fP, \fIAdjustedPixmap\fP, \fIColorset\fP or \fISolid\fP. See the
\fBButtonStyle\fP command for the description of these styles. In the case
of a transition section, \fILeftEnd\fP, \fILeftOfText\fP, \fIRightOfText\fP or
\fIRightEnd\fP, \fIAdjustedPixmap\fP only resize the pixmap in the "y"
direction. For the \fIColorset\fP and \fISolid\fP styles a width of the half
of the title bar height is assumed for the transition sections.
.sp
An example:
.sp
.if n .RS 4
.nf
.fam C
MultiPixmap Main AdjustedPixmap foo.xpm, \(rs
UnderText TiledPixmap bar.xpm, \(rs
Buttons Colorset 2
.fam
.fi
.if n .RE
.sp
Note that the old syntax is still supported: if the style is omitted,
\fITiledPixmap\fP is assumed and adding "(stretched)" between the section
and the file name implies \fIAdjustedPixmap\fP.
\fBUpdateDecor\fP [\fIdecor\fP]::
This command is deprecated and will be removed in the future. There
are plans to replace it with a more flexible solution in fvwm\-3.0.
.sp
This command is kept mainly for backward compatibility. Since all
elements of a decor are updated immediately when they are changed,
this command is mostly useless.
.sp
Updates window decorations. \fIdecor\fP is an optional argument which
specifies the \fIdecor\fP to update. If given, only windows which are
assigned to that particular \fIdecor\fP are updated. This command is
useful, for instance, after a \fBButtonStyle\fP, \fBTitleStyle\fP or
\fBBorderStyle\fP (possibly used in conjunction with \fBAddToDecor\fP).
Specifying an invalid decor results in all windows being updated.
.SS "Controlling the Virtual Desktop"
.sp
\fBDesk\fP \fIarg1\fP [\fIarg2\fP] [\fImin\fP \fImax\fP]
.RS 4
This command has been renamed. Please see \fBGotoDesk\fP command.
.RE
.sp
\fBDesktopName\fP \fIdesk\fP \fIname\fP
.RS 4
Defines the name of the desktop number \fIdesk\fP to \fIname\fP. This name is
used in the \fBWindowList\fP command and in the \fBFvwmPager\fP where it
override the \fILabel\fP 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).
.RE
.sp
\fBDesktopConfiguration\fP global | per\-monitor | shared
.RS 4
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 \(em hence, when a change of
desktop/page happens, the same change occurs across all monitors.
.sp
With per\-monitor , each RandR monitor has a separate copy of desktops,
and hence function independently of one another when switching
desks/pages.
.sp
When \fIshared\fP is set, the desktops are shared amongst all monitors. So for
example, with the following number of desktops defined with two monitors
(\fI[]\fP is monitor1, and \fI<>\fP is monitor2):
.sp
.if n .RS 4
.nf
.fam C
[0] 1 2 <3> 4
.fam
.fi
.if n .RE
.sp
Moving between desktops would still honor the monitor the desktop is being
requested on. If \fImonitor1\fP wanted to switch to desktop 3, then that
desktop is exchanged with \fImonitor2\fP such that the following showed the
active desktop on both monitors:
.sp
.if n .RS 4
.nf
.fam C
<0> 1 2 [3] 4
.fam
.fi
.if n .RE
.sp
This concept is similar to how spectrwm or xmonad handles desktops.
.sp
\fBNote:\fP these each \fBDesktopConfiguration\fP mode can be changed on\-the\-fly.
.RE
.sp
\fBDesktopSize\fP \fIHorizontal\fPx_Vertical_
.RS 4
Defines the virtual desktop size in units of the physical screen size.
.RE
.sp
\fBEdgeResistance\fP \fIdelay\fP\fBEdgeResistance\fP \fIscrolling\fP \fImoving\fP [\fIscreen\-scrolling\fP]
.RS 4
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
.sp
.if n .RS 4
.nf
.fam C
EdgeScroll 100 100
.fam
.fi
.if n .RE
.sp
but find themselves accidentally flipping pages when they do not want
to. If \-1 is given as the delay, scrolling is disabled completely.
.sp
The second form of invocation with two or three arguments is obsolete
and should be replaced with the following three commands as needed:
.sp
.if n .RS 4
.nf
.fam C
EdgeResistance scrolling
Style * EdgeMoveDelay scrolling
Style * EdgeMoveResistance moving
or
Style * EdgeMoveResistance moving screen\-scrolling
.fam
.fi
.if n .RE
.sp
Fvwm does this substitution automatically and prints a warning.
.RE
.sp
\fBEdgeScroll\fP \fIhorizontal\fP[p] \fIvertical\fP[p] [wrap | wrapx | wrapy]
.RS 4
Specifies the percentage of a page to scroll when the cursor hits the
edge of a page. A trailing \*(Aq\fIp\fP\*(Aq changes the interpretation to mean
pixels. If you do not want any paging or scrolling when you hit the
edge of a page include
.sp
.if n .RS 4
.nf
.fam C
EdgeScroll 0 0
.fam
.fi
.if n .RE
.sp
in your \fIconfig\fP file, or possibly better, set the \fBEdgeThickness\fP to
zero. See the \fBEdgeThickness\fP command. If you want whole pages, use
.sp
.if n .RS 4
.nf
.fam C
EdgeScroll 100 100
.fam
.fi
.if n .RE
.sp
Both \fIhorizontal\fP and \fIvertical\fP should be positive numbers.
.sp
If the \fIhorizontal\fP and \fIvertical\fP percentages are multiplied by 1000
or one of the keywords \fIwrap\fP, \fIwrapx\fP and \fIwrapy\fP is given then
scrolling wraps around at the edge of the desktop. If
.sp
.if n .RS 4
.nf
.fam C
EdgeScroll 100000 100000
.fam
.fi
.if n .RE
.sp
is used fvwm scrolls by whole pages, wrapping around at the edge of
the desktop.
.RE
.sp
\fBEdgeThickness\fP 0 | 1 | 2
.RS 4
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.
.sp
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\(cqs 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\(cqre
having trouble with the pan frames and (assuming you do not use the
mouse to flip between pages) should set the EdgeThickness to 0.
.sp
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.
.sp
2 is the default.
.sp
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.
.RE
.sp
\fBEwmhBaseStruts\fP \fIscreen RANDRNAME\fP \fIleft\fP \fIright\fP \fItop\fP \fIbottom\fP
.RS 4
Where left, right, top and bottom are positive or null integers which
define bands at the edge of the screen. If \fIscreen\fP is given, followed
by the RANDRNAME of a given display, then the EwmhBaseStruts are
defined for just RANDRNAME. \fIleft\fP defines a band on the left of your
screen of width \fIleft\fP, \fIright\fP defines a band on the right of your
screen of width \fIright\fP, \fItop\fP defines a band on the top of your
screen of height \fItop\fP and \fIbottom\fP defines a band on the bottom of
your screen of height \fIbottom\fP. 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 \fBExtended Window Manager
Hints\fP section for a definition of the Working Area.
.RE
.sp
\fBEwmhNumberOfDesktops\fP \fInum\fP [\fImax\fP]
.RS 4
This command is useful only for an ewmh compliant pager or taskbar (as
kpager or kicker taskbar) and not for fvwm modules ( \fBFvwmPager\fP or
\fBFvwmIconMan\fP). It causes a compliant application to consider at least
\fInum\fP desktops (desktop 0 to desktop \fInum\fP\-1). The optional argument
\fImax\fP causes a compliant application to never consider more than \fImax\fP
desktops. If \fImax\fP is 0 (the default) there is no limitation. The
actual number of desktops is determined dynamically. It is at least
\fInum\fP, 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 \fImax\fP or
\fImax\fP is null. Moreover, a compliant pager can ask to change \fInum\fP
itself. This is accepted by fvwm only if this number is less than or
equal to \fImax\fP or if \fImax\fP is null. Note that negative desktops are
not supported by the ewmh specification. The default is 4 0.
.RE
.sp
\fBGotoDesk\fP [prev | \fIarg1\fP [\fIarg2\fP] [\fImin\fP \fImax\fP]]
.RS 4
Switches the current viewport to another desktop (workspace, room).
.sp
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 \fIprev\fP is given as the
single argument, the last visited desk number is used.
.sp
If \fIarg1\fP is non zero then the next desktop number is the current
desktop number plus \fIarg1\fP.
.sp
If \fIarg1\fP is zero then the new desktop number is \fIarg2\fP. (If \fIarg2\fP is
not present, then the command has no effect.)
.sp
If \fImin\fP and \fImax\fP are given, the new desktop number is no smaller
than \fImin\fP and no bigger than \fImax\fP. Values out of this range are
truncated (if you gave an absolute desk number) or wrapped around (if
you gave a relative desk number).
.sp
The syntax is the same as for \fBMoveToDesk\fP, which moves a window to a
different desktop.
.sp
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?).
.RE
.sp
\fBGotoDeskAndPage\fP screen | prev | \fIdesk\fP \fIxpage\fP \fIypage\fP
.RS 4
Switches the current viewport to another desktop and page, similar to
the \fBGotoDesk\fP and \fBGotoPage\fP commands. The new desk is \fIdesk\fP and the
new page is (\fIxpage\fP,\fIypage\fP).
.RE
.sp
\fBGotoPage\fP screen | prev | [\fIoptions\fP] \fIx\fP[p] \fIy\fP[p]
.RS 4
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 \fBDesktopSize\fP command. The
lower left page is (0,N), and the lower right page is (M,N), where N
is the desktop\(cqs vertical size as specified in the \fBDesktopSize\fP
command. To switch to a page relative to the current one add a
trailing \*(Aq\fIp\fP\*(Aq after any or both numerical arguments.
.sp
Possible \fIoptions\fP are \fIwrapx\fP and \fIwrapy\fP to wrap around the x or y
coordinate when the viewport is moved beyond the border of the
desktop.
.sp
The name of the RandR screen.
.sp
To go to the last visited page use \fIprev\fP as the first argument. The
\fBGotoPage\fP function should not be used in a pop\-up menu.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
# 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
.fam
.fi
.if n .RE
.RE
.sp
\fBScroll\fP [screen RANDRNAME] [\fIhorizonal\fP[p] \fIvertical\fP[p] | reverse]
.RS 4
Scrolls the virtual desktop\(cqs viewport by \fIhorizontal\fP pages in the
x\-direction and \fIvertical\fP pages in the y\-direction or starts
interactive scrolling of the viewport. Either or both entries may be
negative. Both \fIhorizontal\fP and \fIvertical\fP values are expressed in
percent of pages, so
.sp
.if n .RS 4
.nf
.fam C
Scroll 100 100
.fam
.fi
.if n .RE
.sp
means to scroll down and right by one full page.
.sp
.if n .RS 4
.nf
.fam C
Scroll 50 25
.fam
.fi
.if n .RE
.sp
means to scroll right half a page and down a quarter of a page. The
\fBScroll\fP function should not be called from pop\-up menus. Normally,
scrolling stops at the edge of the desktop.
.sp
If the \fIhorizontal\fP and \fIvertical\fP percentages are 100 or more and are
multiplied by 1000 then scrolling wraps around at the edge of the
desktop. If
.sp
.if n .RS 4
.nf
.fam C
Scroll 100000 0
.fam
.fi
.if n .RE
.sp
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.
.sp
If the letter \*(Aq\fIp\fP\*(Aq is appended to each coordinate (\fIhorizontal\fP
and/or \fIvertical\fP), then the scroll amount is measured in pixels.
.sp
Without arguments or if the option \fIreverse\fP is given interactive
scrolling takes place. The viewport scrolls as the mouse is moved.
With the \fIreverse\fP option scrolling is done in opposite direction of
the mouse movement, and without it scrolling in the same direction as
the mouse.
.sp
The binding
.sp
.if n .RS 4
.nf
.fam C
Mouse 1 A CM Scroll reverse
.fam
.fi
.if n .RE
.sp
gives an effect of grabbing and dragging the viewport with button 1 if Control
and Meta is pressed.
.sp
If \fIscreen\fP 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 \fIDesktopConfiguration\fP and wanting to scroll a monitor other than
the current monitor. Interactive scrolling always scrolls the current monitor.
.RE
.SS "User Functions and Shell Commands"
.sp
\fBAddToFunc\fP [\fIname\fP [I | J | M | C | H | D \fIaction\fP]]
.RS 4
Begins or adds to a function definition. Here is an example:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc Move\-or\-Raise I Raise
+ M Move
+ D Lower
.fam
.fi
.if n .RE
.sp
The function name is "Move\-or\-Raise", and it could be invoked from a
menu or a mouse binding or key binding:
.sp
.if n .RS 4
.nf
.fam C
Mouse 1 TS A Move\-or\-Raise
.fam
.fi
.if n .RE
.sp
The \fIname\fP 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 \fIaction\fP tells what kind of action triggers the
command which follows it. \*(Aq\fII\fP\*(Aq stands for "Immediate", and is
executed as soon as the function is invoked. \*(Aq\fIJ\fP\*(Aq 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. \*(Aq\fIM\fP\*(Aq stands for "Motion", i.e. if
the user starts moving the mouse. \*(Aq\fIC\fP\*(Aq stands for "Click", i.e., if
the user presses and releases the mouse button. \*(Aq\fIH\fP\*(Aq stands for
"Hold", i.e. if the user presses a mouse button and holds it down for
more than \fBClickTime\fP milliseconds. \*(Aq\fID\fP\*(Aq stands for "Double\-click".
The action \*(Aq\fII\fP\*(Aq causes an action to be performed on the button\-press,
if the function is invoked with prior knowledge of which window to act
on.
.sp
There is a number of predefined symbols that are replaced by certain
values if they appear on the command line. Please refer to the
\fBCommand Expansion\fP section for details.
.sp
\fBWarning\fP Please read the comments on executing complex functions in
the section \fBScripting and Complex Functions\fP.
.sp
Examples:
.sp
If you call
.sp
.if n .RS 4
.nf
.fam C
Key F10 R A Function MailFunction xmh "\-font fixed"
.fam
.fi
.if n .RE
.sp
and "MailFunction" is
.sp
.if n .RS 4
.nf
.fam C
AddToFunc MailFunction
+ I Next ($0) Iconify off
+ I Next (AcceptsFocus, $0) Focus
+ I None ($0) Exec exec $0 $1
.fam
.fi
.if n .RE
.sp
Then the last line of the function becomes
.sp
.if n .RS 4
.nf
.fam C
+ I None (xmh) Exec exec xmh \-font fixed
.fam
.fi
.if n .RE
.sp
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
.sp
.if n .RS 4
.nf
.fam C
Key F11 R A Function MailFunction zmail "\-bg pink"
.fam
.fi
.if n .RE
.sp
in the same \fIconfig\fP, if you wanted. An example of using "$[w.id]" is:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc PrintFunction
+ I Raise
+ I Exec xdpr \-id $[w.id]
.fam
.fi
.if n .RE
.sp
Note that "$$" is expanded to \*(Aq$\*(Aq.
.sp
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:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc FuncIconifySameResource "I" All ($0) Iconify on
Mouse 3 6 A FuncIconifySameResource $[w.resource]
.fam
.fi
.if n .RE
.RE
.sp
\fBBeep\fP
.RS 4
As might be expected, this makes the terminal beep.
.RE
.sp
\fBDestroyFunc\fP \fIfunction\fP
.RS 4
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 \fBAddToFunc\fP.
.sp
.if n .RS 4
.nf
.fam C
DestroyFunc PrintFunction
.fam
.fi
.if n .RE
.RE
.sp
\fBEcho\fP \fIstring\fP
.RS 4
Prints a message to the debug log file, which requires logging to be
enabled. See the \fB\-v\fP option or \fBPrintInfo\fP for more information on both
enabling debug logging and the log file location. Potentially useful for
debugging things in your \fIconfig\fP or getting the value of variables.
.sp
.if n .RS 4
.nf
.fam C
Echo Beginning style definitions...
Echo Current desk $[desk.n].
.fam
.fi
.if n .RE
.RE
.sp
\fBEchoFuncDefinition\fP \fIfunction\fP
.RS 4
The \fBEchoFuncDefinition\fP is similar to the \fBEcho\fP command but prints
the definition for the given \fIfunction\fP to the debug log file. It is
useful to find out how fvwm handles quoting and for debugging functions.
.RE
.sp
\fBExec\fP \fIcommand\fP
.RS 4
Executes \fIcommand\fP. You should not use an ampersand \*(Aq&\*(Aq at the end of
the command. You probably want to use an additional "exec" at the
beginning of \fIcommand\fP. Without that, the shell that fvwm invokes to
run your command stays until the command exits. In effect, you\(cqll 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.
.sp
The following example binds function key
.sp
in the root window, with no modifiers, to the exec function. The
program rxvt is started with an assortment of options.
.sp
.if n .RS 4
.nf
.fam C
Key F1 R N Exec exec rxvt \-fg yellow \-bg blue \(rs
\-e /bin/tcsh
.fam
.fi
.if n .RE
.sp
Note that this function doesn\(cqt wait for \fIcommand\fP to complete, so
things like:
.sp
.if n .RS 4
.nf
.fam C
Exec "echo AddToMenu ... > /tmp/file"
Read /tmp/file
.fam
.fi
.if n .RE
.sp
do not work reliably (see the \fBPipeRead\fP command).
.RE
.sp
\fBExecUseShell\fP [\fIshell\fP]
.RS 4
Makes the \fBExec\fP command use the specified shell, or the value of the
\fI$SHELL\fP environment variable if no shell is specified, instead of the
default Bourne shell (\fI/bin/sh\fP).
.sp
.if n .RS 4
.nf
.fam C
ExecUseShell
ExecUseShell /usr/local/bin/tcsh
.fam
.fi
.if n .RE
.RE
.sp
\fBFunction\fP \fIFunctionName\fP
.RS 4
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\(cqs
title\-bar.
.sp
.if n .RS 4
.nf
.fam C
Mouse 1 T A Function Move\-or\-Raise
.fam
.fi
.if n .RE
.sp
The keyword \fBFunction\fP may be omitted if \fIFunctionName\fP does not
coincide with an fvwm command.
.sp
Warning: Please read the comments on executing complex functions in
the section \fBScripting and Complex Functions\fP.
.RE
.sp
\fBInfoStoreAdd\fP \fIkey\fP \fIvalue\fP
.RS 4
Stores the \fIvalue\fP at the given \fIkey\fP. 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.
.sp
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
\fBSetEnv\fP 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\(cqs wanted. Hence the point of \fBInfoStoreAdd\fP is to still
allow for such information to be stored, but kept internal to fvwm.
.sp
In this way, one can build up as many key/value pairs as needed.
Recalling the value of a given key happens through fvwm\(cqs usual
expansion mechanism. See the \fBCommand Expansion\fP section for more
details. For example:
.sp
.if n .RS 4
.nf
.fam C
InfoStoreAdd teddybearprog xteddy
# Echo the value of teddybearprog
Echo $[infostore.teddybearprog]
.fam
.fi
.if n .RE
.sp
Removing an entry from the InfoStore is done with the
\fBInfoStoreRemove\fP command.
.RE
.sp
\fBInfoStoreRemove\fP \fIkey\fP
.RS 4
Removes an entry at the given \fIkey\fP from the InfoStore. Example:
.sp
.if n .RS 4
.nf
.fam C
InfoStoreRemove teddybearprog
.fam
.fi
.if n .RE
.RE
.sp
\fBNop\fP
.RS 4
Does nothing. This is used to insert a blank line or separator in a
menu. If the menu item specification is
.sp
.if n .RS 4
.nf
.fam C
AddToMenu MyMenu " " Nop
.fam
.fi
.if n .RE
.sp
then a blank line is inserted. If it looks like
.sp
.if n .RS 4
.nf
.fam C
+ "" Nop
.fam
.fi
.if n .RE
.sp
then a separator line is inserted. Can also be used as the
double\-click action for \fBMenu\fP or \fBPopup\fP.
.RE
.sp
\fBPipeRead\fP \fIcommand\fP [quiet]
.RS 4
Causes fvwm to read commands from the output of the \fIcommand\fP. This
\fIcommand\fP is executed by \fI/bin/sh\fP 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 \fIQuiet\fP follows the command no
message is produced if the \fIcommand\fP is not found.
.sp
Example:
.sp
.if n .RS 4
.nf
.fam C
AddToMenu HomeDirMenu
PipeRead \*(Aqfor i in $HOME/*; \(rs
do echo "+ $i Exec xterm \-e vi $i"; done\*(Aq
.fam
.fi
.if n .RE
.sp
Note: The \fBPipeRead\fP 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 \fBPipeRead\fP
.sp
.if n .RS 4
.nf
.fam C
BusyCursor Read off
.fam
.fi
.if n .RE
.sp
The \fBPipeRead\fP command executes synchronously. If you want to \fBExec\fP
something, but need the command to run synchronously, you might do
something like:
.sp
.if n .RS 4
.nf
.fam C
PipeRead \*(Aqcommand 1>&2\*(Aq
.fam
.fi
.if n .RE
.sp
The redirection causes any output from the program to go to stderr
instead of being read as a sequence of commands by fvwm. \fBPipeRead\fP
returns 1 if the given command could be executed or \-1 if not (see the
section \fBConditional Commands\fP for the meaning of return codes).
.RE
.sp
\fBRead\fP \fIfilename\fP [quiet]
.RS 4
Causes fvwm to read commands from the file named \fIfilename\fP. If the
keyword \fIQuiet\fP follows the command no message is produced if the file
is not found. If the file name does not begin with a slash (\*(Aq/\*(Aq), fvwm
looks in the user\(cqs data directory, then the system data directory.
The user\(cqs data directory is by default \fI$HOME/.fvwm\fP. It can be
overridden by exporting \fIFVWM_USERDIR\fP set to any other directory. The
\fBRead\fP command returns 1 if the given file could be read or \-1 if not
(see the section \fBConditional Commands\fP for the meaning of return
codes).
.RE
.sp
\fBSetEnv\fP \fIvariable\fP \fIvalue\fP
.RS 4
Set an environment variable to a new value, similar to the shell\(cqs
export or setenv command. The \fIvariable\fP and its \fIvalue\fP are inherited
by processes started directly by fvwm. This can be especially useful
in conjunction with the \fBFvwmM4\fP module. For example:
.sp
.if n .RS 4
.nf
.fam C
SetEnv height HEIGHT
.fam
.fi
.if n .RE
.sp
makes the \fBFvwmM4\fP set variable \fIHEIGHT\fP usable by processes started
by fvwm as the environment variable \fI$height\fP. If \fIvalue\fP includes
whitespace, you should enclose it in quotes. If no \fIvalue\fP is given,
the variable is deleted.
.RE
.sp
\fBSilent\fP \fIcommand\fP
.RS 4
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 \fBSilent\fP
in front of the fvwm \fIcommand\fP. If a function that needs a window is
called with \fBSilent\fP without a window selected, it simply returns
without doing anything. If \fBSilent\fP is used on a user defined function
it affects all function and sub function calls until the original
function exits.
.sp
Another usage of \fBSilent\fP is with binding commands \fBKey\fP, \fBPointerKey\fP
and \fBMouse\fP, this disables error messages.
.sp
\fBSilent\fP also disables the error message for non\-existent commands.
Note: This command is treated as a prefix to its \fIcommand\fP. Expansion
of the command line is done as if \fBSilent\fP was not there.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
Silent Move 0 0
Silent User_defined_function
# do not complain on keyboards without "Help" key
Silent Key Help R A Popup HelpMenu
.fam
.fi
.if n .RE
.RE
.sp
\fBUnsetEnv\fP [\fIvariable\fP]
.RS 4
Unset an environment variable, similar to shell\(cqs export or unsetenv
command. The \fIvariable\fP then is removed from the environment array
inherited by processes started directly by fvwm.
.RE
.sp
\fBWait\fP \fIwindow\fP
.RS 4
This command is intended to be used in fvwm functions only. It causes
execution of a function to pause until a new window matching \fIwindow\fP
appears. This can be a window\(cqs name, class, or resource string. It
may contain the wildcards \*(Aq*\*(Aq and \*(Aq?\*(Aq, 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:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc InitFunction
+ I Exec exec xterm \-geometry 80x64+0+0
+ I Wait xterm
+ I GotoDesk 0 2
+ I Exec exec xmh \-font fixed \-geometry \(rs
507x750+0+0
+ I Wait xmh
+ I GotoDesk 0 0
.fam
.fi
.if n .RE
.sp
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.
.sp
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 \fBFvwmIconMan\fP or \fBFvwmPager\fP during a wait.
.sp
You can escape from a \fBWait\fP pause by pressing Ctrl\-Alt\-Escape (where Alt is
the first modifier). To redefine this key sequence see the \fBEscapeFunc\fP command.
.RE
.sp
\fBStatus\fP \fIOn | Off\fP
.RS 4
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\(cqs
happening in Fvwm. For example, the JSON could be manipulated and sent
to tools such as \fIlemonbar\fP, \fIpolybar\fP, etc.
.sp
The format of the JSON blob looks like this:
.sp
.if n .RS 4
.nf
.fam C
{
"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
},
},
},
},
}
.fam
.fi
.if n .RE
.sp
These sections repeat for all screens/groups/etc, depending on how
many there are of each.
.RE
.SS "Conditional Commands"
.sp
Conditional commands are commands that are only executed if certain
conditions are met. Most conditional commands work on windows, like
\fBNext\fP, \fBThisWindow\fP or \fBAll\fP. There is one conditional command, \fBTest\fP,
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.
.sp
\fBReturn Codes\fP
.RS 4
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
\fBBreak\fP 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 \fBTestRc\fP command. Please
refer to the commands\*(Aq description for examples. The return code can
also be accessed through the variable \fI$[cond.rc]\fP. 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 \fBAddToFunc\fP command and are not inherited
by sub functions. To run a command without altering the return code,
the \fBKeepRc\fP command can be used.
.RE
.sp
\fBThe Ring of Windows\fP
.RS 4
Fvwm stores windows in a ring internally. Think of the focused window
as a cursor on the current position in the ring. The \fBNext\fP command
and many other commands search forwards through the ring for a
matching window, and \fBPrev\fP searches backwards. The windows in the
ring are either ordered by creation time (if the
\fI!FPSortWindowlistByFocus\fP, \fINeverFocus\fP or \fIMouseFocus\fP styles are
used) or by the last time they had the focus.
.RE
.sp
\fBList of Conditional Commands\fP
.RS 4
.sp
\fBAll\fP [\fIoptions\fP] [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Execute \fIcommand\fP 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 \fIoptions\fP can be any combination of \fIReverse\fP and \fIUseStack\fP. If
the option \fIReverse\fP is given the execution order is reversed. The
option \fIUseStack\fP makes All use the stacking order instead of the
window ring when walking through windows. See the \fBConditions\fP section
for a list of conditions.
.sp
This command implies the conditions \fICirculateHit\fP, \fICirculateHitIcon\fP
and \fICirculateHitShaded\fP. They can be turned off by specifying
\fI!CirculateHit\fP etc. explicitly.
.RE
.sp
\fBAny\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP if any window which satisfies all \fIconditions\fP
exists. The command is run in the context of the root window. See
the \fBConditions\fP section for a list of conditions.
.RE
.sp
\fBBreak\fP [\fIlevels\fP]
.RS 4
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 \fIlevels\fP may be given to break out
of the given number of nested functions and continue execution of a
higher level function. The \fBBreak\fP command always has the return
code \-2. Example:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc PickWindowRaiseAndDeiconify
+ I Pick
+ I TestRc (Error) Break
+ I Raise
+ I Iconify off
.fam
.fi
.if n .RE
.RE
.sp
\fBCurrent\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP on the currently focused window if it satisfies
all \fIconditions\fP. See the \fBConditions\fP section for a list of
conditions.
.sp
This command implies the conditions \fICirculateHit\fP,
\fICirculateHitIcon\fP and \fICirculateHitShaded\fP. They can be turned off
by specifying \fI!CirculateHit\fP etc. explicitly.
.RE
.sp
\fBDirection\fP [FromPointer] \fIdirection\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP (typically \fBFocus\fP) on a window in the given
direction which satisfies all \fIconditions\fP. 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 \fIFromPointer\fP option is given, the current
position of the pointer is taken as the starting point. The
\fIdirection\fP may be one of "North", "Northeast", "East", "Southeast",
"South", "Southwest", "West", "Northwest" and "Center". Which window
\fBDirection\fP 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 \fICenter\fP direction simply selects the
window closest to the starting point. Returns \-1 if an invalid
direction was given. See the \fBConditions\fP section for a list of
conditions.
.RE
.sp
\fBKeepRc\fP \fIcommand\fP
.RS 4
Runs the \fIcommand\fP but does not alter the return code of the
previous command. Note: \fBKeepRc\fP is treated as a prefix to its
\fIcommand\fP. Expansion of the command line is done as if \fBKeepRc\fP was
not there.
.RE
.sp
\fBNext\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP (typically \fBFocus\fP) on the next window which
satisfies all \fIconditions\fP. 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 \fBConditions\fP section
for a list of conditions.
.RE
.sp
\fBNone\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP if no window which satisfies all \fIconditions\fP
exists. The command is run in the context of the root window.
Returns 1 if no window matches the conditions and 0 otherwise. See
\fBConditions\fP section for a list of conditions.
.sp
This command implies the conditions \fICirculateHit\fP,
\fICirculateHitIcon\fP and \fICirculateHitShaded\fP. They can be turned off
by specifying \fI!CirculateHit\fP etc. explicitly.
.RE
.sp
\fBNoWindow\fP \fIcommand\fP
.RS 4
Performs \fIcommand\fP, 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.
.RE
.sp
\fBPick\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
\fBPick\fP works like \fBFunction\fP 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 \fIcommand\fP in the context of that
window. This avoids annoying multiple selections with complex
functions. The command is executed only if the given \fIconditions\fP
are met. Returns \-1 if no window was selected. See \fBConditions\fP
section for a list of conditions.
.sp
This command implies the conditions \fICirculateHit\fP,
\fICirculateHitIcon\fP and \fICirculateHitShaded\fP. They can be turned off
by specifying \fI!CirculateHit\fP etc. explicitly.
.RE
.sp
\fBPointerWindow\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP if the window under the pointer satisfies all
\fIconditions\fP. Returns \-1 if there is no window under the pointer.
See \fBConditions\fP section for a list of conditions.
.sp
This command implies the conditions \fICirculateHit\fP,
\fICirculateHitIcon\fP and \fICirculateHitShaded\fP. They can be turned off
by specifying \fI!CirculateHit\fP etc. explicitly.
.RE
.sp
\fBPrev\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP (typically \fBFocus\fP) on the previous window which
satisfies all \fIconditions\fP. 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 \fBConditions\fP section
for a list of conditions.
.RE
.sp
\fBScanForWindow\fP [FromPointer] \fIdir1\fP \fIdir2\fP [(\fIconditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP (typically \fBFocus\fP) on a window in the given
direction which satisfies all \fIconditions\fP. 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 \fIFromPointer\fP option is given, the current
position of the pointer is taken as the starting point. The
direction \fIdir1\fP may be one of "North", "NorthEast", "East",
"SouthEast", "South", "SouthWest", "West", and "NorthWest". Which
window \fBScanForWindow\fP selects depends first on the position along
the primary axis given by \fIdir1\fP. If any windows have the exact same
coordinate along the primary axis, the secondary direction is used
to order the windows. The direction \fIdir2\fP may be one of the same
set of values as \fIdir1\fP. If \fIdir2\fP is not perfectly perpendicular to
\fIdir1\fP, 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
\fBConditions\fP section for a list of conditions.
.RE
.sp
\fBTest\fP [(\fItest\-conditions\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP if all \fItest\-conditions\fP are satisfied. The
\fItest\-conditions\fP are keywords with possible arguments from the list
below and are separated by commas or whitespace. They include:
\fIVersion operator x.y.z\fP, \fIEnvIsSet varname\fP, \fIEnvMatch varname
pattern\fP, \fIEdgeHasPointer direction\fP, \fIEdgeIsActive direction\fP,
\fIStart\fP, \fIInit\fP, \fIRestart\fP, \fIExit\fP, \fIQuit\fP, \fIToRestart\fP, \fITrue\fP,
\fIFalse\fP, \fIF\fP, \fIR\fP, \fIW\fP, \fIX\fP and \fII\fP. A test\-condition prefixed with
"!" is negated.
.sp
The \fIVersion\fP \fIoperator x.y.z\fP test\-condition is fulfilled if the
logical condition of the expression is true. Valid \fIoperator\fP values
are: \fI>=\fP, \fI>\fP, \fI\(lA\fP, \fI<\fP, \fI==\fP and \fI!=\fP.
.sp
Example:
.sp
.if n .RS 4
.nf
.fam C
Test (Version >= 2.5.11) Echo 2.5.11 or later.
.fam
.fi
.if n .RE
.sp
The \fIEnvIsSet\fP \fIvarname\fP test\-condition is true if the given
environment variable is set. The \fIEnvMatch\fP \fIvarname pattern\fP
test\-condition is true if \fIpattern\fP matches the given environment or
infostore variable value. (See \fBInfoStoreAdd\fP). The pattern may
contain special "*" and "?" chars. The "varname" is coded without
the leading dollar sign ($).
.sp
The \fIEdgeHasPointer\fP [\fIdirection\fP] test\-condition is true if the
edge in the given direction currently contains the pointer. The
\fIEdgeIsActive\fP [\fIdirection\fP] 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\fI,\fP North\fI,\fP Top\fI,\fP Up\fI,\fP West\fI,\fP Left\fI,\fP South\fI,\fP
Bottom\fI, \fP Down\fI,\fP Right* and * East\fI. If no direction is
specified \fPAny* is assumed.
.sp
The \fIStart\fP test\-condition is the same as either \fIInit\fP or
\fIRestart\fP. It is only true on startup or restart prior and during
\fBStartFunction\fP execution. The \fIExit\fP test\-condition is the same as
either \fIQuit\fP or \fIToRestart\fP. It is only valid on shutdown during
\fBExitFunction\fP function execution.
.sp
The \fITrue\fP and \fIFalse\fP test\-conditions are unconditionally true and
false.
.sp
Additionally, if a test\-condition name is not recognized, the Error
return code is set and the command is not executed.
.sp
The \fIF\fP \fIfile\fP, \fIR\fP \fIfile\fP, \fIW\fP \fIfile\fP, \fIX\fP \fIfile\fP and \fII\fP \fIfile\fP
test\-conditions test for existence of the given [F]ile (possibly
with [R]ead/[W]rite permissions), e[X]ecutable (in \fI$PATH\fP), or the
[I]mage (in ImagePath).
.sp
Example:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc StartFunction I Test (Init) Exec exec xterm
AddToFunc VerifyVersion
+ I Test (Version 2.5.*) Echo 2.5.x detected
+ I TestRc (NoMatch) \(rs
Test (!Version 2.6.*) Echo Future version
+ I TestRc (NoMatch) \(rs
Echo 2.6.x is detected
Test (F $[FVWM_USERDIR]/local\-config) Read local\-config
Test (X xterm\-utf16) Exec exec xterm\-utf16
.fam
.fi
.if n .RE
.RE
.sp
\fBTestRc\fP [([!]\fIreturncode\fP)] \fIcommand\fP
.RS 4
Performs \fIcommand\fP if the last conditional command returned the
value \fIreturncode\fP. Instead of the numeric values 0 (no match), 1
(match), \-1 (error), and \-2 (break) the symbolic names "\fINoMatch\fP",
"\fIMatch\fP", "\fIError\fP" and "\fIBreak\fP" can be used. If no \fIreturncode\fP
is given, the default 0 is assumed. If the return code is prefixed
with \*(Aq!\*(Aq, the command is executed if \fIreturncode\fP does not match the
value returned by the conditional command. The \fBTestRc\fP command can
only be used inside functions. If the \fIcommand\fP is another
conditional command, the previous return code is replaced by the new
one. Example:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc ToggleXterm
+ I All (my_xtermwindow) Close
+ I TestRc (NoMatch) Exec xterm \-T my_xtermwindow
.fam
.fi
.if n .RE
.RE
.sp
\fBThisWindow\fP [(\fIconditions\fP)] command
.RS 4
\fBThisWindow\fP executes the specified \fIcommand\fP 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. \fBThisWindow\fP is never
interactive. The command is executed only if the given \fIconditions\fP
are met. It returns \-1 if used outside a window context. See
\fBConditions\fP section for a list of conditions.
.sp
This command implies the conditions \fICirculateHit\fP,
\fICirculateHitIcon\fP and \fICirculateHitShaded\fP. They can be turned off
by specifying "!CirculateHit" etc. explicitly.
.RE
.sp
\fBWindowId\fP [\fIid\fP] [(\fIconditions\fP)] | [root [\fIscreen\fP]] \fIcommand\fP
.RS 4
The \fBWindowId\fP command looks for a specific window \fIid\fP and runs the
specified \fIcommand\fP on it. The second form of syntax retrieves the
window id of the root window of the given \fIscreen\fP. If no \fIscreen\fP
is given, the current screen is assumed. The window indicated by
\fIid\fP 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 \fBWarpToWindow\fP
command. Returns \-1 if no window with the given id exists. See
\fBConditions\fP section for a list of conditions.
.sp
This command implies the conditions \fICirculateHit\fP,
\fICirculateHitIcon\fP and \fICirculateHitShaded\fP. They can be turned off
by specifying \fI!CirculateHit\fP etc. explicitly.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
WindowId 0x34567890 Raise
WindowId root 1 WarpToWindow 50 50
WindowId $0 (Silly_Popup) Delete
.fam
.fi
.if n .RE
.sp
In the past this command was mostly useful for functions used with
the \fBWindowList\fP command, or for selective processing of \fBFvwmEvent\fP
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.
.RE
.sp
.if n .RS 4
.nf
.fam C
Pick SetEnv BOOKMARKED_WINDOW $[w.id]
WindowId $[BOOKMARKED_WINDOW] WarpToWindow
.fam
.fi
.if n .RE
.RE
.sp
\fBConditions\fP
.RS 4
The \fIconditions\fP 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).
.sp
In addition, the \fIconditions\fP 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
\*(Aq*\*(Aq and \*(Aq?\*(Aq, and may consist of two or more alternatives, separated by
the character \*(Aq|\*(Aq, 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 \*(Aq!\*(Aq, which prevents \fIcommand\fP if any of the
window name, icon name, class or resource match. However, \*(Aq!\*(Aq 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.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
Next ("Netscape|konqueror|Mozilla*") WarpToWindow 99 90
.fam
.fi
.if n .RE
.sp
This goes to the next web browser window, no matter which of the three
named web browsers is being used.
.sp
.if n .RS 4
.nf
.fam C
Next ("Mozilla*", "Bookmark*") WarpToWindow 99 90
.fam
.fi
.if n .RE
.sp
This goes to Mozilla\(cqs bookmark manager window, ignoring other Mozilla
windows and other browsers\*(Aq bookmark windows.
.sp
.if n .RS 4
.nf
.fam C
All ("XTerm|rxvt", !console) Iconify
.fam
.fi
.if n .RE
.sp
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.
.sp
.if n .RS 4
.nf
.fam C
Next (!"FvwmPager|FvwmForm*|FvwmButtons") Raise
Next (!FvwmPager, !FvwmForm*, !FvwmButtons) Raise
.fam
.fi
.if n .RE
.sp
These two commands are equivalent; either one raises the next window
which is not one of the named fvwm modules.
.sp
Any condition can be negated by using a an exclamation mark (\*(Aq!\*(Aq)
directly in front of its name.
.sp
\fIAcceptsFocus\fP, \fIAnyScreen\fP, \fICirculateHit\fP, \fICirculateHitIcon\fP,
\fICirculateHitShaded\fP, \fIClosable\fP, \fICurrentDesk\fP, \fICurrentGlobalPage\fP,
\fICurrentGlobalPageAnyDesk\fP, \fICurrentPage\fP, \fICurrentPageAnyDesk\fP,
\fICurrentScreen\fP, \fIDesk\fP, \fIFixedPosition\fP, \fIFixedSize\fP, \fIFocused\fP,
\fIHasBorders\fP, \fIHasHandles\fP, \fIHasPointer\fP, \fIHasTitle\fP, \fITitleAtTop\fP,
\fITitleAtBottom\fP, \fITitleAtLeft\fP, \fITitleAtRight\fP, \fIIconic\fP,
\fIIconifiable\fP, \fILayer [n]\fP, \fIMaximizable\fP, \fIMaximized\fP, \fIOverlapped\fP,
\fIPlacedByButton n\fP, \fIPlacedByButton3\fP, \fIPlacedByFvwm\fP, \fIRaised\fP, \fIShaded\fP,
\fIState n\fP, \fISticky\fP, \fIStickyAcrossDesks\fP, \fIStickyAcrossPages\fP, \fIStickyIcon\fP,
\fIStickyAcrossDesksIcon\fP, \fIStickyAcrossPagesIcon\fP, \fITransient\fP,
\fIVisible\fP.
.sp
The \fIAcceptsFocus\fP 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 \fILenience\fP option of the \fBStyle\fP command.
Also, all windows using the \fINeverFocus\fP style are ignored. Note:
\fI!Lenience\fP is equivalent to the deprecated option \fINoLenience\fP.
.sp
With the \fIAnyScreen\fP condition used together with any of the
\fICurrent...\fP conditions, windows that do not intersect the screen
containing the mouse pointer are considered for a match too. For
example:
.sp
.if n .RS 4
.nf
.fam C
# Focus next window on current page,
# regardless of screen
Next (CurrentPage, AnyScreen) Focus
.fam
.fi
.if n .RE
.sp
The \fICirculateHit\fP and \fICirculateHitIcon\fP options override the
\fICirculateSkip\fP and \fICirculateSkipIcon\fP \fBStyle\fP attributes for normal
or iconic windows. The \fICirculateHitShaded\fP option overrides the
\fICirculateSkipShaded\fP \fBStyle.\fP All three options are turned on by
default for the \fBCurrent\fP command. They can be turned off by
specifying \fI!CirculateHit\fP etc. explicitly. Note: Do not confuse these
conditions with the style options of the same name. Specifically,
.sp
.if n .RS 4
.nf
.fam C
Style foo CirculateSkip
Next (foo, CirculateHit) ...
.fam
.fi
.if n .RE
.sp
is not the same as
.sp
.if n .RS 4
.nf
.fam C
Style foo CirculateHit ...
Next (foo)
.fam
.fi
.if n .RE
.sp
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.
.sp
The \fIClosable\fP condition matches only windows that are allowed to be
closed.
.sp
The \fICurrentDesk\fP condition matches only windows that are on the
current desk.
.sp
The \fICurrentGlobalPage\fP 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 \fICurrentDesk\fP
condition.
.sp
The \fICurrentGlobalPageAnyDesk\fP condition matches only windows that are
on the current page of any desk, regardless of RandR screen .
.sp
The \fICurrentPage\fP condition matches only windows that are on the
current page of the current desk. This condition implicitly activates
the \fICurrentDesk\fP condition.
.sp
The \fICurrentPageAnyDesk\fP and \fICurrentScreen\fP conditions matches only
windows that are on the current page of any desk.
.sp
The \fIScreen [name]\fP condition matches only windows which are on the
specified screen.
.sp
The \fIDesk [n]\fP condition matches only windows which are on the
specified desk.
.sp
The \fIFixedPosition\fP condition excludes all windows that do not have a
fixed position, either set through WM hints or the \fBStyle\fP option
\fIFixedPosition\fP. Example:
.sp
.if n .RS 4
.nf
.fam C
DestroyFunc ToggleFixedGeometry
AddToFunc ToggleFixedGeometry
+ I Pick (FixedPosition) \(rs
WindowStyle VariablePosition, VariableSize
+ I TestRc (NoMatch) WindowStyle FixedPosition, FixedSize
.fam
.fi
.if n .RE
.sp
The \fIFixedSize\fP condition excludes all windows that do not have a
fixed size, either set through WM hints or the \fBStyle\fP option
\fIFixedSize\fP.
.sp
The \fIFocused\fP matches on the window that currently has the keyboard
focus. This is not useful for the \fBCurrent\fP command but can be used
with the other conditional commands.
.sp
The \fIHasBorders\fP condition excludes all windows that do not have borders.
.sp
The \fIHasHandles\fP condition excludes all windows that do not have
resize handles.
.sp
The \fIHasPointer\fP condition excludes all windows that do not contain
the pointer.
.sp
The \fIHasTitle\fP condition excludes all windows that do not have a titlebar.
.sp
The \fITitleAtTop\fP, \fITitleAtBottom\fP, \fITitleAtLeft\fP, \fITitleAtRight\fP conditions
test for the titlebar at that window location.
.sp
The \fIIconic\fP condition matches only iconic windows.
.sp
The \fIIconifiable\fP condition matches only windows that are allowed to
be iconified.
.sp
The \fILayer [n]\fP condition matches only windows on the specified layer.
The optional argument of the \fILayer\fP condition defaults to the layer
of the focused window. The negation \fI!Layer\fP switches off the \fILayer\fP
condition.
.sp
The \fIMaximizable\fP condition matches only windows that are allowed to
be maximized.
.sp
The \fIMaximized\fP condition matches only maximized windows.
.sp
The \fIOverlapped\fP condition matches only windows that are overlapped by
other windows on the same layer (or unmanaged windows if the option
\fIRaiseOverUnmanaged\fP of the \fBBugOpts\fP 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.
.sp
The \fIPlacedByButton n\fP condition is fulfilled if the last interactive
motion of the window (with the \fBMove\fP command or as \fIManualPlacement\fP)
was ended by pressing mouse button \fIn\fP. Example:
.sp
.if n .RS 4
.nf
.fam C
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
.fam
.fi
.if n .RE
.sp
The \fIPlacedByButton3\fP condition has the same meaning as
\fIPlacedByButton\fP 3. It remains only for backward compatibility.
.sp
The \fIPlacedByFvwm\fP condition excludes all windows that have been
placed manually or by using the user or program position hint.
.sp
The \fIRaised\fP conditions matches only windows that are fully visible on
the current viewport and not overlapped by any other window.
.sp
The \fIShaded\fP conditions matches only shaded windows (see \fBWindowShade\fP
command).
.sp
The \fIState n\fP or \fI!State n\fP conditions match only windows with the
specified integer state set (or unset). See the \fBState\fP command for
details. The argument may range from 0 to 31.
.sp
The \fISticky\fP, \fIStickyAcrossDesks\fP and \fIStickyAcrossPages\fP match only
windows that are currently sticky, sticky across all desks or sticky
across all pages. Please refer to the \fBStyle\fP options with the same
name and the commands \fBStick\fP, \fBStickAcrossDesks\fP and
\fBStickAcrossPages\fP for details.
.sp
The \fIStickyIcon\fP, \fIStickyAcrossDesksIcon\fP and \fIStickyAcrossPagesIcon\fP
match only windows that become sticky, sticky across all desks or
sticky across all pages when they are in iconified state.
.sp
The \fITransient\fP 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 \fBFvwmIdent\fP module can be
used to find out whether a specific window is transient.
.sp
The \fIVisible\fP condition matches only windows that are at least
partially visible on the current viewport and not completely
overlapped by other windows.
.RE
.SS "Module Commands"
.sp
Fvwm maintains a database of module configuration lines in a form
.sp
.if n .RS 4
.nf
.fam C
*:
.fam
.fi
.if n .RE
.sp
where \fI\fP is either a real module name or an alias.
.sp
This database is initially filled from config file (or from output of
\fB\-cmd\fP config command), and can be later modified either by user (via
\fBFvwmCommand\fP) or by modules.
.sp
When modules are run, they read appropriate portion of database. (The
concept of this database is similar to one used in X resource database).
.sp
Commands for manipulating module configuration database are described
below.
.sp
\fB*\fP \fImodule_config_line\fP
.RS 4
Defines a module configuration. \fImodule_config_line\fP 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.
.sp
.if n .RS 4
.nf
.fam C
*FvwmPager: WindowBorderWidth 1
*FvwmButtons\-TopRight: Geometry 100x100\-0+0
*FvwmButtons\-Bottom: Geometry +0\-0
.fam
.fi
.if n .RE
.RE
.sp
\fBDestroyModuleConfig\fP \fImodule_config\fP
.RS 4
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.
.sp
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\(cqt have wildcards.
.sp
.if n .RS 4
.nf
.fam C
DestroyModuleConfig FvwmButtons*
DestroyModuleConfig FvwmForm: Fore
DestroyModuleConfig FvwmIconMan: Tips*
.fam
.fi
.if n .RE
.RE
.sp
\fBKillModule\fP \fImodulename\fP [\fImodulealias\fP]
.RS 4
Causes the module which was invoked with name \fImodulename\fP to be
killed. The name may include wildcards. If \fImodulealias\fP is given,
only modules started with the given alias are killed.
.sp
.if n .RS 4
.nf
.fam C
# kill all pagers
KillModule FvwmPager
Module FvwmEvent SoundEvent
KillModule FvwmEvent SoundEvent
.fam
.fi
.if n .RE
.RE
.sp
\fBModule\fP \fImodulename\fP [\fImoduleparams\fP]
.RS 4
Specifies a module with its optional parameters which should be
spawned. Currently several modules, including \fBFvwmButtons\fP,
\fBFvwmEvent\fP, \fBFvwmForm\fP, \fBFvwmPager\fP, \fBFvwmScript\fP support aliases.
Aliases are useful if more than one instance of the module should be
spawned. Aliases may be configured separately using \fB*\fP syntax. To
start a module \fBFvwmForm\fP using an alias \fIMyForm\fP, the following
syntax may be used:
.sp
.if n .RS 4
.nf
.fam C
Module FvwmForm MyForm
.fam
.fi
.if n .RE
.sp
At the current time the available modules (included with fvwm) are
\fBFvwmAnimate\fP (produces animation effects when a window is iconified
or de\-iconified), \fBFvwmAuto\fP (an auto raise module), \fBFvwmBacker\fP (to
change the background when you change desktops), \fBFvwmBanner\fP (to
display a spiffy XBM, XPM, PNG or SVG), \fBFvwmButtons\fP (brings up a
customizable tool bar), \fBFvwmCommandS\fP (a command server to use with
shell\(cqs FvwmCommand client), \fBFvwmConsole\fP (to execute fvwm commands
directly), \fBFvwmCpp\fP (to preprocess your \fIconfig\fP with cpp),
\fBFvwmEvent\fP (trigger various actions by events), \fBFvwmForm\fP (to bring
up dialogs), \fBFvwmIconMan\fP (a flexible icon manager), \fBFvwmIdent\fP (to
get window info), \fBFvwmM4\fP (to preprocess your \fIconfig\fP with m4),
\fBFvwmPager\fP (a mini version of the desktop), \fBFvwmPerl\fP (a Perl
manipulator and preprocessor), \fBFvwmProxy\fP (to locate and control
obscured windows by using small proxy windows), \fBFvwmRearrange\fP (to
rearrange windows), \fBFvwmScript\fP (another powerful dialog toolkit),
These modules have their own man pages. There may be other modules out
on there as well.
.sp
Modules can be short lived transient programs or, like \fBFvwmButtons\fP ,
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 \fBModule\fP may be
omitted if \fImodulename\fP is distinct from all fvwm commands.
.RE
.sp
\fBModuleListenOnly\fP \fImodulename\fP [\fImoduleparams\fP]
.RS 4
This command works like the \fBModule\fP 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 \fBFvwmButtons\fP module to implement a
simple clock.
.RE
.sp
\fBModulePath\fP \fIpath\fP
.RS 4
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.
.sp
The \fBModulePath\fP may contain environment variables such as \fI$HOME\fP (or
\fI${HOME}\fP). Further, a \*(Aq+\*(Aq in the \fIpath\fP is expanded to the previous
value of the \fIpath\fP, allowing easy appending or prepending to the
\fIpath\fP.
.sp
For example:
.sp
.if n .RS 4
.nf
.fam C
ModulePath ${HOME}/lib/fvwm/modules:+
.fam
.fi
.if n .RE
.sp
The directory containing the standard modules is available via the
environment variable \fI$FVWM_MODULEDIR\fP.
.RE
.sp
\fBModuleSynchronous\fP [Expect \fIstring\fP] [Timeout \fIsecs\fP] \fImodulename\fP
.RS 4
The \fBModuleSynchronous\fP command is very similar to \fBModule\fP. 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 \fITimeout\fP is given fvwm gives up if the module sent no input
back to fvwm for \fIsecs\fP seconds. If the \fIExpect\fP option is given, fvwm
waits for the given \fIstring\fP instead. \fBModuleSynchronous\fP 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.
.sp
\fBWarning\fP: 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 \fBModuleSynchronous\fP command by using the key
sequence
.sp
(see the \fBEscapeFunc\fP).
.RE
.sp
\fBModuleTimeout\fP \fItimeout\fP
.RS 4
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.
\fItimeout\fP must be greater than zero, or it is reset to the default
value of 30 seconds.
.RE
.sp
\fBSendToModule\fP \fImodulename\fP \fIstring\fP
.RS 4
Sends an arbitrary string (no quotes required) to all modules, whose
alias or name matching \fImodulename\fP, 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.
.RE
.SS "Session Management Commands"
.sp
\fBQuit\fP
.RS 4
Exits fvwm, generally causing X to exit too.
.RE
.sp
\fBQuitScreen\fP
.RS 4
Causes fvwm to stop managing the screen on which the command was
issued.
.RE
.sp
\fBRestart\fP [\fIwindow_manager\fP [\fIparams\fP]]
.RS 4
Causes fvwm to restart itself if \fIwindow_manager\fP is left blank, or to
switch to an alternate window manager (or other fvwm version) if
\fIwindow_manager\fP is specified. If the window manager is not in your
default search path, then you should use the full path name for
\fIwindow_manager\fP.
.sp
This command should not have a trailing ampersand. The command can
have optional parameters with simple shell\-like syntax. You can use
\fI~\fP (is expanded to the user\(cqs home directory) and environmental
variables \fI$VAR\fP or \fI${VAR}\fP. Here are several examples:
.sp
.if n .RS 4
.nf
.fam C
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 \*(Aq"X console"\*(Aq \-T \(rs"X\(rs console\(rs" \-e fvwm \-s
.fam
.fi
.if n .RE
.sp
Note, currently with multi headed displays, restart of fvwms on
different screens works independently.
.RE
.sp
\fBRestart\fP \fB\-\-pass\-args\fP \fIwindow_manager\fP
.RS 4
The same as \fBRestart\fP without parameters but the name for the current
window manager is replaced with the specified \fIwindow_manager\fP and
original arguments are preserved.
.RE
.sp
\fBRestart\fP \fB\-\-dont\-preserve\-state\fP [\fIother\-params\fP]
.RS 4
The same as
.sp
.if n .RS 4
.nf
.fam C
Restart [other\-params]
.fam
.fi
.if n .RE
.sp
but it does not save any window states over the restart.
.sp
Without this option, \fBRestart\fP preserves most per\-window state by
writing it to a file named \fI.fs\-restart\-$HOSTDISPLAY\fP in the user\(cqs
home directory.
.RE
.sp
\fBSaveSession\fP
.RS 4
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.
.RE
.sp
\fBSaveQuitSession\fP
.RS 4
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.
.RE
.SS "Colorsets"
.sp
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.
.sp
\fBColorset\fP \fInum\fP [\fIoptions\fP]
.RS 4
Creates or modifies colorset \fInum\fP. Colorsets are identified by this
number. The number can start at zero and can be a very large number.
.sp
Warning: The highest colorset number used determines memory
consumption. Thus, if you define \*(AqColorset 100000\*(Aq, the memory for
100001 colorsets is used. Keep your colorset numbers as small as
possible.
.sp
By convention, colorsets are numbered like this:
.sp
.if n .RS 4
.nf
.fam C
# 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
.fam
.fi
.if n .RE
.sp
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:
.sp
\fI\c
.URL "http://fvwm\-themes.sourceforge.net/doc/colorsets" "" "\fP"
.sp
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.
.sp
\fIoptions\fP 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.
.sp
\fIfg\fP, \fIFore\fP and \fIForeground\fP take a color name as an argument and set
the foreground color. The special name \fIContrast\fP 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.
.sp
\fIbg\fP, \fIBack\fP and \fIBackground\fP 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 \fIAverage\fP may be used to
select a color that is the average color of the pixmap. If the pixmap
is tinted with the \fITint\fP option, the tint is not taken in account in
the computation of the average color. You should use the \fIbgTint\fP
option to get the "real" average color. The background color is reset
to the default value if the color name is omitted.
.sp
\fIhi\fP, \fIHilite\fP and \fIHilight\fP 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.
.sp
\fIsh\fP, \fIShade\fP and \fIShadow\fP 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.
.sp
\fIfgsh\fP takes a color name as an argument and sets the color used by
the shadowing font effect. See the \fBFont Shadow Effects\fP 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.
.sp
\fIPixmap\fP, \fITiledPixmap\fP and \fIAspectPixmap\fP take a file name as an
argument, search the \fBImagePath\fP 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.
\fITiledPixmap\fP produces repeated copies of the image with no scaling,
\fIPixmap\fP causes the image to be stretched to fit whatever object the
colorset is applied to and \fIAspectPixmap\fP stretches to fit but retains
the image aspect ratio.
.sp
\fITransparent\fP creates a transparent background pixmap. The pixmap is
used as a window background to achieve root transparency. For this you
should use the \fIParentalRelativity\fP option to the \fBStyle\fP command. A
subsequent root background change may be detected or not, this depends
on the program used to set the background. If you use \fBfvwm\-root\fP,
\fBxsetbg\fP (xli), \fBFvwmBacker\fP with solid or colorset colors or a recent
version of \fBEsetroot\fP (>= 9.2) a background change is detected. If
background changes are not detected (e.g., if you use \fBxv\fP or
\fBxsetroot\fP) you can force detection by using the \fB\-d\fP option of
fvwm\-root:
.sp
.if n .RS 4
.nf
.fam C
xv \-root \-quit mybg.png; fvwm\-root \-d
.fam
.fi
.if n .RE
.sp
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.
.sp
Using outline move and resize (see the \fBOpaqueMoveSize\fP command and
the \fIResizeOpaque\fP \fBStyle\fP option) as well as setting the
\fIWindowShadeShrinks\fP style may help. The transparency achieved with
\fITransparent\fP 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:
.sp
.if n .RS 4
.nf
.fam C
Colorset 12 VGradient 200 grey30 grey60
Colorset 17 Transparent
*FvwmIconMan: Colorset 12
*FvwmIconMan: PlainColorset 17
.fam
.fi
.if n .RE
.sp
gives an IconMan with a vertical grey gradient background and the
buttons use the background (by transparency). To obtain a (root)
transparent IconMan:
.sp
.if n .RS 4
.nf
.fam C
Colorset 12 Transparent
Colorset 17 Transparent
Colorset 18 Transparent
Colorset 19 Transparent
*FvwmIconMan: Colorset 12
*FvwmIconMan: PlainColorset 17
*FvwmIconMan: FocusColorset 18
*FvwmIconMan: IconColorset 19
.fam
.fi
.if n .RE
.sp
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:
.sp
.if n .RS 4
.nf
.fam C
FvwmButtons:(Colorset 10, Swallow "FvwmIconMan" \*(AqFvwmIconMan\*(Aq)
.fam
.fi
.if n .RE
.sp
then, \fBFvwmIconMan\fP becomes a child of \fBFvwmButtons\fP and it is
transparent relative to \fBFvwmButtons\fP. So, in this case \fBFvwmIconMan\fP
uses Colorset 10 as background. If you want root transparency use the
\fIRootTransparent\fP option. \fBFvwmButtons\fP \fBFvwmIconMan\fP, and
\fBFvwmIdent\fP, 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 \fBFvwmProxy\fP is simpler,
the two colorsets refer to the window backgrounds. \fBFvwmPager\fP 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 \fBFvwmForm\fP and \fBFvwmScript\fP 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. \fITint\fP may work or not with the
\fITransparent\fP option. When the colorset is drawn on the foreground
\fITint\fP 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 \fIRootTransparent\fP option.
.sp
\fIRootTransparent\fP [ \fIbuffer\fP ] creates a root transparent background.
To make this option work, you must use an \fBEsetroot\fP compatible
program, fvwm\-root with the \-\-retain\-pixmap option or \fBFvwmBacker\fP
with the RetainPixmap option (and colorset or solid backgrounds). The
\fIbuffer\fP keyword is useful only when the \fITint\fP 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 \fIbuffer\fP. 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.
.sp
\fIShape\fP, \fITiledShape\fP and \fIAspectShape\fP take a file name as an
argument, search the \fBImagePath\fP and use it as the shape bitmap.
\fITiledShape\fP produces repeated copies of the bitmap with no scaling,
\fIShape\fP causes the bitmap to be stretched to fit whatever object the
colorset is applied to and \fIAspectShape\fP 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).
.sp
\fBWarning\fP Due to the way X11 implements shapes you cannot take back
making windows shaped. You may have to restart fvwm or the shaped
application.
.sp
\fI?Gradient ...\fP creates a pixmap and stretches it to fit the window.
\fI?Gradient\fP may be one of \fIHGradient\fP, \fIVGradient\fP, \fIDGradient\fP,
\fIBGradient\fP, \fISGradient\fP, \fICGradient\fP, \fIRGradient\fP or \fIYGradient\fP. 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 \fBColor Gradients\fP section for
the syntax of gradients.
.sp
\fITint\fP takes 2 arguments, a color and a percentage between 0 and 100.
It causes the image defined using \fI?Pixmap\fP or \fI?Gradient\fP to be
tinted with the specified color using the percentage. If the image is
transparent \fITint\fP tints only the image part. Unfortunately, a
colorset background specified using the \fITransparent\fP option can give
strange results. See the \fITransparent\fP option for details. With no
arguments this option removes the tint.
.sp
\fIfgTint\fP takes 2 arguments, a color and a percentage between 0 and 100.
It causes the color defined using \fIfg\fP to be tinted with the
specified color using the percentage. With no arguments this option
removes the tint.
.sp
\fIbgTint\fP takes 2 arguments, a color and a percentage between 0 and 100.
It causes the color defined using \fIbg\fP to be tinted with the
specified color using the percentage. If the \fIsh\fP and \fIhi\fP colors are
not specified, they are recomputed from the tinted bg color. With no
arguments this option removes the tint.
.sp
\fIAlpha\fP takes a percentage between 0 and 100 as an argument. It causes
fvwm to merge the image defined using \fI?Pixmap\fP or \fI?Gradient\fP with
the \fIbg\fP 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.
.sp
\fIfgAlpha\fP 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 \fBFont Names and Font Loading\fP
section. The default is 100 and it is restored if no argument is
given.
.sp
\fIDither\fP causes fvwm to dither the image defined using \fI?Pixmap\fP or
\fI?Gradient.\fP 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. \fINoDither\fP causes fvwm to do
not dither the images. \fIDither\fP 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 \fINoDither\fP,
however this effect can be useful with images which contain a lot of
close colors. For example a fine gradient looks more smooth.
.sp
\fIIconTint\fP 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 \fIIcon\fP \fBFvwmButtons\fP button
option) ...etc. With no arguments this option removes the icon tint.
.RE
.sp
\fIIconAlpha\fP 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.
.sp
\fINote\fP: 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.
.sp
\fINoShape\fP removes the shape mask from the colorset while \fIPlain\fP
removes the background pixmap or gradient.
.sp
Examples
.sp
.if n .RS 4
.nf
.fam C
Colorset 3 fg tan, bg navy
.fam
.fi
.if n .RE
.sp
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.
.sp
.if n .RS 4
.nf
.fam C
Colorset 3 bg "navy blue"
.fam
.fi
.if n .RE
.sp
changes the background color of colorset 3 to navy blue. The
foreground and pixmap are unchanged.
.sp
.if n .RS 4
.nf
.fam C
Colorset 3 AspectPixmap large_murky_dungeon.xpm
.fam
.fi
.if n .RE
.sp
causes depression.
.sp
.if n .RS 4
.nf
.fam C
Colorset 3 bg Average
.fam
.fi
.if n .RE
.sp
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.
.sp
.if n .RS 4
.nf
.fam C
Colorset 3 YGradient 200 3 blue 1000 navy 1 blue 1000 navy
.fam
.fi
.if n .RE
.sp
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.
.sp
.if n .RS 4
.nf
.fam C
#!/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
.fam
.fi
.if n .RE
.sp
Makes colorset 7 blink.
.sp
The color names used in colorsets are saved as fvwm variables which
can be substituted in any fvwm command. For example:
.sp
.if n .RS 4
.nf
.fam C
AddToFunc InitFunction
+ I Exec exec xterm \-fg $[fg.cs0] \-bg $[bg.cs0]
.fam
.fi
.if n .RE
.sp
Where $[fg.cs0] is the foreground color of colorset zero. Please refer
to the \fBCommand Expansion\fP section for more information.
.sp
\fBCleanupColorsets\fP
.RS 4
Resets a definition of all colorsets.
.RE
.sp
\fBColor Gradients\fP
.RS 4
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:
\fBHGradient\fP is a horizontal gradient, \fBVGradient\fP is vertical,
\fBDGradient\fP is diagonal from top left to bottom right, \fBBGradient\fP is
backwards diagonal from bottom left to top right, \fBSGradient\fP is
concentric squares, \fBCGradient\fP is concentric circles, \fBRGradient\fP is
a radar like pattern and \fBYGradient\fP is a Yin Yang style (but without
the dots).
.sp
The color gradient syntax has two forms:
.sp
\fB?Gradient\fP \fIcolors\fP \fIstart\-color\fP \fIend\-color\fP
.sp
This form specifies a linear gradient. The arguments denote the total
number of \fIcolors\fP to allocate (between 2 and 1000), the initial color
and the final color.
.sp
Example:
.sp
.if n .RS 4
.nf
.fam C
TitleStyle VGradient 20 rgb:b8/ce/bc rgb:5b/85/d0
.fam
.fi
.if n .RE
.sp
\fB?Gradient\fP \fIcolors\fP \fIsegments\fP \fIcolor\fP \fIlength\fP \fIcolor\fP [\fIlength\fP
\fIcolor\fP] ...
.sp
The second form specifies a nonlinear gradient. The arguments are: the
total number of \fIcolors\fP to allocate (between 2 and 1000), then the
number of \fIsegments\fP. For each segment, specify the starting \fIcolor\fP,
a relative \fIlength\fP, 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.
.sp
Examples:
.sp
.if n .RS 4
.nf
.fam C
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
.fam
.fi
.if n .RE
.RE
.sp
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:
.sp
+
Turn hilighting of the active menu item other than foreground color
off:
.sp
+
.sp
.if n .RS 4
.nf
.fam C
MenuStyle