- an Fvwm Icon Manager


       FvwmIconMan is spawned by fvwm, so no command line invoca-
       tion 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  man-
       ages.  For  example,  the  user may have one manager which
       lists only emacs windows, and another which  lists  every-
       thing 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  Mini-
       Icons  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 verti-
       cally), a maximum number of rows (and then grows  horizon-
       tally),  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 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.


       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
       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 mul-
       tiple  manager  windows, behavior which is unsuitable when
       running transiently. So, when running transiently,  FvwmI-
       conMan  will  only create one manager window. Use the man-
       ager id 'transient' to specify options  for  this  manager


       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 avail-
       able 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  con-
       figuration line may therefore have one of two forms:

       *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 man-
              ager which FvwmIconMan creates when  running  tran-

       The following options may be specified:

       *FvwmIconMan*nummanagers num
              num is a positive integer specifying the total num-
              ber 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
              Man 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

       *FvwmIconMan*[id*]focusandselectbutton  style  [forecolor
              back- color]
              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 but-
              tons. 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, or resource
              name, respectively.  The default is "%c: %i". Warn-
              ing: 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 "FvwmI-

       *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 hori-
              zontally.   If  both  are nonzero, then the manager
              window will be exactly that  size,  and  stay  that
              way.  As columns are created, the buttons will nar-
              ager will grow upwards.  Otherwise,  it  will  grow

       *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

       *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 cur-
              rent  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 "FvwmI-
              conMan". 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]
              manager  is empty). The manager's title is drawn in
              the title button.

       The two following options control which windows  get  han-
       dled  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 expres-
       sion 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 win-
       dow  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 man-
              agement 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

       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  exe-
       cuted  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 com-
       mas. 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  (typi-
       cally  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.

       managed window, or a  FvwmIconMan  button  representing  a
       window.  They  can  either  be an integer (which is inter-
       preted 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 but-
       ton or window. Up, Down, Right, and Left refer to the but-
       ton  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 desig-
       nates 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 win-
       dows 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

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

       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 man-
              ager 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  man-
              Executes  a  relative jump of Integer instructions.
              Backwards jumps are not allowed. The jump  is  com-
              puted  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 multi-
              ple  times  in the same instruction list (though it
              would be perverse to do so.)

       print String
              Prints String to the console. Useful for  debugging

       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 repre-
              sented 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.

       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 but-
       ton.  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  SendToMod-
       ule 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 com-
       mand.  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

       # 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 FvwmI-
       conMan 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*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 man-
       ager is set to grow upwards or leftwards, on some machines
       it may wander occasionally.

       It doesn't handle windows without resource names as grace-
       fully as it should.


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


       Thanks to:
            David Berson (berson@cs.pitt.edu),
            Josh M. Osborne (stripes@va.pubnix.com,

Man(1) output converted with man2html