FvwmButtons
FvwmButtons(1) FvwmButtons(1)
NAME
FvwmButtons - the FVWM buttonbox module
SYNOPSIS
FvwmButtons is spawned by fvwm, so no command line invoca
tion will 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.
INITIALIZATION
During initialization, FvwmButtons will search for a con
figuration file which describes the buttonbox geometry,
color, icons, and actions. The format of this files will
be described later. The configuration file will be the one
which fvwm used during its initialization.
To use FvwmButtons with several different configurations,
you can invoke FvwmButtons with an optional parameter,
which it will use as its name instead (e.g "Module Fvwm
Buttons SomeButtons"). SomeButtons will then read only
the lines in the configuration file starting with "*Some
Buttons", and not the lines belonging to FvwmButtons.
You can also specify an optional configuration file to use
instead of the default fvwm configuration file, by giving
a second argument which is a filename. This will override
the setting "*FvwmButtonsFile", see below.
INVOCATION
FvwmButtons can be invoked by inserting the line 'Module
FvwmButtons' in the .fvwmrc file. This should be placed in
the InitFunction if FvwmButtons is to be spawned during
fvwm's initialization, or can be bound to a menu or mouse
button or keystroke to invoke it later. Fvwm will search
directory specified in the ModulePath configuration option
to attempt to locate FvwmButtons.
CONFIGURATION OPTIONS
The following options int the .fvwmrc file are understood
by FvwmButtons:
*FvwmButtonsBack color
Specifies the background color for the buttons. A
relief and a shadow color will also be calculated
from this.
*FvwmButtonsBoxSize algorithm
This option specifies how serious FvwmButtons takes
the Rows and Colums options (see below). It can be
one of dumb, fixed or smart. If fixed is given and
both Rows and Columns are specified and non-zero,
FvwmButtons will use exactly this numbers of rows
and columns of button. If the box is too small to
accomodate all buttons the module will fail. Using
the smart option FvwmButtons is intelligent enough
to enlarge 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 can be placed. For best
tolerance of configuration of errors use the smart
option.
*FvwmButtonsColumns columns
Specifies the number of columns of buttons to be
created. If unspecified, the number of columns will
be set to the number of buttons requested, divided
by the number of rows. If both the rows and columns
are specified, but do not specify as many buttons
as are defined, then the users columns specifica
tion will be ignored unless the value fixed was
gived to the BoxSize option (see there).
*FvwmButtonsFile filename
Specifies that the configuration for this button is
found in the file filename, which will have to be
given with full pathname, or is assumed to be in
fvwm's startup directory. The configuration file is
in the same format as fvwm's configuration file,
but each line is read as if prefixed by "*FvwmBut
tons". Comments are given by starting a line with
"#", line continuation is done by ending a line
with a "\".
*FvwmButtonsFont font
Specifies the font to be used for labeling the but
tons, or None.
*FvwmButtonsFore color
Specifies the color used for button label text and
monochrome icons.
*FvwmButtonsFrame width
Specifies the width of the relief around each but
ton. If this is given as a negative number, the
relief will at all times be the inverse of the nor
mal relief. In effect, you will get a sunken but
ton, which is raised when activated.
*FvwmButtonsGeometry geometry
Specifies the FvwmButtons window location. The size
should not be specified, as FvwmButtons automati
cally chooses a size which gracefully accomodates
all its buttons. The geometry is a standard X11
window geometry specification.
*FvwmButtonsPadding width height
The amount of free space between the relief of the
button and its contents is normally 2 pixels to the
sides and 4 pixels above and below, except for
swallowed windows and containers, which are not
padded at all, unless given specific orders. This
setting specifies the default horizontal padding to
be width pixels, and the vertical padding to be
height pixels.
*FvwmButtonsPanel title
Specifies the title of a panel. All following
*FvwmButtons configuration commands up to the next
*FvwmButtonsPanel line refer to the panel.
*FvwmButtonsPixmap pixmapfile
Specifies a background pixmap to use. Specify
"none" for a transparent background.
*FvwmButtonsRows rows
Specifies the number of rows of buttons to be cre
ated. If unspecified, 2 rows will be used.
*FvwmButtons(options) [title icon command]
Specifies the contents of a button in the button
box. The following options, separated by commas or
whitespace, can be given a button:
geometry
Specifies the size and position of the button
within the FvwmButtons window or container. The
button will be width times the normal button width
and height times the normal button height. If val
ues for x and y are given, the button is placed x
(y) button units from the left (top) of the con
tainer if x (y) is positive and x (y) units from
the right (bottom) if x (y) is negative. The geome
try is a standard X11 window geometry specifica
tion. Buttons with position arguments (x and y) are
placed before thos without them. If two or more
buttons are forced to overlap by this, FvwmButton
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 con
tains a comma or a closing parenthesis. The current
options are:
Mouse n - this action is only executed for mouse
button n. One actions can be defined for each
mouse button, in addition to the general action.
Back color
Specifies the background color to be used drawing
this box. A relief color and a shadow color will
also be calculated from this.
Center
The contents of the button is centered on the but
ton. This is the default but may be changed by Left
or Right.
Container [(options)]
Specifies that this button will contain a miniature
buttonbox, more or less equivalent to swallowing
another FvwmButtons module. The options are the
same as can be given for a single button, but they
affect all the contained buttons. Options available
for this use are Back, Font, Fore, Frame and
Padding. Flags for Title and Swallow options can be
set with Title(flags) and Swallow(flags). You
should also specify either "Columns width" or "Rows
height", or "Rows 2" will be assumed for purpose of
arranging the buttons inside the container. For an
example, see the Sample configuration section.
The container button itself (separate from the con
tents) can take format options like Frame and
Padding, and commands can be bound to it. This
means you can make a sensitive relief around a con
tainer, like
*FvwmButtons(2x2, Frame 5, Padding 2 2, Action
Beep,\
Container(Frame 1))
Typically you will want to at least give the con
tainer a size setting widthxheight.
End Specifies that no more buttons are defined for the
current container, and further buttons will be put
in the container's parent. This option should be
given on a line by itself, i.e
*FvwmButtons(End)
Font fontname
Specifies that the font fontname is to be used for
labeling this button.
Fore color
Specifies a color of the title and monochrome icons
in this button.
Frame width
The relief of the button will be width pixels wide.
If width is given as a negative number, the relief
will at all times be the inverse of the normal
relief. In effect, you will get a sunken button,
which is raised when activated.
Icon filename
The name of an X11 bitmap file or XPM color icon
file, containing the icon to display on the button.
FvwmButtons will search through the path specified
in the fvwm IconPath or PixmapPath configuration
items to find the icon file.
Left The contents of the button will be 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 calcula
tions of buttonsizes. Useful for the odd button
that gets just a couple of pixels to large to keep
in line, and therefor blows up your whole button
box. "NoSize" is equivalent to "Size 0 0".
Padding width height
The amount of free space between the relief of the
button and its contents is normally 2 pixels to the
sides and 4 pixels above and below, except for
swallowed windows and containers, which are by
default not padded at all. This option sets the
horizontal padding to width and the vertical
padding to height.
Panel [ (direction) ] name
Pop up a panel in the specified direction from the
invoking button. A position set with *FvwmButtons
Geometry is taken as a relative offset to this
position. direction may be "up" (the default),
"left", "down" od "right". The panel is a button
bar itself. See FvwmButtonsPanel. To get the panel
at a specific place on the screen use "geometry" in
place of the direction. The *FvwmButtonsGeometry
line will then be treated as a normal X geometry
specification.
Right
The contents of the button will be aligned to the
Right. The default is to center the contents on the
button.
Size width height
Specifies that the contents of this button will
require width by height pixels, regardless of what
size FvwmButtons calculates from the icon and the
title. A buttonbar with only swallowed windows will
not get very large without this option specified,
as FvwmButtons does not consider sizes for swallow
ing buttons. Note that this option gives the mini
mum space assured; other buttons might require the
buttonbox to use larger sizes.
Swallow [(flags)] hangon command
Causes FvwmButtons to execute command, and when a
window matching the name hangon appears, it is cap
tured and swallowed into this button. An example:
*FvwmButtons(Swallow XClock 'Exec xclock &')
will take the first window whose name, class or
resource is "XClock" and display it in the button.
Modules can be swallowed by specifying the module
instead of 'Exec whatever', like:
*FvwmButtons(Swallow "FvwmPager" "FvwmPager 0 0")
The flags that can be given to swallow are:
NoClose / Close - Specifies whether the swallowed
program in this button will be unswallowed or
closed when FvwmButtons exit cleanly. "NoClose" can
be combined with "UseOld" to have windows survive
restart of windowmanager. The default setting is
"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 pro
grams that doesn't accept window manager protocol.
The default value is "NoKill". This has no effect
if "NoClose" is specified.
NoRespawn / Respawn - Specifies whether the swal
lowed program is to be respawn if it dies. If
"Respawn" is specified, the program will be
respawned using the original command. Use this
option with care, the program might have a very
legitimate reason to die.
NoOld / UseOld - Specifies whether the button will
try to swallow an existing window matching the
hangon name before spawning one itself with com
mand. The default value is "NoOld". "UseOld" can
be combined with "NoKill" to have windows survive
restart of windowmanager. If you want FvwmButtons
to swallow an old window, and not spawn one itself
if failing, let the command be "Nop":
*FvwmButtons(Swallow (UseOld) "Console" Nop)
If you want to be able to start it yourself, com
bine it with an action:
*FvwmButtons(Swallow (UseOld) "Console" Nop, \
Action `Exec "Console" console &`)
NoTitle / UseTitle - Specifies whether the title of
the button will be taken from the swallowed win
dow's title or not. If "UseTitle" is given, the
title on the button will change dynamically to
reflect the window name. The default is "NoTitle".
Title [(options)] name
Specifies the title which will be written on the
button. Whitespace can be included in the title by
quoting it. If a title at any time is to long for
its buttons, characters are chopped of one at a
time until it fits. If justify is "Right", the
head is removed, otherwise its tail is removed.
These options can be given to Title:
Center - The title will be centered horizontally.
This is the default.
Left - The title will be justified to the left
side.
Right - The title will be justified to the right
side.
Side - This will cause the title to appear on the
right hand side of any icon or swallowed window,
instead of below it which is the default. If you
use small icons, and combine this with the "Left"
option, you can get a look similar to fvwm's menus.
Legacy fields [title icon command]
These fields are kept for compatibility with previ
ous versions of FvwmButtons, and their use is dis
couraged. The title field is similar to the option
Title name. If the title field is "-", no title
will be displayed. The icon field is similar to
the option Icon filename. If the icon field is "-"
no icon will be 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 FvwmButtons. See
fvwm(1) for more info on this. The Exec command has
a small extension when used in Actions, its syntax
is here:
Exec ["hangon"] command
When FvwmButtons finds such an Exec command, the
button will remain pushed in until a window whose
name or class matches the qouted portion of the
command is encountered. This is intended to provide
visual feedback to the user that the action he has
requested will be performed. If the qouted portion
contains no characters, then the button will pop
out immediately. Note that users can continue
pressing the button, and re-executing the command,
even when it looks "pressed in."
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 charac
ters; single quote:
'This is a "quote"',
double quote:
"It's another `quote'",
and backquote:
`This is a strange quote`.
The backquoting is purposeful if you use a prepro
cessor like FvwmCpp and want it to get into your
commands, like this:
#define BG gray60
*FvwmButtons(Swallow "xload" `Exec xload -bg BG
&`)
Furthermore a single character can be quoted with a
preceding backslash '´.
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 colums 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 ob 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 buttonsize they
get from this scheme. If a particular configuration
requires more space for a swallowed window, it can
be set in that button's configuration line using
the option "Size width height". This will tell
FvwmButtons to give this button at least width by
height pixels inside the relief and padding.
SAMPLE CONFIGURATION
The following are excepts from a .fvwmrc file which
describe FvwmButtons initialization commands:
##########################################################
# Load any modules which should be started during fvwm
# initialization
ModulePath /usr/lib/X11/fvwm:/usr/bin/X11
# Make sure FvwmButtons is always there.
AddToFunc InitFunction "I" Module FvwmButtons
AddToFunc RestartFunction "I" Module FvwmButtons
# Make it titlebar-less, sticky, and give it an icon
Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
# Make the menu/panel look like CDE
Style "FvwmButtonsPanel" Title, NoHandles, BorderWidth 0
Style "FvwmButtonsPanel" NoButton 2, NoButton 4, Sticky
##########################################################
*FvwmButtonsFore Black
*FvwmButtonsBack rgb:90/80/90
*FvwmButtonsGeometry -135-5
*FvwmButtonsRows 1
*FvwmButtonsBoxSize smart
*FvwmButtonsFont -*-helvetica-medium-r-*-*-12-*
*FvwmButtonsPadding 2 2
*FvwmButtons(Title WinOps,Panel WinOps)
*FvwmButtons(Title Tools ,Panel 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 &`)
The last lines are a little tricky - one spawns an Fvwm
Pager module, and captures it to display in a quadruple
width button. is used, the Pager will be as big as possi
ble within the button's relief.
The final line is even more magic. Note the combination of
UseOld and NoKill, which will try to swallow an existing
window with the name "xload15" when starting up (if fail
ing: starting one with the specified command), which is
unswallowed when ending FvwmButtons.
The other panels are specified after the root panel:
########## PANEL
*FvwmButtonsPanel WinOps
*FvwmButtonsBack bisque2
*FvwmButtonsGeometry -3-3
*FvwmButtonsColumns 1
*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 )
########## PANEL
*FvwmButtonsPanel Tools
*FvwmButtonsBack bisque2
*FvwmButtonsGeometry -1-1
*FvwmButtonsColumns 1
*FvwmButtons(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:
##########################################################
# Make it titlebar-less, sticky, and give it an icon
Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
*FvwmButtonsFont 5x7
*FvwmButtonsBack rgb:90/80/90
*FvwmButtonsFore black
*FvwmButtonsFrame 1
# 9x11 pixels per button, 4x4 pixels for the frame
*FvwmButtonsGeometry 580x59+0-0
*FvwmButtonsRows 5
*FvwmButtonsColumns 64
*FvwmButtonsBoxSize fixed
*FvwmButtonsPadding 1 1
# Menu Popups
*FvwmButtons(9x1+3+0, Padding 0, Title "Modules", \
Action `Menu Modulepopup mouse c -8p Nop`)
# 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-0 -padding 1 \
-analog -chime -bg rgb:90/80/90`)
*FvwmButtons(13x5, Left, Swallow (NoClose) \
"FvwmIconMan" 'Module FvwmIconMan')
*FvwmButtons(20x5, Padding 0, Swallow "xosview" \
`Exec /usr/X11R6/bin/xosview -cpu -int -page -net \
-geometry 100x50+0-0 -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 and Dominik Vogt.
Nov 1 1998 FvwmButtons(1)
Man(1) output converted with
man2html