FVWMBUTTONS(1)

📦
version 1.1.5 · 5 versions
, in ubuntu stonking

💖 FVWMBUTTONS(1) — fvwm modules era 💖

okay bestie, gather round, because this is the module that gives your fvwm a whole lil button box and honestly? it's giving main character energy. the manual name is FVWMBUTTONS(1), it lives in the Fvwm Modules section, and yes we are reading the whole thing together, no skimming, no cap. 🎀

✨ NAME ✨

FvwmButtons — the fvwm buttonbox module. that's it, that's the vibe.

🌸 SYNOPSIS 🌸

Module FvwmButtons [-g geometry] [-transient | -transientpanel]
[name[configfile]]
🚨 real talk: FvwmButtons can only be invoked by fvwm. if you try to launch it straight from the command line it will simply not work. not me finding that out the hard way 😭

🦋 DESCRIPTION 🦋

okay so here's the tea. FvwmButtons gives you a lil window full of buttons that sits on the X terminal's root window. you can smash those buttons literally whenever, and each one can trigger a command you chose, run by the window manager. and ngl? it only works when fvwm is your window manager. that's the whole relationship. 💜

the buttonbox can be any configuration or geometry you want, and it can have monochrome or color icons to represent the actions it'll invoke. oh and other applications can even be 'swallowed' by the button bar (yes, swallowed, we'll get to that, it's iconic).

panels that open when you press a button? also available, we love a nested moment. see the CREATING PANELS section for the details. ✨

