Cull unused functions when compiling against librplay.

[fvwm.git] / modules / FvwmButtons / FvwmButtons.1.in

.\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
.TH FvwmButtons 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
.UC
.SH NAME
FvwmButtons \- the fvwm buttonbox module
.SH SYNOPSIS
.nf
Module FvwmButtons [-g geometry] [-transient | -transientpanel] [name[configfile]]
.fi

\fIFvwmButtons\fP can only be invoked by fvwm.
Command line invocation of the \fIFvwmButtons\fP module will not work.

.SH 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
.I "CREATING PANELS"
section for details.

.SH OPTIONS

The
.I -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
.I -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
.I -transient
is an option, not a configuration setting you can use the same
configuration for transient and non transient button bars.

The
.I -transientpanel
option does roughly the same as the
.I -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.

.SH 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 \fIOptionalName\fP argument, the
\fIOptionalName\fP is used to find configuration commands.  For
example:
.nf
.sp
AddToFunc StartFunction Module FvwmButtons MyButtonBox
.sp
.fi
FvwmButtons will then use only the lines
starting with "*MyButtonBox", instead of the default "*FvwmButtons".

.SH CONFIGURATION OPTIONS
The following commands are understood by FvwmButtons:

.IP "*FvwmButtons: Back \fIcolor\fP"
Specifies the background color for the buttons. The relief and shadow color
are calculated from the background color.

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

If
.I 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
.I 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.

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

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

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

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

.IP "*FvwmButtons: Columns \fIcolumns\fP"
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 \fIBoxSize\fP option is \fIfixed\fP.

.IP "*FvwmButtons: File \fIfilename\fP"
Specifies that the configuration for this button is found in the
file \fIfilename\fP. \fIFilename\fP 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 "\\".

.IP "*FvwmButtons: Font \fIfont\fP"
Specifies the font to be used for labeling the buttons, or
\fINone\fP.

.IP "*FvwmButtons: Fore \fIcolor\fP"
Specifies the color used for button label text and monochrome
icons.

.IP "*FvwmButtons: Frame \fIwidth\fP"
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.

.IP "*FvwmButtons: Geometry \fIgeometry\fP"
Specifies the FvwmButtons window location and size.  The geometry
is a standard X11 window geometry specification.

.IP "*FvwmButtons: ButtonGeometry \fIgeometry\fP"
This option works like the \fIGeometry\fP 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.

.IP "*FvwmButtons: Padding \fIwidth height\fP"
This option specifies the default horizontal padding to be
\fIwidth\fP pixels, and the vertical padding to be \fIheight\fP
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.

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

.IP "*FvwmButtons: Rows \fIrows\fP"
Specifies the number of rows of buttons to be created. The default
is 2 rows.

.IP "*FvwmButtons: (\fIoptions\fP) [\fItitle icon command\fP]"
Specifies the contents of a button in the buttonbox. The following
\fIoptions\fP, separated by commas or whitespace, can be given a
button:
.\" Start relative indent:
.RS
.IP "\fIgeometry\fP"
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 \fIwidth\fP times the
normal button width and \fIheight\fP times the normal button
height. If values for \fIx\fP and \fIy\fP 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.

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

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

In the \fIcommand\fP part, you can use a number of predefined
variables: \fI$left\fP, \fI$right\fP, \fI$top\fP and \fI$bottom\fP
are substituted by the left, right, top and bottom coordinates of
the button pressed. \fI$-left\fP, \fI$-right\fP, \fI$-top\fP and
\fI$-bottom\fP 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). \fI$width\fP and \fI$height\fP are replaced by
the width or height of the button. The variables \fI$fg\fP and
\fI$bg\fP are replaced with the name of the foreground or
background color set with the \fIBack\fP or \fIFore\fP option (see
below). All this is done regardless of any quoting characters. To
get a literal '$' use the string '$$'.

Example:

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

