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 mouse.

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.

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.

Name            Description                Default

nummanagers     number of managers         1
action          binds command to event     Mouse 0 N sendcommand Iconify
background      default background         gray
buttongeometry  size of button in pixels   100x17
colorset        default colorset
dontshow        list of windows to ignore
drawicons       use mini icons             false
focusandselectbutton                       flat grey black
focusandselectcolorset
focusbutton     style for focused buttons  up grey black
focuscolorset
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
iconbutton      style for icon buttons     up black grey
iconcolorset
managergeometry size of manager in buttons 0x1
noiconaction    animate iconification      NOP
plainbutton     style for normal buttons   up black grey
plaincolorset
resolution      global/desk/page/screen    global
reverse         normal, icon or none       none
selectbutton    style for selected buttons flat black grey
selectcolorset
shape           use shape extension        false
show            list of windows to show
showonlyicons   only icons visible         false
sort            keep managers sorted       name
title           manager title              FvwmIconMan
title           manager title              FvwmIconMan
titlebutton     style for title button     raisededge black grey
titlebutton     style for title button     raisededge black grey
titlecolorset
titlecolorset
usewinlist      honor WinListSkip?         true

*FvwmIconMan*optionname optionvalue

To specify that the optionname takes the value optionvalue for all managers.

*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 ACTIONS.

*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*]colorset colorset

The default colorset used. Overrides background and foreground. See FvwmTheme.

*FvwmIconMan*[id*]drawicons value

If your version of fvwm is capable of using mini icons, then this option determines if FvwmIconMan displays the mini icons. Otherwise, it generates an error message. "true" means that mini icons are shown for iconified windows, "false" that mini icons are never shown, and "always" that mini icons are shown for all windows.

*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*]focusandselectcolorset colorset

Works like focusandselectbutton but uses colorsets instead. The style setting can still only be applied with focusandselectbutton. See FvwmTheme.

*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*]focuscolorset colorset

Works like focusbutton but uses colorsets instead. The style setting can still only be applied with focusbutton. See FvwmTheme.

*FvwmIconMan*[id*]followfocus boolean

If true, then the button appearance reflects which window currently has focus. Default is false.

*FvwmIconMan*[id*]font font

Specifies the font to be used for labeling the buttons. The default is 8x13.

*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, 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".

*FvwmIconMan*[id*]iconbutton style [forecolor backcolor]

Same as the plainbutton option, but specifies the look of buttons whose windows are iconified.

*FvwmIconMan*[id*]iconcolorset colorset

Works like iconbutton but uses colorsets instead. The style setting can still only be applied with iconbutton. See FvwmTheme.

*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*]noiconaction action

Tells FvwmIconMan to do action when a NoIcon style window is iconified or de-iconified. Relevant coordinates are appended to action so that the icon can be traced to an FvwmIconMan button. An example action is "*FvwwmIconMan*NoIconAction SendToModule FvwmAnimate animate". A blank or null action turns this feature off.

*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*]plaincolorset colorset

Works like plainbutton but uses colorsets instead. The style setting can still only be applied with plainbutton. See FvwmTheme.

*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, page, screen, !desk, !page, or !screen. 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 are down. If page, then only those windows on the current page are shown. If screen, then only those windows on the current Xinerama screen are shown. !desk reverses the sense of desk, displaying only those windows not on the current desk. Likewise, !page shows only those windows not on the current page and !screen shows only those windows not on the current Xinerama screen. The default is global. If Xinerama is not active or only a single screen is used, page and screen are equivalent.

*FvwmIconMan*[id*]reverse class

Causes certain classes of buttons to have their relief lines reversed so that up and down styles are reversed. This has no affect on flat buttons. The class can be icon, normal or none. The default is none.

*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*]selectcolorset colorset

Works like selectbutton but uses colorsets instead. The style setting can still only be applied with selectbutton. See FvwmTheme.

*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*]sort value

If name, then the manager list is sorted by name. If namewithcase, then it is sorted by name sensitive to case. If id, then the manager list is sorted by the window id, which never changes after the window is created. Or it can be set to none, which results in no sorting. Default is name.

*FvwmIconMan*[id*]title titlestring

*FvwmIconMan*[id*]title titlestring

Specifies the window title string for that manager window.

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 title bar of the manager window, if any, and in the drawn in the title bar of the manager window, if any, and in the title button, which is the button drawn when the manager is empty. title button, which is the button drawn when the manager is empty.

*FvwmIconMan*[id*]titlebutton style [forecolor

*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 title button (the button drawn when the manager is empty). The manager's title is drawn in the title button. manager's title is drawn in the title button.

*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.

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 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*]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*]showonlyicons boolean

Only iconified windows are shown if boolean is true.

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 the sorted 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 jmp.

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.

select

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.

Examples:

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 fvwm, don't quote FvwmIconMan either.

##############################################################
# 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
# 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 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        name
*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*titleButton          raisededge white steelblue
*FvwmIconMan*NoIconAction         "SendToModule FvwmAnimate animate"

*FvwmIconMan*1*title           "Emacs windows"
*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*title           "All windows"
*FvwmIconMan*2*iconname        "FvwmIconMan: all"
*FvwmIconMan*2*format          "%c: %i"
*FvwmIconMan*2*dontshow        icon=Untitled
*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*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

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

Thanks to:
        David Berson <berson@cs.pitt.edu>,
        Gren Klanderman <greg@alphatech.com>,
        David Goldberg <dsg@mitre.org>,
        Pete Forman <gsez020@compo.bedford.waii.com>,
        Neil Moore <amethyst@maxwell.ml.org>,
        Josh M. Osborne <stripes@va.pubnix.com,
        Adam Rice <wysiwyg@glympton.airtime.co.uk>,
        Chris Siebenmann <cks@hawkwind.utcs.toronto.edu>,
        Bjorn Victor <victor@delial.docs.uu.se>.

for contributing either code or truly keen ideas.