Provided by: fvwm_2.6.5.ds-3_amd64 bug

NAME

       FvwmButtons - the fvwm buttonbox module

SYNOPSIS

       Module FvwmButtons [-g geometry] [-transient | -transientpanel] [name[configfile]]

       FvwmButtons  can  only  be  invoked  by  fvwm.  Command line invocation of the FvwmButtons
       module will not 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.  Even  other  applications  can  be
       'swallowed' by the button bar.

       Panels  that  are opened on a button press are available too.  See CREATING PANELS section
       for details.

OPTIONS

       The -g option specifies the geometry of the main window. The  command  line  option  takes
       precedence over any other geometry settings in the configuration file.

       The  -transient option tells FvwmButtons to terminate itself after the first key or button
       press has been received (presses to open a sub panel do not count) or a sub panel has been
       closed  or  respawned. This is especially useful for sub panels where you want to select a
       single button and have  it  closed  automatically.   It  could  be  used  to  create  two-
       dimensional  graphical  menus.  Since -transient is an option, not a configuration setting
       you can use the same configuration for transient and non transient button bars.

       The -transientpanel option does roughly the same as the -transient option, but instead  of
       closing  the  whole  button  bar, the window is merely hidden.  This is very useful if the
       button bar is started as a subpanel of another button bar because it avoids that  it  must
       be started again when something is selected.

INVOCATION

       FvwmButtons is spawned by fvwm, so command line invocation will not work.

       FvwmButtons  can be invoked by inserting the line 'Module FvwmButtons OptionalName' in the
       .fvwm2rc file. This should be placed in the StartFunction if FvwmButtons is to be  spawned
       during  fvwm's initialization. This can be bound to a menu or mouse button or keystroke to
       invoke it later.

       When  invoked  with  the  OptionalName  argument,  the  OptionalName  is  used   to   find
       configuration commands.  For example:

       AddToFunc StartFunction Module FvwmButtons MyButtonBox

       FvwmButtons  will  then  use  only  the lines starting with "*MyButtonBox", instead of the
       default "*FvwmButtons".

