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).
+
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).
+
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].
+
Please refer to the *Colorsets* section for details about colorsets.
$[schedule.last]::
This is replaced by the id of the last command that was scheduled with
the *Schedule* command, even if this command was already executed.
$[schedule.next]::
This is replaced by the id the next command used with *Schedule* will
get (unless a different id is specified explicitly).
$[cond.rc]::
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 *Conditional Commands* in the command list.
$[func.context]::
The context character of the running command as used in the *Mouse*,
*Key* or *PointerKey* command. This is useful for example with:
+
....
Mouse 3 FS N WindowShade $$[func.context]
....
$[debuglog.state]::
Either _0_ (debug log closed) or _1_. Indicates the current state of
debugging and logging facility.
$[gt._str_]::
return the translation of _str_ by looking in the current locale
catalogs. If no translation is found _str_ is returned as is. See the
*LocalePath* command.
$[infostore._key_]::
Return the value of the item stored in the InfoStore at the given _key_.
If no key is present, the unexpanded string is returned.
$[...]::
If the string within the braces is neither of the above, fvwm tries to
find an environment variable with this name and replaces its value if
one is found (e.g. "$[PAGER]" could be replaced by "more"). Otherwise
the string is left as is.
+
Some examples can be found in the description of the *AddToFunc*
command.
== SCRIPTING & COMPLEX FUNCTIONS
To achieve the more complex effects, fvwm has a number of commands that
improve its scripting abilities. Scripts can be read from a file with
*Read*, from the output of a command with *PipeRead* or written as a
complex function with the *AddToFunc* command. For the curious, section
7 of the fvwm FAQ shows some real life applications of scripting. Please
refer to the sections *User Functions and Shell Commands* and
*Conditional Commands* for details. A word of warning: during execution
of complex functions, fvwm needs to take all input from the mouse
pointer (the pointer is "grabbed" in the slang of X). No other programs
can receive any input from the pointer while a function is run. This can
confuse some programs. For example, the xwd program refuses to make
screen shots when run from a complex function. To achieve the same
functionality you can use the *Read* or *PipeRead* command instead.
== LIST OF FVWM COMMANDS
The command descriptions below are grouped together in the following
sections. The sections are hopefully sorted in order of usefulness to
the newcomer.
* *Menu commands*
* *Miscellaneous commands*
* *Commands affecting window movement and placement*
* *Commands for focus and mouse movement*
* *Commands controlling window state*
* *Commands for mouse and key bindings*
* *The Style command (controlling window styles)*
* *Other commands controlling window styles*
* *Commands controlling the virtual desktop*
* *Commands for user functions and shell commands*
* *Conditional commands*
* *Module commands*
* *Quit, restart and session management commands*
* *Colorsets*
* *Color gradients*
=== Menus
Before a menu can be opened, it has to be populated with menu items
using the *AddToMenu* command and bound to a key or mouse button with
the *Key*, *PointerKey* or *Mouse* command (there are many other ways to
invoke a menu too). This is usually done in the configuration file.
Fvwm menus are extremely configurable in look and feel. Even the
slightest nuances can be changed to the user's 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 *MenuStyle* command to learn more.
*Types of Menus*::
In fvwm there are four slightly different types of menus:
+
*Popup* menus can appear everywhere on the screen on their own or
attached to a part of a window. The *Popup* 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.
+
*Menu* is a very similar command, but the menus it opens are slightly
less transient. When invoked by clicking a mouse button, it stays open
and can be navigated with no button held. But if it is invoked by a
button press followed by mouse motion, it behaves exactly like a popup
menu.
+
_Tear off menus_ or _Pin up menus_ are menus from either of the above
two commands that have been "torn off" their original context and
pinned on the desktop like a normal window. They are created from
other menus by certain key presses or mouse sequences or with the
*TearMenuOff* command from inside a menu.
+
_Sub menus_ are menus inside menus. When a menu item that has the
*Popup* command as its action is selected, the named menu is opened as
an inferior menu to the parent. Any type of menu can have sub menus.
*Menu Anatomy*::
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.
+
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.
+
Finally, there may be a picture running up either side of the menu (a
"side bar").
*Menu Navigation*::
Menus can be navigated either with the keyboard or with the mouse.
Many people prefer to use the mouse, but it can be rather tedious.
Once you get the hang of it, 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 *Tear Off Menus* section for
details.
*Mouse Navigation*::
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.
+
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 _MouseWheel_ menu style.
+
Clicking on a selected item activates it - what happens exactly
depends on the type of the item.
+
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).
+
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.
*Keyboard Navigation*::
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).
+
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 _AutomaticHotkeys_
menu style fvwm automatically assigns hotkeys to all menu items.
+
The most basic keys to navigate through menus are the cursor keys
(move up or down one item, enter or leave a sub menu),
+
(activate item) and
+
(close menu). Numerous other keys can be used to navigate through
menus by default:
+
_Enter_, _Return_, _Space_ activate the current item.
+
_Escape_, _Delete_, _Ctrl-G_ exit the current sequence of menus or
destroy a tear off menu.
+
_J_, _N_, _Cursor-Down_, _Tab_, _Meta-Tab_, _Ctrl-F_, move to the next
item.
+
_K_, _P_, _Cursor-Up_, _Shift-Tab_, _Shift-Meta-Tab_, _Ctrl-B_, move
to the prior item.
+
_L_, _Cursor-Right_, _F_ enter a sub menu.
+
_H_, _Cursor-Left_, _B_ return to the prior menu.
+
_Ctrl-Cursor-Up_, _Ctrl-K_ _Ctrl-P_, _Shift-Ctrl-Meta-Tab_, _Page-Up_
move up five items.
+
_Ctrl-Cursor-Down_, _Ctrl-J_ _Ctrl-N_, _Ctrl-Meta-Tab_ _Page-Down_
move down five items.
+
_Shift-P_, _Home_, _Shift-Cursor-Up_, _Ctrl-A_ move to the first item.
+
_Shift-N_, _End_, _Shift-Cursor-Down_, _Ctrl-E_ move to the last item.
+
_Meta-P_, _Meta-Cursor-Up_, _Ctrl-Cursor-Left_, _Shift-Ctrl-Tab_, move
up just below the next separator.
+
_Meta-N_, _Meta-Cursor-Down_, _Ctrl-Cursor-Right_, _Ctrl-Tab_, move
down just below the next separator.
+
_Insert_ opens the "More..." sub menu if any.
+
_Backspace_ tears off the menu.
*Menu Bindings*::
The keys and mouse buttons used to navigate the menu can be configured
using the *Key* and *Mouse* commands with the special context 'M',
possible combined with 'T' for the menu title, 'I' for other menu
items, 'S' for any border or sidepic, '[' for left border including a
left sidepic, ']' for right border including a right sidepic, '-' for
top border, '_' for bottom border. The menu context uses its own set
of actions that can be bound to keys and mouse buttons. These are
_MenuClose_, _MenuCloseAndExec_, _MenuEnterContinuation_,
_MenuEnterSubmenu_, _MenuLeaveSubmenu_, _MenuMoveCursor_,
_MenuCursorLeft_, _MenuCursorRight_, _MenuSelectItem_, _MenuScroll_
and _MenuTearOff_.
+
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.
+
*MenuClose* exits from the current sequence of menus or destroys a
tear off menu.
+
*MenuCloseAndExec* exits from the current sequence of menus or
destroys a tear off menu and executes the rest of the line as a
command.
+
*MenuEnterContinuation* opens the "More..." sub menu if any.
+
*MenuEnterSubmenu* enters a sub menu.
+
*MenuLeaveSubmenu* returns to the prior menu.
+
*MenuMoveCursor* _n_ [_m_] 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 's'
to indicate that the items should refer only to the first items after
separators.
+
*MenuCursorLeft* enters a sub menu with the _SubmenusLeft_ menu style,
and returns to the prior menu with the _SubmenusRight_ menu style.
+
*MenuCursorRight* enters a sub menu with the _SubmenusRight_ menu
style, and returns to the prior menu with the _SubmenusLeft_ menu
style.
+
*MenuSelectItem* triggers the action for the menu item.
+
**MenuScroll **__n__ performs menu scrolling according to the
_MouseWheel_ menu style with _n_ items. The distance can be suffixed
with an 's' to indicate the items should refer only to the first items
after separators.
+
*MenuTearOff* turns a normal menu into a "torn off" menu. See *Tear
Off Menus* for details.
*Tear Off Menus*::
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
+
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 *TearMenuOff*.
+
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:
+
....
Mouse 2 MT A -
....
+
and to remove the builtin backspace binding, use:
+
....
Key Backspace M A -
....
+
See the section *Menu Bindings* for details on how to assign other
bindings for tear off.
+
Note that prior to fvwm 2.5.20 the tear off mouse bindings were
redefined in different way, which no longer work.
+
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:
+
....
Style fvwm_menu UsePPosition
....
+
To remove borders and buttons from a tear-off menu but keep the menu
title, you can use
+
....
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
....
+
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.
+
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.
+
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.
+
To create a tear off menu without opening the normal menu first, the
option _TearOffImmediately_ can be added to the *Menu* or *Popup*
command.
*AddToMenu* _menu-name_ [_menu-label_ _action_]::
Begins or adds to a menu definition. Typically a menu definition looks
like this:
+
....
AddToMenu Utilities Utilities Title
+ Xterm Exec exec xterm -e tcsh
+ Rxvt Exec exec rxvt
+ "Remote Logins" Popup Remote-Logins
+ Top Exec exec rxvt -T Top -n Top -e top
+ Calculator Exec exec xcalc
+ Xman Exec exec xman
+ Xmag Exec exec xmag
+ emacs Exec exec xemacs
+ Mail MailFunction xmh "-font fixed"
+ "" Nop
+ Modules Popup Module-Popup
+ "" Nop
+ Exit Fvwm Popup Quit-Verify
....
+
The menu could be invoked via
+
....
Mouse 1 R A Menu Utilities Nop
....
+
or
+
....
Mouse 1 R A Popup Utilities
....
+
There is no end-of-menu symbol. Menus do not have to be defined in a
contiguous region of the _config_ 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 *Nop* function are used to insert a separator
into the menu.
+
The keywords _DynamicPopUpAction_ and _DynamicPopDownAction_ have a
special meaning when used as the name of a menu item. The action
following the keyword is executed whenever the menu is popped up or
down. This way you can implement dynamic menus. It is even possible to
destroy itself with *DestroyMenu* and the rebuild from scratch. When
the menu has been destroyed (unless you used the _recreate_ option
when destroying the menu), do not forget to add the dynamic action
again.
+
Note: Do not trigger actions that require user interaction. They may
fail and may screw up your menus. See the *Silent* command.
+
*Warning* Do not issue *MenuStyle* commands as dynamic menu actions.
Chances are good that this crashes fvwm.
+
The keyword _Greyed_ will still render the menu item, but will grey it out
making the option unselectable.
+
There are several configurable scripts installed together with fvwm
for automatic menu generation. They have their own man pages. Some of
them, specifically *fvwm-menu-directory* and *fvwm-menu-desktop*, may
be used with _DynamicPopupAction_ to create a directory listing or
GNOME/KDE application listing.
+
Example (File browser):
+
....
# You can find the shell script fvwm_make_browse_menu.sh
# in the utils/ directory of the distribution.
AddToMenu BrowseMenu
+ DynamicPopupAction PipeRead \
'fvwm_make_browse_menu.sh BrowseMenu'
....
+
Example (Picture menu):
+
....
# Build a menu of all .jpg files in
# $HOME/Pictures
AddToMenu JpgMenu foo title
+ DynamicPopupAction Function MakeJpgMenu
AddToFunc MakeJpgMenu
+ I DestroyMenu recreate JpgMenu
+ I AddToMenu JpgMenu Pictures Title
+ I PipeRead 'for i in $HOME/Pictures/*.jpg; \
do echo AddToMenu JpgMenu "`basename $i`" Exec xv $i; done'
....
+
The keyword _MissingSubmenuFunction_ has a similar meaning. It is
executed whenever you try to pop up a sub menu that does not exist.
With this function you can define and destroy menus on the fly. You
can use any command after the keyword, but if the name of an item
(that is a submenu) defined with *AddToFunc* follows it, fvwm executes
this command:
+
....
Function
....
+
i.e. the name is passed to the function as its first argument and can
be referred to with "$0".
+
The *fvwm-menu-directory* script mentioned above may be used with
_MissingSubmenuFunction_ to create an up to date recursive directory
listing.
+
Example:
+
....
# There is another shell script fvwm_make_directory_menu.sh
# in the utils/ directory of the distribution. To use it,
# define this function in your configuration file:
DestroyFunc MakeMissingDirectoryMenu
AddToFunc MakeMissingDirectoryMenu
+ I PipeRead fvwm_make_directory_menu.sh $0
DestroyMenu SomeMenu
AddToMenu SomeMenu
+ MissingSubmenuFunction MakeMissingDirectoryMenu
+ "Root directory" Popup /
....
+
This is another implementation of the file browser that uses sub menus
for subdirectories.
+
Titles can be used within the menu. If you add the option _top_ behind
the keyword *Title*, the title is added to the top of the menu. If
there was a title already, it is overwritten.
+
....
AddToMenu Utilities Tools Title top
....
+
All text up to the first Tab in the menu label is aligned to the left side of
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 _ItemFormat_ option of the *MenuStyle* command.
+
If the menu-label contains an ampersand ('&'), the next character is
taken as a hot-key for the menu item. Hot-keys are underlined in the
label. To get a literal '&', insert "&&". Pressing the hot-key moves
through the list of menu items with this hot-key or selects an item
that is the only one with this hot-key.
+
If the menu-label contains a sub-string which is set off by stars,
then the text between the stars is expected to be the name of an image
file to insert in the menu. To get a literal '*', insert "**". For
example
+
....
+ Calculator*xcalc.xpm* Exec exec xcalc
....
+
inserts a menu item labeled "Calculator" with a picture of a
calculator above it. The following:
+
....
+ *xcalc.xpm* Exec exec xcalc
....
+
Omits the "Calculator" label, but leaves the picture.
+
If the menu-label contains a sub-string which is set off by percent
signs, then the text between the percent signs is expected to be the
name of 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 '%', insert "%%".
For example
+
....
+ Calculator%xcalc.xpm% Exec exec xcalc
....
+
inserts a menu item labeled "Calculator" with a picture of a
calculator to the left. The following:
+
....
+ %xcalc.xpm% Exec exec xcalc
....
+
Omits the "Calculator" label, but leaves the picture. The pictures
used with this feature should be small (perhaps 16x16).
+
If the menu-name (not the label) contains a sub-string which is set
off by at signs ('@'), then the text between them is expected to be
the name of an image file to draw along the left side of the menu (a
side pixmap). You may want to use the _SidePic_ option of the
*MenuStyle* command instead. To get a literal '@', insert "@@". For
example
+
....
AddToMenu StartMenu@linux-menu.xpm@
....
+
creates a menu with a picture in its bottom left corner.
+
If the menu-name also contains a sub-string surrounded by '^'s, then
the text between '^'s is expected to be the name of an X11 color and
the column containing the side picture is colored with that color. You
can set this color for a menu style using the _SideColor_ option of
the *MenuStyle* command. To get a literal '^', insert "^^". Example:
+
....
AddToMenu StartMenu@linux-menu.xpm@^blue^
....
+
creates a menu with a picture in its bottom left corner and colors
with blue the region of the menu containing the picture.
+
In all the above cases, the name of the resulting menu is name
specified, stripped of the substrings between the various delimiters.
*ChangeMenuStyle* _menustyle_ _menu_ ...::
Changes the menu style of _menu_ to _menustyle_. You may specify more
than one menu in each call of *ChangeMenuStyle*.
*CopyMenuStyle* _orig-menustyle_ _dest-menustyle_::
Copy _orig-menustyle_ to _dest-menustyle_, where _orig-menustyle_ is
an existing menu style. If the menu style _dest_menustyle_ does not
exist, then it is created.
*DestroyMenu* [recreate] _menu_::
Deletes a menu, so that subsequent references to it are no longer
valid. You can use this to change the contents of a menu during an
fvwm session. The menu can be rebuilt using *AddToMenu*. The optional
parameter _recreate_ tells fvwm not to throw away the menu completely
but to throw away all the menu items (including the title).
+
....
DestroyMenu Utilities
....
*DestroyMenuStyle* _menustyle_::
Deletes the menu style named _menustyle_ and changes all menus using
this style to the default style, you cannot destroy the default menu
style.
+
....
DestroyMenuStyle pixmap1
....
*Menu* _menu-name_ [_position_] [_double-click-action_]::
Causes a previously defined menu to be popped up in a sticky manner.
That is, if the user invokes the menu with a click action instead of a
drag action, the menu stays up. The command _double-click-action_ is
invoked if the user double-clicks a button (or hits the key rapidly
twice if the menu is bound to a key) when bringing up the menu. If the
double click action is not specified, double clicking on the menu does
nothing. However, if the menu begins with a menu item (i.e. not with a
title or a separator) and the double click action is not given, double
clicking invokes the first item of the menu (but only if the pointer
really was over the item).
+
The pointer is warped to where it was when the menu was invoked if it
was both invoked and closed with a keystroke.
+
The _position_ arguments allow placement of the menu somewhere on the
screen, for example centered on the visible screen or above a title
bar. Basically it works like this: you specify a _context-rectangle_
and an offset to this rectangle by which the upper left corner of the
menu is moved from the upper left corner of the rectangle. The
_position_ arguments consist of several parts:
+
{empty}[_context-rectangle_] _x_ _y_ [_special-options_]
+
The _context-rectangle_ can be one of:
+
_Root_:::
the root window of the current screen.
+
_Mouse_:::
a 1x1 rectangle at the mouse position.
+
_Window_:::
the frame of the context window.
+
_Interior_:::
the inside of the context window.
+
_Title_:::
the title of the context window or icon.
+
__Button__:::
+
_Icon_:::
the icon of the context window.
+
_Menu_:::
the current menu.
+
_Item_:::
the current menu item.
+
_Context_:::
the current window, menu or icon.
+
_This_:::
whatever widget the pointer is on (e.g. a corner of a window or the
root window).
+
_Rectangle_ <__geometry__>:::
the rectangle defined by <__geometry__> in X geometry format. Width
and height default to 1 if omitted.
If the context-rectangle is omitted or illegal (e.g. "item" on a
window), "Mouse" is the default. Note that not all of these make sense
under all circumstances (e.g. "Icon" if the pointer is on a menu).
The offset values _x_ and _y_ specify how far the menu is moved from
its default position. By default, the numeric value given is
interpreted as a percentage of the context rectangle's width (height),
but with a trailing '_m_' the menu's width (height) is used instead.
Furthermore a trailing '_p_' changes the interpretation to mean
pixels.
Instead of a single value you can use a list of values. All additional
numbers after the first one are separated from their predecessor by
their sign. Do not use any other separators.
If _x_ or _y_ are prefixed with "'__o__" 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's width/height is right over the pixel at percent
of the menu's width/height. So "o0" means that the top/left borders of
the menu and the rectangle overlap, with "o100" it's the bottom/right
borders and if you use "o50" they are centered upon each other (try it
and you will see it is much simpler than this description). The
default is "o0". The prefix "o" is an abbreviation for
"+-m".
A prefix of '_c_' is equivalent to "o50". Examples:
....
# window list in the middle of the screen
WindowList Root c c
# menu to the left of a window
Menu name window -100m c+0
# popup menu 8 pixels above the mouse pointer
Popup name mouse c -100m-8p
# somewhere on the screen
Menu name rectangle 512x384+1+1 +0 +0
# centered vertically around a menu item
AddToMenu foobar-menu
+ "first item" Nop
+ "special item" Popup "another menu" item +100 c
+ "last item" Nop
# above the first menu item
AddToMenu foobar-menu
+ "first item" Popup "another menu" item +0 -100m
....
Note that you can put a sub menu far off the current menu so you could
not reach it with the mouse without leaving the menu. If the pointer
leaves the current menu in the general direction of the sub menu the
menu stays up.
The _special-options_:
To create a tear off menu without opening the normal menu, add the
option _TearOffImmediately_. 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:
....
# Forbid fvwm to place the menu window
Style UsePPosition
# Menu at top left corner of screen
Menu Root 0p 0p TearOffImmediately
....
The _Animated_ and _Mwm_ or _Win_ menu styles may move a menu
somewhere else on the screen. If you do not want this you can add
_Fixed_ as an option. This might happen for example if you want the
menu always in the top right corner of the screen.
Where do you want a menu to appear when you click on 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 _SelectInPlace_ option. If
you want the pointer on the title of the menu, use _SelectWarp_ too.
Note that these options apply only if the _PopupAsRootMenu_
*MenuStyle* option is used.
The pointer is warped to the title of a sub menu whenever the pointer
would be on an item when the sub menu is popped up (_fvwm_ menu style)
or never warped to the title at all (_Mwm_ or _Win_ menu styles). You
can force (forbid) warping whenever the sub menu is opened with the
_WarpTitle_ (_NoWarp_) option.
Note that the _special-options_ do work with a normal menu that has no
other position arguments.
*MenuStyle* _stylename_ [_options_]::
Sets a new menu style or changes a previously defined style. The
_stylename_ is the style name; if it contains spaces or tabs it has to
be quoted. The name "*" is reserved for the default menu style. The
default menu style is used for every menu-like object (e.g. the window
created by the *WindowList* command) that had not be assigned a style
using the *ChangeMenuStyle*. See also *DestroyMenuStyle*. When using
monochrome color options are ignored.
_options_ is a comma separated list containing some of the keywords
Fvwm / Mwm / Win, BorderWidth, Foreground, Background, Greyed,
HilightBack / !HilightBack, HilightTitleBack, ActiveFore /
!ActiveFore, MenuColorset, ActiveColorset, GreyedColorset,
TitleColorset, Hilight3DThick / Hilight3DThin / Hilight3DOff,
Hilight3DThickness, Animation / !Animation, Font, TitleFont, MenuFace,
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.
In the above list some options are listed as option pairs or triples
with a '/' 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.
Some options are now negated by prefixing ! to the option. This is the
preferred form for all such options. The other negative forms are now
deprecated and will be removed in the future.
This is a list of MenuStyle deprecated negative options:
ActiveForeOff, AnimationOff, AutomaticHotkeysOff, HilightBackOff,
TitleWarpOff
_Fvwm_, _Mwm_, _Win_ reset all options to the style with the same name
in former versions of fvwm. The default for new menu styles is _Fvwm_
style. These options override all others except _Foreground_,
_Background_, _Greyed_, _HilightBack_, _ActiveFore_ and _PopupDelay_,
so they should be used only as the first option specified for a menu
style or to reset the style to defined behavior. The same effect can
be created by setting all the other options one by one.
_Mwm_ and _Win_ style menus popup sub menus automatically. _Win_ menus
indicate the current menu item by changing the background to dark.
_Fvwm_ sub menus overlap the parent menu, _Mwm_ and _Win_ style menus
never overlap the parent menu.
_Fvwm_ style is equivalent to !HilightBack, Hilight3DThin,
!ActiveFore, !Animation, Font, MenuFace, PopupOffset 0 67, TitleWarp,
TitleUnderlines1, SeparatorsShort, TrianglesRelief, PopupDelayed,
PopdownDelayed, PopupDelay 150, PopdownDelay 150, PopupAsSubmenu,
HoldSubmenus, SubmenusRight, BorderWidth 2, !AutomaticHotkeys,
UniqueHotkeyActivatesImmediate, PopupActiveArea 75.
_Mwm_ style is equivalent to !HilightBack, Hilight3DThick,
!ActiveFore, !Animation, Font, MenuFace, PopupOffset -3 100,
!TitleWarp, TitleUnderlines2, SeparatorsLong, TrianglesRelief,
PopupImmediately, PopdownDelayed, PopdownDelay 150, PopupAsSubmenu,
HoldSubmenus, SubmenusRight, BorderWidth 2,
UniqueHotkeyActivatesImmediate, !AutomaticHotkeys, PopupActiveArea 75.
_Win_ style is equivalent to HilightBack, Hilight3DOff, ActiveFore,
!Animation, Font, MenuFace, PopupOffset -5 100, !TitleWarp,
TitleUnderlines1, SeparatorsShort, TrianglesSolid, PopupImmediately,
PopdownDelayed, PopdownDelay 150, PopupAsSubmenu, RemoveSubmenus,
SubmenusRight, BorderWidth 2, UniqueHotkeyActivatesImmediate,
!AutomaticHotkeys, PopupActiveArea 75.
_BorderWidth_ takes the thickness of the border around the menus in
pixels. It may be zero to 50 pixels. The default is 2. Using an
illegal value reverts the border width to the default.
_Foreground_ and _Background_ may have a color name as an argument.
This color is used for menu text or the menu's background. You can
omit the color name to reset these colors to the built-in default.
_Greyed_ may have a color name as an argument. This color is the one
used to draw a menu-selection which is prohibited (or not recommended)
by the Mwm hints which an application has specified. If the color is
omitted the color of greyed menu entries is based on the background
color of the menu.
_HilightBack_ and _!HilightBack_ switch hilighting the background of
the selected menu item on and off. A specific background color may be
used by providing the color name as an argument to _HilightBack_. If
you use this option without an argument the color is based on the
menu's background color. The _ActiveColorset_ option overrides the
specified color. If the colorset has a non solid background it is used
for the hilighting.
_HilightTitleBack_ switches hilighting the background of menu titles
on. If a _TitleColorset_ was used, the background colour is taken from
there. Otherwise the color is based on the menu's background color. If
the colorset has a non solid background it is used for the hilighting.
_ActiveFore_ and _!ActiveFore_ switch hilighting the foreground of the
selected menu item on and off. A specific foreground color may be used
by providing the color name as an argument to _ActiveFore_. Omitting
the color turns hilighting on when an _ActiveColorset_ is used.
_ActiveFore_ turns off hilighting the foreground completely. The
_ActiveColorset_ option overrides the specified color.
_MenuColorset_ controls if a colorset is used instead of the
_Foreground_, _Background_ and _MenuFace_ menu styles. If the
_MenuColorset_ keyword is followed by a number equal to zero or
greater, this number is taken as the number of the colorset to use. If
the number is omitted, the colorset is switched off and the regular
menu styles are used again. The foreground and background colors of
the menu items are replaced by the colors from the colorset. If the
colorset has a pixmap defined, this pixmap is used as the background
of the menu. Note that the _MenuFace_ menu style has been optimized
for memory consumption and may use less memory than the background
from a colorset. The shape mask from the colorset is used to shape the
menu. Please refer to the *Colorsets* section for details about
colorsets.
_ActiveColorset_ works exactly like _MenuColorset_, but the foreground
from the colorset replaces the color given with the _ActiveFore_ menu
style and the colorset's background color replaces the color given
with the _HilightBack_ command (to turn on background hilighting you
have to use the _HilightBack_ menu style too). If specified, the
hilight and shadow colors from the colorset are used too. The pixmap
and shape mask from the colorset are not used. Hilighting the
background or foreground can be turned off individually with the
_!ActiveFore_ or _!HilightBack_ menu styles.
_GreyedColorset_ works exactly like _MenuColorset_, but the foreground
from the colorset replaces the color given with the _Greyed_ menu
style. No other parts of the colorset are used.
_TitleColorset_ works exactly like _MenuColorset_, but is used only
for menu titles.
_Hilight3DThick_, _Hilight3DThin_ and _Hilight3DOff_ determine if the
selected menu item is hilighted with a 3D relief. Thick reliefs are
two pixels wide, thin reliefs are one pixel wide.
_Hilight3DThickness_ takes one numeric argument that may be between
-50 and +50 pixels. With negative values the menu item gets a pressed
in look. The above three commands are equivalent to a thickness of 2,
1 and 0.
_Animation_ and _!Animation_ 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.
_Font_ and _TitleFont_ 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 _TitleFont_ is given, it is used for all menu titles instead of
the normal font.
_MenuFace_ enforces a fancy background upon the menus. You can use the
same options for _MenuFace_ as for the *ButtonStyle*. See description
of *ButtonStyle* command and the *Color Gradients* sections for more
information. If you use _MenuFace_ without arguments the style is
reverted back to normal.
Some examples of MenuFaces are:
....
MenuFace DGradient 128 2 lightgrey 50 blue 50 white
MenuFace TiledPixmap texture10.xpm
MenuFace HGradient 128 2 Red 40 Maroon 60 White
MenuFace Solid Maroon
....
Note: The gradient styles H, V, B and D are optimized for high speed
and low memory consumption in menus. This is not the case for all the
other gradient styles. They may be slow and consume huge amounts of
memory, so if you encounter performance problems with them you may be
better off by not using them. To improve performance you can try one
or all of the following:
Turn hilighting of the active menu item other than foreground color
off:
....
MenuStyle