Note: With fvwm versions prior to 2.5.0, actions could not be
assigned to a button that swallowed an application window (see
\fISwallow\fP 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 \fIActionIgnoresClientWindow\fP can be
used on the button:

.nf
.sp
  *FvwmButtons: (Action beep, ActionIgnoresClientWindow, \\
     Swallow xeyes "Exec exec xeyes")
.sp
.fi

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.

.IP "ActionIgnoresClientWindow"
See the note in the description of \fIAction\fP above.

.IP "ActionOnPress"
Usually the action is executed on the button release except for
the \fBPopup\fP action.  This option changes this behavior, the
action is executed on the button press.  This may be good, for
example, with \fBMenu\fP or \fBSendToModule\fP that generates
popups, or when \fBFrame\fP is 0 and the button would look
unresponsive otherwise.

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

.IP "Center"
The contents of the button is centered on the button. This is the
default but may be changed by \fILeft\fP or \fIRight\fP.

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

.IP "Colorset \fIcolorset\fP"
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
.I colorset
is not applied to the swallowed module. You should use the
.I 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.

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

.IP "PressColorset \fIcolorset\fP"
Use colorset \fIcolorset\fP for the background color/image and/or title
color of the button when it is pressed.

.IP "Container [(\fIoptions\fP)]"
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
\fIBack, Font, Fore, Frame\fP and \fIPadding\fP. Flags for Title
and Swallow options can be set with \fITitle(flags)\fP and
\fISwallow(flags)\fP. You should also specify either "Columns
\fIwidth\fP" or "Rows \fIheight\fP", or "Rows 2" will be
assumed. For an example, see the \fISample configuration\fP
section.

The container button itself (separate from the contents) can take
format options like \fIFrame\fP and \fIPadding\fP, and commands
can be bound to it. This means you can make a sensitive relief
around a container, like
.nf
.sp
  *FvwmButtons: (2x2, Frame 5, Padding 2 2, Action Beep,\\
      Container(Frame 1))
.sp
.fi
Typically you will want to at least give the container a size
setting \fIwidth\fPx\fIheight\fP.

.IP "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
.nf
.sp
  *FvwmButtons: (End)
.sp
.fi

.IP "Font \fIfontname\fP"
Specifies that the font \fIfontname\fP is to be used for labeling
this button.

.IP "Fore \fIcolor\fP"
Specifies the foregound color of the title and monochrome icons in
this button.

.IP "Frame \fIwidth\fP"
The relief of the button will be \fIwidth\fP pixels wide. If
\fIwidth\fP is given as a negative number, the relief is
inverted. This makes the button sunken normally and raised when
activated.

.IP "Icon \fIfilename\fP"
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.

.IP "ActiveIcon \fIfilename\fP"
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).

.IP "PressIcon \fIfilename\fP"
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).

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

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

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

.IP "Padding \fIwidth height\fP"
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 \fIwidth\fP and the vertical padding to \fIheight\fP.

.IP "Panel [ (\fIoptions\fP) ] \fIhangon\fP \fIcommand\fP"
Panels can be swallowed exactly like windows are swallowed by
buttons with the \fISwallow\fP 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
\fIoptions\fP can be any of the \fIflags\fP described for the
Swallow command.  In addition a direction 'left', 'right', 'up'
or 'down' can be used to specify the sliding direction.

.\" dje: Looks like there should be another indent here...
The \fIsteps animation-steps\fP option defines the number of
animation steps.

The \fIdelay ms\fP 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 \fIsmooth\fP 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
.I Hints
option causes FvwmButtons to use the applications size hints to
calculate the size of the animation steps.
.I Hints
is the default.  If the number of steps is not what you want, try
using
.I NoHints.

The
.I 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 \fIindicator\fP 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
\fIindicator\fP 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 \fIPadding\fP option to leave a few
pixels between the indicator and the frame of the button.

The \fIposition\fP option allows to place the panel. The syntax
is:
.nf
.sp
position [\fIcontext-window\fP] [\fIpos\fP] [\fIx\fP \fIy\fP] [\fIborder-opts\fP]
.sp
.fi
.\" dje, even another indent to describe these suboptions.  4 indents is
.\" probably not a good idea.  Each is 1/2 inch by default...
The argument \fIcontext-window\fP can be one of: Button, Module or
Root. The  \fIcontext-window\fP 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 \fIpos\fP 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 \fIx\fP and \fIy\fP 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 \fIborder-opts\fP 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 \fICREATING PANELS\fP section for further
information on panels.

Example:
.nf
.sp
  # 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)
  ...
.sp
.fi

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

.IP "Size \fIwidth height\fP"
Specifies that the contents of this button require \fIwidth\fP by
\fIheight\fP 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.

.IP "Swallow [(\fIflags\fP)] \fIhangon\fP \fIcommand\fP"
Causes FvwmButtons to execute \fIcommand\fP, and when a window
with a name, class or resource matching \fIhangon\fP appears, it
is captured and swallowed into this button.  The \fIhangon\fP
string may contain wildcard characters ('*') that match any
substring.  Swallow replaces the variables \fI$fg\fP and \fI$bg\fP
as described above for the \fIAction\fP 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:
.nf
.sp
  *FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')
.sp
.fi
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:
.nf
.sp
  *FvwmButtons: (Swallow "FvwmPager" "FvwmPager 0 0")
.sp
.fi
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 \fIcommand\fP. 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 \fIhangon\fP name before spawning one itself
with \fIcommand\fP.  The \fIhangon\fP 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 \fIcommand\fP be "Nop":
.nf
.sp
  *FvwmButtons: (Swallow (UseOld) "Console" Nop)
.sp
.fi
If you want to be able to start it yourself, combine it with an
action:
.nf
.sp
  *FvwmButtons: (Swallow (UseOld) "Console" Nop, \\
               Action `Exec "Console" console &`)
.sp
.fi
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
.I command
is "Fvwm" or the 6 first letters of the
.I command
is "Module".
NoFvwmModule and FvwmModule override this logic.

.IP "Title [(\fIoptions\fP)] \fIname\fP"
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 \fIjustify\fP is "Right", the head is removed,
otherwise its tail is removed. These \fIoptions\fP 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.

.IP "ActiveTitle \fIname\fP"
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).

.IP "PressTitle \fIname\fP"
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).

