FVWMICONMAN(1)

📦
version 1.1.5 · 5 versions
, in ubuntu stonking

🌸 FVWMICONMAN(1) — the fvwm icon manager, bestie edition 🌸

okay so this is FvwmIconMan from the Fvwm Modules manual, and it's literally an fvwm icon manager. Iconic. Let's get into it ✨

✨ NAME ✨

FvwmIconMan — an fvwm icon manager 🎀

💅 SYNOPSIS 💅

FvwmIconMan is spawned by fvwm, so no command line invocation will work.
okay so real talk: you can't just run this from your shell, bestie. FvwmIconMan gets spawned by fvwm, so no command line invocation will work. fvwm runs the show, periodt. 💀

🦋 DESCRIPTION 🦋

FvwmIconMan is an icon manager modeled after the TWM icon manager. And the way that you can have multiple icon managers? Obsessed. Each one gets armed with a list of window types that it manages. So like, you could have one manager that lists only emacs windows, and another manager that lists everything else. Slay, honestly.

You can also specify what resolution each icon manager uses, too. For example, one icon manager might manage windows on all desks, and another might manage only those on the current desk, page or screen. Chef's kiss.

FvwmIconMan can display the miniature icons that fvwm provides for its managed windows. Cute right?? 🥺

And the managers can be shaped however you want:

  • a maximum number of columns (so it grows vertically),
  • a maximum number of rows (so then it grows horizontally),
  • or stay at a fixed size, and adjust the size of the window buttons to fit — think win95's Taskbar, iykyk.

And when support is compiled in for the X Shape extension, then the manager windows may be shaped. It's giving custom silhouette. 👑

You can specify actions to be run when mouse or key events are received. For example, you could bind the first mouse button to iconify the selected window, and make bindings for the arrow keys to navigate the manager window without the mouse. Accessibility queen. 🫶

FvwmIconMan can be set to display which window currently has the keyboard focus, and by binding the select event (see below) to the fvwm Focus function, you can emulate the TWM icon manager's behavior. Retro but make it cunt. 💅

🎀 INITIALIZATION 🎀

During initialization, FvwmIconMan searches through the fvwm configuration file for the options described below. 🔍

⚠️ Highly recommended, bestie: make FvwmIconMan a sticky window. And if you want to make use of the followfocus option, and/or you're binding an action to Focus, then you should make FvwmIconMan clicktofocus. Also — when using the Shape option, it's recommended that the FvwmIconMan window not be decorated at all by fvwm. No cap.

🌈 INVOCATION 🌈

FvwmIconMan gets invoked by inserting this line in the .fvwm2rc file:

Module FvwmIconMan

If FvwmIconMan is to be spawned during fvwm's initialization, then this line should be placed in the StartFunction declarations. Or, it can be bound to a menu, mouse button, or keystroke to invoke it later. Your call, main character. 💖

okay so if you want to run FvwmIconMan in a transient mode — like with the built in window list — then pass -Transient as an argument. The invocation

Module FvwmIconMan -Transient

will do nicely. ✨ In this mode, FvwmIconMan will pop up one manager window directly under the cursor. When the mouse button is released, it will execute the appropriate action, and then exit. 🦋

Things get somewhat complicated by the fact that you can specify that FvwmIconMan creates multiple manager windows — behavior which is unsuitable when running transiently. So when running transiently, FvwmIconMan will only create one manager window. Use the manager id transient to specify options for this manager window. Note it down bestie, it's important. 📝

FvwmIconMan may also accept an alias name as an argument. For example:

Module FvwmIconMan FvwmIconMan-Variant2

Two of them?? Greedy. Love that for us. 💜

✨ CONFIGURATION OPTIONS REFERENCE CHART ✨

okay bestie, real talk: FvwmIconMan has ✨acquired✨ quite a few options over the years. and I assume you share my absolute hatred of paging through a sixty-mile man page just to find one setting, so here's a terse lil reference chart of everything available 💅

every one of these gets the full detail treatment in the next section — this is just the vibe check so you know what exists 🦋