💅 OPTIONS 💅

  • -g — sets the geometry of the main window. this command line option takes precedence over any other geometry settings in the configuration file, so if something looks off, check here first bestie.
  • -transient — tells FvwmButtons to terminate itself after the first key or button press lands (presses that open a sub panel don't count) or after a sub panel has been closed or respawned. this is especially useful for sub panels where you wanna pick one single button and have it just close itself automatically. it could be used to make two-dimensional graphical menus. and since -transient is an option and not a configuration setting, you can use the same config for transient and non-transient button bars. versatility, periodt.
  • -transientpanel — does roughly the same as -transient, except instead of closing the whole button bar, the window is merely hidden. super useful if the button bar is started as a subpanel of another button bar, because it avoids having to start it all over again every time you select something. 🫶

🌈 INVOCATION 🌈

FvwmButtons is spawned by fvwm, so command line invocation will not work. (yes we said it twice, it's important, iykyk.)

to bring it to life, insert this line in the .fvwm2rc file:

Module FvwmButtons OptionalName

this should be placed in the StartFunction if FvwmButtons is to be spawned during fvwm's initialization. and you can bind it to a menu or mouse button or keystroke to invoke it later too — options, we love options. 💖

when you invoke it with the OptionalName argument, that OptionalName is used to find configuration commands. for example:

AddToFunc StartFunction Module FvwmButtons MyButtonBox

FvwmButtons will then use only the lines starting with *MyButtonBox, instead of the default *FvwmButtons. cute, right? ✨

👑 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. it's giving matched set. 🎀
  • *FvwmButtons: BoxSize algorithm — this option specifies how serious FvwmButtons takes the Rows and Columns options (see below). it can be one of dumb, fixed or smart.

if fixed is used and both Rows and Columns are specified and non-zero, FvwmButtons uses exactly the number of rows and columns specified. if the box is too small to accommodate all buttons the module will fail. 😭

if smart is used, FvwmButtons enlarges the box so all buttons have a chance to fit. the number of columns is increased to at least the width of the widest button and new rows are added until all buttons are placed. for the best tolerance of configuration errors use the smart option. she's forgiving, she's understanding. 💜

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 fvwm man page for details about colorsets.
  • *FvwmButtons: ActiveColorset colorset — tells the module to use colorset colorset for the background color/image and/or title color of a button when the mouse is hovering above a button. hover glow up ✨
  • *FvwmButtons: PressColorset colorset — tells the module to use colorset colorset for the background color/image and/or title color of a button when it is pressed. tactile feedback but make it fashion 💅
  • *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. math is math, bestie.
  • *FvwmButtons: File filename — specifies that the configuration for this button is found in the file filename. Filename can be a full pathname, or is assumed to be in fvwm's startup directory. the configuration file is in the same format as fvwm's configuration file, but each line is read as if prefixed by *FvwmButtons. comments are given by starting a line with #. line continuation is done by ending a line with a \.
  • *FvwmButtons: Font font — specifies the font to be used for labeling the buttons, or None.
  • *FvwmButtons: Fore color — specifies the color used for button label text and monochrome icons.
  • *FvwmButtons: Frame width — specifies the width of the relief around each button. if this is a negative number, the relief is inverted. this makes the button sunken normally and raised when activated. upside-down behaviour, obsessed. 🙈
  • *FvwmButtons: Geometry geometry — specifies the FvwmButtons window location and size. the geometry is a standard X11 window geometry specification.
  • *FvwmButtons: ButtonGeometry geometry — this option works like the Geometry option except that the size is the size of a single button. the size of the whole FvwmButtons window is calculated by multiplying the button dimension by the number of rows and columns.
  • *FvwmButtons: Padding width height — this option specifies the default horizontal padding to be width pixels, and the vertical padding to be height pixels. the amount of free space between the relief of the button and its contents is normally 2 pixels on the sides and 4 pixels above and below, except for swallowed windows and containers, which are not padded at all, unless this option is used. personal space, respected. 🫶
  • *FvwmButtons: Pixmap pixmapfile — specifies a background pixmap to use. specify "none" (without the double quotes) for a transparent background. transparent era 🦋
  • *FvwmButtons: Rows rows — specifies the number of rows of buttons to be created. the default is 2 rows.
  • *FvwmButtons: WindowName name — if FvwmButtons has a titlebar enabled with Title style, (for example, some transient subpanel), this option can set it's Window name and Icon name to a string provided with this parameter. if omitted, default for Window and Icon name is the window resource name which itself is simply "FvwmButtons", or is derived from the alias by which FvwmButtons configuration is referenced. this enables setting a title with spaces and larger number of non-ASCII characters which is not allowed as an alias for FvwmButtons module instance otherwise. cute title with a space in it? we love to see it. 😌
  • *FvwmButtons: (options) [title icon command] — specifies the contents of a button in the buttonbox. the following options, separated by commas or whitespace, can be given a button:
    • geometry — specifies the size and position of the button within the FvwmButtons window or container. the geometry is a standard X11 window geometry specification. the button is width times the normal button width and height times the normal button height. if values for x and y are given, the button is placed x (y) button units from the left (top) of the container if x (y) is positive and x (y) units from the right (bottom) if x (y) is negative. buttons with position arguments (x and y) are placed before those without them. if two or more buttons are forced to overlap by this, FvwmButtons exits with an error message. 💀 no overlap allowed, this is a no-contact sport.
    • Action [(options)] command — specifies an fvwm command to be executed when the button is activated by pressing return or a mouse button. the command needs to be quoted if it contains a comma or a closing parenthesis.

the current options of the Action are: Mouse n — this action is only executed for mouse button n. one action can be defined for each mouse button, in addition to the general action.

in the command part, you can use a number of predefined variables: $left, $right, $top and $bottom are substituted by the left, right, top and bottom coordinates of the button pressed. $-left, $-right, $-top and $-bottom are substituted likewise, but the coordinates are calculated from the bottom or the right edge of the screen instead (for a button that is 5 pixels away from the right screen border, $-right will be 5). $width and $height are replaced by the width or height of the button. the variables $fg and $bg are replaced with the name of the foreground or background color set with the Back or Fore option (see below). all this is done regardless of any quoting characters. to get a literal '$' use the string '$$'.

example:

*FvwmButtons: (Title xload, Action (Mouse 1) \
  `Exec exec xload -fg $fg -bg $bg -geometry -3000-3000`)
note: with fvwm versions prior to 2.5.0, actions could not be assigned to a button that swallowed an application window (see Swallow option). such actions worked only when the border around the button was clicked. this is now possible, but to get back the old behavior, the ActionIgnoresClientWindow can be used on the button: 🕰️
*FvwmButtons: (Action beep, ActionIgnoresClientWindow, \
   Swallow xeyes "Exec exec xeyes")

in this example, the action is only executed when you click on the border of the button or the transparent part of the xeyes window, but not on the xeyes window itself. sneaky but make it intentional ✨

  • ActionIgnoresClientWindow — see the note in the description of Action above. ⬆️
  • ActionOnPress — usually the action is executed on the button release except for the Popup action. this option changes this behavior, the action is executed on the button press. this may be good, for example, with Menu or SendToModule that generates popups, or when Frame is 0 and the button would look unresponsive otherwise. instant reaction, main character reflexes 🔥

(bestie this page is long and there is SO much more coming — panels, swallowing, the whole extended universe. stay with me, part 2 is on the way 💖)

  • Back color — okay bestie, this sets the background color used to draw this box 💖. A relief color and a shadow color are calculated from this. Iconic.
  • Center — the contents of the button are centered on the button. This is the default, but it may be changed by Left or Right. Periodt.
  • Top — the contents of the button are vertically aligned at the top of the button. The default is to vertically center it. Slay.
  • Colorset colorset — the given colorset can be applied to a container, a swallowed application, and a simple button. To apply it to a button or container, simply put the option in a line with a button or container description. Drawing backgrounds for individual buttons and containers with colorsets requires a lot of communication with the X server. So if you are not content with the drawing speed of dozens of buttons with colorset backgrounds, do not use colorsets here. Setting colorsets as the background of swallowed applications does not have this restriction but depends entirely on the swallowed application. It may work as you wish, but since it involves fiddling with other applications' windows there is no guarantee for anything. I have tested three applications: xosview works nicely with a colorset background, xload works only with a VGradient or solid background, and an analog xclock leaves a trail painted in the background color after its hands.

If the swallowed window is an fvwm module (see the (No)FvwmModule option to Swallow), then the colorset is not applied to the swallowed module. You should use the colorset in the module configuration. If the swallowed module has a transparent colorset background, then the FvwmButtons background (and not the button colorset) is seen by transparency of the background of the swallowed module. Refer to the fvwm man page for details about colorsets. 🫶

  • ActiveColorset colorset — use colorset colorset for the background color/image and/or title color of the button when the mouse is hovering above it. Hover glow-up fr fr.
  • PressColorset colorset — use colorset colorset for the background color/image and/or title color of the button when it is pressed. The press moment gets its own little fit 💅.
  • Container [(options)] — this specifies that this button will contain a miniature buttonbox, equivalent to swallowing another FvwmButtons module. The options are the same as can be given for a single button, but they affect all the contained buttons. Options available for this use are Back, Font, Fore, Frame and Padding. Flags for Title and Swallow options can be set with Title(flags) and Swallow(flags). You should also specify either "Columns width" or "Rows height", or "Rows 2" will be assumed. For an example, see the Sample configuration section.

The container button itself (separate from the contents) can take format options like Frame and Padding, and commands can be bound to it. This means you can make a sensitive relief around a container, like

*FvwmButtons: (2x2, Frame 5, Padding 2 2, Action Beep,\
                         Container(Frame 1))

Typically you will want to at least give the container a size setting widthx_height_.

  • End — specifies that no more buttons are defined for the current container, and further buttons will be put in the container's parent. This option should be given on a line by itself, i.e.
*FvwmButtons: (End)
  • Font fontname — specifies that the font fontname is to be used for labeling this button.
  • Fore color — specifies the foreground color of the title and monochrome icons in this button.
  • Frame width — the relief of the button will be width pixels wide. If width is given as a negative number, the relief is inverted. This makes the button sunken normally and raised when activated. Sneaky little 3D flip.
  • Icon filename — the name of an image file containing the icon to display on the button. FvwmButtons searches through the path specified in the fvwm ImagePath configuration item to find the icon file.
  • ActiveIcon filename — the name of an image file containing an alternative icon to display on the button when the mouse is hovering above the button. If no ActiveIcon is specified, the image specified by Icon is displayed (if there is one). Hover makeover ✨.
  • PressIcon filename — the name of an image file containing an alternative icon to display on the button when the button is pressed. If no PressIcon is specified, the image specified by Icon is displayed (if there is one). Pressed and cute.
  • Id id — the id to be used to identify this button. The first character of the id should be alphabetic. See also the "DYNAMICAL ACTIONS" section.
  • Left — the contents of the button are aligned to the left. The default is to center the contents on the button.
  • NoSize — this option specifies that this button will not be considered at all when making the initial calculations of button sizes. Useful for the odd button that gets just a couple of pixels too large to keep in line, and therefore blows up your whole buttonbox. "NoSize" is equivalent to "Size 0 0". Not me letting one tiny button ruin the whole grid 😭.
  • Padding width height — the amount of free space between the relief of the button and its contents is normally 2 pixels to the sides and 4 pixels above and below, except for swallowed windows and containers, which are by default not padded at all. This option sets the horizontal padding to width and the vertical padding to height.
  • Panel [ (options) ] hangon command — panels can be swallowed exactly like windows are swallowed by buttons with the Swallow command below, but they are not displayed within the button. Instead they are hidden until the user presses the panel's button. Then the panel (the window of the swallowed application) opens with a sliding animation. The options can be any of the flags described for the Swallow command. In addition a direction 'left', 'right', 'up' or 'down' can be used to specify the sliding direction. Main character entrance, honestly.
    • 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 application's 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. Second option to indicator may be given which enters the look of the triangle. If this keyword is in, triangle will appear pressed in, while out will make triangle to appear depressed (3D raised). If this keyword is omitted, default will be out or depressed.
    • The position option allows one to place the panel. The syntax is:

position [context-window] [pos] [x y] [border-opts]

The argument context-window can be one of: Button, Module or Root. The context-window is the window from which panel percentage offsets are calculated. Button specifies the panel's button, Module specifies FvwmButtons itself, and Root specifies a virtual screen. The context-window together with the sliding direction define a line segment which is one of the borders of the context-window: the top/bottom/left/right border for sliding up/down/left/right.

The pos argument can be one of: center, left or right (for sliding up or a down) or top or bottom (for sliding left or right). It defines the vertical (sliding up and down) or the horizontal (sliding left and right) position of the Panel on the line segment. For example, for a sliding up if you use a left pos, then the left borders of the panel and of the context-window will be aligned.

The offset values x and y specify how far the panel is moved from it's default position. By default, the numeric value given is interpreted as a percentage of the context window's width (height). A trailing "p" changes the interpretation to mean "pixels". All offset calculations are relative to the buttons location, even when using a root context.

The border-opts are: mlr, mtb, noplr and noptb. They define which border widths are taken in account. By default, the borders of FvwmButtons are not taken in account. mlr reverses this default for the left and the right border and mtb reverses this default for the top and the bottom border. Conversely, by default the borders of the Panel are taken in account. noplr reverses this default for the left and the right border and noptb reverses this default for the top and the bottom border.

...The defaults are sliding up with a delay of five milliseconds and twelve animation steps. ✨ Wanna post the panel with zero animation? Set the number of steps to zero, bestie, it just snaps up. And the default position is 'Button center'.

If you want the whole deep dive on panels, slide over to the CREATING PANELS section 💅

Example, because a vibe needs a demo:

# 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 — shoves the contents of the button all the way to the right side. If you don't say this, the default is centering the contents on the button. no notes, she's centered by default 🎀
  • Size width height — says "bestie, this button needs exactly width by height pixels", no matter what size FvwmButtons would've cooked up from the icon and title. Real talk though: a button bar with only swallowed windows stays teeny tiny unless you specify this, because FvwmButtons straight up does not consider sizes for swallowing buttons. Also note that this option gives the minimum space assured — other buttons might make the whole buttonbox go bigger. minimum, not maximum, iykyk 🦋
  • Swallow [(flags)] hangon command — makes FvwmButtons run command, and the moment a window shows up with a name, class or resource that matches hangon, it gets captured and swallowed right into this button 🫶 The hangon string can contain wildcard characters ('*') that match any substring. Swallow replaces the $fg and $bg variables just like described above for the Action option — but heads up, if you use the UseOld and NoClose options then the app isn't restarted when FvwmButtons restarts, so it doesn't get the new colors (assuming you changed them, main character behavior). Example:
*FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')

This grabs the first window whose name, class, or resource is "XClock" and displays it in the button. If no matching window exists, that Exec command makes one. The argument -geometry -3000-3000 is there so the window first draws way off-screen before it gets swallowed into FvwmButtons. iconic, honestly.

Modules can get swallowed too — you just specify the module instead of 'Exec whatever', like:

*FvwmButtons: (Swallow "FvwmPager" "FvwmPager 0 0")

The flags you can hand to Swallow are:

  • NoClose / Close — controls whether the swallowed program sitting in this button gets un-swallowed or closed when FvwmButtons exits cleanly. NoClose can be combined with UseOld so your windows survive a restart of the window manager 😌 (yes, the whole point). Default setting is Close.
  • NoHints / Hints — says whether the hints coming from the swallowed program get ignored or not. Super handy for forcing a window to resize itself to fit its button. Default value is Hints.
  • NoKill / Kill — decides whether the swallowed program gets closed by killing it or by sending it a message. Great for ending programs that don't accept window manager protocol. Default value is NoKill. Zero effect if NoClose is specified, btw.
  • NoRespawn / Respawn / SwallowNew — says whether the swallowed program gets respawned (restarted) if it dies. With Respawn, it's respawned using the original command. ⚠️ Use this option with care — the program might have a perfectly legitimate reason to die, bestie. If SwallowNew is given instead, the program is not respawned, but if a new window with the specified name appears, it gets swallowed. 💀
  • NoOld / UseOld — controls whether the button tries 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. Default value is NoOld. You can combine UseOld with NoKill to have windows survive a window manager restart. If you want FvwmButtons to swallow an old window and just not spawn one itself if that fails, let the command be Nop:
*FvwmButtons: (Swallow (UseOld) "Console" Nop)

And if you want to be able to start it yourself, pair it with an action:

*FvwmButtons: (Swallow (UseOld) "Console" Nop, \
             Action `Exec "Console" console &`)
  • NoTitle / UseTitle — picks whether the button's title comes from the swallowed window's title or not. With UseTitle, the title on the button changes dynamically to reflect the window name ✨ (living title, we love to see it). Default is NoTitle.
  • NoFvwmModule / FvwmModule — so by default, FvwmButtons treats a swallowed window as an fvwm module window if the first 4 letters of the command are Fvwm or the first 6 letters are Module. NoFvwmModule and FvwmModule override that logic entirely. 🧚
  • Title [(options)] name — sets the title to be written on the button. Got whitespace in it? Quote it. And if a title is ever too long for its button at any point, characters get chopped off one at a time until it fits — if justify is "Right" the head gets removed, otherwise the tail gets removed. These options can be given to Title:
    • Center — title is centered horizontally. This is the default. 💖
    • Left — title is justified to the left side.
    • Right — title is justified to the right side.
    • Side — makes the title show up on the right hand side of any icon or swallowed window, instead of below it (which is the default). If you're working with small icons and you combine this with the Left or Right option, you can get a look similar to fvwm's menus. lowkey a serve 👑
  • ActiveTitle name — the title written on the button while the mouse is hovering above it. No ActiveTitle specified? Then whatever Title set gets displayed (if there is any).
  • PressTitle name — the title written on the button while the button is pressed. No PressTitle specified? Again, the text from Title shows up (if there is any).
  • Legacy fields [title icon command] — okay these fields are only kept around for compatibility with previous versions of FvwmButtons, and using them is discouraged, fr fr 🚩 The title field works like the option Title name. If the title field is -, no title is displayed. The icon field works like the option Icon filename. If the icon field is -, no icon is displayed. And the command field works like the option Action command, or alternatively Swallow "hangon" command.

The command

Any fvwm command gets recognized by FvwmButtons. Peep fvwm(1) for the full tea 💅

The Exec command has a lil extension when it's used inside Actions — here's its syntax:

Exec ["hangon"] command

Example:

*FvwmButtons: (Action Exec "xload" xload)

The hangon string must be enclosed in double quotes. When FvwmButtons runs into an Exec command like this, the button stays pushed in until a window whose name, class or resource matches the quoted part of the command shows up. This is meant to give the user visual feedback that the action they asked for is actually happening ✨ The hangon string may contain wildcard characters ('*') that match any substring. And if the quoted portion contains no characters at all, the button pops right back out immediately. ⚠️ Note that users can keep pressing the button and re-executing the command even while it looks pressed in — yes, even then. 💀

Quoting

Any string containing whitespace has to be quoted. And contrary to earlier versions, commands no longer need to be quoted — in that case any quoting character gets passed on to the application untouched. Only commas ',' and closing parentheses ')' have to be quoted inside a command. You can quote 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 it's like that on purpose — for when you're using a preprocessor and you want it to reach into your commands, like this:

#define BG gray60
*FvwmButtons: (Swallow "xload" `Exec xload -bg BG &`)

And remember: any single character can be quoted with a preceding backslash \. 🦋

✨ CREATING PANELS ✨

okay so bestie, listen — the old versions of FvwmButtons (we're talking fvwm 2.0.46 all the way to 2.3.6) handled panels completely differently. and like… you literally can not use your old panel config with the new panel feature, no cap. go read "CONVERTING OLD PANEL CONFIGURATIONS" if you need the tea. 💅

🎀 HOW TO CREATE NEW PANELS 🎀

any program that can be launched from within fvwm and that has a window can be your panel. literally anything. a terminal window? panel. something like xload or xosview? panel. another fvwm module — even FvwmButtons itself? also panel, bestie. all you gotta know is how to start your app from fvwm. 🦋

the button that invokes the panel is configured as easily 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, but here's the glow-up: the application is not put into the button when it starts up — instead it gets hidden from view. 👀 when you press the button for the panel, the window slides into view. iconic behavior honestly. the -g -30000-30000 option tells the application it should be created somewhere very far to the top and left of your visible screen. otherwise you'd see it flashing for a moment when FvwmButtons starts up, and that's just not the vibe. some applications do not work well with this kind of syntax, so you may have to live with the short flashing of the window. sorry bestie, we can't all be perfect. 😭

if you want to make a panel from another instance of FvwmButtons you can totes do so, but you must give it a different name (my_first_panel in above example). ⚠️ if you run FvwmButtons under the same name, new panels are created recursively until your system runs out of resources and FvwmButtons crashes! 💀 to configure a second button bar with a different name, simply put *new_name in place of *FvwmButtons in your configuration file. if you are not familiar with the Swallow option or if you want to learn more about how "swallowing" panels works, refer to the description of the Swallow option. 📚

now that your panel basically works you will want to tune it a bit. you may not want a window title on the panel. to disable the title use the fvwm Style command. if your button bar is "sticky" you may want to make the panel sticky too. and probably the panel window should have no icon in case it is iconified. 🫶

Style name_of_panel_window NoTitle, Sitcky, NoIcon

(and yes, that's exactly how it's spelled in the original — Sitcky with the lil typo, we don't fix what we didn't break 💖)

you may want your panel to stay open only until you select something in it. you can give FvwmButtons the -transientpanel option after the -g option in the command. FvwmPager has a similar option -transient. ✨

last, but not least, you can now put an icon, a title or a small arrow in the button so that you can see what it is for. a title or icon can be specified as usual. to activate the arrow, just add (indicator) after the Panel keyword in the example above and the Padding option to leave a few pixels between the arrow and the border of the button. an optional direction in which the panel is opened can be given too: 👑

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

there are several more options to configure how your panel works, for example the speed and smoothness of the sliding animation. please refer to the description of the Panel option for further details. 🌈

🌸 CONVERTING OLD PANEL CONFIGURATIONS 🌸

this section describes how to convert a pretty old syntax used in 2.2.x versions. you may skip it if your syntax is more recent. no worries bestie, we support your journey. 💜

with the old panel feature you first had one or more lines defining panels in your main FvwmButtons configuration:

...
*FvwmButtons(Title WinOps,Panel WinOps)
*FvwmButtons(Title Tools ,Panel Tools)
...

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

*FvwmButtonsPanel WinOps
*FvwmButtonsBack bisque2
...

*FvwmButtonsPanel Tools
*FvwmButtonsBack bisque2
...

and perhaps you had style commands for you panels:

Style FvwmButtonsPanel Title, NoHandles, BorderWidth 0
Style FvwmButtonsPanel NoButton 2, NoButton 4, Sticky

the new configuration looks much the same, but now the configuration of the main panel is independent of the configuration of the sub panels. the lines invoking the panels use the same syntax as the Swallow option, so you simply add the name of the window to use as a panel and the command to execute instead of the panel name. note that you give the new instance of FvwmButtons a different name. 🦋

*FvwmButtons: (Title WinOps, Panel WinOps \
  "Module FvwmButtons WinOps")
*FvwmButtons: (Title Tools , Panel Tools \
  "Module FvwmButtons Tools")

if you used something like Panel-d you now have to use Panel(down) instead. to make the new panel vanish as soon as a button was selected start FvwmButtons with the -transientpanel option:

*FvwmButtons: (Title Tools , Panel(down) Tools \
  "Module FvwmButtons -transientpanel Tools")

the rest of the configuration is very easy to change. delete the lines *FvwmButtonsPanel <name> and add <name> to all of the following configuration lines for the panel instead. use the same name in your Style commands:

*WinOps: Back bisque2
...
*Tools: Back bisque2
...
Style "WinOps" Title, NoHandles, BorderWidth 0
Style "WinOps" NoButton 2, NoButton 4, Sticky
Style "Tools" Title, NoHandles, BorderWidth 0
Style "Tools" NoButton 2, NoButton 4, Sticky

that's it. periodt. 💅 the new panels are much more flexible. please refer to other parts of this documentation for details.

💀 WHY WAS THE PANEL FEATURE REWRITTEN? 💀

there are several reasons. the most important one is that the program code implementing the panels was very disruptive and caused a lot of problems. at the same time it made writing new features for FvwmButtons difficult at best. 😭

the second reason is that most users were simply unable to make it work — it was way too complicated. even I (the author of the new code) had to spend several hours before I got it working the first time. embarrassing but real. 🙈

the third reason is that the new panels are more versatile. any application can be a panel in FvwmButtons, not just other instances of FvwmButtons itself. so I sincerely hope that nobody is angry about the change. yes — you have to change your configuration, but the new feature is much easier to configure, especially if you already know how the Swallow option works. 🫶

🔥 ARRANGEMENT ALGORITHM 🔥

FvwmButtons tries to arrange its buttons as best it can, by using recursively, on each container including the buttonbox itself, the following algorithm. let's break it down bestie, it's giving geometry class but make it cute. ✨

🎀 Getting the size right

first it calculates the number of button unit areas it will need, by adding the width times the height in buttons of each button. containers are for the moment considered a normal button. then it considers the given rows and columns arguments. if the number of rows is given, it will calculate how many columns are needed, and stick to that, unless columns is larger, in which case you will get some empty space at the bottom of the buttonbox. if the number of columns is given, it calculates how many rows it needs to fit all the buttons. if neither is given, it assumes you want two rows, and finds the number of columns from that. if the BoxSize option is set to smart at least the height/width of the tallest/widest button is used while the fixed value prevents the box from getting resized if both rows and columns have been set to non-zero. 💖

🦋 Shuffling buttons

now it has a large enough area to place the buttons in, all that is left is to place them right. there are two kinds of buttons: fixed and floating buttons. a fixed button is forced to a specific slot in the button box by a x/y geometry argument. all other buttons are considered floating. fixed buttons are placed first. ⚠️ should a fixed button overlap another one or shall be place outside the buttons window, FvwmButtons exits with an error message. 💀 after that the floating buttons are placed. the algorithm tries to place the buttons in a left to right, top to bottom western fashion. if a button fits at the suggested position it is placed there, if not the current slot stays empty and the slot to the right will be considered. after the button has been placed, the next button is tried to be placed in the next slot and so on until all buttons are placed. additional rows are added below the bottom line of buttons until all buttons are placed if necessary if the BoxSize option smart is used. 👑

🌈 Containers

containers are arranged by the same algorithm, in fact they are shuffled recursively as the algorithm finds them. it's giving fractal energy honestly. 🌀

⭐ Clarifying example

an example might be useful here: suppose you have 6 buttons, all unit sized except number two, which is 2x2. this makes for 5 times 1 plus 1 times 4 equals 9 unit buttons total area. assume you have requested 3 columns. 💅

1) +---+---+---+   2) +---+---+---+   3) +---+---+---+
   | 1 |       |      | 1 |       |      | 1 |       |
   +---+       +      +---+   2   +      +---+   2   +
   |           |      |   |       |      | 3 |       |
   +           +      +   +---+---+      +---+---+---+
   |           |      |           |      |   |   |   |
   +-----------+      +---+-------+      +---+---+---+

