FvwmIconMan − an Fvwm Icon Manager

FvwmIconMan is spawned by fvwm, so no command line invocation will work.

FvwmIconMan is an icon manager modeled after the TWM icon manager.  The user may
have multiple icon managers, each of which armed with a list of window types
which it manages. For example, the user may have one manager which lists only
emacs windows, and another which lists everything else. You may also specify
what resolution each icon manager uses, for example, one icon manager may manage
windows on all desks, and another may manage only those on the current desk, or
page. If you have applied the MiniIcons patch to fvwm2, then FvwmIconMan can
display the miniature icons for its managed windows. The managers may have a
maximum number of columns (and so grows vertically), a maximum number of rows
(and then grows horizontally), or stay at a fixed size, and adjust the size of
the window buttons to fit (think win95’s Taskbar). And when support is compiled
in for the X Shape extension, then the manager windows may be shaped.

You can specify actions to be run when mouse, or key events are received. For
example, you could bind the first mouse button to iconify the selected window,
and make bindings for the arrow keys to navigate the manager window without the

FvwmIconMan can be set to display which window currently has the keyboard focus,
and by binding the select event (see below) to the fvwm Focus function, you can
emulate the TWM icon manager’s behavior.

During initialization, FvwmIconMan searches though the fvwm configuration file
for the options which are described below. It is highly recommended that you
make FvwmIconMan be a sticky window. And if you want to make use of the
followfocus option, and/or binding an action to Focus, then you should make
FvwmIconMan clicktofocus. Also, when using the Shape option, it’s recommended
that the FvwmIconMan window not be decorated at all by fvwm.

FvwmIconMan can be invoked by inserting the line ’Module FvwmIconMan’ in the
.fvwmrc file. If FvwmIconMan is to be spawned during fvwm’s initialization, then
this line should be placed in the InitFunction and ResetFunction declarations,
or it can be bound to a menu, mouse button, or keystroke to invoke it later.
FvwmIconMan should be placed in the ModulePath (defined in the .fvwmrc file) in
order for fvwm to find it.

If you wish to run FvwmIconMan in a transient mode, such as with the built in
window list, then pass Transient as an argument. The invocation "Module
FvwmIconMan Transient" will do nicely. In this mode, FvwmIconMan will pop up one
manager window directly under the cursor. When the mouse button is released, it
will execute the appropriate action, and then exit.  Things are somewhat
complicated by the fact that you can specify that FvwmIconMan create multiple
manager windows, behavior which is unsuitable when running transiently. So, when
running transiently, FvwmIconMan will only create one manager window. Use the
manager id ’transient’ to specify options for this manager window.


FvwmIconMan has acquired quite a few options. I assume others share my dislike
of paging though a long manpage, so here is a terse reference chart describing
the available options. They are described in more detail in the next section.

Name            Description                Default

action          binds command to event     Mouse 0 N sendcommand Iconify
background      default background         gray
buttongeometry  size of button in pixels   100x17
dontshow        list of windows to ignore
drawicons       use miniicons              false
focusandselectbutton                       flat black white
focusbutton     style for focused buttons  up black white
followfocus     show which win has focus   false
font                                       8x13
foreground      default text color         white
format          describes button label     "%c: %i"
iconname        manger icon name           FvwmIconMan
managergeometry size of manager in buttons 0x1
nummanagers     number of managers         1
plainbutton     style for normal buttons   up white gray
resolution      global, desk, or page      global
selectbutton    style for selected buttons flat white gray
shape           use shape extension        false
show            list of windows to show
sort            keep managers sorted       true
title           manager title              FvwmIconMan
titlebutton     style for title button     raisededge white gray
usewinlist      honor WinListSkip?         true

With the exception of the nummanagers option, all of the options may be defined
on a per‐manager basis. So, for example, the user may have his emacs manager
with a red foreground, and his xterm manager with a blue one. A configuration
line may therefore have one of two forms:

*FvwmIconMan*optionname optionvalue
     To specify that the optionname takes the value optionvalue for all