CONFIGURATION OPTIONS

       The following commands are understood by FvwmButtons:

       *FvwmButtons: Back color
              Specifies the background color for the buttons. The relief  and  shadow  color  are
              calculated from the background color.

       *FvwmButtons: BoxSize algorithm
              This  option  specifies  how serious FvwmButtons takes the Rows and Columns options
              (see below). It can be one of dumb, fixed or smart.

              If fixed is used and both Rows and Columns are specified and non-zero,  FvwmButtons
              uses  exactly the number of rows and columns specified.  If the box is too small to
              accommodate all buttons the module will fail.

              If smart is used FvwmButtons enlarges the box so all buttons have a chance to  fit.
              The  number  of columns is increased to at least the width of the widest button and
              new rows are added until  all  buttons  are  placed.  For  the  best  tolerance  of
              configuration errors use the smart option.

              dumb is neither fixed nor smart.  This is the default.

       *FvwmButtons: Colorset colorset
              Tells  the module to use colorset colorset for the window background.  Refer to the
              FvwmTheme man page for details about colorsets.

       *FvwmButtons: ActiveColorset colorset
              Tells the module to use colorset colorset for  the  background  color/image  and/or
              title color of a button when the mouse is hovering above a button.

       *FvwmButtons: PressColorset colorset
              Tells  the  module  to  use colorset colorset for the background color/image and/or
              title color of a button when it is pressed.

       *FvwmButtons: Columns columns
              Specifies the number of columns of buttons  to  be  created.  If  unspecified,  the
              number  of columns is set to the number of buttons requested, divided by the number
              of rows. If both the rows and columns are specified, but the number of  buttons  is
              more  than  the  rows  and  columns allow for, the columns specification is ignored
              unless the BoxSize option is fixed.

       *FvwmButtons: File filename
              Specifies that the configuration for this button is found  in  the  file  filename.
              Filename  can  be a 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 "*FvwmButtons". Comments are given by starting a
              line with "#". Line continuation is done by ending a line with a "\".

       *FvwmButtons: Font font
              Specifies the font to be used for labeling the buttons, or None.

       *FvwmButtons: Fore color
              Specifies the color used for button label text and monochrome icons.

       *FvwmButtons: Frame width
              Specifies the width of the relief around each button. If this is a negative number,
              the  relief  is  inverted.  This  makes  the button sunken normally and raised when
              activated.

       *FvwmButtons: Geometry geometry
              Specifies the FvwmButtons window location and size.  The geometry is a standard X11
              window geometry specification.

       *FvwmButtons: ButtonGeometry geometry
              This  option  works  like the Geometry option except that the size is the size of a
              single button.   The  size  of  the  whole  FvwmButtons  window  is  calculated  by
              multiplying the button dimension by the number of rows and columns.

       *FvwmButtons: Padding width height
              This  option  specifies  the default horizontal padding to be width pixels, and the
              vertical padding to be height pixels. The amount of free space between  the  relief
              of the button and its contents is normally 2 pixels on the sides and 4 pixels above
              and below, except for swallowed windows and containers, which  are  not  padded  at
              all, unless this option is used.

       *FvwmButtons: Pixmap pixmapfile
              Specifies  a  background pixmap to use.  Specify "none" (without the double quotes)
              for a transparent background.

       *FvwmButtons: Rows rows
              Specifies the number of rows of buttons to be created. The default is 2 rows.

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

              geometry
                     Specifies  the size and position of the button within the FvwmButtons window
                     or container. The geometry is a standard X11 window geometry  specification.
                     The  button  is  width  times  the  normal button width and height times the
                     normal button height. If values for x and y are given, the button is  placed
                     x (y) button units from the left (top) of the container if x (y) is positive
                     and x (y) units from the right (bottom) if x (y) is negative.  Buttons  with
                     position arguments (x and y) are placed before those without them. If two or
                     more buttons are forced to overlap by this, FvwmButtons exits with an  error
                     message.

              Action [(options)] command
                     Specifies  an  fvwm  command  to be executed when the button is activated by
                     pressing return or a mouse button. The command needs  to  be  quoted  if  it
                     contains a comma or a closing parenthesis.

                     The  current  options  of  the  Action  are:  Mouse  n - this action is only
                     executed for mouse button n. One  action  can  be  defined  for  each  mouse
                     button, in addition to the general action.

                     In  the  command  part, you can use a number of predefined variables: $left,
                     $right, $top and $bottom are substituted by the left, right, top and  bottom
                     coordinates  of  the button pressed. $-left, $-right, $-top and $-bottom are
                     substituted likewise, but the coordinates are calculated from the bottom  or
                     the  right  edge  of  the screen instead (for a button that is 5 pixels away
                     from the right screen border, $-right will be 5).  $width  and  $height  are
                     replaced by the width or height of the button. The variables $fg and $bg are
                     replaced with the name of the foreground or background color  set  with  the
                     Back  or Fore option (see below). All this is done regardless of any quoting
                     characters. To get a literal '$' use the string '$$'.

                     Example:

                       *FvwmButtons: (Title xload, Action (Mouse 1) \
                         `Exec exec xload -fg $fg -bg $bg -geometry -3000-3000`)

                     Note: With fvwm versions prior to 2.5.0, actions could not be assigned to  a
                     button  that  swallowed  an  application  window (see Swallow option).  Such
                     actions worked only when the border around the button was clicked.  This  is
                     now    possible,    but    to    get    back    the    old   behavior,   the
                     ActionIgnoresClientWindow can be used on the button:

                       *FvwmButtons: (Action beep, ActionIgnoresClientWindow, \
                          Swallow xeyes "Exec exec xeyes")

                     In this example, the action is only executed when you click on the border of
                     the button or the transparent part of the xeyes window, but not on the xeyes
                     window itself.

              ActionIgnoresClientWindow
                     See the note in the description of Action above.

              ActionOnPress
                     Usually the action is executed on the button release except  for  the  Popup
                     action.   This  option  changes this behavior, the action is executed on the
                     button press.  This may be good, for example, with Menu or SendToModule that
                     generates  popups, or when Frame is 0 and the button would look unresponsive
                     otherwise.

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

              Center The  contents  of  the button is centered on the button. This is the default
                     but may be changed by Left or Right.

              Top    The contents of the button is vertically aligned at the top of  the  button.
                     The default is to vertically center it.

              Colorset colorset
                     The  given  colorset  can be applied to a container, a swallowed application
                     and a simple button.  To apply it to a button or container, simply  put  the
                     option   in  a  line  with  a  button  or  container  description.   Drawing
                     backgrounds for individual buttons and containers with colorsets requires  a
                     lot  of communication with the X server.  So if you are not content with the
                     drawing speed of dozens of buttons with colorset  backgrounds,  do  not  use
                     colorsets   here.    Setting   colorsets  as  the  background  of  swallowed
                     applications does not have this restriction  but  depends  entirely  on  the
                     swallowed  application.   It  may  work  as  you wish, but since it involves
                     fiddling  with  other  applications'  windows  there  is  no  guarantee  for
                     anything.   I  have  tested  three applications: xosview works nicely with a
                     colorset background, xload works only with a VGradient or  solid  background
                     and  an  analog  xclock leaves a trail painted in the background color after
                     its hands.

                     If the swallowed window is an fvwm module (see the (No)FvwmModule option  to
                     Swallow),  then  the  colorset  is  not applied to the swallowed module. You
                     should use the colorset in the module configuration. If the swallowed module
                     has  a transparent colorset background, then the FvwmButtons background (and
                     not the button colorset) is seen by transparency of the  background  of  the
                     swallowed  module. Refer to the man page of the FvwmTheme module for details
                     about colorsets.

              ActiveColorset colorset
                     Use colorset colorset for the background color/image and/or title  color  of
                     the button when the mouse is hovering above it.

              PressColorset colorset
                     Use  colorset  colorset for the background color/image and/or title color of
                     the button when it is pressed.

              Container [(options)]
                     Specifies that this button will contain a miniature buttonbox, 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  an  example,  see  the  Sample
                     configuration section.

                     The  container  button  itself  (separate from the contents) 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 container, like

                       *FvwmButtons: (2x2, Frame 5, Padding 2 2, Action Beep,\
                           Container(Frame 1))

                     Typically  you  will  want  to  at  least  give the container 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 the foregound 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  is  inverted.  This  makes  the  button  sunken
                     normally and raised when activated.

              Icon filename
                     The  name  of  an  image file, containing the icon to display on the button.
                     FvwmButtons searches through  the  path  specified  in  the  fvwm  ImagePath
                     configuration item to find the icon file.

              ActiveIcon filename
                     The  name of an image file, containing an alternative icon to display on the
                     button when the mouse is hovering above the  button.  If  no  ActiveIcon  is
                     specified, the image specified by Icon is displayed (if there is one).

              PressIcon filename
                     The  name of an image file, containing an alternative icon to display on the
                     button when the button is pressed. If no PressIcon is specified,  the  image
                     specified by Icon is displayed (if there is one).

              Id id  The  id  to  be used to identify this button.  The first character of the id
                     should be alphabetic.  See also the "DYNAMICAL ACTIONS" section.

              Left   The contents of the button are aligned to the left. The default is to center
                     the contents on the button.

              NoSize This  option  specifies  that this button will not be considered at all when
                     making the initial calculations of button sizes. Useful for the  odd  button
                     that  gets  just  a couple of pixels too large to keep in line, and therefor
                     blows up your whole buttonbox. "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.

              Panel [ (options) ] hangon command
                     Panels can be swallowed exactly like windows are swallowed by  buttons  with
                     the  Swallow  command  below,  but they are not displayed within the button.
                     Instead they are hidden until the user presses the panel's button.  Then the
                     panel  (the  window  of  the  swallowed  application)  opens  with a sliding
                     animation.  The options can be any of the flags described  for  the  Swallow
                     command.   In  addition  a  direction 'left', 'right', 'up' or 'down' can be
                     used to specify the sliding direction.

                     The steps animation-steps option defines the number of animation steps.

                     The delay ms option sets the delay between the steps  of  the  animation  in
                     milliseconds.   Use  zero  for  no  delay.  The  maximum delay is 10 seconds
                     (10000). It doesn't make any sense to use the delay option unless  you  also
                     use the smooth option.

                     The  smooth  option  causes  the panel  to  redraw  between the steps of the
                     animation.  The sliding animation may be smoother this way,  it  depends  on
                     the  application,  and  display  speed.   The application may appear to grow
                     instead of sliding out.  The animation may be slower.

                     The Hints option causes FvwmButtons to use the applications  size  hints  to
                     calculate  the  size  of the animation steps.  Hints is the default.  If the
                     number of steps is not what you want, try using NoHints.

                     The noborder option tells FvwmButtons to ignore the borders  of  the  window
                     when  calculating  positions  for the animation (equivalent to set noplr and
                     noptb in the position option).

                     With the indicator option set, FvwmButtons will draw a small triangle in the
                     button  that  will open a panel.  The triangle points in the direction where
                     the panel will pop up.  The indicator keyword may be followed by a  positive
                     integer  that  specifies  the  maximum  width  and  height of the indicator.
                     Without this size FvwmButtons will make the indicator fit  the  button.  You
                     will  probably  want to use the Padding option to leave a few pixels between
                     the indicator and the frame of the button.

                     The position option allows one to place the panel. The syntax is:

                     position [context-window] [pos] [x y] [border-opts]

                     The argument context-window can be one  of:  Button,  Module  or  Root.  The
                     context-window  is  the  window  from  which  panel  percentage  offsets are
                     calculated.  Button  specifies  the   panel's   button,   Module   specifies
                     FvwmButtons  itself, and Root specifies a virtual screen. The context-window
                     together with the sliding direction define a line segment which  is  one  of
                     the  borders  of  the  context-window:  the top/bottom/left/right border for
                     sliding up/down/left/right.

                     The pos argument can be one of: center, left or right (for sliding up  or  a
                     down)  or top or bottom (for sliding left or right). It defines the vertical
                     (sliding up and down) or the horizontal (sliding left and right) position of
                     the  Panel  on  the line segment. For example, for a sliding up if you use a
                     left pos, then the left borders of the panel and of the context-window  will
                     be aligned.

                     The  offset  values  x  and  y  specify how far the panel is moved from it's
                     default position. By default, the numeric value given is  interpreted  as  a
                     percentage  of  the  context window's width (height). A trailing "p" changes
                     the interpretation to mean "pixels". All offset calculations are relative to
                     the buttons location, even when using a root context.

                     The  border-opts  are:  mlr,  mtb, noplr and noptb. They define which border
                     widths are taken in account. By default, the borders of FvwmButtons are  not
                     taken  in  account.  mlr  reverses  this  default for the left and the right
                     border and mtb reverses this default for the  top  and  the  bottom  border.
                     Conversely,  by default the borders of the Panel are taken in account. noplr
                     reverses this default for the left and the right border and  noptb  reverses
                     this default for the top and the bottom border.

                     The  defaults  are  sliding  up with a delay of five milliseconds and twelve
                     animation steps. To post the panel without any animation, set the number  of
                     steps to zero. The default position is 'Button center'.

                     Please  refer  to  the  CREATING  PANELS  section for further information on
                     panels.

                     Example:

                       # To include the panel in a button
                       *FvwmButtons: (Panel(down, delay 0, steps 16) \
                         SubPanel "Module FvwmButtons SubPanel")

                       # To define the panel as an instance of
                       # FvwmButtons with a different name:
                       *SubPanel: (Icon my_lock.xpm, Action Exec xlock)
                       *SubPanel: (Icon my_move.xpm, Action Move)
                       ...

              Right  The contents of the button are aligned to  the  right.  The  default  is  to
                     center the contents on the button.

              Size width height
                     Specifies  that  the contents of this button require width by height pixels,
                     regardless of what size FvwmButtons calculates from the icon and the  title.
                     A  button  bar  with  only swallowed windows will not get very large without
                     this option specified, as FvwmButtons does not consider sizes for swallowing
                     buttons.  Note  that  this  option  gives  the  minimum 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 with a name,  class
                     or  resource matching hangon appears, it is captured and swallowed into this
                     button.  The hangon string may contain wildcard characters ('*') that  match
                     any  substring.   Swallow  replaces  the  variables $fg and $bg as described
                     above for the Action option (but if you use the UseOld and  NoClose  options
                     the  application  is not be restarted when FvwmButtons is restarted and thus
                     does not get the new colors - if you changed them).  An example:

                       *FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')

                     takes the first window whose  name,  class,  or  resource  is  "XClock"  and
                     displays  it  in  the  button.   If  no matching window is found, the "Exec"
                     command creates one.  The argument "-geometry -3000-3000" is  used  so  that
                     the   window  is  first  drawn  out  of  sight  before  its  swallowed  into
                     FvwmButtons.

                     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 un-swallowed or closed when FvwmButtons exits cleanly. "NoClose" can
                     be  combined  with  "UseOld" to have windows survive a restart of the window
                     manager. 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
                     programs that doesn't accept window manager protocol. The default  value  is
                     "NoKill". This has no effect if "NoClose" is specified.

                     NoRespawn  /  Respawn / SwallowNew - Specifies whether the swallowed program
                     is to be respawned (restarted) if it dies. If "Respawn"  is  specified,  the
                     program  is respawned using the original command. Use this option with care,
                     the program might have a legitimate  reason  to  die.   If  "SwallowNew"  is
                     given,  the program is not respawned, but if a new window with the specified
                     name appears, it is swallowed.

                     NoOld / UseOld - Specifies  whether  the  button  will  try  to  swallow  an
                     existing  window  matching  the  hangon name before spawning one itself with
                     command.  The hangon string may contain wildcard characters ('*') that match
                     any  substring.The  default  value is "NoOld". "UseOld" can be combined with
                     "NoKill" to have windows survive a restart of the  window  manager.  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, combine 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 window's title or not. If "UseTitle" is given, the title
                     on the button changes dynamically to reflect the window name. The default is
                     "NoTitle".

                     NoFvwmModule  /  FvwmModule  -  By default, FvwmButtons treats the swallowed
                     window as an fvwm module window if the 4 first letters  of  the  command  is
                     "Fvwm"  or the 6 first letters of the command is "Module".  NoFvwmModule and
                     FvwmModule override this logic.

              Title [(options)] name
                     Specifies the title to be written on the button. Whitespace can be  included
                     in  the  title  by  quoting  it.  If a title at any time is too 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 is centered horizontally. This is the default.

                     Left - The title is justified to the left side.

                     Right - The title is justified to the right side.

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

              ActiveTitle name
                     Specifies  the  title to be written on the button when the mouse is hovering
                     above the button. If no ActiveTitle is  specified,  the  text  specified  by
                     Title is displayed (if there is any).

              PressTitle name
                     Specifies  the title to be written on the button when the button is pressed.
                     If no PressTitle is specified, the text specified by Title is displayed  (if
                     there is any).

              Legacy fields [title icon command]
                     These   fields   are  kept  for  compatibility  with  previous  versions  of
                     FvwmButtons, and their use is discouraged. The title field is similar to the
                     option  Title  name.  If  the title field is "-", no title is displayed. The
                     icon field is similar to the option Icon filename. If the icon field is  "-"
                     no  icon  is  displayed.  The  command field is similar to the option Action
                     command or alternatively Swallow "hangon" command.

              The command
                     Any fvwm  command  is  recognized  by  FvwmButtons.  See  fvwm(1)  for  more
                     information.

                     The Exec command has a small extension when used in Actions, its syntax is:

                       Exec ["hangon"] command

                     Example:

                       *FvwmButtons: (Action Exec "xload" xload)

                     The hangon string must be enclosed in double quotes.  When FvwmButtons finds
                     such an Exec command, the button remains pushed  in  until  a  window  whose
                     name,  class  or  resource  matches  the  quoted  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.  The hangon string may
                     contain wildcard characters ('*') that match any substring.  If  the  quoted
                     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. Contrary to earlier
                     versions commands no longer need to be quoted.  In  this  case  any  quoting
                     character  will  be  passed on to the application untouched. Only commas ','
                     and closing parentheses ')' have to be quoted inside a command. Quoting  can
                     be done with any of the three quotation characters; single quote:

                       'This is a "quote"',

                     double quote:

                       "It's another `quote'",

                     and back quote:

                       `This is a strange quote`.

                     The  back  quoting is unusual but used on purpose, if you use a preprocessor
                     like FvwmCpp and want it to get into your commands, like this:

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

                     Any single character can be quoted with a preceding backslash '\'.