each bullet here is: name → what it does → default, fr fr.

  • NumManagers — number of managers. default: 1
  • Action — binds a command to an event. default: Mouse 0 N sendcommand Iconify
  • Background — default background. default: gray
  • ButtonGeometry — size of a button, in pixels. (no default)
  • Colorset — default colorset. (no default)
  • DontShow — list of windows to ignore. (no default)
  • DrawIcons — use mini icons. default: false
  • FocusAndSelectButton — (no blurb given). default: flat grey black
  • FocusAndSelectColorset — (no blurb given). (no default)
  • FocusButton — style for focused buttons. default: up grey black
  • FocusColorset — (no blurb given). (no default)
  • FollowFocus — show which window has focus. default: false
  • Font — (no blurb given). default: 8x13
  • Foreground — default text color. default: white
  • Format — describes the button label. default: "%c: %i"
  • IconName — manager icon name. default: FvwmIconMan
  • IconAndSelectButton — (no blurb given). default: up black grey
  • IconAndSelectColorset — (no blurb given). (no default)
  • IconButton — style for icon buttons. default: up black grey
  • IconColorset — (no blurb given). (no default)
  • ManagerGeometry — size of the manager, in buttons. default: 0x1
  • MaxButtonWidth — max width of a button. (no default)
  • MaxButtonWidthByColumns — (no blurb given). (no default)
  • NoIconAction — animate iconification. default: NOP
  • PlainButton — style for normal buttons. default: up black grey

okay bestie the chart keeps going, here's the rest of it 💅 (option — what it does — default, same as always):

  • PlainColorset — chart left this one blank on both description and default 🙈
  • ReliefThickness — size of button relief — default 2
  • Resolution — window filters — default desk page
  • Reverse — can be normal, icon or none — default none
  • SelectButton — the style for selected buttons — default flat black grey
  • SelectColorset — no description, no default in the chart ✨
  • Shape — use shape extension — default false
  • Show — list of windows to show
  • ShowOnlyIcons — only icons visible — default false
  • ShowNoIcons — icons are not displayed — default false
  • ShowTransient — transient windows visible — default false
  • ShowOnlyFocused — only focused visible — default false
  • Sort — keep managers sorted — default name
  • SortWeight — weight for sorting
  • Tips — Tool Tips mode — default none
  • TipsDelays — Tool Tips mapping delays — default 1000 300
  • TipsFont — Font for Tool Tips — default is the default fvwm font
  • TipsColorset — Tool Tips Colorset — default 0
  • TipsFormat — describes the Tips label — default is the Format value
  • TipsBorderWidth — Tool Tips border size — default 1
  • TipsPlacement — Tips placement vs button — default updown
  • TipsJustification — Tips Just vs button — default leftup
  • TipsOffsets — Tips placement Offsets — default 3 2
  • Title — manager title — default FvwmIconMan
  • TitleButton — style for title button — default raisededge black grey
  • TitleColorset — also blank in the chart, no shame 💀
  • UseWinList — honor WinListSkip? — default true

💖 CONFIGURATION OPTIONS 💖

okay so here's the moment you've been waiting for, the actual options section, let's go 🫶

Literally every single one of these options except for nummanagers can be set per-manager. Which means?? it means you can have one vibe per manager, no cap. So for example the user can have their emacs manager rocking a red foreground, and their xterm manager living in blue. Two managers, two completely different aesthetics, both valid, both slaying 💅

Because of that, a configuration line can take one of two forms:

✨ hold that thought bestie, the actual two forms are coming right up in the next part ✨

Okay so now the slot syntax — how you actually tell FvwmIconMan stuff in your config 💅

  • *FvwmIconMan: OptionName OptionValue — sets OptionName to OptionValue for every single manager. All of them. The whole squad. 🫶
  • *FvwmIconMan: ManagerId OptionName OptionValue — sets OptionName to OptionValue for one specific manager, ManagerId. And ManagerId can be either a positive integer, or the literal string "transient". An integer id points at the managers FvwmIconMan creates when it's running normally, and "transient" points at the one single manager it creates when it's running transiently. ✨
The old-school syntax that uses an asterisk instead of white spaces before ManagerId and OptionName is still supported too, bestie — but it's obsolete now. It's giving legacy code energy. Let it go. 💀

Now the moment you've been waiting for —

