xenial (1) FvwmButtons.1.gz

Provided by: fvwm_2.6.5.ds-4.1_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.