*FvwmIconMan*managerid*optionname optionvalue
     To specify that the option optionname takes the value optionvalue for
     manager managerid. Mangerid may either be a positive integer, or the string
     "transient". An integral id refers to managers which FvwmIconMan creates
     when running normally, and an id of "transient" refers to the single
     manager which FvwmIconMan creates when running transiently.

     The following options may be specified:


*FvwmIconMan*nummanagers num
     num is a positive integer specifying the total number of icon managers.
     Since FvwmIconMan would like to know how many managers there are before
     handling any manager specific options, this should come first. The default
     is 1.

*FvwmIconMan*[id*]action type binding
     Binds an FvwmIconMan command to an event. Type may be one of the values:
     Key, Mouse, or Select. Actions are described in the following section

*FvwmIconMan*[id*]background background
     Specifies the default background color.

*FvwmIconMan*[id*]buttongeometry geometry
     Specifies the initial geometry of an individual button in pixels. If the
     specified height is 0, then the button height is determined from the font
     size. X and Y coordinates are ignored.

*FvwmIconMan*[id*]drawicons boolean
     If your version of fvwm2 is capable of using MiniIcons, then this option
     determines if FvwmIconMan displays the MiniIcons. Otherwise, it generates
     an error message.

*FvwmIconMan*[id*]focusbutton style [forecolor backcolor]
     Same as the plainbutton option, but specifies the look of buttons whose
     windows have the keyboard focus.

*FvwmIconMan*[id*]focusandselectbutton style [forecolor backcolor]
     Same as the plainbutton option, but specifies the look of buttons which are
     both selected, and have the keyboard focus.

*FvwmIconMan*[id*]font font
     Specifies the font to be used for labeling the buttons. The default is

*FvwmIconMan*[id*]foreground foreground
     Specifies the default foreground color.

*FvwmIconMan*[id*]format formatstring
     A printf like format string which describes the string to be printed in the
     manager window for each managed window. Possible flags are: %t, %i, %c, and
     %r for the window’s title, icon, class, or resource name, respectively.
     The default is "%c: %i". Warning: m4 reserves the word format, so if you
     use m4, take appropriate action.


*FvwmIconMan*[id*]iconname iconstring
     Specifies the window icon name for that manager window. Iconstring may
     either be a single word, or a string enclosed in quotes. The default is

*FvwmIconMan*[id*]managergeometry geometry
     Specifies the initial geometry of the manager, in units of buttons. If
     height is 0, then the manager will use width columns, and will grow
     vertically once it has more than width windows. Likewise, if width is 0, it
     will use height rows, and grow horizontally.  If both are nonzero, then the
     manager window will be exactly that size, and stay that way. As columns are
     created, the buttons will narrow to accommodate.  If the geometry is
     specified with a negative y coordinate, then the window manager will grow
     upwards. Otherwise, it will grow downwards.

*FvwmIconMan*[id*]plainbutton style [forecolor backcolor]
     Specifies how normal buttons look. style may be one of flat, up, down,
     raisededge, or sunkedge, and describes how the button is drawn. The color
     options are both optional, and if not set, then the default colors are
     used. If on a monochrome screen, then the style option is ignored, but must
     still be set.

*FvwmIconMan*[id*]resolution resolution
     Specifies when the manager will display an entry for a certain window.
     resolution may take one of the following values: global, desk, or page. If
     global, then all windows of the appropriate type (see the show and dontshow
     options below) will be shown. If desk, then only those windows on the
     current desk will be down. And if page, then only those windows on the
     current page will be shown. The default is global.

*FvwmIconMan*[id*]selectbutton style [forecolor backcolor]
     Same as the plainbutton option, but specifies the look of buttons when the
     mouse is over them.

*FvwmIconMan*[id*]shape boolean
     If True, then use make the window shaped. Probably only useful if you have
     multiple columns or rows. If FvwmIconMan wasn’t compiled to support the
     Shape extension, this generates an error message. When using shaped
     windows, it’s recommended that a fvwm style is made for FvwmIconMan that
     has no borders.  Otherwise, fvwm will get confused.

*FvwmIconMan*[id*]title titlestring
     Specifies the window title string for that manager window. Titlestring may
     either be a single word, or a string enclosed in quotes. The default is
     "FvwmIconMan". This will be drawn in the titlebar of the manager window, if
     any, and in the title button, which is the button drawn when the manager is


