- the FVWM buttonbox module


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


       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.


       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.


       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.


       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.

       *FvwmButtonsPixmap pixmapfile
              Specifies a  background  pixmap  to  use.   Specify
              "none" for a transparent background.

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

              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-
                    Container(Frame 1))

              Typically you will want to at least give  the  con-
              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


         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.

              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.
              Specifies  that  the  contents  of this button will
              require width by height pixels, regardless of  what
              size  FvwmButtons  calculates from the icon and the
              title. A buttonbar with only swallowed windows will
              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

              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.

              hangon  name  before  spawning one itself with com-
              mand.  The default value is "NoOld".  "UseOld"  can
              be  combined  with "NoKill" to have windows survive
              restart of windowmanager. If you  want  FvwmButtons
              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

              Right - The title will be justified  to  the  right

              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
              similar  to  the  option Action command or alterna-
              tively Swallow "hangon" command.

       The 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."

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

                '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


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

              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
              moment considered a normal button.  Then it consid-
              ers the given rows and columns arguments.   If  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

              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 |   |
                 +-----------+      +---+-------+      +---+---+---+
                 | 1 | 2 |   |      | 1 |       |
                 +---+---+---+      +---+   2   |
                 | 3 |   |   |      | 3 |       |
                 +---+---+---+      +---+---+---+
                 | 4 | 5 | 6 |      | 4 | 5 | 6 |
                 +---+---+---+      +---+---+---+

              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.


       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

       *FvwmButtonsFore Black
       *FvwmButtonsBack rgb:90/80/90
       *FvwmButtonsGeometry -135-5
       *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(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  FvwmButtons  program, and the concept for interfacing
       this module to the Window Manager, are all  original  work
       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.


       Robert Nation.  Somewhat enhanced by Jarl Totland.

Man(1) output converted with man2html