.IP "Legacy fields [\fItitle icon command\fP]"
These fields are kept for compatibility with previous versions of
FvwmButtons, and their use is discouraged. The \fItitle\fP field
is similar to the option Title \fIname\fP. If the title field is
"-", no title is displayed. The \fIicon\fP field is similar to the
option Icon \fIfilename\fP. If the icon field is "-" no icon is
displayed. The \fIcommand\fP field is similar to the option Action
\fIcommand\fP or alternatively Swallow "\fIhangon\fP"
\fIcommand\fP.
.IP "The \fIcommand\fP"
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:
.nf
.sp
  Exec ["hangon"] command
.sp
.fi
Example:
.nf
.sp
  *FvwmButtons: (Action Exec "xload" xload)
.sp
.fi
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.

.IP "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:
.nf
.sp
  #define BG gray60
  *FvwmButtons: (Swallow "xload" `Exec xload -bg BG &`)
.sp
.fi
Any single character can be quoted with a preceding
backslash '\\'.
.RE
.\" End relative indent
.SH 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.


.SS 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
\fIPanel\fP option:

.nf
.sp
*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")
.sp
.fi

This works like the \fISwallow\fP 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 \fISwallow\fP option or if you want to learn
more about how 'swallowing' panels works, refer to the description
of the \fISwallow\fP 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 \fIStyle\fP 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.

.nf
.sp
Style name_of_panel_window NoTitle, Sitcky, NoIcon
.sp
.fi

You may want your panel to stay open only until you select
something in it.  You can give FvwmButtons the
\fI-transientpanel\fP 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 \fIPadding\fP 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:

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

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 \fIPanel\fP
option for further details.

.SS 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:

.nf
.sp
...
*FvwmButtons(Title WinOps,Panel WinOps)
*FvwmButtons(Title Tools ,Panel Tools)
...
.sp
.fi

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

.nf
.sp
*FvwmButtonsPanel WinOps
*FvwmButtonsBack bisque2
...

*FvwmButtonsPanel Tools
*FvwmButtonsBack bisque2
...
.sp
.fi

And perhaps you had style commands for you panels:

.nf
.sp
Style FvwmButtonsPanel Title, NoHandles, BorderWidth 0
Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky
.sp
.fi

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.

.nf
.sp
*FvwmButtons: (Title WinOps, Panel WinOps \\
  "Module FvwmButtons WinOps")
*FvwmButtons: (Title Tools , Panel Tools \\
  "Module FvwmButtons Tools")
.sp
.fi

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:

.nf
.sp
*FvwmButtons: (Title Tools , Panel(down) Tools \\
  "Module FvwmButtons -transientpanel Tools")
.sp
.fi

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:

.nf
.sp
*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
.sp
.fi

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

.SS 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.

.SH 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.
.IP "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 \fIrows\fP and \fIcolumns\fP
arguments. If the number of rows is given, it will calculate how
many columns are needed, and stick to that, unless \fIcolumns\fP
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
\fIsmart\fP at least the height/width of the tallest/widest button
is used while the \fIfixed\fP value prevents the box from getting
resized if both \fIrows\fP and \fIcolumns\fP have been set to
non-zero.
.IP "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 \fIsmart\fP is used.
.IP "Containers"
Containers are arranged by the same algorithm, in fact they are
shuffled recursively as the algorithm finds them.
.IP "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.
.nf
.sp
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 |
   +---+---+---+      +---+---+---+      +---+---+---+
.sp
.fi
.IP "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 \fIwidth height\fP". This will tell FvwmButtons
to give this button at least \fIwidth\fP by \fIheight\fP pixels
inside the relief and padding.

.SH DYNAMICAL ACTIONS
A running FvwmButtons instance may receive some dynamical actions.
This is achived using the fvwm command
.nf
.sp
SendToModule FvwmButtons-Alias <action> <params>
.sp
.fi
Supported actions:

.IP "ChangeButton \fIbutton_id\fP options"
where
.I button_id
is the id of the button to change as specified using the
.B Id
button option. It may also be a number, in this case the button
with the given number is assumed.  And finally,
.I 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
.BR Title ", " ActiveTitle ", " PressTitle ", " Icon ", "
.BR ActiveIcon " and " PressIcon .

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

.IP "PressButton \fIbutton_id\fP [\fImouse_button\fP]"
where
.I button_id
is the id of the button to press as specified using the
.B Id
button option and
.I 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
.I mouse_button
option is omitted "1" assumed. This command behaves exactly like if
the button in question was pressed using the mouse.

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

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

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

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

.nf
.sp
##########################################################
# 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 &`)
.sp
.fi

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
\fIUseOld\fP and \fINoKill\fP, 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:

.nf
.sp
########## 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)
.sp
.fi

The color specification \fIrgb:90/80/90\fP is actually the most
correct way of specifying independent colors in X, and should be
used instead of the older \fI#908090\fP. If the latter
specification is used in your configuration file, you should be
sure to escape the hash in any of the \fIcommand\fPs 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:
.nf
.sp
##########################################################
# 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`)
.sp
.fi

.SH BUGS

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

.SH 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.

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