Index of Section 1 Manual Pages
| Interix / SUA | FvwmButtons.1 | Interix / SUA |
FvwmButtons(1) FvwmButtons(1)
NAME
FvwmButtons - the FVWM buttonbox module
SYNOPSIS
FvwmButtons [-g geometry ] [-transient | -transientpanel]
[ name [ config file ] ]
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 re-spawned. This is espe-
cially 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 tran-
sient 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 Optional-
Name 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 but-
tons are placed. For the best tolerance of configu-
ration of 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: 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 contin-
uation is done by ending a line with a "\".
*FvwmButtons: Font font
Specifies the font to be used for labeling the but-
tons, 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 but-
ton. 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 con-
tents is normally 2 pixels on the sides and 4 pix-
els 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 transpar-
ent background.
*FvwmButtons: Rows rows
Specifies the number of rows of buttons to be cre-
ated. The default is 2 rows.
*FvwmButtons: (options) [title icon command]
Specifies the contents of a button in the button-
box. The following options, separated by commas or
whitespace, can be given a button:
geometry
Specifies the size and position of the but-
ton within the FvwmButtons window or con-
tainer. The geometry is a standard X11 win-
dow 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. 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 bot-
tom 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: (Swallow xload \
`Exec exec xload -fg $fg -bg $bg -geometry -3000-3000`)
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.
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.
Colorset colorset
The given colorset can be applied to a con-
tainer, a swallowed application and a simple
button. To apply it to a button or con-
tainer, simply put the option in a line with
a button or container description. Drawing
backgrounds for individual buttons and con-
tainers 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 col-
orsets as the background of swallowed appli-
cations does not have this restriction but
depends entirely on the swallowed applica-
tion. 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. Refer to the man page of the
FvwmTheme module for details about col-
orsets.
Container [(options)]
Specifies that this button will contain a
miniature buttonbox, equivalent to swallow-
ing 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 but-
tons 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 pix-
els 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 X11 bitmap file or XPM color
icon file, containing the icon to display on
the button. FvwmButtons searches through the
path specified in the fvwm ImagePath config-
uration item to find the icon file.
Left The contents of the button are aligned to
the left. The default is to center the con-
tents 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 con-
tainers, 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 addi-
tion 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 dis-
play 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 calcu-
lating positions for the animation (equiva-
lent 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 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 Fvwm-
Buttons 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 posi-
tion. 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. Con-
versely, 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 anima-
tion, 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 con-
tents 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 FvwmBut-
tons 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 matching the name hangon
appears, it is captured and swallowed into
this button. 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 will not be
restarted when FvwmButtons is restarted and
thus will 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 swal-
lowed 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 - Specifies whether the
swallowed program is to be re-spawned (re-
started) if it dies. If "Respawn" is speci-
fied, the program is re-spawned using the
original command. Use this option with care,
the program might have a legitimate reason
to die.
NoOld / UseOld - Specifies whether the but-
ton will try to swallow an existing window
matching the hangon name before spawning one
itself with command. The default value is
"NoOld". "UseOld" can be combined with
"NoKill" to have windows survive a restart
of the window manager. If you want FvwmBut-
tons 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 "UseTi-
tle" is given, the title on the button
changes dynamically to reflect the window
name. The default is "NoTitle".
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 com-
bine this with the "Left" or "Right" option,
you can get a look similar to fvwm's menus.
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 sim-
ilar 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 alterna-
tively Swallow "hangon" command.
The command
Any fvwm command is recognized by FvwmBut-
tons. See fvwm2(1) for more infomation.
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 or class matches the
quoted portion of the command is encoun-
tered. This is intended to provide visual
feedback to the user that the action he has
requested will be performed. 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 com-
mands 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 charac-
ters; 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 pur-
pose, 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 informa-
tion.
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 appli-
cation 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 flash-
ing for a moment when FvwmButtons starts up. Some appli-
cations 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 Fvwm-
Buttons 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 will be cre-
ated 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 -transient-
panel option after the -g option in the command. Fvwm-
Pager 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 acti-
vate 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
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 con-
figuration of the sub panels. The lines invoking the pan-
els use the same syntax as the Swallow option, so you sim-
ply 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 ' and add
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 disrup-
tive 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 applica-
tion 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 but-
tonbox itself, the following algorithm.
Getting the size right
First it calculates the number of button unit areas
it will need, by adding the width times the height
in buttons of each button. Containers are for the
moment considered a normal button. Then it consid-
ers the given rows and columns arguments. If the
number of rows is given, it will calculate how many
columns are needed, and stick to that, unless
columns is larger, in which case you will get some
empty space at the bottom of the buttonbox. If the
number of columns is given, it calculates how many
rows it needs to fit all the buttons. If neither
is given, it assumes you want two rows, and finds
the number of columns from that. 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 but-
tons. 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 but-
tons are placed first. Should a fixed button over-
lap another one or shall be place outside the but-
tons window, FvwmButtons exits with an error mes-
sage. 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 but-
ton 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 but-
tons 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 but-
ton. The unit button size of a container is set to
be large enough to hold the largest button in it
without squeezing it. Swallowed windows are simply
expected to be comfortable with the button size
they get from this scheme. If a particular configu-
ration requires more space for a swallowed window,
it can be set in that button's configuration line
using the option "Size width height". This will
tell FvwmButtons to give this button at least width
by height pixels inside the relief and padding.
SAMPLE CONFIGURATION
The following are excepts from a .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 Fvwm-
Pager module, and captures it to display in a quadruple
width button. is used, the Pager will be as big as possi-
ble within the button's relief.
The final line is even more magic. Note the combination of
UseOld and NoKill, which will try to swallow an existing
window with the name "xload15" when starting up (if fail-
ing: starting one with the specified command), which is
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 but-
tons.
##########################################################
# 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, copy-
right 1996. The statement above still applies.
AUTHOR
Robert Nation. Somewhat enhanced by Jarl Totland, Jui-
Hsuan Joshua Feng.
3 July 2001 FvwmButtons(1)