4) +---+---+---+   5) +---+-------+   6) +---+-------+
   | 1 |       |      | 1 |       |      | 1 |       |
   +---+   2   +      +---+   2   |      +---+   2   |
   | 3 |       |      | 3 |       |      | 3 |       |
   +---+---+---+      +---+---+---+      +---+-------+
   | 4 |       |      | 4 | 5 |   |      | 4 | 5 | 6 |
   +---+---+---+      +---+---+---+      +---+---+---+

🌸 What size will the buttons be?

when FvwmButtons has read the icons and fonts that are required by its configuration, it can find out which size is needed for every non-swallowing button. the unit button size of a container is set to be large enough to hold the largest button in it without squeezing it. swallowed windows are simply expected to be comfortable with the button size they get from this scheme. if a particular configuration requires more space for a swallowed window, it can be set in that button's configuration line using the option "Size width height". this will tell FvwmButtons to give this button at least width by height pixels inside the relief and padding. 🎀

okay bestie, we're in the FINAL stretch and this is where it gets interactive 💅

🦋 DYNAMICAL ACTIONS 🦋

So like, your FvwmButtons isn't just a static little baby — a running instance can receive commands at run time. Obsessed. You do it with the fvwm command:

SendToModule FvwmButtons-Alias <action> <params>

