FvwmButtons(1)

📦 version 2.7.0, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ FvwmButtons(1) ✨

Fvwm Modules section, bestie 🎀 this one is all about the buttonbox 💖

🧚 NAME 🧚

okay so FvwmButtons is literally the fvwm buttonbox module ✨

💅 SYNOPSIS 💅

Module FvwmButtons [-g geometry] [-transient | -transientpanel] [name[configfile]]

ngl, FvwmButtons can only be invoked by fvwm 🙅‍♀️ Command line invocation of the FvwmButtons module will not work. 💀

🦋 DESCRIPTION 🦋

The FvwmButtons module gives you a window of buttons that sits on the X terminal's root window 🌸 Anytime, you can press a button and the window manager will run a user-specified command for you. FvwmButtons only works when fvwm is used as the window manager, so no other WM vibes here 🙈

The buttonbox can be any configuration or geometry you want 🍓 and it can have monochrome or color icons for the actions it's going to invoke. Even other applications can get swallowed by the button bar 😭 literally iconic.

Panels that open on a button press are available too ✨ check the CREATING PANELS section for all the deets.

👑 OPTIONS 👑

  • -g geometry — sets the geometry of the main window. The command line option slays any other geometry settings in the configuration file 👑
  • -transient — tells FvwmButtons to shut itself down after the first key or button press has been received (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 want to pick one button and have it closed automatically 🫶 It could even be used to make two-dimensional graphical menus. Since -transient is an option and not a configuration setting, you can use the same configuration for transient and non-transient button bars 🧚
  • -transientpanel — does roughly the same thing as -transient, 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 means it doesn't have to be started again every time something gets selected 💜

🌈 INVOCATION 🌈

FvwmButtons is spawned by fvwm, so command line invocation won't 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. It can also be bound to a menu, 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 MyButtonBox

FvwmButtons will then use only the lines starting with "*MyButtonBox", instead of the default "*FvwmButtons". Main character energy 👑

🎀 CONFIGURATION OPTIONS 🎀

The following commands are understood by FvwmButtons, so let's get into it 💅

*FvwmButtons: Back color

Sets the background color for the buttons 🌸 The relief and shadow color get calculated from the background color, so you don't have to do that math yourself 🧮

*FvwmButtons: BoxSize algorithm

This one decides how seriously FvwmButtons takes the Rows and Columns options (see below) 🔥 It can be 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 you asked for. ⚠️ If the box is too small to accommodate all the buttons, the module will fail 💀

If smart is used, FvwmButtons enlarges the box so all the 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 every button is placed. For the best tolerance of configuration errors, use the smart option 🫶

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

*FvwmButtons: Colorset colorset

Tells the module to use colorset colorset for the window background 🎨 Refer to the fvwm man page for the deets on colorsets.

*FvwmButtons: ActiveColorset colorset

Tells the module to use colorset colorset for the background color/image and/or title color of a button while the mouse is hovering above it 🦋

*FvwmButtons: PressColorset colorset

Tells the module to use colorset colorset for the background color/image and/or title color of a button when it's pressed 💖

*FvwmButtons: Columns columns

Specifies how many columns of buttons get created 🍓 If it's 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 can hold, the columns specification is ignored unless the BoxSize option is fixed 🙈

*FvwmButtons: File filename

Specifies that the configuration for this button lives in the file filename 📂 filename can be a full pathname, or it's assumed to be in fvwm's startup directory. The configuration file uses the same format as fvwm's configuration file, but each line is read as if it's prefixed by "*FvwmButtons". Comments are made by starting a line with "#". Line continuation is done by ending a line with a "\" 🧚

*FvwmButtons: Font font

Specifies the font 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 it's activated 🫶

*FvwmButtons: Geometry geometry

Specifies the FvwmButtons window location and size 📍 The geometry is a standard X11 window geometry specification.

*FvwmButtons: ButtonGeometry geometry

This one works like Geometry, except the size is the size of a single button 🍓 The size of the whole FvwmButtons window gets calculated by multiplying the button dimension by the number of rows and columns 🧮

*FvwmButtons: Padding width height

Sets the default horizontal padding to width pixels, and the vertical padding to height pixels 💅 The free space between a button's relief and its contents is normally 2 pixels on the sides and 4 pixels above and below. The exception is swallowed windows and containers, which aren't padded at all unless this option is used 🌸

*FvwmButtons: Pixmap pixmapfile

Specifies a background pixmap to use 🖼️ Specify "none" (without the double quotes) for a transparent background 🦋

*FvwmButtons: Rows rows

Specifies the number of rows of buttons to be created. The default is 2 rows 💖

*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 to a button:

geometry

Sets 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) get placed before the ones without them. If two or more buttons are forced to overlap by this, FvwmButtons exits with an error message 💀