🌈 The Options Themselves 🌈

  • *FvwmIconMan: NumManagers num — num is a positive integer, and it's the total number of icon managers. FvwmIconMan rly wants to know how many managers exist before it starts handling any manager-specific options, so put this one first. The default is 1.
  • *FvwmIconMan: [id] Action type binding — binds an FvwmIconMan command to an event. type can be one of: Key, Mouse, or Select. The actions themselves live in the section coming up later, ACTIONS. 🎀
  • *FvwmIconMan: [id] Background background — sets the default background color. Iconic. 💖
  • *FvwmIconMan: [id] ButtonGeometry geometry — sets the initial geometry of one individual button, in pixels. If the height you give it is 0, then the button height gets figured out from the font size instead. And the X and Y coordinates? Ignored. Completely. 🙈
  • *FvwmIconMan: [id] Colorset colorset — the default colorset used. This one overrides background and foreground, so watch out, it's got main character energy. 👑
  • *FvwmIconMan: [id] DrawIcons value — this controls the behavior of the space placed before each button label. Default is "false", which means there's an empty space before every label, and a relief button gets drawn in there next to all iconified windows — provided 'ReliefThickness' isn't zero. If you set it to "true", a mini icon gets drawn in place of that relief button, next to all iconified windows. If you set it to "always", a mini icon gets drawn for all windows, periodt. Quick note tho: iconified windows that don't have mini icons will still show a relief button unless 'ReliefThickness' is zero. And last but not least, if it's "none", the space before the label is gone completely — no mini icons, no relief buttons, nothing. 🦋
  • *FvwmIconMan: [id] FocusAndSelectButton style [forecolor backcolor] — same as the plainbutton option, but it describes the look of buttons that are both selected and have the keyboard focus. Double threat. 🔥
  • *FvwmIconMan: [id] FocusAndSelectColorset colorset — works like focusandselectbutton but uses colorsets instead. The style setting still can only be applied with focusandselectbutton tho, no cap.
  • *FvwmIconMan: [id] FocusButton style [forecolor backcolor] — same as the plainbutton option, but describes the look of buttons whose windows have the keyboard focus.
  • *FvwmIconMan: [id] FocusColorset colorset — works like focusbutton but uses colorsets instead. The style setting can still only be applied with focusbutton.
  • *FvwmIconMan: [id] FollowFocus boolean — if true, then the button appearance reflects which window currently has focus. Default is false.
  • *FvwmIconMan: [id] Font font — the font used for labeling the buttons. The default is 8x13. ✨
  • *FvwmIconMan: [id] Foreground foreground — sets the default foreground color. 🎀
  • *FvwmIconMan: [id] Format formatstring — a printf-like format string that describes the string printed in the manager window for each managed window. The possible flags are: %t, %i, %c, %r, and %s — for the window's title, icon title, class, resource name, or screen respectively. The default is "%c: %i". Obsessed with a good format string ngl. 💅
  • *FvwmIconMan: [id] IconName iconstring — the window icon name for that manager window. Iconstring can be either a single word, or a string wrapped in quotes. The default is "FvwmIconMan".
  • *FvwmIconMan: [id] IconAndSelectButton style [forecolor backcolor] — same as the plainbutton option, but describes the look of buttons whose windows are iconified and the button is selected.
  • *FvwmIconMan: [id] IconButton style [forecolor backcolor] — same as the plainbutton option, but describes the look of buttons whose windows are iconified.
  • *FvwmIconMan: [id] IconAndSelectColorset colorset — works like IconAndSelectButton but uses colorsets instead. The style setting can still only be applied with iconbutton.
  • *FvwmIconMan: [id] IconColorset colorset — works like iconbutton but uses colorsets instead. The style setting can still only be applied with iconbutton.
  • *FvwmIconMan: [id] ManagerGeometry geometry — the initial geometry of the manager, measured in units of buttons. If height is 0, the manager uses width columns and grows vertically once it's got more than width windows. Same deal the other way: if width is 0, it uses height rows and grows horizontally. If both are nonzero, then the manager window is exactly that size and stays that way, no growing, no nonsense. As columns get created, the buttons narrow to accommodate. And if the geometry has a negative y coordinate, then the window manager grows upwards. Otherwise it grows downwards. 🌈
  • *FvwmIconMan: [id] MaxButtonWidth width — defines a maximum for the width of a button, in pixels. By default there's no maximum at all. A value of 0 resets it back to the default. Heads up: this maximum is only used with a non growing manager — the kind where the ManagerGeometry option specifies a non zero width and height. 💖
  • *FvwmIconMan: [id] MaxButtonWidthByColumns col — another way to set the button width. col is the number of columns of icons, and the button width gets determined by dividing the total width of FvwmIconMan by the number of columns. For example, if the width of the FvwmIconMan manager is 1024 and MaxButtonWidthByColumns is 4, then MaxButtonWidth is 256. Super useful when you don't know the width of the manager at config time — say, for a swallowed FvwmIconMan. iykyk 🧚
  • *FvwmIconMan: [id] NoIconAction action — tells FvwmIconMan to do action when a NoIcon style window gets iconified or de-iconified. The relevant coordinates get appended to action so the icon can be traced back to an FvwmIconMan button. An example action is "*FvwwmIconMan: NoIconAction SendToModule FvwmAnimate animate". And a blank or null action turns this whole feature off. ✨
  • *FvwmIconMan: [id] PlainButton style [forecolor backcolor] — describes how normal buttons look. style can be one of flat, up, down, raisededge, or sunkedge, and it describes how the button is drawn. Both color options are optional, and if you don't set them, the default colors get used. And if you're on a monochrome screen, the style option is ignored — but you still have to set it. Annoying? Yeah. True? Also yeah. 😭
  • *FvwmIconMan: [id] PlainColorset colorset — works like plainbutton but uses colorsets instead. The style setting can still only be applied with plainbutton.
  • *FvwmIconMan: [id] ReliefThickness num — num is an integer for how many pixels thick the relief at the edge of non-flat buttons should be. Setting it to 0 produces flat buttons, just as if you'd set the values for FocusAndSelectButton, FocusButton, IconAndSelectButton, IconButton, PlainButton, SelectButton, and TitleButton all to flat. And if num is negative, the button gets inverted, as if you'd used Reverse for all classes. 💅
  • *FvwmIconMan: [id] Resolution [filter(s)] — a list of filters, separated by spaces, that configures which windows get displayed. If you give it no filters, then all windows of the appropriate type are shown (check the show and dontshow options below for that). Each filter then limits which windows are displayed, and can take one of these values: desk, page, screen, !desk, !page, !screen, or invert. desk only shows windows on the current desk, and page only shows windows on the current page. !desk and !page only show windows not on the current desk or page respectively. And invert reverses the filter, displaying the windows that did not match. 🌀