*FvwmIconMan*[id*]titlebutton style [forecolor backcolor]
     Same as the plainbutton option, but specifies the look of the title button
     (the button drawn when the manager is empty). The manager’s title is drawn
     in the title button.

     The two following options control which windows get handled by which
managers. A manager can get two lists, one of windows to show, and one of
windows to ignore. If only the show list is given, then that manager will show
only the windows in the list. If only the dontshow list is given, then the
manager will show all windows except those in the list. If both lists are given,
then a window will be shown if it is not in the dontshow list, and in the show
list. And finally, if neither list is given, then the manager will handle all
windows. Each list is made up of patterns of the form type=pattern, where type
is one of class, resource, title, or icon, and pattern is an expression of the
same format used in the fvwm style command (minimalistic shell pattern
matching). Quotes around the pattern will be taken as part of the expression. If
a window could be handled by more than one manager, then the manager with the
lowest id gets it.

*FvwmIconMan*[id*]show pattern list
     If a window matches one of the patterns in the list, then it may be handled
     by this manager.

*FvwmIconMan*[id*]dontshow pattern list
     If a window matches one of the patterns in the list, then it may not be
     handled by this manager.

*FvwmIconMan*[id*]usewinlist boolean
     If true, then honor the WinListSkip style flag. Otherwise, all windows are
     subject to possible management according to the show and dontshow lists.

*FvwmIconMan*[id*]followfocus boolean
     If true, then the button appearance reflects which window currently has
     focus.  Default is false.

*FvwmIconMan*[id*]sort boolean
     If true, then the icon manager is kept sorted. Default is true.

Actions are commands which may be bound to an event of the type: a keypress, a
mouse click, or the mouse entering a window manager button ‐ denoted by the
action types Key, Mouse, and Select.

Normally, actions bound to a mouse click are executed when the button is
pressed. In transient mode, the action is executed when the button is released,
since it is assumed that FvwmIconMan was bound to some mouse event. A
tip/warning: FvwmIconMan still keeps track of the mouse button and any modifier
keys in this case, so if you bind FvwmIconMan to say, meta‐button3, then it


would be wise to ensure that the action you want to execute will be executed
when the meta‐button3 event occurs (which would be the button release, assuming
you kept your finger on the meta key).

The syntax for actions are:

Key actions: Key Keysym Modifiers FunctionList
     Keysym and Modifiers are exactly the same as for the fvwm Key command.

Mouse actions: Mouse Button Modifiers FunctionList
     Button and Modifiers are exactly the same as for the fvwm Mouse command.

Select actions: Select FunctionList

     A FunctionList is a sequence of commands separated by commas. They are
executed in left to right order, in one shared context ‐ which currently only
contains a pointer to the "current" button. If a button is selected (typically
by the mouse pointer sitting on it) when the action is executed, then the
current button is initialized to that button. Otherwise, it points to nothing.

Most of the available commands then modify this "current" button, either by
moving it around, making it become the selected button, or sending commands to
fvwm acting on the window represented by that button. Note that while this
current button is initialized to be the selected button, the selected button
does not implicitly follow it around. This way, the user can send commands to
various windows, without changing which button is selected.

Commands take five types of arguments: Integer, Manager, Window, Button, and
String. A String is a string specified exactly as for fvwm ‐ either in quotes or
as a single word not in quotes. Again, you may bind a sequence of commands to an
event, by listing them separated by commas.

Window and Button types look exactly the same in the .fvwm2rc file, but are
interpreted as either specifying a managed window, or a FvwmIconMan button
representing a window. They can either be an integer (which is interpreted
module N where N is the number of buttons ‐ so 0 is the first and ‐1 is the
last), or one of the strings: Select, Focus, Up, Down, Right, Left, Next, Prev.
Select and Focus refer to the currently selected or focused button or window.
Up, Down, Right, and Left refer to the button or window above, below, to the
right of, or to the left of the current button in the manager window, allowing
navigation around the manager window. Next and Prev designates the window,
button, or manager after or before the current button, allowing navigation of
the one dimensional list of windows which is drawn in the manager window. If the
manager is sorted, Next and Prev move through the windows in alphabetical order.