CREATING PANELS

       Former versions of FvwmButtons (fvwm 2.0.46 to 2.3.6) had  a  different  way  of  handling
       panels.   You  can  not use your old panel configuration with the new panel feature.  Read
       "CONVERTING OLD PANEL CONFIGURATIONS" for more information.

   HOW TO CREATE NEW PANELS
       Any program that can be launched from within fvwm and that has a window can be used  as  a
       panel.   A  terminal window could be your panel, or some application like xload or xosview
       or another fvwm module, including FvwmButtons itself.  All you need  to  know  is  how  to
       start your application from fvwm.

       The  button  that  invokes  the  panel  is  as  easily  configured  as  any  other button.
       Essentially you need nothing more than the Panel option:

       *FvwmButtons: (Panel my_first_panel \
         "Module FvwmButtons -g -30000-30000 my_first_panel")
       *FvwmButtons: (Panel my_second_panel \
         "Exec exec xterm -g -30000-30000 -n my_second_panel")

       This works like the Swallow option.  The difference is that the  application  is  not  put
       into the button when it starts up but instead hidden from view.  When you press the button
       for the panel the window slides  into  view.   The  '-g  -30000-30000'  option  tells  the
       application  that  it  should  be  created  somewhere very far to the top and left of your
       visible screen.  Otherwise you would see it flashing for a moment when FvwmButtons  starts
       up.   Some  applications do not work well with this kind of syntax so you may have to live
       with the short flashing of the window.  If you want to make a panel from another  instance
       of  FvwmButtons  you can do so, but you must give it a different name ('my_first_panel' in
       above example).  If you run FvwmButtons under  the  same  name,  new  panels  are  created
       recursively  until your system runs out of resources and FvwmButtons crashes! To configure
       a  second  button  bar  with  a  different  name,  simply  put  '*new_name'  in  place  of
       '*FvwmButtons'  in  your  configuration  file.   If  you are not familiar with the Swallow
       option or if you want to learn more about how 'swallowing'  panels  works,  refer  to  the
       description of the Swallow option.

       Now  that  your  panel basically works you will want to tune it a bit.  You may not want a
       window title on the panel.  To disable the title use the  fvwm  Style  command.   If  your
       button  bar is 'sticky' you may want to make the panel sticky too.  And probably the panel
       window should have no icon in case it is iconified.

       Style name_of_panel_window NoTitle, Sitcky, NoIcon

       You may want your panel to stay open only until you select something in it.  You can  give
       FvwmButtons the -transientpanel option after the -g option in the command. FvwmPager has a
       similar option '-transient'.

       Last, but not least, you can now put an icon, a title or a small arrow in  the  button  so
       that  you  can see what it is for. A title or icon can be specified as usual.  To activate
       the arrow, just add '(indicator)' after the 'Panel' keyword in the example above  and  the
       Padding  option  to leave a few pixels between the arrow and the border of the button.  An
       optional direction in which the panel is opened can be given too:

       *FvwmButtons: (Padding 2, Panel(down, indicator) my_first_panel \
         "Module FvwmButtons -g -30000-30000 -transientpanel my_first_panel")

       There are several more options to configure how your panel works, for  example  the  speed
       and  smoothness  of  the  sliding  animation. Please refer to the description of the Panel
       option for further details.

   CONVERTING OLD PANEL CONFIGURATIONS
       This section describes how to convert a pretty old syntax used in 2.2.x versions.  You may
       skip it if your syntax is more recent.

       With  the  old  panel feature you first had one or more lines defining panels in your main
       FvwmButtons configuration:

       ...
       *FvwmButtons(Title WinOps,Panel WinOps)
       *FvwmButtons(Title Tools ,Panel Tools)
       ...

       After the last configuration line for the main panel the configuration of the first  panel
       followed, introduced with a line beginning with *FvwmButtonsPanel:

       *FvwmButtonsPanel WinOps
       *FvwmButtonsBack bisque2
       ...

       *FvwmButtonsPanel Tools
       *FvwmButtonsBack bisque2
       ...

       And perhaps you had style commands for you panels:

       Style FvwmButtonsPanel Title, NoHandles, BorderWidth 0
       Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky

       The  new configuration looks much the same, but now the configuration of the main panel is
       independent of the configuration of the sub panels.  The lines invoking the panels use the
       same  syntax  as  the Swallow option, so you simply add the name of the window to use as a
       panel and the command to execute instead of the panel name.  Note that you  give  the  new
       instance of FvwmButtons a different name.

       *FvwmButtons: (Title WinOps, Panel WinOps \
         "Module FvwmButtons WinOps")
       *FvwmButtons: (Title Tools , Panel Tools \
         "Module FvwmButtons Tools")

       If  you  used something like 'Panel-d' you now have to use 'Panel(down)' instead.  To make
       the new panel vanish as  soon  as  a  button  was  selected  start  FvwmButtons  with  the
       '-transientpanel' option:

       *FvwmButtons: (Title Tools , Panel(down) Tools \
         "Module FvwmButtons -transientpanel Tools")

       The rest of the configuration is very easy to change.  Delete the lines '*FvwmButtonsPanel
       <name>' and add <name> to all of the following configuration lines for the panel  instead.
       Use the same name in your Style commands:

       *WinOps: Back bisque2
       ...
       *Tools: Back bisque2
       ...
       Style "WinOps" Title, NoHandles, BorderWidth 0
       Style "WinOps" NoButton 2, NoButton 4, Sticky
       Style "Tools" Title, NoHandles, BorderWidth 0
       Style "Tools" NoButton 2, NoButton 4, Sticky

       That's  it.   The  new panels are much more flexible.  Please refer to other parts of this
       documentation for details.

   WHY WAS THE PANEL FEATURE REWRITTEN?
       There are several reasons.  The most important one is that the program  code  implementing
       the  panels  was  very  disruptive and caused a lot of problems.  At the same time it made
       writing new features for FvwmButtons difficult at best.  The second reason  is  that  most
       users were simply unable to make it work - it was way too complicated.  Even I (the author
       of the new code) had to spend several hours before I got it working the first  time.   The
       third reason is that the new panels are more versatile.  Any application can be a panel in
       FvwmButtons, not just other instances of FvwmButtons itself.  So  I  sincerely  hope  that
       nobody is angry about the change. Yes - you have to change your configuration, but the new
       feature is much easier to configure, especially if you already know how the Swallow option
       works.