Notes, bestie, and these ones actually matter: page and desk are independent. If the only filter is page, then you'll see windows on the current page on all desks. To only see windows on the current page and desk (which is the default), you need both filters: 'desk page'. You can only have one of desk/!desk, page/!page, or screen/!screen — the last one issued takes precedence. The invert filter reverses the whole filter, so 'invert desk page' is not the same as '!desk !page'. And sticky windows are visible on all pages and desks, so they match all page and desk filters — but they won't match the inverted filter. 🫶

The filters can also take additional parameters to state which desk, page, or screen to show (or not show). [!]desk [n] can take the desk number, which will only show windows (not) on the stated desk. [!]page [x] [y] can take the horizontal x and vertical y page numbers, which will only show windows (not) on the stated page.

[!]screen [S] shows windows (not) on monitor S, which can be:

  • NAME: the "NAME" of the specific RandR monitor. 💖
  • c: the current RandR monitor (containing the pointer)
  • p: the primary RandR monitor
  • g: the global monitor

Since all windows are on the global monitor, screen g effectively does nothing — iconic behavior honestly. c is the current monitor at the time resolution is issued, and once it's set it will not change. So this filter is best used with a RandR NAME. 👑

Also: this configuration line is respected while FvwmIconMan is running as well — the resolution gets changed dynamically when sent to fvwm. 🌈

  • *FvwmIconMan: [id] Reverse class — causes certain classes of buttons to have their relief lines reversed, so that up and down styles get swapped. This has no affect on flat buttons. class can be icon, normal or none. The default is none. 🙈
  • *FvwmIconMan: [id] SelectButton style [forecolor backcolor] — same as the plainbutton option, but describes the look of buttons when the mouse is over them. 🖱️
  • *FvwmIconMan: [id] SelectColorset colorset — works like selectbutton but uses colorsets instead. The style setting can still only be applied with selectbutton. 💜
  • *FvwmIconMan: [id] Shape boolean — bestie if this is True, the window gets shaped 💅. Ngl it's probably only useful if you've got multiple columns or rows going on. So here's the tea: if FvwmIconMan wasn't compiled with support for the Shape extension, this just throws an error message at you. And when you are using shaped windows, pls pls make a fvwm style for FvwmIconMan that has no borders — otherwise fvwm gets confused and that's not the vibe 🫠
  • *FvwmIconMan: [id] Sort value — sorts the manager list, iconic behavior honestly. Your options:
    • name — sorts by name ✨
    • namewithcase — sorts by name, but case-sensitive this time 👀
    • id — sorts by the window id, which fr never changes once the window is created, no cap
    • weighted — sorts by weight (go read the sortweight description below, it's right there)
    • none — no sorting at all, chaotic but valid 💀

Default is name.

  • *FvwmIconMan: [id] SortWeight weight pattern-list — gives the specified weight to windows that match pattern-list. The list is made up of patterns of the form type=pattern, where type is one of class, resource, title, icon, or screen 🎀 and pattern is an expression in the same format used in the fvwm style command (that's minimalistic shell pattern matching, iykyk). You can give multiple sort weights. Every window gets matched against the list of sort weights in order, and gets the weight from the first match. Lower-weighted windows go first in the manager list. Example time:
*FvwmIconMan: Sort weighted
*FvwmIconMan: SortWeight 1 class=XTerm title=special*
*FvwmIconMan: SortWeight 10 class=XTerm
*FvwmIconMan: SortWeight 5

So in this example: xterm windows whose titles start with "special" (weight 1) are listed first 💖, then everything that isn't an xterm (weight 5), and the other xterms (weight 10) are dead last. If no default weight (empty pattern list) is given, the default weight is 0. This is only relevant if the sort type is set to weighted, so don't come crying if it does nothing otherwise.

  • *FvwmIconMan: [id] Title title-string — sets the window title string for that manager window. Titlestring can be a single word, or a string wrapped in quotes. Default is "FvwmIconMan". It gets drawn in the title bar of the manager window (if there is one) and in the title button, which is the button drawn when the manager is empty 🎀
  • *FvwmIconMan: [id] TitleButton style [forecolor backcolor] — literally the same as the plainbutton option, but it specifies the look of the title button (the button drawn when the manager is empty). The manager's title is drawn in the title button, cute right?
  • *FvwmIconMan: [id] UseWinList boolean — if true, then it honors the WinListSkip style flag ✨. Otherwise, all windows are subject to possible management according to the show and dontshow lists.

Okay so the next two options control which windows get handled by which managers. A manager can get two lists: one of windows to show, and one of windows to ignore. Here's the breakdown bestie:

  • If only the show list is given, then that manager shows only the windows in the list.
  • If only the DontShow list is given, then the manager shows all windows except those in the list.
  • If both lists are given, then a window is shown if it is not in the DontShow list, and it's in the Show list.
  • And finally, if neither list is given, the manager handles all windows, slay 💅

Each list is made up of patterns of the form type=pattern, where type is one of class, resource, title, or icon, and pattern is an expression of the same format used in the fvwm style command (minimalistic shell pattern matching, again). Quotes around the pattern will be taken as part of the expression, so watch out for that 😭. And if a window could be handled by more than one manager? Then the manager with the lowest id gets it. Periodt.

  • *FvwmIconMan: [id] Show pattern list — if a window matches one of the patterns in the list, then it may be handled by this manager 🫶
  • *FvwmIconMan: [id] DontShow pattern list — if a window matches one of the patterns in the list, then it may not be handled by this manager 🙅
  • *FvwmIconMan: [id] ShowTransient boolean — show transient windows in the list (default false).
  • *FvwmIconMan: [id] ShowOnlyIcons boolean — only iconified windows are shown if boolean is true.
  • *FvwmIconMan: [id] ShowNoIcons boolean — only windows that are not iconified are shown if boolean is true.
  • *FvwmIconMan: [id] ShowOnlyFocused boolean — only the window with the focus is shown if boolean is true 🌸

The following two options control tips, and honestly? They're the main character energy of this whole page.

  • *FvwmIconMan: [id] Tips value — where value can be always, needed or false. Default is false, meaning no tips are displayed. With always, tips are enabled, periodt. With needed, a tip is displayed only if either the button string is truncated or the tip string is not equal to the button string. And get this — this configuration line is respected when FvwmIconMan is running as well, so no restart needed 💖
  • *FvwmIconMan: [id] TipsDelays delay [mappeddelay] — where delay and mappeddelay are time out values in milliseconds. If no mappeddelay is given, delay is assumed. Default is 1000 300. So when the cursor is on a button, FvwmIconMan waits delay milliseconds before displaying the tip ✨. And in the case where a tip is already mapped and the cursor goes to another button, FvwmIconMan waits mappeddelay milliseconds before displaying the new tip.
  • *FvwmIconMan: [id] TipsFont fontname — specifies the font to be used for tips. Default is the default fvwm font.
  • *FvwmIconMan: [id] TipsColorset colorset — specifies the colors for the tips window. Default is colorset 0.
  • *FvwmIconMan: [id] TipsFormat formatstring — similar to the Format option, but for the tips window. The default is the format string from the Format option 🎀
  • *FvwmIconMan: [id] TipsBorderWidth pixels — specifies the border width (in pixels) of the tips window. Default is 1.
  • *FvwmIconMan: [id] TipsPlacement value — where value can be up, down, right, left, updown or leftright. This value specifies the position of the tips window relative to its button 🦋. Default is updown, where buttons on the top half of the screen get tips below the button, otherwise the tips are above the button.
  • *FvwmIconMan: [id] TipsJustification value — where value can be leftup, rightdown or center. Specifies the justification (direction) of the tips window relative to its button after the tips window has been placed ✨. Default is leftup, which means that if a tip is placed above or below its button, then the left border of the tip and of the button are aligned. If the tip is placed on the left or on the right of its button, leftup aligns the top borders. rightdown and center work like leftup but in different directions. And the alignment is adjusted by the TipsOffset option — see the next option, it's right there 👇
  • *FvwmIconMan: [id] TipsOffsets placementoffset justoffset — where placementoffset and justoffset are offsets in pixels for the TipsPlacement and TipsJustification configuration option. Default is 3 2.

🎀 ACTIONS 🎀

Okay bestie, this is the part where it gets fun. Actions are literally just commands you can bind to an event. And there are three flavors of event: a key press, a mouse click, or the mouse entering a window manager button — those are called action types Key, Mouse, and Select. Slay.

Normally, actions bound to a mouse click run the instant the button goes down. But in transient mode? The action runs when the button is released, because the assumption is that FvwmIconMan got bound to some mouse event. And here's a tip slash warning, pay attention: FvwmIconMan is still keeping track of the mouse button and any modifier keys in this case. So if you bind FvwmIconMan to, say, meta-button3, then it would be wise for you to make sure that the action you want executed will actually fire when the meta-button3 event occurs (which would be the button release, assuming you kept your finger on the meta key). Don't say I didn't warn you 💅

The syntax for actions are:

Key actions: Key Keysym Modifiers FunctionList
Mouse actions: Mouse Button Modifiers FunctionList
Select actions: Select FunctionList
  • For Key actions, Keysym and Modifiers are exactly the same as for the fvwm Key command.
  • For Mouse actions, Button and Modifiers are exactly the same as for the fvwm Mouse command.

And a FunctionList? That's a sequence of commands separated by commas. They get executed in left to right order, all in one shared context — which, currently, only contains a pointer to the "current" button. Here's the tea: if a button is selected (typically because the mouse pointer is sitting on it) when the action is executed, then the current button gets initialized to that button. Otherwise, it points to nothing. Rough, I know. 🫠

Most of the available commands then modify this "current" button — either by moving it around, making it become the selected button, or sending commands to fvwm acting on the window represented by that button. Important note, bestie: while this current button is initialized to be the selected button, the selected button does not implicitly follow it around. That's a feature, not a bug! It means the user can send commands to all kinds of windows without changing which button is selected. Iconic behavior honestly.

Commands take five types of arguments: Integer, Manager, Window, Button, and String. A String is a string specified exactly as for fvwm — either in quotes or as a single word not in quotes. And again, you may bind a sequence of commands to an event by listing them separated by commas.

So here's the confusing bit. Window and Button types look exactly the same in the .fvwm2rc file, but they're interpreted as either specifying a managed window, or a FvwmIconMan button representing a window. They can either be:

  • an integer — which gets interpreted modulo N where N is the number of buttons, so 0 is the first and N-1 is the last, or
  • one of these strings: Select, Focus, Up, Down, Right, Left, Next, Prev.

Let's break those down:

  • Select and Focus refer to the currently selected or focused button or window.
  • Up, Down, Right, and Left refer to the button or window above, below, to the right of, or to the left of the current button in the manager window — allowing you to navigate around the manager window. It's giving ✨directional✨.
  • Next and Prev designate the window, button, or manager after or before the current button, allowing navigation of the one dimensional list of windows which is drawn in the manager window. And if the manager is sorted, Next and Prev move through the windows in the sorted order. Keep that in mind.

Now the Manager type can either be an integer, Next, or Prev. The meaning is analogous to that of the Button type, but in terms of the integral index of the managers, restricted to managers which are nonempty.

The following functions are currently defined:

  • bif Button Integer/String — a relative branch instruction, bestie. If Button is Select or Focus, then take the branch if there is a selected button or a focused button. If Button is an integer, then branch if nonzero. If it's one of Up, Down, Right, Left, Next, Prev, then the branch is taken when the current button can move in that direction. If the branch is taken, then Integer commands are skipped. And no backwards branches are allowed. Periodt.
  • bifn Button Integer/String — the complement of bif. The branch is taken if Button evaluates to false, by the criteria listed for bif.
  • gotobutton Button — sets current button to Button. If Button is an integer, then the current button is set to Button modulo the number of buttons, in whichever manager contains the selected button, if any.
  • gotomanager Manager — sets button to button 0 of Manager. This will only go to a visible, nonempty manager. So an integral argument is taken modulo the number of such managers.
  • jmp Integer/String — executes a relative jump of Integer instructions. Backwards jumps are not allowed. The jump is computed relative to the instruction following the jmp.
  • label String — provides a label that previous instructions can jump to. It will not be visible to subsequent jump instructions, and the same label can be used multiple times in the same instruction list (though it would be perverse to do so, and honestly? respect the chaos 🍓).
  • print String — prints String to the console. Useful for debugging actions.
  • printdebug — prints defined actions to the console. Should only be used by developers. To enable this command, set CONFIG and FUNCTIONS variables to '1' in the modules/FvwmIconMan/debug.h and recompile this module.
  • quit — quits FvwmIconMan.
  • refresh — causes all manager windows to redraw themselves.
  • ret — stop executing the entire action.
  • searchback String — sets button to button before the current one whose printed string in the manager window matches specified String, which may contain wildcards.
  • searchforward String — sets button to button after the current one whose printed string in the manager window matches specified String, which may contain wildcards.
  • select — selects the current button, if any. If a select action has been specified, it will then be run. Therefore, it is considered unwise to set the select button in the select action. (Not me warning you twice. 🫶)
  • sendcommand Command — sends the fvwm command Command to the window represented by the current button, if any.
  • warp — warps cursor to current button, if any.

🌸 Examples 🌸

gotobutton select, gotobutton Down, select

Selects the button below the currently selected button. Since the current button is already initialized to the selected button, this may be shortened to gotobutton Down, select.

gotobutton Up, select

Selects the button above the currently selected button.

gotobutton 0, select

Selects the first button of the current manager. If there is no current manager, which is the case when no button is selected, then this does nothing.

gotobutton -1, select

Selects the last button of the current manager.

gotobutton focus, select

Selects the button corresponding to the focused window.

gotobutton focus, Iconify

Sends the fvwm command Iconify to the focused window. Note that this does not change the selected button.

bif Next 3, gotobutton 0, select, ret, gotobutton Next, select

If a button is selected, and it's the last button, go to button 0. If it's not the last button, go to the next button. Otherwise, do nothing. Basically, this action cycles through all buttons in the current manager.

bif select 7, bif focus 3, gotomanager 0, select, ret, gotobutton focus, \
select, ret, gotobutton down, select

This is good for sending to FvwmIconMan with a SendToModule command. If there is a selected button, it moves down. Otherwise, if there is a focused button, it is selected. Otherwise, button 0 of manager 0 gets selected.

bif select Select, bif focus Focus, gotomanager 0, select, ret, label Focus, \
gotobutton focus, select, ret, label Select, gotobutton down, select

Same as previous, but using the label instruction.

In addition to being bound to keys and mice, actions can be sent from fvwm to FvwmIconMan via the SendToModule command. Don't quote the command when using SendToModule. Also, due to a bug in the current version of fvwm, don't quote FvwmIconMan either. 💀 Yeah. That's just how it is right now.

💖 SAMPLE CONFIGURATIONS 💖

Okay bestie, here's where it gets fun. First up: the absolute bare-minimum baby invocation of FvwmIconMan — one single manager, handling literally every window. Simplest possible slay ✨

##############################################################
# Load any modules which should be started during
# fvwm initialization
ModulePath /usr/lib/X11/fvwm:/usr/bin/X11
Module FvwmIconMan

# Make FvwmIconMan title-bar-less, sticky, and give it an icon
Style "Fvwm*"      Icon toolbox.xpm,NoTitle,NoHandles,Sticky
Style "FvwmIconMan" HandleWidth 5, Handles, BorderWidth 5

##############################################################
##############################################################
#Definitions used by the modules

*FvwmIconMan: NumManagers        1
*FvwmIconMan: Resolution         global
*FvwmIconMan: Background         slategrey
*FvwmIconMan: Foreground         white
*FvwmIconMan: Font               7x13
*FvwmIconMan: ButtonGeometry     100x0
*FvwmIconMan: ManagerGeometry    1x0-0+0

Next up is the Reader's Digest version of the author's personal config — like, the ✨condensed✨ cut. It's got two managers: one just for emacs, and one for everything else, minus the stuff that has no icon title. Only windows on the current page get shown. Heads up though, using the drawicons and shape options means fvwm and FvwmIconMan both have to be compiled with the right options, no cap 🫶. And peep how geometry and show options are set per manager, while all the others are shared across everybody:

Style "FvwmIconMan"  NoTitle, Sticky, WindowListSkip, BorderWidth 0
Style "FvwmIconMan"  HandleWidth 0

Key F8 A N SendToModule FvwmIconMan bif select Select, bif focus Focus, \
  gotomanager 0, select, sendcommand WarpToWindow, ret, label Focus, \
  gotobutton focus, select, sendcommand WarpToWindow, ret, label Select, \
  gotobutton prev, select, sendcommand WarpToWindow
Key F9 A N SendToModule FvwmIconMan bif select Select, bif focus Focus, \
  gotomanager 0, select, sendcommand WarpToWindow, ret, label Focus, \
  gotobutton focus, select, sendcommand WarpToWindow, ret, label Select, \
  gotobutton next, select, sendcommand WarpToWindow

*FvwmIconMan: NumManagers 2
*FvwmIconMan: Resolution  page
*FvwmIconMan: Background  steelblue
*FvwmIconMan: Foreground  white
*FvwmIconMan: Font        7x13
*FvwmIconMan: UseWinList  true
*FvwmIconMan: DrawIcons   true
*FvwmIconMan: Shape       true
*FvwmIconMan: FollowFocus true
*FvwmIconMan: Sort        name
*FvwmIconMan: PlainButton          up white steelblue
*FvwmIconMan: SelectButton         down white steelblue
*FvwmIconMan: FocusButton          up white brown
*FvwmIconMan: FocusAndSelectButton down white brown
*FvwmIconMan: TitleButton          raisededge white steelblue
*FvwmIconMan: NoIconAction         "SendToModule FvwmAnimate animate"

*FvwmIconMan: 1 Title           "Emacs windows"
*FvwmIconMan: 1 IconName        "FvwmIconMan: Emacs"
*FvwmIconMan: 1 Format          "%i"
*FvwmIconMan: 1 Show            resource=emacs resource=gemacs
*FvwmIconMan: 1 ManagerGeometry 1x0-400+0
*FvwmIconMan: 1 ButtonGeometry  200x0

*FvwmIconMan: 2 Title           "All windows"
*FvwmIconMan: 2 IconName        "FvwmIconMan: all"
*FvwmIconMan: 2 Format          "%c: %i"
*FvwmIconMan: 2 DontShow        icon=Untitled
*FvwmIconMan: 2 ManagerGeometry 2x4-0+0
*FvwmIconMan: 2 ButtonGeometry  200x0

*FvwmIconMan: transient Geometry 194x100
*FvwmIconMan: transient DontShow icon=Untitled
*FvwmIconMan: transient Action   Mouse 0 A sendcommand select select Iconify

*FvwmIconMan: Action        Mouse        1 N sendcommand Iconify
*FvwmIconMan: Action        Mouse        2 N sendcommand WarpToWindow
*FvwmIconMan: Action        Mouse        3 N sendcommand "Module FvwmIdent FvwmIdent"
*FvwmIconMan: Action        Key        Left  N gotobutton Left, select
*FvwmIconMan: Action        Key        Right N gotobutton Right, select
*FvwmIconMan: Action        Key        Up    N gotobutton Up, select
*FvwmIconMan: Action        Key        Down  N gotobutton Down, select
*FvwmIconMan: Action        Key        q     N quit

🚧 UNFINISHED BUSINESS 🚧

Okay so there's one bug the author knows about, and honestly a real actual fix for it would be so appreciated 😭. Here's the tea: when an icon manager is set to grow upwards or leftwards, on some machines it might just… wander occasionally. It's giving lost in the sauce. Not iconic behavior, we know 💀

Also, it doesn't handle windows without resource names as gracefully as it should. Like, it tries, but bestie… it could do better 🙈

👑 AUTHOR 👑

Brady Montz (bradym@cs.arizona.edu). Legend behavior, fr fr 💜

🌈 THANKS 🌈

Major shoutout to everyone who contributed either code or truly keen ideas (their words, and honestly? iconic phrasing):

  • David Berson berson@cs.pitt.edu
  • Gren Klanderman greg@alphatech.com
  • David Goldberg dsg@mitre.org
  • Pete Forman gsez020@compo.bedford.waii.com
  • Neil Moore amethyst@maxwell.ml.org
  • Josh M. Osborne stripes@va.pubnix.com
  • Adam Rice <wysiwyg@glympton.airtime.co.uk,
  • Chris Siebenmann cks@hawkwind.utcs.toronto.edu
  • Bjorn Victor victor@delial.docs.uu.se

And that's the whole page, bestie!! 🎀 This one's from the FVWMICONMAN(1) manual, dated 2026-07-31 — so go forth, configure your icon managers, and absolutely slay the geometry 💅✨ 🦋 🌸 💖

📦 where this page comes from