Module FvwmButtons [-g geometry] [-transient | -transientpanel] [name[configfile]]
FvwmButtons can only be invoked by fvwm. Command line invocation of the FvwmButtons module will not work.
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.
The -g option specifies the geometry of the main window. The command line option takes precedence over any other geometry settings in the configuration file.
The -transient option tells FvwmButtons to terminate itself after the first key or button press has been received (presses to open a sub panel do not count) or a sub panel has been closed or respawned. This is especially useful for sub panels where you want to select a single button and have it closed automatically. It could be used to create two-dimensional graphical menus. Since -transient is an option, not a configuration setting you can use the same configuration for transient and non transient button bars.
The -transientpanel option does roughly the same as the -transient option, but instead of closing the whole button bar, the window is merely hidden. This is very useful if the button bar is started as a subpanel of another button bar because it avoids that it must be started again when something is selected.
FvwmButtons is spawned by fvwm, so command line invocation will not work.
FvwmButtons can be invoked by inserting the line 'Module FvwmButtons OptionalName' in the .fvwm2rc file. This should be placed in the StartFunction if FvwmButtons is to be spawned during fvwm's initialization. This can be bound to a menu or mouse button or keystroke to invoke it later.
When invoked with the OptionalName argument, the OptionalName is used to find configuration commands. For example:
AddToFunc StartFunction Module FvwmButtons MyButtonBoxFvwmButtons will then use only the lines starting with "*MyButtonBox", instead of the default "*FvwmButtons".
If fixed is used and both Rows and Columns are specified and non-zero, FvwmButtons uses exactly the number of rows and columns specified. If the box is too small to accommodate all buttons the module will fail.
If smart is used FvwmButtons enlarges the box so all buttons have a chance to fit. The number of columns is increased to at least the width of the widest button and new rows are added until all buttons are placed. For the best tolerance of configuration errors use the smart option.
dumb is neither fixed nor smart. This is the default.
The current options of the Action are: Mouse n - this action is only executed for mouse button n. One action can be defined for each mouse button, in addition to the general action.
In the command part, you can use a number of predefined variables: $left, $right, $top and $bottom are substituted by the left, right, top and bottom coordinates of the button pressed. $-left, $-right, $-top and $-bottom are substituted likewise, but the coordinates are calculated from the bottom or the right edge of the screen instead (for a button that is 5 pixels away from the right screen border, $-right will be 5). $width and $height are replaced by the width or height of the button. The variables $fg and $bg are replaced with the name of the foreground or background color set with the Back or Fore option (see below). All this is done regardless of any quoting characters. To get a literal '$' use the string '$$'.
Example:
*FvwmButtons: (Title xload, Action (Mouse 1) \
`Exec exec xload -fg $fg -bg $bg -geometry -3000-3000`)
Note: With fvwm versions prior to 2.5.0, actions could not be assigned to a button that swallowed an application window (see Swallow option). Such actions worked only when the border around the button was clicked. This is now possible, but to get back the old behavior, the ActionIgnoresClientWindow can be used on the button:
*FvwmButtons: (Action beep, ActionIgnoresClientWindow, \
Swallow xeyes "Exec exec xeyes")
In this example, the action is only executed when you click on the border of the button or the transparent part of the xeyes window, but not on the xeyes window itself.
If the swallowed window is an fvwm module (see the (No)FvwmModule option to Swallow), then the colorset is not applied to the swallowed module. You should use the colorset in the module configuration. If the swallowed module has a transparent colorset background, then the FvwmButtons background (and not the button colorset) is seen by transparency of the background of the swallowed module. Refer to the man page of the FvwmTheme module for details about colorsets.
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.
*FvwmButtons: (End)
The steps animation-steps option defines the number of animation steps.
The delay ms option sets the delay between the steps of the animation in milliseconds. Use zero for no delay. The maximum delay is 10 seconds (10000). It doesn't make any sense to use the delay option unless you also use the smooth option.
The smooth option causes the panel to redraw between the steps of the animation. The sliding animation may be smoother this way, it depends on the application, and display speed. The application may appear to grow instead of sliding out. The animation may be slower.
The Hints option causes FvwmButtons to use the applications size hints to calculate the size of the animation steps. Hints is the default. If the number of steps is not what you want, try using NoHints.
The noborder option tells FvwmButtons to ignore the borders of the window when calculating positions for the animation (equivalent to set noplr and noptb in the position option).
With the indicator option set, FvwmButtons will draw a small triangle in the button that will open a panel. The triangle points in the direction where the panel will pop up. The indicator keyword may be followed by a positive integer that specifies the maximum width and height of the indicator. Without this size FvwmButtons will make the indicator fit the button. You will probably want to use the Padding option to leave a few pixels between the indicator and the frame of the button.
The position option allows to place the panel. The syntax is:
position [context-window] [pos] [x y] [border-opts]The argument context-window can be one of: Button, Module or Root. The context-window is the window from which panel percentage offsets are calculated. Button specifies the panel's button, Module specifies FvwmButtons itself, and Root specifies a virtual screen. The context-window together with the sliding direction define a line segment which is one of the borders of the context-window: the top/bottom/left/right border for sliding up/down/left/right.
The pos argument can be one of: center, left or right (for sliding up or a down) or top or bottom (for sliding left or right). It defines the vertical (sliding up and down) or the horizontal (sliding left and right) position of the Panel on the line segment. For example, for a sliding up if you use a left pos, then the left borders of the panel and of the context-window will be aligned.
The offset values x and y specify how far the panel is moved from it's default position. By default, the numeric value given is interpreted as a percentage of the context window's width (height). A trailing "p" changes the interpretation to mean "pixels". All offset calculations are relative to the buttons location, even when using a root context.
The border-opts are: mlr, mtb, noplr and noptb. They define which border widths are taken in account. By default, the borders of FvwmButtons are not taken in account. mlr reverses this default for the left and the right border and mtb reverses this default for the top and the bottom border. Conversely, by default the borders of the Panel are taken in account. noplr reverses this default for the left and the right border and noptb reverses this default for the top and the bottom border.
The defaults are sliding up with a delay of five milliseconds and twelve animation steps. To post the panel without any animation, set the number of steps to zero. The default position is 'Button center'.
Please refer to the CREATING PANELS section for further information on panels.
Example:
# To include the panel in a button
*FvwmButtons: (Panel(down, delay 0, steps 16) \
SubPanel "Module FvwmButtons SubPanel")
# To define the panel as an instance of
# FvwmButtons with a different name:
*SubPanel: (Icon my_lock.xpm, Action Exec xlock)
*SubPanel: (Icon my_move.xpm, Action Move)
...
*FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')takes the first window whose name, class, or resource is "XClock" and displays it in the button. If no matching window is found, the "Exec" command creates one. The argument "-geometry -3000-3000" is used so that the window is first drawn out of sight before its swallowed into FvwmButtons.
Modules can be swallowed by specifying the module instead of 'Exec whatever', like:
*FvwmButtons: (Swallow "FvwmPager" "FvwmPager 0 0")The flags that can be given to swallow are:
NoClose / Close - Specifies whether the swallowed program in this button will be un-swallowed or closed when FvwmButtons exits cleanly. "NoClose" can be combined with "UseOld" to have windows survive a restart of the window manager. The default setting is "Close".
NoHints / Hints - Specifies whether hints from the swallowed program in this button will be ignored or not, useful in forcing a window to resize itself to fit its button. The default value is "Hints".
NoKill / Kill - Specifies whether the swallowed program will be closed by killing it or by sending a message to it. This can be useful in ending programs that doesn't accept window manager protocol. The default value is "NoKill". This has no effect if "NoClose" is specified.
NoRespawn / Respawn / SwallowNew - Specifies whether the swallowed program is to be respawned (restarted) if it dies. If "Respawn" is specified, the program is respawned using the original command. Use this option with care, the program might have a legitimate reason to die. If "SwallowNew" is given, the program is not respawned, but if a new window with the specified name appears, it is swallowed.
NoOld / UseOld - Specifies whether the button will try to swallow an existing window matching the hangon name before spawning one itself with command. The hangon string may contain wildcard characters ('*') that match any substring.The default value is "NoOld". "UseOld" can be combined with "NoKill" to have windows survive a restart of the window manager. If you want FvwmButtons to swallow an old window, and not spawn one itself if failing, let the command be "Nop":
*FvwmButtons: (Swallow (UseOld) "Console" Nop)If you want to be able to start it yourself, combine it with an action:
*FvwmButtons: (Swallow (UseOld) "Console" Nop, \
Action `Exec "Console" console &`)
NoTitle / UseTitle -
Specifies whether the title of the button will be taken from the
swallowed window's title or not. If "UseTitle" is given, the title
on the button changes dynamically to reflect the window name. The
default is "NoTitle".
NoFvwmModule / FvwmModule - By default, FvwmButtons treats the swallowed window as an fvwm module window if the 4 first letters of the command is "Fvwm" or the 6 first letters of the command is "Module". NoFvwmModule and FvwmModule override this logic.
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.
The Exec command has a small extension when used in Actions, its syntax is:
Exec ["hangon"] commandExample:
*FvwmButtons: (Action Exec "xload" xload)The hangon string must be enclosed in double quotes. When FvwmButtons finds such an Exec command, the button remains pushed in until a window whose name, class or resource matches the quoted portion of the command is encountered. This is intended to provide visual feedback to the user that the action he has requested will be performed. The hangon string may contain wildcard characters ('*') that match any substring. If the quoted portion contains no characters, then the button will pop out immediately. Note that users can continue pressing the button, and re-executing the command, even when it looks pressed in.
'This is a "quote"',
double quote:
"It's another `quote'",
and back quote:
`This is a strange quote`.
The back quoting is unusual but used on purpose, if you use a preprocessor like FvwmCpp and want it to get into your commands, like this:
#define BG gray60 *FvwmButtons: (Swallow "xload" `Exec xload -bg BG &`)Any single character can be quoted with a preceding backslash '\'.
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.
Any program that can be launched from within fvwm and that has a window can be used as a panel. A terminal window could be your panel, or some application like xload or xosview or another fvwm module, including FvwmButtons itself. All you need to know is how to start your application from fvwm.
The button that invokes the panel is as easily configured as any other button. Essentially you need nothing more than the Panel option:
*FvwmButtons: (Panel my_first_panel \ "Module FvwmButtons -g -30000-30000 my_first_panel") *FvwmButtons: (Panel my_second_panel \ "Exec exec xterm -g -30000-30000 -n my_second_panel")
This works like the Swallow option. The difference is that the application is not put into the button when it starts up but instead hidden from view. When you press the button for the panel the window slides into view. The '-g -30000-30000' option tells the application that it should be created somewhere very far to the top and left of your visible screen. Otherwise you would see it flashing for a moment when FvwmButtons starts up. Some applications do not work well with this kind of syntax so you may have to live with the short flashing of the window. If you want to make a panel from another instance of FvwmButtons you can do so, but you must give it a different name ('my_first_panel' in above example). If you run FvwmButtons under the same name, new panels are created recursively until your system runs out of resources and FvwmButtons crashes! To configure a second button bar with a different name, simply put '*new_name' in place of 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 the panel window should have no icon in case it is iconified.
Style name_of_panel_window NoTitle, Sitcky, NoIcon
You may want your panel to stay open only until you select something in it. You can give FvwmButtons the -transientpanel option after the -g option in the command. FvwmPager has a similar option '-transient'.
Last, but not least, you can now put an icon, a title or a small arrow in the button so that you can see what it is for. A title or icon can be specified as usual. To activate the arrow, just add 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.
This section describes how to convert a pretty old syntax used in 2.2.x versions. You may skip it if your syntax is more recent.
With the old panel feature you first had one or more lines defining panels in your main FvwmButtons configuration:
*FvwmButtons(Title WinOps,Panel WinOps) *FvwmButtons(Title Tools ,Panel Tools)
After the last configuration line for the main panel the configuration of the first panel followed, introduced with a line beginning with *FvwmButtonsPanel:
*FvwmButtonsPanel WinOps *FvwmButtonsBack bisque2 *FvwmButtonsPanel Tools *FvwmButtonsBack bisque2
And perhaps you had style commands for you panels:
Style FvwmButtonsPanel Title, NoHandles, BorderWidth 0 Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky
The new configuration looks much the same, but now the configuration of the main panel is independent of the configuration of the sub panels. The lines invoking the panels use the same syntax as the Swallow option, so you simply add the name of the window to use as a panel and the command to execute instead of the panel name. Note that you give the new instance of FvwmButtons a different name.
*FvwmButtons: (Title WinOps, Panel WinOps \ "Module FvwmButtons WinOps") *FvwmButtons: (Title Tools , Panel Tools \ "Module FvwmButtons Tools")
If you used something like 'Panel-d' you now have to use nel(down)' instead. button was selected start FvwmButtons with the '-transientpanel' option:
*FvwmButtons: (Title Tools , Panel(down) Tools \ "Module FvwmButtons -transientpanel Tools")
The rest of the configuration is very easy to change. Delete the lines '*FvwmButtonsPanel <name>' and add <name> to all of the following configuration lines for the panel instead. Use the same name in your Style commands:
*WinOps: Back bisque2 *Tools: Back bisque2 Style "WinOps" Title, NoHandles, BorderWidth 0 Style "WinOps" NoButton 2, NoButton 4, Sticky Style "Tools" Title, NoHandles, BorderWidth 0 Style "Tools" NoButton 2, NoButton 4, Sticky
That's it. The new panels are much more flexible. Please refer to other parts of this documentation for details.
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.
FvwmButtons tries to arrange its buttons as best it can, by using recursively, on each container including the buttonbox itself, the following algorithm.
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 | +---+---+---+ +---+---+---+ +---+---+---+
SendToModule FvwmButtons-Alias <action> <params>Supported actions:
*FvwmButtons: (Id note1, Title "13:30 - Dinner", Icon clock1.xpm) SendToModule FvwmButtons Silent \ ChangeButton note1 Icon clock2.xpm, Title "18:00 - Go Home"
##########################################################
# Load any modules which should be started during fvwm
# initialization
# Make sure FvwmButtons is always there.
AddToFunc StartFunction "I" Module FvwmButtons
# Make it titlebar-less, sticky, and give it an icon
Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky
# Make the menu/panel look like CDE
Style "WinOps" Title, NoHandles, BorderWidth 0
Style "WinOps" NoButton 2, NoButton 4, Sticky
Style "Tools" Title, NoHandles, BorderWidth 0
Style "Tools" NoButton 2, NoButton 4, Sticky
##########################################################
DestroyModuleConfig FvwmButtons: *
*FvwmButtons: Fore Black
*FvwmButtons: Back rgb:90/80/90
*FvwmButtons: Geometry -135-5
*FvwmButtons: Rows 1
*FvwmButtons: BoxSize smart
*FvwmButtons: Font -*-helvetica-medium-r-*-*-12-*
*FvwmButtons: Padding 2 2
*FvwmButtons: (Title WinOps, Panel WinOps \
"Module FvwmButtons -transientpanel WinOps")
*FvwmButtons: (Title Tools, Panel Tools \
"Module FvwmButtons -transientpanel Tools")
*FvwmButtons: (Title Resize, Icon resize.xpm, Action Resize)
*FvwmButtons: (Title Move, Icon arrows2.xpm, Action Move )
*FvwmButtons: (Title Lower, Icon Down, Action Lower )
*FvwmButtons: (Title Raise, Icon Up, Action Raise )
*FvwmButtons: (Title Kill, Icon bomb.xpm, Action Destroy)
*FvwmButtons: (1x1,Container(Rows 3,Frame 1))
*FvwmButtons: (Title Dopey ,Action \
`Exec "big_win" xterm -T big_win -geometry 80x50 &`)
*FvwmButtons: (Title Snoopy, Font fixed, Action \
`Exec "small_win" xterm -T small_win &`)
*FvwmButtons: (Title Smokin')
*FvwmButtons: (End)
*FvwmButtons: (Title Xcalc, Icon rcalc.xpm, \
Action `Exec "Calculator" xcalc &`)
*FvwmButtons: (Title XMag, Icon magnifying_glass2.xpm, \
Action `Exec "xmag" xmag &`)
*FvwmButtons: (Title Mail, Icon mail2.xpm, \
Action `Exec "xmh" xmh &`)
*FvwmButtons: (4x1, Swallow "FvwmPager" `FvwmPager 0 3` \
Frame 3)
*FvwmButtons: (Swallow(UseOld,NoKill) "xload15" `Exec xload \
-title xload15 -nolabel -bg rgb:90/80/90 -update 15 \
-geometry -3000-3000 &`)
The last lines are a little tricky - one spawns an FvwmPager module, and captures it to display in a quadruple width button. is used, the Pager will be as big as possible within the button's relief.
The final line is even more magic. Note the combination of UseOld and NoKill, which will try to swallow an existing window with the name "xload15" when starting up (if failing: starting one with the specified command), which is un-swallowed when ending FvwmButtons. The swallowed application is started with "-geometry -3000-3000" so that it will not be visible until its swallowed.
The other panels are specified after the root panel:
########## PANEL WinOps DestroyModuleConfig WinOps: * *WinOps: Back bisque2 *WinOps: Geometry -3-3 *WinOps: Columns 1 *WinOps: (Title Resize, Icon resize.xpm, Action Resize) *WinOps: (Title Move, Icon arrows2.xpm, Action Move ) *WinOps: (Title Lower, Icon Down, Action Lower ) *WinOps: (Title Raise, Icon Up, Action Raise ) ########## PANEL Tools DestroyModuleConfig Tools: * *Tools: Back bisque2 *Tools: Geometry -1-1 *Tools: Columns 1 *Tools: (Title Kill, Icon bomb.xpm, Action Destroy)
The color specification rgb:90/80/90 is actually the most correct way of specifying independent colors in X, and should be used instead of the older #908090. If the latter specification is used in your configuration file, you should be sure to escape the hash in any of the commands which will be executed, or fvwm will consider the rest of the line a comment.
Note that with the x/y geometry specs you can easily build button windows with gaps. Here is another example. You can not accomplish this without geometry specs for the buttons:
########################################################## # Another example ########################################################## # Make it titlebar-less, sticky, and give it an icon Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky DestroyModuleConfig FvwmButtons: * *FvwmButtons: Font 5x7 *FvwmButtons: Back rgb:90/80/90 *FvwmButtons: Fore black *FvwmButtons: Frame 1 # 9x11 pixels per button, 4x4 pixels for the frame *FvwmButtons: Geometry 580x59+0-0 *FvwmButtons: Rows 5 *FvwmButtons: Columns 64 *FvwmButtons: BoxSize fixed *FvwmButtons: Padding 1 1 # Pop up a module menu directly above the button. *FvwmButtons: (9x1+3+0, Padding 0, Title "Modules", \ Action `Menu Modulepopup rectangle \ $widthx$height+$lleft+$top o+50 -100m`) # first row of buttons from left to right: *FvwmButtons: (3x2+0+1, Icon my_lock.xpm, Action `Exec xlock`) *FvwmButtons: (3x2+3+1, Icon my_recapture.xpm, Action Recapture) *FvwmButtons: (3x2+6+1, Icon my_resize.xpm, Action Resize) *FvwmButtons: (3x2+9+1, Icon my_move.xpm, Action Move) *FvwmButtons: (3x2+12+1, Icon my_fvwmconsole.xpm, \ Action 'Module FvwmConsole') # second row of buttons from left to right: *FvwmButtons: (3x2+0+3, Icon my_exit.xpm, Action QuitSave) *FvwmButtons: (3x2+3+3, Icon my_restart.xpm, Action Restart) *FvwmButtons: (3x2+6+3, Icon my_kill.xpm, Action Destroy) *FvwmButtons: (3x2+9+3, Icon my_shell.xpm, Action 'Exec rxvt') # big items *FvwmButtons: (10x5, Swallow (NoKill, NoCLose) \ "FvwmPager" 'FvwmPager * * -geometry 40x40-1024-1024') *FvwmButtons: (6x5, Swallow "FvwmXclock" `Exec xclock \ -name FvwmXclock -geometry 40x40+0-3000 -padding 1 \ -analog -chime -bg rgb:90/80/90`) *FvwmButtons: (13x5, Swallow (NoClose) \ "FvwmIconMan" 'Module FvwmIconMan') *FvwmButtons: (20x5, Padding 0, Swallow "xosview" \ `Exec /usr/X11R6/bin/xosview -cpu -int -page -net \ -geometry 100x50+0-3000 -font 5x7`)
The action part of the Swallow option must be quoted if it contains any whitespace character.
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.