           FvwmButtons - the FVWM buttonbox module

## SYNOPSIS

           FvwmButtons is spawned by fvwm, so no command line invoca-
           tion will work.

## DESCRIPTION

           The FvwmButtons module provides a window of buttons  which
           sits  on  the X terminal's root window. The user can press
           the buttons at any time, and trigger invocation of a user-
           specified  command by the window manager. FvwmButtons only
           works when fvwm is used as the window manager.

           The buttonbox can be of any configuration or geometry, and
           can  have  monochrome  or  color  icons  to  represent the
           actions which would be invoked.

## INITIALIZATION

           During initialization, FvwmButtons will search for a  con-
           figuration  file  which  describes the buttonbox geometry,
           color, icons, and actions. The format of this  files  will
           be described later. The configuration file will be the one
           which fvwm used during its initialization.

           To use FvwmButtons with several different  configurations,
           you  can  invoke  FvwmButtons  with an optional parameter,
           which it will use as its name instead (e.g  "Module  Fvwm-
           Buttons  SomeButtons").   SomeButtons  will then read only
           the lines in the configuration file starting with  "*Some-
           Buttons", and not the lines belonging to FvwmButtons.

           You can also specify an optional configuration file to use
           instead of the default fvwm configuration file, by  giving
           a  second argument which is a filename. This will override
           the setting "*FvwmButtonsFile", see below.

## INVOCATION

           FvwmButtons can be invoked by inserting the  line  'Module
           FvwmButtons' in the .fvwmrc file. This should be placed in
           the InitFunction if FvwmButtons is to  be  spawned  during
           fvwm's  initialization, or can be bound to a menu or mouse
           button or keystroke to invoke it later. Fvwm  will  search
           directory specified in the ModulePath configuration option
           to attempt to locate FvwmButtons.

## CONFIGURATION OPTIONS

           The following options int the .fvwmrc file are  understood
           by FvwmButtons:
                  Specifies  the  background color for the buttons. A
                  relief and a shadow color will also  be  calculated
                  from this.

           *FvwmButtonsColumns columns
                  Specifies  the  number  of columns of buttons to be
                  created. If unspecified, the number of columns will
                  be  set to the number of buttons requested, divided
                  by the number of rows. If both the rows and columns
                  are  specified,  but do not specify as many buttons
                  as are defined, then the users  columns  specifica-
                  tion will be ignored.

           *FvwmButtonsFile filename
                  Specifies that the configuration for this button is
                  found in the file filename, which will have  to  be
                  given  with  full  pathname, or is assumed to be in
                  fvwm's startup directory. The configuration file is
                  in  the  same  format as fvwm's configuration file,
                  but each line is read as if prefixed by  "*FvwmBut-
                  tons".  Comments  are given by starting a line with
                  "#", line continuation is done  by  ending  a  line
                  with a "\".

           *FvwmButtonsFont font
                  Specifies the font to be used for labeling the but-
                  tons, or None.

           *FvwmButtonsFore color
                  Specifies the color used for button label text  and
                  monochrome icons.

           *FvwmButtonsFrame width
                  Specifies  the width of the relief around each but-
                  ton. If this is given as  a  negative  number,  the
                  relief will at all times be the inverse of the nor-
                  mal relief. In effect, you will get a  sunken  but-
                  ton, which is raised when activated.

           *FvwmButtonsGeometry geometry
                  Specifies the FvwmButtons window location. The size
                  should not be specified, as  FvwmButtons  automati-
                  cally  chooses  a size which gracefully accomodates
                  all its buttons. The geometry  is  a  standard  X11
                  window geometry specification.

           *FvwmButtonsPadding width height
                  The  amount of free space between the relief of the
                  button and its contents is normally 2 pixels to the
                  sides  and  4  pixels  above  and below, except for
                  swallowed windows and  containers,  which  are  not
                  padded  at  all, unless given specific orders. This
                  height pixels.

           *FvwmButtonsRows rows
                  Specifies the number of rows of buttons to be  cre-
                  ated. If unspecified, 2 rows will be used.

           *FvwmButtons(options) [title icon command]
                  Specifies  the  contents of a button in the button-
                  box.  The following options, separated by commas or
                  whitespace, can be given a button:

             widthxheight
                  The  button  will  be width times the normal button
                  width and height times the normal button height.

             Action [(options)] command
                  Specifies an fvwm command to be executed  when  the
                  button  is  activated by pressing return or a mouse
                  button. If command contains whitespace it  must  be
                  quoted. The current options are:

                  Mouse  n  -  this action is only executed for mouse
                  button n.  One actions  can  be  defined  for  each
                  mouse button, in addition to the general action.

             Back color
                  Specifies  the  background color to be used drawing
                  this box. A relief color and a  shadow  color  will
                  also be calculated from this.

             Container [(options)]
                  Specifies that this button will contain a miniature
                  buttonbox, more or less  equivalent  to  swallowing
                  another  FvwmButtons  module.  The  options are the
                  same as can be given for a single button, but  they
                  affect all the contained buttons. Options available
                  for this  use  are  Back,  Font,  Fore,  Frame  and
                  Padding. Flags for Title and Swallow options can be
                  set  with  Title(flags)  and  Swallow(flags.    You
                  should also specify either "Columns width" or "Rows
                  height", or "Rows 2" will be assumed for purpose of
                  arranging  the buttons inside the container. For an
                  example, see the Sample configuration section.

                  The container button itself (separate from the con-
                  tents)  can  take  format  options  like  Frame and
                  Padding, and commands can  be  bound  to  it.  This
                  means you can make a sensitive relief around a con-
                  tainer, like

                    *FvwmButtons(2x2, Frame 5, Padding  2  2,  Action
                  Beep,\
                  tainer a size setting widthxheight.

             End  Specifies that no more buttons are defined for  the
                  current  container, and further buttons will be put
                  in the container's parent. This  option  should  be
                  given on a line by itself, i.e

                    *FvwmButtons(End)

             Font fontname
                  Specifies  that the font fontname is to be used for
                  labeling this button.

             Fore color
                  Specifies a color of the title and monochrome icons
                  in this button.

             Frame width
                  The relief of the button will be width pixels wide.
                  If width is given as a negative number, the  relief
                  will  at  all  times  be  the inverse of the normal
                  relief.  In effect, you will get a  sunken  button,
                  which is raised when activated.

             Icon filename
                  The  name  of  an X11 bitmap file or XPM color icon
                  file, containing the icon to display on the button.
                  FvwmButtons  will search through the path specified
                  in the fvwm IconPath  or  PixmapPath  configuration
                  items to find the icon file.

             NoSize
                  This  option specifies that this button will not be
                  considered at all when making the initial  calcula-
                  tions  of  buttonsizes.  Useful  for the odd button
                  that gets just a couple of pixels to large to  keep
                  in  line,  and therefor blows up your whole button-
                  box. "NoSize" is equivalent to "Size 0 0".

             Padding width height
                  The amount of free space between the relief of  the
                  button and its contents is normally 2 pixels to the
                  sides and 4 pixels  above  and  below,  except  for
                  swallowed  windows  and  containers,  which  are by
                  default not padded at all.  This  option  sets  the
                  horizontal   padding  to  width  and  the  vertical
                  padding to height.

             Size width height
                  Specifies that the contents  of  this  button  will
                  require  width by height pixels, regardless of what
                  not get very large without this  option  specified,
                  as FvwmButtons does not consider sizes for swallow-
                  ing buttons. Note that this option gives the  mini-
                  mum  space assured; other buttons might require the
                  buttonbox to use larger sizes.

             Swallow [(flags)] hangon command
                  Causes FvwmButtons to execute command, and  when  a
                  window matching the name hangon appears, it is cap-
                  tured and swallowed into this button.  An example:

                    *FvwmButtons(Swallow XClock 'Exec xclock &')

                  will take the first window  whose  name,  class  or
                  resource  is "XClock" and display it in the button.
                  Modules can be swallowed by specifying  the  module
                  instead of 'Exec whatever', like:

                    *FvwmButtons(Swallow "FvwmPager" "FvwmPager 0 0")

                  The flags that can be given to swallow are:

                  NoClose / Close - Specifies whether  the  swallowed
                  program  in  this  button  will  be  unswallowed or
                  closed when FvwmButtons exit cleanly. "NoClose" can
                  be  combined  with "UseOld" to have windows survive
                  restart of windowmanager. The  default  setting  is
                  "Close".

                  NoHints  / Hints - Specifies whether hints from the
                  swallowed program in this button will be ignored or
                  not, useful in forcing a window to resize itself to
                  fit its button. The default value is "Hints".

                  NoKill / Kill -  Specifies  whether  the  swallowed
                  program  will be closed by killing it or by sending
                  a message to it. This can be useful in ending  pro-
                  grams  that doesn't accept window manager protocol.
                  The default value is "NoKill".  This has no  effect
                  if "NoClose" is specified.

                  NoRespawn  /  Respawn - Specifies whether the swal-
                  lowed program is to be  respawn  if  it  dies.   If
                  "Respawn"   is   specified,  the  program  will  be
                  respawned using  the  original  command.  Use  this
                  option  with  care,  the  program might have a very
                  legitimate reason to die.

                  NoOld / UseOld - Specifies whether the button  will
                  try  to  swallow  an  existing  window matching the
                  hangon name before spawning one  itself  with  com-
                  mand.   The default value is "NoOld".  "UseOld" can
                  to swallow an old window, and not spawn one  itself
                  if failing, let the command be "Nop":

                    *FvwmButtons(Swallow (UseOld) "Console" Nop)

                  If  you  want to be able to start it yourself, com-
                  bine it with an action:

                    *FvwmButtons(Swallow (UseOld) "Console" Nop, \
                                 Action `Exec "Console" console &`)

                  NoTitle / UseTitle - Specifies whether the title of
                  the  button  will  be taken from the swallowed win-
                  dow's title or not. If  "UseTitle"  is  given,  the
                  title  on  the  button  will  change dynamically to
                  reflect the window name. The default is  "NoTitle".

             Title [(options)] name
                  Specifies  the  title  which will be written on the
                  button.  Whitespace can be included in the title by
                  quoting  it.  If a title at any time is to long for
                  its buttons, characters are chopped  of  one  at  a
                  time  until  it  fits.   If justify is "Right", the
                  head is removed, otherwise  its  tail  is  removed.
                  These options can be given to Title:

                  Center  -  The title will be centered horizontally.
                  This is the default.

                  Left - The title will  be  justified  to  the  left
                  side.

                  Right  -  The  title will be justified to the right
                  side.

                  Side - This will cause the title to appear  on  the
                  right  hand  side  of any icon or swallowed window,
                  instead of below it which is the default.   If  you
                  use  small  icons, and combine this with the "Left"
                  option, you can get a look similar to fvwm's menus.

           Legacy fields [title icon command]
                  These fields are kept for compatibility with previ-
                  ous versions of FvwmButtons, and their use is  dis-
                  couraged.  The title field is similar to the option
                  Title name. If the title field  is  "-",  no  title
                  will  be  displayed.   The icon field is similar to
                  the option Icon filename. If the icon field is  "-"
                  no  icon  will  be displayed.  The command field is
                  similar to the option Action  command  or  alterna-
                  tively Swallow "hangon" command.
                  Any  fvwm command is recognized by FvwmButtons. See
                  fvwm(1) for more info on this. The Exec command has
                  a  small extension when used in Actions, its syntax
                  is here:

                    Exec ["hangon"] command

                  When FvwmButtons finds such an  Exec  command,  the
                  button  will  remain pushed in until a window whose
                  name or class matches the  qouted  portion  of  the
                  command is encountered. This is intended to provide
                  visual feedback to the user that the action he  has
                  requested  will be performed. If the qouted portion
                  contains no characters, then the  button  will  pop
                  out  immediately.   Note  that  users  can continue
                  pressing the button, and re-executing the  command,
                  even when it looks "pressed in."

           Quoting
                  Any   string  which  contains  whitespace  must  be
                  quoted. This include commands.  Quoting can be done
                  with  any of the three quotation characters; single
                  quote:

                    'This is a "quote"',

                  double quote:

                    "It's another `quote'",

                  and backquote:

                    `This is a strange quote`.

                  The backquoting is purposeful if you use a  prepro-
                  cessor  like  FvwmCpp  and want it to get into your
                  commands, like this:

                    #define BG gray60
                    *FvwmButtons(Swallow "xload" `Exec xload  -bg  BG
                  &`)

## ARRANGEMENT ALGORITHM

           FvwmButtons  tries  to arrange its buttons as best it can,
           by using recursively, on each container including the but-
           tonbox itself, the following algorithm.

           Getting the size right
                  First it calculates the number of button unit areas
                  it will need, by adding the width times the  height
                  in  buttons  of each button. Containers are for the
                  the number of rows is given, it will calculate  how
                  many  columns are needed, and stick to that, unless
                  columns is larger, in which case you will get  some
                  empty space at the bottom of the buttonbox.  If the
                  number of columns is given, it calculates how  many
                  rows  it  needs to fit all the buttons.  If neither
                  is given, it assumes you want two rows,  and  finds
                  the number of columns from that.

           Shuffling buttons
                  Now it has a large enough area to place the buttons
                  in, all that is left is to place  them  right.  The
                  algorithm assumes the buttons are all of unit size,
                  and places them in a left to right, top  to  bottom
                  western  fashion.   Then  it looks at button 1, and
                  considers: Is this button larger than  normal?   If
                  it  isn't, the same thing is done for the next but-
                  tons.  When a button is found that is  larger  than
                  1x1,  space  must be provided for it. The algorithm
                  assumes it is in the right  coordinate,  its  upper
                  left  corner  should be unchanged. It then "slides"
                  away the buttons that occupies  the  places  needed
                  for this button. The buttons are slid to the right,
                  wrapping around to the  next  line.  When  all  the
                  space  has  been  cleared for this button the algo-
                  rithm continues with the  next  button,  doing  the
                  same.

           Containers
                  Containers  are  arranged by the same algorithm, in
                  fact they are shuffled recursively as the algorithm
                  finds them.

           Clarifying example
                  An example might be useful here: Suppose you have 6
                  buttons, all unit sized except number two, which is
                  2x2. This makes for 5 times 1 plus 1 times 4 equals
                  9  unit  buttons  total  area.  Assume   you   have
                  requested 3 columns.

                  1) +---+---+---+   2) +---+---+---+   3) +---+---+---+
                     | 1 | 2 | 3 |      | 1 | 2 |   |      | 1 | 2 |   |
                     +---+---+---+      +---+---+---+      +---+---+---+
                     | 4 | 5 | 6 |      | 3 | 4 | 5 |      | 3 |   | 4 |
                     +---+---+---+      +---+---+---+      +---+---+---+
                     |           |      | 6 |       |      | 5 | 6 |   |
                     +-----------+      +---+-------+      +---+---+---+

                  4) +---+---+---+   5) +---+-------+
                     | 1 | 2 |   |      | 1 |       |
                     +---+---+---+      +---+   2   |
                     | 3 |   |   |      | 3 |       |
                     +---+---+---+      +---+---+---+

                  The  algorithm  starts  as  in  figure 1. The first
                  large button it finds is number 2, and it will  try
                  to free up each of the unit areas it occupies, in a
                  left to right, top to bottom order. First  it  sees
                  that  button 3 is in its way, and it shifts all the
                  buttons, giving figure 2. Now it finds that  button
                  4  is  in  the  way,  so button 4 to 6 are shifted,
                  yielding  figure  3.  Button  4  is  still  barring
                  progress,  so  it  shifts  button 4 to 6 once more,
                  ending up at figure 4. Now  all  the  button  units
                  required by button 2 are freed, and button 2 can be
                  given its real size.

           What size will the buttons be?
                  When FvwmButtons has read the icons and fonts  that
                  are  required by its configuration, it can find out
                  which size is needed for every non-swallowing  but-
                  ton.  The unit button size of a container is set to
                  be large enough to hold the largest  button  in  it
                  without  squeezing it. Swallowed windows are simple
                  expected to be comfortable with the buttonsize they
                  get from this scheme. If a particular configuration
                  requires more space for a swallowed window, it  can
                  be  set  in  that button's configuration line using
                  the option "Size  width  height".  This  will  tell
                  FvwmButtons  to  give this button at least width by
                  height pixels inside the relief and padding.

