neoflux - a Fluxbox-style window manager for X11 with grouping, a
slit, and chord keybindings
neoflux [--replace]
neoflux
{--check-config|--whats-new|--version|--help}
neoflux is a reparenting window manager for X11, written in
Rust, in the spirit of Fluxbox. It wraps each managed window in a decorated
frame and adds three signature features:
- Window grouping /
tabbing
- Windows can be merged into a single frame and switched between with tabs.
On the focused window the active tab takes 50% of the title bar's tab band
and the rest share the other half (see tab-min-width to keep them
readable); on unfocused windows all tabs are the same width (see
tab-unfocused).
- The slit
- A WindowMaker-style dock for dockapps (wmclock,
wmsystemtray, and the like), with up to four slits, one per screen
edge.
- Chord
keybindings
- Emacs / PekWM-style multi-key shortcuts: press a leader key, then a second
key from a chord table.
neoflux is configured entirely through plain-text TOML files in
~/.config/neoflux/, which are re-read live by the reconfigure
action. It speaks enough EWMH / ICCCM to cooperate with panels, pagers,
wmctrl(1), and xdotool(1).
- --replace,
-replace
- Take over from a window manager already running on this display, via the
ICCCM manager selection (it asks the running WM to step down). Use this to
switch to neoflux from a terminal without ending the X session.
- --check-config
- Read the configuration files exactly as a start or a reconfigure
would and report every problem found — a TOML error or unknown key
(which voids that whole file), a binding whose key or action is not
understood, a theme that cannot be loaded, a window rule that would match
every window — then exit: status 0 if there are none, 1 otherwise.
It starts nothing and touches no running session, so it is safe to run
before pressing Reconfigure. (The Xresources overlay is not consulted; it
needs an X server.) The on-screen banner shows only the first problem and
a count; this lists them all.
- --whats-new
- List the configuration keys and default bindings each version added
(newest first) and exit. The same list, filtered to what is new since the
version that last ran, is shown once as an on-screen banner after an
upgrade.
- --version,
-V
- Print the version and exit.
- --help,
-h
- Print a usage summary (options, config and log paths) and exit.
Any other argument is an error (exit status 2).
On first run neoflux seeds a starter set of files in
~/.config/neoflux/. Any of these you delete is recreated at the next
fresh login (not on a restart). All use the same TOML format and are
optional; keep everything in config.toml or break pieces out. The
files are merged in memory as overlays — there is no file
include directive.
Your files are never rewritten, so they drift behind new releases:
a missing key simply takes its built-in default, but a [keys] or
[chords] table replaces the defaults wholesale, so new default
bindings do not reach an existing keys.toml. To catch up, neoflux
rewrites ~/.config/neoflux/defaults/ on every fresh start with the
reference files shipped in the running binary (the starter set, the themes,
and config.example.toml with every key documented) — always
current, never read by neoflux, never to be edited. After an upgrade a
banner notes how many config changes arrived; neoflux --whats-new
lists them, and diff -u defaults/keys.toml keys.toml shows exactly
what your file lacks.
- config.toml
- The main file; may hold any and all settings. Loaded after the Xresources
overlay.
- theme.toml
- Appearance overlay (border colours, [titlebar], [grips],
...). Loaded below config.toml, so config.toml still wins on
conflicts. Seeded as a symlink to the active
themes/<name>.toml; the desktop menu's “Themes”
submenu repoints it.
- keys.toml
- [keys], [chords] and the chord-leader / argument keys.
Loaded last, so it wins.
- The [[menu]] root menu (the Fluxbox menu equivalent). Loaded
after config.toml, so its menu replaces config.toml's.
- startup
- A shell script run once at login. See STARTUP below.
- slitlist
- Pins dockapp order within the slit (one WM_CLASS per line). Maintained
automatically by the slit menu's Move Up / Move Down; you may also edit
it.
- themes/<name>.toml
- The theme library. Pick one via the “Themes” menu (which
repoints theme.toml) or the theme = "..." key.
Bundled: bora-black (the default), conky-colors,
zenburn, the seasonal autumn, winter, spring,
summer, halloween and festive, and
high-contrast (black on white) and high-contrast-dark
(yellow and white on black). Missing bundled themes are re-created at
startup; your edits to existing ones are kept. Fonts and sizes set in
config.toml's [titlebar] and [menu-style] override
every theme.
A bare key = value line must come before the first
[section] header (a TOML rule); sections may then appear in any
order. Colours are "#rrggbb" (also
"0xrrggbb" or "rrggbb"). Booleans are
true / false. An unparseable file is skipped with the rest of
the config left intact, and the error is logged and shown in an on-screen
banner at startup / reconfigure.
Bare top-level keys (set in config.toml). Appearance keys
marked (theme) normally live in theme.toml; setting them in
config.toml pins them over the theme.
- mod-key = super
- The default modifier referred to as $mod/mod in bindings.
One of super, alt, control, shift.
- focus =
click
- Focus model: click (click to focus), sloppy (focus follows
the pointer but stays on the last window while the pointer is over the
bare desktop), or follows-mouse (strict: over the bare desktop no
window has the focus). Panels and desktop-icon windows never take the
focus this way.
- click-raises =
true
- A click in a window's content raises it as well as focusing it. Set
false to focus only; a press on the title bar or border, and a
bound Super+button, still raise.
- auto-raise =
false
- auto-raise-delay =
300
- With sloppy or follows-mouse focus, raise the window the
pointer rests on after this many milliseconds (0 = at once). Moving
on before the delay runs out cancels it.
- focus-new-windows =
true
- Give a newly opened window the focus. Set false and it opens under
the window in use, marked as wanting attention (see ATTENTION),
unless no window has the focus or it is a dialog of the window in
use.
- prevent-focus-stealing
= false
- What a program's request to activate one of its own windows does.
true only marks the window as wanting attention; requests from
taskbars, pagers, rofi and wmctrl still switch to it.
- scale = 1.0
- One multiplier for HiDPI screens (0.5 to 4): title-bar height, fonts,
border, grips, corner radius, the pager, gaps and the snap distance are
all multiplied by it after the theme and config are read, so themes stay
written in plain pixels. Open windows pick up a new scale on Restart.
Dockapps and window contents are not scaled (use --size for the
flux dock apps and Xft.dpi for applications).
- placement =
center
- Where a window that does not position itself opens: center,
cascade, or none. Windows that request a position are always
honored. center / cascade use the monitor under the pointer.
- Draw the built-in clickable desktop pager (bottom-left). Set false
to remove it entirely.
- tab-click =
focus-and-tab
- What clicking a tab does: focus-and-tab or keep-tab.
- auto-group =
off
- Auto-tabbing of new windows: off; same-class tabs a new
window into an existing window of the same WM_CLASS; all tabs every
new normal window into the current one, so there is always a single tabbed
window and its tab strip serves as the taskbar (next-tab /
prev-tab switch). Dialogs, transient windows,
utility/toolbar/splash/notification/dock/desktop windows and anything a
[[window-rule]] skip-grouping names stay separate.
auto-group-same-class = true is the older spelling of
same-class.
- confirm-quit =
true
- Pop an “are you sure?” confirmation before the quit
action logs you out. Set false for an immediate exit.
- fullscreen = cover
- What a fullscreen request produces — a client's
_NET_WM_STATE_FULLSCREEN, map-time state such as mpv --fs,
or the fullscreen action. cover spans the whole monitor
above the slits (the EWMH default, “movie mode”);
fill spans only the free area, so slits and their dockapps stay
visible and clickable. Either way the client is told it is fullscreen.
Override per window with [[window-rule]] fullscreen; pick a mode
explicitly with the movie and fill actions.
- cycle-minimized =
true
- Include minimized windows in the Super+Tab switcher. Keep this on when
using hidden desktops: a window minimized on a hidden desktop appears in
the window list only while you are on that desktop, so the switcher is its
keyboard recovery path — switch to that desktop and cycle to it,
and it restores in place (a lone minimized window is restored by a single
press).
- theme =
<name>
- Load themes/<name>.toml explicitly. A bare name maps into
themes/; a path or .toml is used as-is. This takes
precedence over the theme.toml symlink, so the Themes picker
will appear not to work while it is set. Normally left unset.
- border-width = 2
(theme)
- Window border thickness in pixels.
- border-color =
#555555 (theme)
- border-color-focused
= #4488cc (theme)
- Unfocused / focused window border colours.
- desktop-color =
#2e3440 (theme)
- Solid root-window colour shown where no background image or command
paints.
- chord-leader =
Super+x
- The chord leader key (see CHORDS).
- argument-key =
Super+u
- The universal-argument prefix (see UNIVERSAL ARGUMENT). The old
name chord-leader-u is still accepted with a warning; a
[chords-u] table is ignored.
Edge and window snapping.
edges includes the edges of the free area: a window snaps against a slit
or a panel as it does against the screen edge.
Optional. Overrides snap.gap. screen = gap to
monitor edges; window = gap between windows. Honored by snap and
maximize.
The Fluxbox-style resize handle.
- edges =
bottom
- Which grabbable resize strip(s): none, top, bottom,
both.
- width = 8
- Strip thickness, px (floor 2).
- corner =
28
- Diagonal corner-zone length at each end, px.
Rounded frame corners (needs the X SHAPE extension; ignored if
absent). The border wraps the title bar, so rounding top rounds the
title bar's top corners. Maximized / fullscreen windows are always
square.
The title-bar look and button layout. Colour / font / height keys
are (theme) keys.
- height = 20
(theme)
- Title-bar height, px.
- bg = #333333
(theme)
- bg-focused = #4488cc
(theme)
- Unfocused / focused title-bar colour (top of the gradient).
- bg-to = ...
(theme)
- bg-focused-to = ...
(theme)
- Optional gradient bottoms; omit for a flat fill.
- fg = #eeeeee
(theme)
- Title text and button-glyph colour.
- font = sans-serif
(theme)
- A single family or a CSS-style preference list (["Source Sans
3", "sans-serif"]); the first installed family
wins. Generic names always resolve.
- font-size = 11.0
(theme)
- In pixels (no DPI scaling). Floored at 1.
- left = []
- right =
["minimize", maximize , close ]
- Title-bar buttons per side, left-to-right. Kinds: close,
maximize, minimize, shade, stick,
menu.
- tab-min-width =
0
- Minimum width (px) for the non-active tabs in a group. The active tab
normally takes 50%; if that would shrink the others below this floor, the
active tab gives up space so they stay readable, and the active tab itself
never drops below the floor. 0 disables the floor (pure 50% split).
When even the floor cannot fit every tab, all tabs split evenly below it
(a one-time note is logged).
- tab-unfocused =
equal
- Tab widths on an unfocused bar: equal (all tabs the same
width — the "active" tab there is only what will show
once the group is focused, so it gets no extra room and is easier to hit)
or active-half (the focused-bar 50% layout everywhere).
- tab-dim =
0.55
- tab-dim-focused =
1.0
- Brightness factors for the non-active tabs, multiplied into
bg / bg-to: tab-dim on an unfocused bar (whose active
tab shows plain bg), tab-dim-focused on a focused bar (whose
active tab shows bg-focused). 1.0 = unchanged, below 1 darker,
above 1 lighter (clamped). On a dark theme, darkening is nearly invisible
— lighten instead, e.g. tab-dim = 1.6. Theme keys.
Per-button themed images go in
[titlebar.buttons.<kind>] tables with image (base),
focus, and pressed PNG paths; missing variants fall back to
image, and with no image the built-in vector glyph is
drawn.
Popup-menu appearance (root, window, and slit menus). Colours come
from [titlebar]; only font and font-size (px) are
separate, and both default to the title bar's. Row height scales with the
font size.
- count = 4
- Number of virtual desktops (1–64).
- names = ["1", 2
, 3 , 4 ]
- Per-desktop names (used in menus and the pager).
- hidden =
[]
- 1-based desktops reachable only by their explicit keybind: skipped by
next/prev cycling and the window menus. Their windows are also left out of
_NET_CLIENT_LIST (what rofi's window mode, taskbars and wmctrl
-l show) except while that hidden desktop is the current one. To also
hide them from an external pager, make them the last desktops (e.g.
count=8, hidden=[7,8]; with [[workspaces.monitor]]
blocks, the last desktops of the last block) — EWMH desktops
are contiguous, so only a trailing block drops off the pager.
- backgrounds =
[]
- Per-desktop background: a .png path (set as the root image) or a
shell command, e.g. "feh --bg-fill ~/wall.png". With
independent monitors (below) each monitor shows its own current desktop's
image, composited into one root image; a shell command cannot be split per
monitor and paints whatever it paints.
- edge-drag =
true
- Dropping a dragged window hard against the outer left or right screen edge
sends it to the previous / next desktop and follows it. Set false
to make that an ordinary move.
Give one output its
own desktops, independent of
the primary monitor's (the i3/xmonad model): switching desktops on one monitor
leaves the other's windows where they are. Each block appends a contiguous
range after the desktops defined so far, so with
count=4 above and a
4-desktop block the second monitor owns desktops 5–8 (the total is
capped at 64). A monitor without a block mirrors the primary (the classic
one-big-desktop behaviour), so the default is unchanged. See
DESKTOPS.
- output =
DP-2
- The RANDR output/monitor name, as printed by xrandr --listmonitors.
Required. Naming the primary output is a no-op (the block folds into the
primary). An output that is absent costs nothing: its desktops are dormant
until it appears (see DESKTOPS), so list every output a laptop
might dock to.
- count =
4
- Desktops in this block (1–64).
- names =
[]
- hidden =
[]
- backgrounds
= []
- As for [workspaces], but monitor-local: hidden = [2]
hides this monitor's second desktop, whatever its global number. Unnamed
desktops get their global number.
Root (right-click) menu entries; an array of tables. Replaces the
default single “Terminal” item. May live in menu.toml
instead. Each entry has label plus either command or a nested
submenu, and optionally icon:
- command =
firefox
- Selecting the entry runs this shell command.
- icon =
/path/to/icon.png
- Image drawn to the left of the label. PNG only; a bad path just renders no
icon (with a note in the log).
- [[menu.submenu]]
- Nested entries (same keys; nests freely, e.g.
[[menu.submenu.submenu]]). The parent entry needs no
command: it becomes a drill-in picker — marked with a
trailing arrow, opened in place with a leading “back” row
— like the built-in Themes menu.
neoflux-menugen(1) generates a categorized menu.toml
(one submenu per application category, with icons) from the installed
applications' .desktop files.
Up to four slit definitions (a list replaces the four-edges
default). Each has edge
(top/right/bottom/left) and optional size
(omit = auto-size to the largest dockapp; a number pins a fixed width, min
8). See THE SLIT.
Route dockapps to a slit by WM_CLASS. Each has class and
either slit = N or slits = [N, ...] (0-based). With a list,
each new instance of the class fills the next listed slit.
Per-window rules (the Fluxbox apps equivalent). Match on
class (WM_CLASS class), name (WM_CLASS instance), and/or
title (case-insensitive substring); all present matchers must match.
Then apply any of: desktop (1-based), sticky,
maximized, shaded, above, skip-grouping,
decor (none/border/normal), fullscreen
(cover/fill: this window's fullscreen policy, overriding the
top-level key), x, y, width, height.
Mouse bindings added to the built-in defaults (last match wins, so
they override). See MOUSE.
Keyboard bindings and chords. ([chords-u] is retired; see
UNIVERSAL ARGUMENT.) A binding that cannot be understood is
reported on screen at start and on reconfigure, and by
--check-config. A [keys] / [chords] table
replaces the built-in set wholesale. See KEYBINDINGS and
CHORDS.
A binding maps a combo to an action: "Mod+Mod+key" =
"action". Modifier tokens are super, alt,
control (ctrl), shift, and $mod/mod (the
configured mod-key); mod4/win and mod1 are
accepted aliases. The key is an X keysym name (Tab, Return,
Right, F1, a letter/digit, an XF86... multimedia name,
or ASCII punctuation by its keysym name — bracketleft,
semicolon, grave, as xev(1) prints them — or
simply the character itself: [, ;, `. Only +
must be spelled plus, since it separates the tokens.) An unrecognized
modifier or key name is rejected and logged rather than silently
dropped.
- spawn:CMD
- Run a shell command.
- send:COMBO
- Synthesize a key combo to the focused window (whatever application it is),
e.g. "Super+Shift+Right" =
"send:ctrl+Page_Down" for the next browser tab. The window
receives exactly COMBO: any modifiers you are still holding from
the trigger binding (that Super+Shift) are released around the synthetic
keystroke and restored afterwards, so they do not leak into it.
- desktop:N
- Switch to desktop N (1-based).
- move-to-desktop:N
- Move the focused window to desktop N (1-based).
- move-to-monitor:WHICH
- Move the focused window to another monitor — next /
prev (left to right, wrapping), a 1-based index, or an output name
(DP-2) — keeping its offset within the monitor, onto the
desktop that monitor is showing. The pointer follows. Maximized /
fullscreen windows are restored first.
- focus-monitor:WHICH
- Put keyboard focus on another monitor (same WHICH forms): its
top-most window, or nothing if it is empty. That monitor becomes the
target of the desktop actions and the pointer moves there, so new windows
open on it.
- close
- Politely close the focused window.
- kill
- Force-kill the focused window at once: its process is sent SIGKILL when it
runs on this machine and names a plausible process ID, and its X
connection is closed either way. (close is the polite form; a
second close on a window that did not answer the first also
escalates to this.)
- quit,
exit
- Leave neoflux (guarded by confirm-quit).
- reconfigure,
reconfig, reload
- Re-read every config file and re-apply the keymap and decoration colours
live.
- restart
- Re-exec neoflux in place (keeps your windows; does not re-run
startup).
- cancel
- Abort an in-progress chord (the Emacs C-g of neoflux).
- center,
center-both, center-horizontal,
center-vertical
- Center the focused window on its monitor. The center-free-*
variants center it in the monitor's free area instead — what
is left after the slits, panels and the screen gap.
- next-tab,
prev-tab
- Cycle tabs within the focused group.
- move-tab-left,
move-tab-right
- Shift the focused tab one slot along its group's bar (also offered in the
tab icon's right-click menu).
- next-window,
prev-window (focus-next, focus-prev)
- Cycle windows on the current desktop, on every monitor. See WINDOW
SWITCHER.
- next-window:monitor,
prev-window:monitor
- The same switcher limited to the monitor you are on. See WINDOW
SWITCHER.
- last-window
(focus-last)
- Jump back to the previously focused window; pressed repeatedly it flips
between the two most recent windows.
- detach
- Detach the focused tab into its own window.
- desktop-next,
desktop-prev
- Switch to the next / previous visible desktop.
- toggle-sticky
- Toggle showing the window on all desktops.
- picture-in-picture,
toggle-above
- Toggle always-on-top for the focused window.
- minimize,
iconify
- Minimize the focused window.
- maximize,
toggle-maximize
- Toggle maximize (fill the monitor's free area).
- fullscreen,
toggle-fullscreen
- Toggle fullscreen in the configured mode (top-level fullscreen key
or the window's rule): cover the whole monitor, or fill the free area
leaving the slits visible. No decoration either way.
- movie,
fullscreen-cover
- Toggle “movie mode”: fullscreen covering the whole monitor,
above the slits. From a fill-mode fullscreen window this promotes it, and
a second press drops back to fill rather than to a normal window.
- fill,
fullscreen-fill
- Toggle fill-mode fullscreen (the free area only). From movie mode it
switches rather than exits.
- root-menu,
window-menu, window-list
- Open the root menu or the go-to-window list at the pointer, or the focused
window's operations menu at its title bar, with the first row highlighted
(see MENUS for the keys that drive an open menu).
- focus-slit:left|right|top|bottom|N|next|prev
- Park keyboard focus on a dockapp: the first one in the slit on that edge
(or slit N, 0-based like --dock N), or
next/prev — from a window, the first non-empty slit;
while parked, the next/previous dockapp along the slit. See THE
SLIT.
- shade,
toggle-shade
- Toggle window shading (roll up to the title bar).
- show-desktop,
toggle-show-desktop
- Toggle _NET_SHOWING_DESKTOP (minimize all / restore).
- lock-window,
lock, stay-focused
- Lock the screen to the focused window, or unlock it again. See WINDOW
LOCK.
- move-left:N,
move-right:N, move-up:N,
move-down:N
- Nudge ("scootch") the focused window N pixels in that
direction (nudge-* are aliases). Maximized and fullscreen windows
stay put. Bound by default as chords: Super+x then an arrow key
moves 5 px.
- grow-width:N,
shrink-width:N, grow-height:N,
shrink-height:N
- Resize the focused window by N pixels from the keyboard; the
top-left corner stays put. A window that resizes in steps (a terminal's
character cells) changes by at least one step. Not bound by default.
- tile:left,
tile:right, tile:top, tile:bottom
- tile:top-left,
tile:top-right, tile:bottom-left,
tile:bottom-right
- Fit the focused window to a half or a quarter of its monitor's free area
(clear of slits, panels and the screen gap; the two halves are [gaps]
window apart). The same action again on a window already there puts it
back where it was before it was tiled.
- focus-urgent
- Go to the window that is asking for attention, switching desktop if
needed. See ATTENTION. Not bound by default.
A key that sits on the shifted level of its key can be named
directly: "Super+plus" is the same as
"Super+Shift+equal" on a US layout.
Super+Return spawn:xterm
Super+Shift+q quit
Super+Shift+c close
Super+c center-both
Super+Tab next-window
Super+Shift+Tab prev-window
Super+grave next-window:monitor
Super+Shift+grave prev-window:monitor
Super+Alt+Tab last-window
Super+Right next-tab
Super+Left prev-tab
Super+Control+Right move-tab-right
Super+Control+Left move-tab-left
Super+Shift+Right desktop-next
Super+Shift+Left desktop-prev
Super+F1..F4 desktop:1..4
Super+1..4 move-to-desktop:1..4
Super+s shade
Super+Shift+s toggle-sticky
Super+f fullscreen
Super+Shift+f movie
Super+m maximize
Super+n minimize
Super+Alt+Left tile:left
Super+Alt+Right tile:right
Super+Shift+l lock-window
With more than four desktops, raise count and add
Super+F5.. / Super+5.. bindings to match.
A chord is a leader key followed by a single key from a chord
table. Press chord-leader (default Super+x), release, then
press a key listed in [chords]. The chord values are the same action
strings as keybindings; cancel (or any unbound key) aborts. A bare
modifier press never cancels a pending chord, so Super+x followed by
a Super+-key works.
Default [chords] (after Super+x):
c close
space center-both
d detach
p picture-in-picture
r root-menu
m window-menu
w window-list
s focus-slit:next
g cancel
Left move-left:5
Right move-right:5
Up move-up:5
Down move-down:5
argument-key (default Super+u) is neoflux's Emacs
C-u: press it, optionally type digits, then run any keybinding or
chord, and that binding receives the number. A banner shows the argument as
you type it. What a binding does with it:
- move-left/right/up/down,
grow-/shrink-width/height
- Typed digits replace the binding's pixel count; the bare prefix
multiplies it by 4 per press. So Super+u 4 0 Super+x Left
nudges 40 px, Super+u Super+x Left nudges 20 px (5×4),
Super+u Super+u Super+x Left 80 px.
- desktop:N,
move-to-desktop:N
- Typed digits pick the desktop instead: Super+u 3 Super+F1 goes to
desktop 3, Super+u 6 Super+1 sends the window to desktop 6 (handy
past the bound F-keys). The bare prefix leaves the binding's own target
alone.
- next-tab,
prev-tab, next-window, prev-window (and their
:monitor forms), desktop-next, desktop-prev
- Repeat that many times (bare prefix = 4): Super+u 3 Super+Tab skips
ahead three windows.
Every other action ignores the argument. Any other key (g,
Escape, an unbound key) abandons it; the digits are typed without
modifiers (keypad digits also count), and Super+u pressed after
digits is ignored.
A [[mouse]] entry has context, button,
optional mods, and action. Context is root,
titlebar, or window. Button is 1=left, 2=middle, 3=right,
4/5=wheel. mods uses the same modifier tokens as keybindings (empty =
none). Actions: move, resize, group (tab),
raise, lower, shade, maximize, minimize,
close, window-menu (menu), window-list
(clientmenu), root-menu, next-tab, prev-tab,
spawn:CMD, none.
Built-in defaults:
titlebar L=move M=lower R=window-menu
window Super+L=move Super+M=group Super+R=resize
root M=window-list R=root-menu
In a tabbed group, a plain left-click on a tab switches to it and
a plain drag moves the whole window. To reorder tabs, hold the
modifier: Super+left-drag (the window-context move binding)
started on a tab slides that tab along the bar without moving the window;
dragged clearly off the bar, the tab detaches into a window of its
own that follows the pointer, and releasing over another window's title bar
(Super still held) groups it into that window. To move a whole tabbed window
with the modifier, Super+left-drag its body.
A plain left-drag on a titled window's bare border (outside the
grips) resizes toward the pressed edge, widening to a diagonal within
corner px of a frame corner — it never moves the window.
Moving with the mouse is a title-bar (or Super+drag) gesture only. A window
with no title bar keeps the configured title-bar action on its border, since
that border is its only mouse handle.
While a resize drags (modifier drag or grip), a small popup at the
window's center shows the live dimensions: in pixels, or — for a
client that declares resize increments in WM_NORMAL_HINTS (terminals,
emacs) — in the client's own units (columns x rows), as in
Fluxbox.
next-window / prev-window (default Super+Tab /
Super+Shift+Tab) cycle windows on the current desktop in stacking
order, top to bottom: from the top window, next-window steps to
the one below it, working toward the least-recently-raised, then wraps. The
order is frozen for the duration of a tab sequence so each press marches
down the stack rather than bouncing between the top two; it re-reads the
stack whenever focus moves by other means. With cycle-minimized set,
minimized windows are included (focusing one restores it in place). When the
desktop's only window is minimized, a press restores and focuses it rather
than doing nothing for want of a second window to cycle to.
These switchers take in every monitor (each showing its own
desktop when [[workspaces.monitor]] gives it one), as Alt+Tab does on
most desktops. next-window:monitor / prev-window:monitor
(default Super+grave / Super+Shift+grave, the key above Tab) cycle only the
monitor you are on: the one the focused window is on, or the one under the
pointer when nothing is focused. A window belongs to the monitor its frame
overlaps most. Pressing the other switcher in the middle of a sequence
starts a fresh one.
Switch with desktop:N / desktop-next /
desktop-prev, and send the focused window with
move-to-desktop:N. Dragging a window to the left or right
screen edge moves it to the adjacent desktop (skipping hidden ones). After a
switch, focus goes to the top-most normal window on the target desktop
(always-on-top / picture-in-picture windows are skipped unless they are the
only thing visible).
Hidden desktops ([workspaces] hidden) are reachable
only by their explicit keybind and never appear in next/prev cycling, the
desktop rows of the window menu, Send to desktop, or — when
placed as a trailing block — external pagers. Their windows stay
secret too: a window on a hidden desktop is left out of the window menu and
of the Group with / Merge group with pickers (and of
_NET_CLIENT_LIST) except while that hidden desktop is the current
one. A window minimized on a hidden desktop is recovered via the Super+Tab
switcher with cycle-minimized on (see WINDOW SWITCHER), or
from the window menu once you are on that desktop.
Independent monitors. By default every monitor shows the
same desktop, as one wide desktop spanning them all. A
[[workspaces.monitor]] block gives an output its own desktop range
with its own current desktop, so e.g. desktop:6 switches only the
monitor that owns desktop 6 and moves keyboard focus there (the top-most
window on that monitor, or nothing if it is empty), while the other monitor
keeps showing what it was showing. desktop-next / desktop-prev
cycle within the desktops of the focused monitor — the one
holding the focused window, or the one last switched or clicked on —
and wrap within that range. move-to-desktop:N onto another
monitor's desktop slides the window over to that monitor at the same offset;
move-to-monitor:next does the same without naming a desktop, and
focus-monitor:next moves keyboard focus across (neither is bound by
default). Dragging (or nudging) a window onto another monitor makes it join
the desktop that monitor is showing, so it stays put there. Dragging to a
screen edge changes desktop only at an outer edge; the seam between
two monitors is just part of the move. The built-in pager shows one strip
per monitor with that monitor's desktops. New windows join the current
desktop of the monitor they open on. Sticky windows stay visible
everywhere.
EWMH has a single current desktop, so _NET_CURRENT_DESKTOP
(what external pagers and wmctrl -d show) reports the focused
monitor's, and an external pager highlights only that one; clicking a
desktop in it still switches the monitor that owns that desktop. If an
output with its own desktops is unplugged (or was never present — a
laptop's docking monitor), its desktops fold into the primary monitor
until it returns, when they slide back. While folded, an empty
desktop of that set is dormant: absent from next/prev cycling, the
pager, the menus, and the advertised EWMH count, exactly like a hidden
desktop, so an absent monitor adds no phantom desktops. It is still
reachable by desktop:N, and any window on it (one that was
there at unplug time, or one you park there) keeps or brings it in view as
an ordinary primary desktop. Several blocks for outputs that are never
plugged in at the same time are fine. reconfigure also re-enumerates
monitors.
The slit swallows dockapps. By default there are four auto-sized
slits, one per edge, in CSS order, so a dockapp's --dock N (the
flux-dock-apps flag) lands on 0=top, 1=right, 2=bottom, 3=left; a
dockapp with no --dock goes to the right. A dockapp may also set the
_NEOFLUX_SLIT property to pick a slit, and [[slit-rule]]
routes by WM_CLASS. Out-of-range targets are clamped to the last slit.
Right-click a slit for its menu: choose the screen edge it sits on
(live for the session), and — when the click is on a specific dockapp
— Move Up / Move Down to reorder it (persisted to
slitlist) and Send to slit N to move it to another slit
(live for the session; a reconfigure / restart re-routes per rule).
Intra-slit order is pinned by the slitlist file: listed WM_CLASS
names sort first in file order, the rest follow in arrival order.
Keyboard focus in the slit. The focus-slit action
(default chord Super+x then s) parks the X keyboard focus on a
dockapp, so a keyboard, remote control or game pad can drive it: the dockapp
sees FocusIn and draws a ring (the flux dock apps fluxLauncher and
fluxVolume do; arrows move their selection or the level, Return activates),
while the window manager keeps Tab / Shift+Tab to step along
the slit and Escape to hand focus back to the window that had it.
Clicking or switching to any window ends it too. No window is advertised as
active while focus is in the slit.
A window that declares itself a panel
(_NET_WM_WINDOW_TYPE_DOCK: tint2, xfce4-panel, a polybar that is not
override-redirect), a desktop (_NET_WM_WINDOW_TYPE_DESKTOP:
xfdesktop, pcmanfm --desktop) or a notification is treated as furniture
rather than as a window: it keeps the size and place it asks for, has no
title bar, is on every desktop, stays out of the window switcher and the
window list, is not focused when it appears or when the pointer passes over
it (a click still focuses it), cannot be dragged, minimized or hidden by
show-desktop. Panels and notifications are kept above other windows
and a desktop window below them; a fullscreen window in cover mode
goes over panels while it has the focus. A panel's reserved edge
(_NET_WM_STRUT) is honoured while the panel is showing.
A dialog (WM_TRANSIENT_FOR) that does not position itself
opens centred on the window it belongs to, and is raised with that window so
it cannot end up underneath it.
A window that asks for attention (the urgency hint,
_NET_WM_STATE_DEMANDS_ATTENTION, or one held back by
focus-new-windows / prevent-focus-stealing) gets a red title
bar, a (!) mark in the window list, and a red band on its desktop's
cell in the pager. Focusing it answers the request; focus-urgent goes
straight to it.
Restart (and the session wrapper's restart after a crash)
keeps tab groups and the tab each was showing, desktops and the desktop each
monitor was on, sticky, shaded, always-on-top, minimized, maximized and
fullscreen windows (and where each returns to when restored), the stacking
order and the focused window. Not kept: the window-switcher history, a
window lock, and windows tiled with tile: remain where they are but
forget where they came from.
The lock-window action (default Super+Shift+l) pins
the screen to the focused window — for handing the keyboard to
someone, letting someone look over your shoulder, or just staying on task.
Every other window is hidden, on every monitor; the locked window keeps its
place and is fully usable (its tabs, maximize, fullscreen, shade, nudge,
close, and anything the application does itself). Its dialogs open and take
focus as usual; any other new window is held hidden until the lock is
released. Desktop switching, window cycling, the menus, spawn,
minimize, sticky, detach, reconfigure, restart and quit are refused with a
reminder banner naming the unlock key. The slits stay visible, so clocks and
meters keep going, but clicks on them are swallowed. The pager strip shows
but does not switch. The same action unlocks; closing the locked window
unlocks too.
This is a courtesy lock, not a security boundary: X11 has no
isolation, so the locked application can still start other programs, a
terminal inside it is a full escape, and the virtual-terminal switch keys
still work. For a real kiosk or screen lock, use a dedicated tool.
Every menu can be driven from the keyboard while it is open:
Up/Down (Page_Up/Page_Down,
Home/End) move the highlight, Return/space run
the highlighted row, Right drills into a submenu, Escape,
Left or XF86Back close the menu, and a letter jumps to the
next row starting with it. The mouse keeps working at the same time. Open a
menu without the mouse with the root-menu, window-menu and
window-list actions (default chords Super+x then r /
m / w); a key-opened menu starts with its first row
highlighted.
- Root menu
- Right-click the desktop (or the middle button for the window list). Shows
your [[menu]] entries plus Themes, Reconfigure,
Restart, and Exit. Exit honors confirm-quit.
- Window
list
- One row per desktop (selecting it switches there), each followed by that
desktop's windows, indented and bulleted, in title order; sticky windows
come last under an All desktops heading. Selecting a window focuses
it, switching desktop if needed. A multi-tab group lists the tab it
currently displays first, in bold, with its other tabs indented beneath
it; minimized windows are italic. Windows on hidden desktops are omitted
unless that desktop is the current one.
- Window
menu
- Per-window operations (the title bar's right-click menu): minimize,
maximize, shade, center, sticky, picture-in-picture, grouping,
send-to-desktop, close, kill.
The startup file is an ordinary shell script
(/bin/sh), run once at a fresh login. Put background helpers
— a wallpaper setter, a panel, a compositor — here, each
backgrounded with a trailing & so the script returns:
feh --bg-fill ~/wallpaper.png &
xfce4-panel &
xterm
Do not end it with exec neoflux (unlike a classic
Fluxbox startup) — neoflux runs the script itself, after it is
already managing the screen. It is interpreted by sh (sh
path), so any #! shebang line is ignored and no execute
bit is required. Its standard output and error are appended to the log file,
so a command that fails there leaves a trace. The script is run detached, so
a final foreground command (no &) blocks only that one line,
never the window manager; and it is not re-run on a restart
(the NEOFLUX_RESTART environment variable marks the re-exec).
- DISPLAY
- The X display to manage.
- NEOFLUX_LOG
- Log verbosity, in the syntax of RUST_LOG: info (the
default), debug, trace, or per-module filters. The log is
~/.local/state/neoflux/neoflux.log (under $XDG_STATE_HOME if
set); once it passes 2 MB it is moved to neoflux.log.1 at the next
start.
- XDG_CONFIG_HOME,
XDG_STATE_HOME
- Override ~/.config (configuration) and ~/.local/state (the
log).
- NEOFLUX_RESTART
- Set to 1 across a restart re-exec so the new instance skips
re-seeding the default config and re-running startup. Not meant to
be set by hand.
- ~/.config/neoflux/config.toml
- Main configuration.
- ~/.config/neoflux/theme.toml
- Active theme (a symlink into themes/).
- ~/.config/neoflux/keys.toml
- Keybindings and chords.
- ~/.config/neoflux/menu.toml
- Root menu.
- ~/.config/neoflux/startup
- Login script.
- ~/.config/neoflux/slitlist
- Dockapp order within the slit.
- ~/.config/neoflux/themes/
- Theme library.
- ~/.config/neoflux/defaults/
- Reference copies of every shipped config file for the installed version,
rewritten on each fresh start. Never read by neoflux; diff against your
own files after an upgrade. Do not edit.
- ~/.local/state/neoflux/last-version
- The version that last ran; drives the one-time post-upgrade banner.
- ~/.local/state/neoflux/neoflux.log
- Runtime log (config-parse warnings, out-of-range indices, and the like
land here).
neoflux-import(1), neoflux-menugen(1),
neoflux-session(1), fluxbox(1), wmctrl(1),
xdotool(1)
neoflux-import(1) converts an existing ~/.fluxbox
configuration (keys, apps, init, menu, slitlist, and styles) into neoflux's
TOML files. neoflux-menugen(1) generates menu.toml from
installed applications. neoflux-session(1) is the display-manager
session wrapper.
neoflux is developed by Chris (OsugiSakae).