and here's every single action it supports, no cap:

  • ChangeButton button_id options — this one can change the title or the icon of a button at literal run time. button_id is the id of the button you wanna change, exactly as you specified it with the Id button option. It can also just be a number — in that case, the button with that given number is assumed. And finally?? button_id can be in the form +x+y, where x is a column number and y is a row number of the button you're changing. You can specify multiple option pairs (name with value) by delimiting them with a comma. Currently the options include Title, ActiveTitle, PressTitle, Colorset, Icon, ActiveIcon and PressIcon. These work just like the configuration options of the same name. Slay.
  • ExpandButtonVars button_id command — replaces variables present in the command exactly like in the Action button option does, and then sends the command back to fvwm. button_id has the same syntax as described up in ChangeButton. 🫶
  • PressButton button_id [mouse_button] — simulates a mouse click on a button, king behavior tbh. button_id is the id of the button to press as specified using the Id button option, and mouse_button is the number of mouse button used to click on the button, e.g "1" for the left mouse button etc. Quotes around the number are not necessary. If the mouse_button option is omitted, mouse button 1 is assumed. This command behaves exactly as if the mouse button was pressed and released on the button in question. Not me pressing buttons I can't even see 😭
  • Silent — this prefix may be specified before other actions. It disables all possible error and warning messages. shhh 🤫