ARRANGEMENT ALGORITHM

       FvwmButtons  tries  to  arrange  its buttons as best it can, by using recursively, on each
       container including the buttonbox 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 moment
              considered a normal button. Then it considers 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. If the
              BoxSize option is set to smart at least  the  height/width  of  the  tallest/widest
              button  is used while the fixed value prevents the box from getting resized if both
              rows and columns have been set to non-zero.

       Shuffling buttons
              Now it has a large enough area to place the buttons in, all  that  is  left  is  to
              place  them  right.  There  are two kinds of buttons: fixed and floating buttons. A
              fixed button is forced to a specific slot in the  button  box  by  a  x/y  geometry
              argument.  All  other  buttons  are  considered  floating. Fixed buttons are placed
              first. Should a fixed button overlap another one or  shall  be  place  outside  the
              buttons  window,  FvwmButtons  exits with an error message. After that the floating
              buttons are placed. The algorithm tries to place the buttons in a  left  to  right,
              top  to  bottom  western  fashion. If a button fits at the suggested position it is
              placed there, if not the current slot stays empty and the slot to the right will be
              considered. After the button has been placed, the next button is tried to be placed
              in the next slot and so on until all buttons are placed. Additional rows are  added
              below  the  bottom line of buttons until all buttons are placed if necessary if the
              BoxSize option smart is used.

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

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

       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
              button.  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 simply expected to
              be  comfortable  with  the  button  size 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.