The Manager type can either be an integer, Next, or Prev.  The meaning is
analogous to that of the Button type, but in terms of the integral index of the
managers, restricted to managers which are nonempty.

The following functions are currently defined:


bif Button Integer/String
     A relative branch instruction. If Button is Select or Focus, then take the
     branch if there is a selected button or a focused button. If Button is an
     integer, then branch if nonzero. If it is one of Up, Down, Right, Left,
     Next, Prev, then the branch is taken when the current button can move in
     that direction. If the branch is taken, then Integer commands are skipped.
     No backwards branches are allowed.

bifn Button Integer/String
     The complement of bif. The branch is taken if Button evaluates to false, by
     the criteria listed for bif.

gotobutton Button
     Sets current button to Button. If Button is an integer, then the current
     button is set to Button modulo the number of buttons, in the whichever
     manager contains the selected button, if any.

gotomanager Manager
     Sets button to button 0 of Manager. This will only go to a visible,
     nonempty manager. So an integral argument is taken modulo the number of
     such managers.

jmp Integer/String
     Executes a relative jump of Integer instructions. Backwards jumps are not
     allowed. The jump is computed relative to the instruction following the

label String
     Provides a label that previous instructions can jump to. It will not be
     visible to subsequent jump instructions, and the same label can be used
     multiple times in the same instruction list (though it would be perverse to
     do so.)

print String
     Prints String to the console. Useful for debugging actions.

quit Quits FvwmIconMan.

ret  Stop executing the entire action.

     Selects the current button, if any. If a select action has been specified,
     it will then be run. Therefore, it is considered unwise to set the select
     button in the select action.


sendcommand Command
     Sends the fvwm command Command to the window represented by the current
     button, if any.

warp Warps cursor to current button, if any.


     gotobutton select, gotobutton Down, select

Selects the button below the currently selected button. Since the current button
is already initialized to the selected button, this may be shortened to
"gotobutton Down , select".

     gotobutton Up, select

Selects the button above the currently selected button.

     gotobutton 0, select

Selects the first button of the current manager. If there is no current manager,
which is the case when no button is selected, then this does nothing.

     gotobutton ‐1, select

Selects the last button of the current manager.

     gotobutton focus, select

Selects the button corresponding to the focused window.

     gotobutton focus, Iconify

Sends the fvwm command Iconify to the focused window. Note that this does not
change the selected button.

     bif Next 3, gotobutton 0, select, ret, gotobutton Next, select

If a button is selected, and it’s the last button, go to button 0. If it’s not
the last button, go to the next button. Otherwise, do nothing. Basically, this
action cycles through all buttons in the current manager.


     bif select 7, bif focus 3, gotomanager 0, select, ret, gotobutton focus, select, ret, gotobutton down, select

This is good for sending to FvwmIconMan with a SendToModule command. If there is
a selected button, it moves down. Otherwise, if there is a focused button, it is
selected. Otherwise, button 0 of manager 0 gets selected.

     bif select Select, bif focus Focus, gotomanager 0, select, ret, label Focus, gotobutton focus, select, ret, label Select, gotobutton down, select

Same as previous, but using the label instruction.

     In addition to being bound to keys and mice, actions can be sent from fvwm
to FvwmIconMan via the SendToModule command. Don’t quote the command when using
SendToModule. Also, due to a bug in the current version of fvwm2, don’t quote
FvwmIconMan either.

This first example is of a the simplest invocation of FvwmIconMan, which only
has one manager, and handles all windows:

# Load any modules which should be started during
# fvwm initialization
ModulePath /usr/lib/X11/fvwm:/usr/bin/X11
Module FvwmIconMan

# Make FvwmIconMan title‐bar‐less, sticky, and give it an icon
Style "Fvwm*"      Icon toolbox.xpm,NoTitle,NoHandles,Sticky
Style "FvwmIconMan" HandleWidth 5, Handles, BorderWidth 5

#Definitions used by the modules