## SAMPLE CONFIGURATION

           The following  are  excepts  from  a  .fvwmrc  file  which
           describe FvwmButtons initialization commands:

           ##########################################################
           # Load any modules which should be started during fvwm
           # initialization

           ModulePath /usr/lib/X11/fvwm:/usr/bin/X11

           # Make sure FvwmButtons is always there.
           AddToFunc InitFunction     "I" Module FvwmButtons
           AddToFunc RestartFunction  "I" Module FvwmButtons

           # Make it titlebar-less, sticky, and give it an icon
           Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky

           ##########################################################

           *FvwmButtonsFore Black
           *FvwmButtonsRows 1
           *FvwmButtonsFont -*-helvetica-medium-r-*-*-12-*
           *FvwmButtonsPadding 2 2

           *FvwmButtons(Title Resize,Icon resize.xpm ,Action Resize)
           *FvwmButtons(Title Move  ,Icon arrows2.xpm,Action Move  )
           *FvwmButtons(Title Lower ,Icon Down       ,Action Lower )
           *FvwmButtons(Title Raise ,Icon Up         ,Action Raise )
           *FvwmButtons(Title Kill  ,Icon bomb.xpm   ,Action Destroy)

           *FvwmButtons(1x1,Container(Rows 3,Frame 1))
           *FvwmButtons(Title Dopey ,Action \
               `Exec "big_win" xterm -T big_win -geometry 80x50 &`)
           *FvwmButtons(Title Snoopy, Font fixed, Action \
               `Exec "small_win" xterm -T small_win &`)
           *FvwmButtons(Title Smokin')
           *FvwmButtons(End)

           *FvwmButtons(Title Xcalc, Icon rcalc.xpm,\
                        Action `Exec "Calculator" xcalc &`)
           *FvwmButtons(Title XMag, Icon magnifying_glass2.xpm,\
                        Action `Exec "xmag" xmag &`)
           *FvwmButtons(Title Mail, Icon mail2.xpm,\
                        Action `Exec "xmh" xmh &`)
           *FvwmButtons(4x1, Swallow "FvwmPager" `FvwmPager 0 3`\
                        Frame 3)

           *FvwmButtons(Swallow(UseOld,NoKill) "xload15" `Exec xload\
                -title xload15 -nolabel -bg rgb:90/80/90 -update 15 &`)

           The  last  lines are a little tricky - one spawns an Fvwm-
           Pager module, and captures it to display  in  a  quadruple
           width button.  is used, the Pager will be as big as possi-
           ble within the button's relief.

           The final line is even more magic. Note the combination of
           UseOld  and  NoKill, which will try to swallow an existing
           window with the name "xload15" when starting up (if  fail-
           ing:  starting  one  with the specified command), which is
           unswallowed when ending FvwmButtons.

           The color specification rgb:90/80/90 is actually the  most
           correct  way  of  specifying  independent colors in X, and
           should be used instead of the older #908090. If the latter
           specification  is  used  in  your  configuration file, you
           should be sure to escape the hash in any of  the  commands
           which  will be executed, or fvwm will consider the rest of
           the line a comment.

## COPYRIGHTS

           by Robert Nation

           Copyright 1993, Robert Nation. No guarantees or warranties
           or anything are provided or implied in any way whatsoever.
           Use this program at your own risk. Permission to use  this
           program for any purpose is given, as long as the copyright
           is kept intact.

           Further modifications and patching by Jarl Totland,  copy-
           right 1996.  The statement above still applies.

## AUTHOR

           Robert Nation.  Somewhat enhanced by Jarl Totland.