DYNAMICAL ACTIONS

       A  running FvwmButtons instance may receive some dynamical actions.  This is achived using
       the fvwm command

       SendToModule FvwmButtons-Alias <action> <params>

       Supported actions:

       ChangeButton button_id options
              where button_id is the id of the button to change as specified using the Id  button
              option.  It  may also be a number, in this case the button with the given number is
              assumed.  And finally, button_id may be in the form +x+y,  where  x  and  y  are  a
              column  number  and  a  row  number of the button to be changed.  It is possible to
              specify multiple option pairs (name with value) by  delimiting  them  using  comma.
              Currently  options  include  Title,  ActiveTitle,  PressTitle, Icon, ActiveIcon and
              PressIcon.

       ExpandButtonVars button_id command
              where button_id has the same syntax as described in ChangeButton above. Command may
              be any fvwm command with variables $var that are expanded if supported.

       PressButton button_id [mouse_button]
              where  button_id  is the id of the button to press as specified using the Id button
              option and mouse_button is the number of mouse button used to click on  the  button
              e.g  "1"  for  left  mouse  button  etc. Quotes around the number is not needed. If
              mouse_button option is omitted "1" assumed. This command behaves  exactly  like  if
              the button in question was pressed using the mouse.

       Silent This  prefix  may be specified before other actions. It disables all possible error
              and warning messages.

       Example:

              *FvwmButtons: (Id note1, Title "13:30 - Dinner", Icon clock1.xpm)

              SendToModule FvwmButtons Silent \
                ChangeButton note1 Icon clock2.xpm, Title "18:00 - Go Home"