Example, look at her go:

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

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

🌸 SAMPLE CONFIGURATION 🌸

The following are excerpts from a .fvwm2rc file which describe FvwmButtons initialization commands — read them and weep, they're iconic:

##########################################################
# 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, ngl — one of them 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. 😤 (yes bestie, we're all looking at that sentence together)

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 it's swallowed. Sneaky. Love that for us. 🧚

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. 😱 drama!

Note that with the x/y geometry specs you can easily build button windows with gaps. You can not accomplish this without geometry specs for the buttons. periodt.

Here's another example, because one is never enough:

##########################################################
# 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)

# 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. That's it, that's the bug note. Respect it or perish. 🙈

👑 HISTORY 👑

The FvwmButtons program, and the concept for interfacing this module to the Window Manager, are all original work by Robert Nation. Legend status honestly. 🌟

Originally, FvwmGoodStuff preceded FvwmButtons. The lore is real, iykyk. 📜

💖 AUTHOR 💖

Robert Nation (1993). Somewhat enhanced by Jarl Totland (1996), Jui-Hsuan Joshua Feng, Scott Smedley.

and that's a wrap bestie!! 🎀 this lil manual is dated 2026-07-31 and it's FVWMBUTTONS(1) in your man pages — go forth and button your heart out, no cap. 💅✨🦋

📦 where this page comes from