*FvwmIconMan*nummanagers        1
*FvwmIconMan*resolution         global
*FvwmIconMan*background         slategrey
*FvwmIconMan*foreground         white
*FvwmIconMan*font               7x13
*FvwmIconMan*buttongeometry     100x0
*FvwmIconMan*managergeometry    1x0‐0+0

This example is the Reader’s Digest version of my personal configuration. It has
two managers, one for emacs and one for everything else, minus things with no
icon title. Only windows on the current page are displayed. The use of the
drawicons and shape options requires that fvwm and FvwmIconMan we compiled with
the correct options. Note how the geometry and show options are specified per
manager, and the others are common to all:


Style "FvwmIconMan"  NoTitle, Sticky, WindowListSkip, BorderWidth 0
Style "FvwmIconMan"  HandleWidth 0

Key F8 A N SendToModule FvwmIconMan bif select Select, bif focus Focus, gotomanager 0, select, sendcommand WarpToWindow, ret, label Focus, gotobutton focus, select, sendcommand WarpToWindow, ret, label Select, gotobutton prev, select, sendcommand WarpToWindow
Key F9 A N SendToModule FvwmIconMan bif select Select, bif focus Focus, gotomanager 0, select, sendcommand WarpToWindow, ret, label Focus, gotobutton focus, select, sendcommand WarpToWindow, ret, label Select, gotobutton next, select, sendcommand WarpToWindow

*FvwmIconMan*numManagers 2
*FvwmIconMan*Resolution  page
*FvwmIconMan*background  steelblue
*FvwmIconMan*foreground  white
*FvwmIconMan*font        7x13
*FvwmIconMan*usewinlist  true
*FvwmIconMan*drawicons   true
*FvwmIconMan*shape   true
*FvwmIconMan*followfocus true
*FvwmIconMan*sort    true
*FvwmIconMan*plainbutton          up white steelblue
*FvwmIconMan*selectbutton         down white steelblue
*FvwmIconMan*focusbutton          up white brown
*FvwmIconMan*focusandselectButton down white brown
*FvwmIconMan*titleButton          raisededge white steelblue

*FvwmIconMan*1*title           "Emacs windows"
*FvwmIconMan*1*iconname        "FvwmIconMan: Emacs"
*FvwmIconMan*1*format          "%i"
*FvwmIconMan*1*show            resource=emacs resource=gemacs
*FvwmIconMan*1*managergeometry 1x0‐400+0
*FvwmIconMan*1*buttongeometry  200x0

*FvwmIconMan*2*title           "All windows"
*FvwmIconMan*2*iconname        "FvwmIconMan: all"
*FvwmIconMan*2*format          "%c: %i"
*FvwmIconMan*2*dontshow        icon=Untitled
*FvwmIconMan*2*managergeometry 2x4‐0+0
*FvwmIconMan*2*buttongeometry  200x0

*FvwmIconMan*transient*geometry 194x100
*FvwmIconMan*transient*dontshow icon=Untitled
*FvwmIconMan*transient*action   Mouse 0 A sendcommand select select Iconify

*FvwmIconMan*action Mouse     1 N sendcommand Iconify
*FvwmIconMan*action Mouse     2 N sendcommand WarpToWindow
*FvwmIconMan*action Mouse     3 N sendcommand "Module FvwmIdent FvwmIdent"
*FvwmIconMan*action Key  Left  N gotobutton Left, select
*FvwmIconMan*action Key  Right N gotobutton Right, select
*FvwmIconMan*action Key  Up    N gotobutton Up, select
*FvwmIconMan*action Key  Down  N gotobutton Down, select
*FvwmIconMan*action Key  q     N quit


There is one bug that I know of. A honest to goodness solution to this would be
appreciated. When an icon manager is set to grow upwards or leftwards, on some
machines it may wander occasionally.

It doesn’t handle windows without resource names as gracefully as it should.

Brady Montz (bradym@cs.arizona.edu).

Thanks to:
     David Berson (berson@cs.pitt.edu),
     Josh M. Osborne (stripes@va.pubnix.com,
     Bjorn Victor (victor@delial.docs.uu.se),
     Adam Rice (wysiwyg@glympton.airtime.co.uk).