SAMPLE CONFIGURATION

       The following are excerpts from a .fvwm2rc file which describe FvwmButtons  initialization
       commands:

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

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

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

       # Make the menu/panel look like CDE
       Style "WinOps" Title, NoHandles, BorderWidth 0
       Style "WinOps" NoButton 2, NoButton 4, Sticky
       Style "Tools" Title, NoHandles, BorderWidth 0
       Style "Tools" NoButton 2, NoButton 4, Sticky

       ##########################################################
       DestroyModuleConfig FvwmButtons: *
       *FvwmButtons: Fore Black
       *FvwmButtons: Back rgb:90/80/90
       *FvwmButtons: Geometry -135-5
       *FvwmButtons: Rows 1
       *FvwmButtons: BoxSize smart
       *FvwmButtons: Font -*-helvetica-medium-r-*-*-12-*
       *FvwmButtons: Padding 2 2

       *FvwmButtons: (Title WinOps, Panel WinOps \
         "Module FvwmButtons -transientpanel WinOps")
       *FvwmButtons: (Title Tools, Panel Tools   \
         "Module FvwmButtons -transientpanel Tools")

       *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    \
            -geometry -3000-3000 &`)

       The  last  lines  are a little tricky - one spawns an FvwmPager module, and captures it to
       display in a quadruple width button. is used, the Pager will be as big as possible  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  failing:
       starting  one  with the specified command), which is un-swallowed when ending FvwmButtons.
       The swallowed application is started with "-geometry -3000-3000" so that it  will  not  be
       visible until its swallowed.

       The other panels are specified after the root panel:

       ########## PANEL WinOps
       DestroyModuleConfig WinOps: *
       *WinOps: Back bisque2
       *WinOps: Geometry -3-3
       *WinOps: Columns 1

       *WinOps: (Title Resize, Icon resize.xpm,  Action Resize)
       *WinOps: (Title Move,   Icon arrows2.xpm, Action Move  )
       *WinOps: (Title Lower,  Icon Down,        Action Lower )
       *WinOps: (Title Raise,  Icon Up,          Action Raise )

       ########## PANEL Tools
       DestroyModuleConfig Tools: *
       *Tools: Back bisque2
       *Tools: Geometry -1-1
       *Tools: Columns 1

       *Tools: (Title Kill,    Icon bomb.xpm,    Action Destroy)

       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.

       Note  that with the x/y geometry specs you can easily build button windows with gaps. Here
       is another example. You can not accomplish this without geometry specs for the buttons:

       ##########################################################
       # Another example
       ##########################################################

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

       DestroyModuleConfig FvwmButtons: *
       *FvwmButtons: Font        5x7
       *FvwmButtons: Back rgb:90/80/90
       *FvwmButtons: Fore        black
       *FvwmButtons: Frame       1
       # 9x11 pixels per button, 4x4 pixels for the frame
       *FvwmButtons: Geometry    580x59+0-0
       *FvwmButtons: Rows        5
       *FvwmButtons: Columns     64
       *FvwmButtons: BoxSize     fixed
       *FvwmButtons: Padding     1 1

       # Pop up a module menu directly above the button.
       *FvwmButtons: (9x1+3+0, Padding 0, Title "Modules",   \
         Action `Menu Modulepopup rectangle \
         $widthx$height+$lleft+$top o+50 -100m`)

       # first row of buttons from left to right:
       *FvwmButtons: (3x2+0+1, Icon my_lock.xpm, Action `Exec xlock`)
       *FvwmButtons: (3x2+3+1, Icon my_recapture.xpm, Action Recapture)
       *FvwmButtons: (3x2+6+1, Icon my_resize.xpm, Action Resize)
       *FvwmButtons: (3x2+9+1, Icon my_move.xpm, Action Move)
       *FvwmButtons: (3x2+12+1, Icon my_fvwmconsole.xpm,     \
         Action 'Module FvwmConsole')

       # second row of buttons from left to right:
       *FvwmButtons: (3x2+0+3, Icon my_exit.xpm, Action QuitSave)
       *FvwmButtons: (3x2+3+3, Icon my_restart.xpm, Action Restart)
       *FvwmButtons: (3x2+6+3, Icon my_kill.xpm, Action Destroy)
       *FvwmButtons: (3x2+9+3, Icon my_shell.xpm, Action 'Exec rxvt')

       # big items
       *FvwmButtons: (10x5, Swallow (NoKill, NoCLose)        \
         "FvwmPager" 'FvwmPager * * -geometry 40x40-1024-1024')
       *FvwmButtons: (6x5, Swallow "FvwmXclock" `Exec xclock \
         -name FvwmXclock -geometry 40x40+0-3000 -padding 1  \
         -analog -chime -bg rgb:90/80/90`)
       *FvwmButtons: (13x5, Swallow (NoClose)                \
       "FvwmIconMan" 'Module FvwmIconMan')
       *FvwmButtons: (20x5, Padding 0, Swallow "xosview"     \
         `Exec /usr/X11R6/bin/xosview -cpu -int -page -net   \
         -geometry 100x50+0-3000 -font 5x7`)

BUGS

       The action part of the Swallow option  must  be  quoted  if  it  contains  any  whitespace
       character.

COPYRIGHTS

       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, copyright 1996.  The  statement  above
       still applies.

AUTHOR

       Robert Nation.  Somewhat enhanced by Jarl Totland, Jui-Hsuan Joshua Feng, Scott Smedley.