Action [(options)] command

Specifies an fvwm command to run when the button gets 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, which means 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 bunch of predefined variables 🧚 $left, $right, $top and $bottom get substituted by the left, right, top and bottom coordinates of the button that was 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 (so for a button that's 5 pixels away from the right screen border, $-right will be 5). $width and $height get 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 happens 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 only worked 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 👀

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 flips that, so the action is executed on the button press instead 🔥 This may be good, for example, with Menu or SendToModule that generate popups, or when Frame is 0 and the button would otherwise look unresponsive 😭

Back color

Specifies the background color to be used when drawing this box. A relief color and a shadow color are calculated from this 🌈

  • Center: The contents sit smack in the middle of the button 🎀. That's the default, but you can switch it up with Left or Right if you want something different 💅.
  • Top: The contents hug the top of the button instead of floating in the middle 🦋. By default it's vertically centred, so only use this if you want that top-aligned look ✨.

🌈 Colorset colorset

Okay so a colorset can be slapped onto a container, a swallowed application, or a simple button 💖. To apply it, just put the option on the same line as that button or container's description 💅.

⚠️ Bestie, real talk: painting individual buttons and containers with colorsets means a LOT of chatting with the X server 😭. If you're not happy with how fast dozens of buttons with colorset backgrounds draw, don't use colorsets here 💀.

Colorsets as the background of swallowed applications don't have that same speed problem 🍓, but how it looks depends entirely on the swallowed app 🤷‍♀️. It might work exactly how you want, but since it means fiddling with other apps' windows, there's zero guarantee for anything 😭. I tested three apps: xosview looks gorgeous with a colorset background 🔥, xload only works with a VGradient or solid background 🙈, and an analog xclock leaves a trail painted in the background color after its hands ⏰ (not it 💀).

If the swallowed window is an fvwm module (see the (No)FvwmModule option to Swallow), the colorset does NOT get applied to it 🙅‍♀️. You need to use the colorset in the module's own configuration instead 🧚. And if the swallowed module has a transparent colorset background, what you see through it is the FvwmButtons background, not the button colorset 🌸. Refer to the fvwm man page for the deets on colorsets 📖.

  • ActiveColorset colorset: When your mouse is hovering over the button 👀, this uses colorset colorset for its background color/image and/or title color.
  • PressColorset colorset: Same energy, but this kicks in when the button is pressed 👇.

📦 Container [(options)]

This makes the button a mini buttonbox, basically the same as swallowing another FvwmButtons module 🧚. The options are the same ones you'd give a single button, but they affect every button inside 💜. For containers, you can use Back, Font, Fore, Frame and Padding 🎀. Flags for Title and Swallow can be set with Title(flags) and Swallow(flags) ✨.

⚠️ You should also give either Columns width or Rows height, or else Rows 2 gets assumed 🙃. For an example, check out the Sample configuration section 📚.

The container button itself (separate from its contents) can take format options like Frame and Padding, and you can bind commands to it 👑. This means you can make a sensitive relief around a container, like this:

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

Typically you'll want to at least give the container a size setting widthxheight 💅.

🛑 End

This says no more buttons are defined for the current container 🙅‍♀️, so any further buttons get put in the container's parent 🌸. Give it on a line by itself, like this:

*FvwmButtons: (End)
  • Font fontname: Uses the font fontname for labeling this button 🔤.
  • Fore color: Sets the foreground color for the title and monochrome icons on this button 🎨.
  • Frame width: The relief of the button gets width pixels wide 🖼️. If you give a negative number, the relief flips, so the button looks sunken normally and pops up raised when activated 😭🔥.
  • Icon filename: The name of an image file with the icon you want on the button 🖼️. FvwmButtons searches through the path in the fvwm ImagePath configuration item to find it 🔍.
  • ActiveIcon filename: An alternative icon for when the mouse is hovering over the button 👀. If you don't specify one, the Icon image gets shown instead (if there is one) 💖.
  • PressIcon filename: An alternative icon for when the button is pressed 👇. If there's no PressIcon, the Icon image gets shown instead (if there is one) 🫶.
  • Id id: The id used to identify this button 🆔. The first character should be alphabetic 🔤. See also the "DYNAMICAL ACTIONS" section 🦋.
  • Left: Aligns the contents to the left 👈. The default is to center the contents on the button 🎀.
  • NoSize: This button won't be considered at all when making the initial calculations of button sizes 🙈. It's useful for that one odd button that's just a couple of pixels too large and ends up blowing up your whole buttonbox 💀. NoSize is equivalent to Size 0 0 ✨.
  • Padding width height: The free space between the relief of the button and its contents is normally 2 pixels to the sides and 4 pixels above and below 🌸. Swallowed windows and containers 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 🧚. The difference is they're NOT displayed within the button 🙈. Instead, they stay hidden until the user presses the panel's button, and then the panel (the window of the swallowed application) slides open with an animation 🎀. The options can be any of the flags described for the Swallow command 💅. You can also use a direction left, right, up or down to set the sliding direction 🦋.

  • steps animation-steps: Sets the number of animation steps 🪜.
  • delay ms: 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 😭.
  • smooth: Makes the panel redraw between the steps of the animation 🌈. The sliding might look smoother this way, but it depends on the application and display speed 🤷‍♀️. The application may appear to grow instead of sliding out, and the animation may be slower 🐢.
  • Hints: Tells 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 isn't what you want, try NoHints 🔁.
  • noborder: Tells FvwmButtons to ignore the borders of the window when calculating positions for the animation 🖼️. This is equivalent to setting noplr and noptb in the position option 🧠.
  • indicator: With this on, FvwmButtons draws a small triangle in the button that opens the panel 🔺. The triangle points in the direction where the panel will pop up ⬆️. You can follow indicator with a positive integer for the maximum width and height of the indicator 📏. Without that size, FvwmButtons makes the indicator fit the button 💅. You'll probably want to use the Padding option to leave a few pixels between the indicator and the frame of the button ✨.
  • position: This lets you place the panel 📍. The syntax is:
position [context-window] [pos] [x y] [border-opts]
  • context-window can be Button, Module or Root 🪟. This is the window that panel percentage offsets get calculated from. Button is the panel's button, Module is FvwmButtons itself, and Root is a virtual screen 🌍. The context-window and the sliding direction together 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 📏.
  • pos can be center, left or right (for sliding up or down), or top or bottom (for sliding left or right) 🎯. It sets the vertical (sliding up and down) or horizontal (sliding left and right) position of the Panel on that line segment 💜. For example, if you slide up and use a left pos, the left borders of the panel and the context-window get aligned 👈.
  • x y are the offset values, and they say how far the panel moves from its default position 🦋. By default, the number you give is read as a percentage of the context window's width (height) 📊. Add a trailing p and it switches to pixels 📐. All offset calculations are relative to the button's location, even when you're using a root context 🫶.

The border-opts are mlr, mtb, noplr and noptb 💅, and they decide which border widths get counted 📏. By default the borders of FvwmButtons are NOT counted 👀. mlr flips that for the left and right borders, and mtb flips it for the top and bottom. The Panel is the opposite: its borders ARE counted by default, so noplr flips that for the left and right, and noptb flips it for the top and bottom ✨.

The defaults are a slide-up 🧚 with a five millisecond delay and twelve animation steps. If you want the panel to pop up with zero animation, set the steps to 0. The default position is 'Button center' 🎀.

Go peek at the CREATING PANELS section for more panel tea 🫖.

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

The contents of the button get lined up to the right 👉. By default they're centered, so this is for when you want that right-side glow 💖.

📐 Size width height

Tells the button that its contents need at least width by height pixels 🦋, no matter what size FvwmButtons would have figured out from the icon and title. If your button bar only has swallowed windows, it won't get very big without this, because FvwmButtons doesn't count sizes for swallowing buttons 🥲. This only sets the minimum space it's guaranteed though. Other buttons might make the buttonbox go bigger.

🫧 Swallow [(flags)] hangon command

FvwmButtons runs command, and when a window whose name, class or resource matches hangon shows up, it gets captured and swallowed into this button 🍓. The hangon string can use * wildcards to match any substring. Swallow swaps out $fg and $bg the same way the Action option does (but if you use UseOld and NoClose, the app won't restart when FvwmButtons restarts, so it won't pick up any new colors you changed 🙈).

Here's an example:

*FvwmButtons: (Swallow XClock 'Exec xclock -geometry -3000-3000 &')

This grabs the first window whose name, class or resource is "XClock" and shows it in the button. If there's no matching window, the "Exec" command makes one for you. The "-geometry -3000-3000" argument is there so the window gets drawn out of sight first, then swallowed into FvwmButtons 🫣.

You can also swallow modules by putting the module in place of 'Exec whatever':

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

Here are the flags you can give swallow 🧁:

  • NoClose / Close — Decides whether the swallowed program in this button gets un-swallowed or closed when FvwmButtons exits cleanly. NoClose can be paired with UseOld so windows survive a window manager restart 🦋. The default is Close.
  • NoHints / Hints — Decides whether the swallowed program's hints get ignored. This is handy for forcing a window to resize itself to fit its button 📏. The default is Hints.
  • NoKill / Kill — Decides whether the swallowed program gets closed by killing it or by sending it a message. This helps when a program doesn't accept window manager protocol 💀. The default is NoKill. This does nothing if NoClose is specified.
  • NoRespawn / Respawn / SwallowNew — Decides whether the swallowed program gets respawned (restarted) if it dies. With Respawn, it's restarted using the original command. Use this one with care 🙃, since the program might have a legit reason to die. With SwallowNew, the program isn't respawned, but if a new window with the specified name shows up, it gets swallowed 🌈.
  • NoOld / UseOld — Decides whether the button tries to swallow an existing window matching the hangon name before spawning one with command itself 🔥. The hangon string can use * wildcards to match any substring. The default is NoOld. UseOld can be combined with NoKill so windows survive a window manager restart 💜. If you want FvwmButtons to swallow an old window and NOT spawn one if it fails, make the command Nop:
  • NoTitle / UseTitle — Decides whether the button's title comes from the swallowed window's title. With UseTitle, the button title changes on the fly to match the window name ✨. The default is NoTitle.
  • NoFvwmModule / FvwmModule — By default, FvwmButtons treats the 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 👑.

Some examples for the NoOld / UseOld flag:

*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 &`)

🏷️ Title [(options)] name

Sets the title written on the button 🌸. Quote it if you want whitespace in there. If a title is 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 work with Title:

  • Center — Centers the title horizontally. This is the default 🎯.
  • Left — Justifies the title to the left side 👈.
  • Right — Justifies the title to the right side 👉.
  • Side — Puts the title on the right hand side of any icon or swallowed window, instead of underneath, which is the default 🧚. If you use small icons and combine this with Left or Right, you can get a look similar to fvwm's menus 🍭.

🖱️ ActiveTitle name

The title written on the button while your mouse is hovering over it 🫶. If you don't set an ActiveTitle, the text from Title shows up instead (if there is any).

👇 PressTitle name

The title written on the button while it's being pressed 😭. If you don't set a PressTitle, the text from Title shows up instead (if there is any).

🕰️ Legacy fields [title icon command]

These fields are kept around for compatibility with older versions of FvwmButtons, and using them is discouraged 🙅. The title field works like the Title name option. If the title field is -, no title shows. The icon field works like the Icon filename option. If the icon field is -, no icon shows. The command field works like the Action command option, or like Swallow "hangon" command 🔁.

🎬 The command

FvwmButtons recognizes any fvwm command. See fvwm(1) for more info 💖.

The Exec command gets a little extension when it's used in Actions. Its syntax is:

Exec ["hangon"] command

Example:

*FvwmButtons: (Action Exec "xload" xload)

The hangon string has to be wrapped in double quotes 🎀. When FvwmButtons spots an Exec command like this, the button stays pushed in until a window whose name, class or resource matches the quoted part shows up. It's basically visual feedback so the user knows the action they asked for is actually happening ✨. The hangon string can use * wildcards to match any substring. If the quoted part is empty, the button pops out right away. Heads up though: users can keep pressing the button and re-running the command, even when it looks pressed in 🙈.

💬 Quoting

Any string with whitespace in it has to be quoted. Unlike earlier versions, commands don't need quotes anymore 🥳. If you do quote one, the 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`.

Back quoting is a bit unusual, but it's used on purpose. If you run a preprocessor like FvwmCpp and want it to get into your commands, it looks like this:

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

Any single character can be quoted with a backslash \ in front of it 🦋.

✨ CREATING PANELS ✨

okay so bestie, heads up 😭 former versions of FvwmButtons (fvwm 2.0.46 to 2.3.6) handled panels in a totally different way. You can not use your old panel configuration with the new panel feature, so don't even try 🙅. Read "CONVERTING OLD PANEL CONFIGURATIONS" for the full tea ☕.

🎀 HOW TO CREATE NEW PANELS 🎀

Any program that can be launched from within fvwm and that has a window can be used as a panel 🦋. A terminal window could be your panel, or some application like xload or xosview, or another fvwm module, including FvwmButtons itself 🌈. Literally all you need to know is how to start your application from fvwm 💅.

The button that invokes the panel is just as easy to configure as any other button 🍓. Honestly you only need 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 the big difference is that the application doesn't get shoved into the button when it starts up. Instead it's hidden from view 🙈, and when you press the button, the window slides into view ✨. The -g -30000-30000 option tells the application to create itself somewhere very far to the top and left of your visible screen 🧚. Otherwise you'd see it flash for a moment when FvwmButtons starts up 😭. Some applications don't vibe with this kind of syntax, so you might have to live with the short flash 💀. If you want to make a panel from another instance of FvwmButtons, you totally can, but you have to give it a different name (my_first_panel in the example above) 🫶.

💀 Warning, bestie: if you run FvwmButtons under the same name, new panels are created recursively until your system runs out of resources and FvwmButtons crashes! Don't do it 😭.

To configure a second button bar with a different name, simply put *new_name in place of *FvwmButtons in your configuration file 🌸. If you're not familiar with the Swallow option, or you want to learn more about how 'swallowing' panels works, check out the description of the Swallow option 📖.

Now that your panel basically works, you'll want to tune it a bit ✨. You might not want a window title on the panel, and you can get rid of it with the fvwm Style command 💅. If your button bar is sticky, you may want the panel to be sticky too 🫶. And the panel window should probably have no icon in case it gets iconified 🙈.

Style name_of_panel_window NoTitle, Sitcky, NoIcon

You might 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 you can see what it's 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 use the Padding option to leave a few pixels between the arrow and the border of the button. You can also give an optional direction the panel opens in 🎀:

*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 🦋. Check the description of the Panel option for all the details 📖.

🧩 CONVERTING OLD PANEL CONFIGURATIONS 🧩

This section describes how to convert a pretty old syntax used in 2.2.x versions 🕰️. You can 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 your 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, plus 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 too:

*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, bestie 🥳. 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, because 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 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 ✨

okay so FvwmButtons is literally the queen of lining things up 👑 it figures out where every button goes by running the same little algorithm recursively on each container, including the buttonbox itself 🫶 fr fr it's giving organized

🧮 Getting the size right

First it works out how many button unit areas it's gonna need 💖 it adds up the width times the height (in buttons) of every button. Containers count as a normal button for now, ngl. Then it looks at the rows and columns arguments 🎀

  • if rows is given, it works out how many columns it needs and sticks to that, unless columns is bigger, in which case you get some empty space at the bottom of the buttonbox 🌸
  • if 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. 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 big enough area to place the buttons in, so all that's left is placing them right 🎀 there are two kinds of buttons: fixed and floating 🦋 A fixed button is forced into a specific slot by an x/y geometry argument. All other buttons are considered floating.

Fixed buttons get placed first. Should a fixed button overlap another one, or be placed outside the buttons window, FvwmButtons exits with an error message 💀 After that the floating buttons get placed. The algorithm tries to place them in a left to right, top to bottom western fashion 📖 If a button fits at the suggested position, it's placed there. If not, the current slot stays empty and the slot to the right gets considered. After a button is placed, the next button tries the next slot, and so on until every button is placed ✨

Additional rows get added below the bottom line of buttons until all buttons are placed, if necessary, when the BoxSize option smart is used 🌈

🪆 Containers

Containers are arranged by the same algorithm. They're basically 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 its configuration needs, it can find out what size every non-swallowing button needs 📐 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 comfy with the button size they get from this scheme 🦋

If a particular configuration needs more space for a swallowed window, it can be set in that button's configuration line using the option "Size width height". This tells FvwmButtons to give that button at least width by height pixels inside the relief and padding 💜

✨ DYNAMICAL ACTIONS ✨

A running FvwmButtons instance can receive some commands at run time 🧚 This is achieved using the fvwm command:

SendToModule FvwmButtons-Alias <action> <params>

🎯 Supported actions

  • ChangeButton button_id options — this one lets you swap the title or icon of a button while fvwm is running 🎀 button_id is the id of the button to change, as set with the Id button option. It can also be a number, in which case the button with that number is assumed. And finally, button_id may be in the form +x+y, where x and y are the column number and row number of the button you want to change 🧩 You can set several option pairs (name with value) by delimiting them with a comma. Currently the options include Title, ActiveTitle, PressTitle, Colorset, Icon, ActiveIcon and PressIcon 💅 They work just like the configuration options with the same names.
  • ExpandButtonVars button_id command — replaces variables in the command exactly like the Action button option does, then sends the command back to fvwm 🔁 button_id uses the same syntax as described under ChangeButton above.
  • PressButton button_id [mouse_button] — simulates a mouse click on a button 🖱️ button_id is the id of the button to press, as set with the Id button option. mouse_button is the number of the mouse button used to click on the button, e.g. "1" for the left mouse button etc. Quotes around the number aren't necessary 🙈 If the mouse_button option is omitted, mouse button 1 is assumed. This behaves exactly as if the mouse button was pressed and released on the button in question 💖
  • Silent — this prefix may be specified before other actions 🤫 It disables all possible error and warning messages 🙊

🌸 Example

Example:

*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 ✨

Okay bestie, here's a juicy peek at some .fvwm2rc excerpts that set up FvwmButtons's initialization commands 💅

##########################################################
# Load any modules which should be started during fvwm
# initialization

# Make sure FvwmButtons is always there.
AddToFunc StartFunction  "I" Module FvwmButtons

# Make it titlebar-less, sticky, and give it an icon
Style "FvwmButtons" Icon toolbox.xpm, NoTitle, Sticky

# Make the menu/panel look like CDE
Style "WinOps" Title, NoHandles, BorderWidth 0
Style "WinOps" NoButton 2, NoButton 4, Sticky
Style "Tools" Title, NoHandles, BorderWidth 0
Style "Tools" NoButton 2, NoButton 4, Sticky

##########################################################
DestroyModuleConfig FvwmButtons: *
*FvwmButtons: Fore Black
*FvwmButtons: Back rgb:90/80/90
*FvwmButtons: Geometry -135-5
*FvwmButtons: Rows 1
*FvwmButtons: BoxSize smart
*FvwmButtons: Font -*-helvetica-medium-r-*-*-12-*
*FvwmButtons: Padding 2 2

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

*FvwmButtons: (Title Resize, Icon resize.xpm,  Action Resize)
*FvwmButtons: (Title Move,   Icon arrows2.xpm, Action Move  )
*FvwmButtons: (Title Lower,  Icon Down,        Action Lower )
*FvwmButtons: (Title Raise,  Icon Up,          Action Raise )
*FvwmButtons: (Title Kill,   Icon bomb.xpm,    Action Destroy)

*FvwmButtons: (1x1,Container(Rows 3,Frame 1))
*FvwmButtons: (Title Dopey ,Action                          \
    `Exec "big_win" xterm -T big_win -geometry 80x50 &`)
*FvwmButtons: (Title Snoopy, Font fixed, Action             \
    `Exec "small_win" xterm -T small_win &`)
*FvwmButtons: (Title Smokin')
*FvwmButtons: (End)

*FvwmButtons: (Title Xcalc, Icon rcalc.xpm,                 \
             Action `Exec "Calculator" xcalc &`)
*FvwmButtons: (Title XMag, Icon magnifying_glass2.xpm,      \
             Action `Exec "xmag" xmag &`)
*FvwmButtons: (Title Mail, Icon mail2.xpm,                  \
             Action `Exec "xmh" xmh &`)
*FvwmButtons: (4x1, Swallow "FvwmPager" `FvwmPager 0 3`     \
             Frame 3)

*FvwmButtons: (Swallow(UseOld,NoKill) "xload15" `Exec xload \
     -title xload15 -nolabel -bg rgb:90/80/90 -update 15    \
     -geometry -3000-3000 &`)

Okay so the last lines are a little tricky 🙈 One spawns an FvwmPager module and captures it so it can display in a quadruple width button. When the frame is used, the Pager will be as big as possible within the button's relief 🌸

The final line is even more magic ✨ Check out the combo of UseOld and NoKill! It'll try to swallow an existing window named "xload15" on startup (if that fails, it starts one with the specified command instead). That swallowed app gets un-swallowed when FvwmButtons ends. And it's launched with -geometry -3000-3000 so it stays hidden until it's swallowed, iykyk 🫣

The other panels get 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 spec rgb:90/80/90 is actually the most correct way to specify independent colors in X, so use it instead of the older #908090 🎨 If you do use the hash version in your config, you need to escape the hash in any command that gets executed, or fvwm will think the rest of the line is a comment and ghost your command 👻

Note that with the x/y geometry specs you can build button windows with gaps, which is so cute. Here's another example. You literally cannot pull this off 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`)

💀 BUGS 💀

The action part of the Swallow option must be quoted if it contains any whitespace character. Don't skip this, bestie, or it's giving chaos 😭

🎀 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, warranties, or anything else 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 🌈

👑 AUTHOR 👑

Robert Nation, with some enhancements from Jarl Totland, Jui-Hsuan Joshua Feng, and Scott Smedley. Legends only 🫶

Okay that's the whole tea, bestie! ✨ This page is from the 3rd Berkeley Distribution, version 2.7.0, dated 19 October 2022. Now go make your FvwmButtons slay 💅🦋

📦 where this page comes from