FreeBSD Manual Pages
WIDERIVER(1) User Manuals WIDERIVER(1) NAME wideriver - tiling window manager for the river wayland compositor SYNOPSIS wideriver [OPTION...|COMMAND...] DESCRIPTION Tiling window manager for the river wayland compositor, inspired by dwm and xmonad * Per-tag state * Master/stack(s) left, right and wide layouts * Monocle with alternate borders * Layout toggling * Dwindling, diminishing and even stacks * Inner, outer and smart gaps Layout Symbol Master Stack Directions ---------------------------------------------------- Left a aaax Left Right Down, Right Right aaax a Right Left Down, Left Top aaa~aax Top Bottom Right, Down Bottom aaa'aax Bottom Top Right, Up Wide aaax aaax Mid Left Up, Left Right Down, Right Monocle a n a All - - QUICK START $XDG_CONFIG_HOME/river/init Set server side decorations. Required to display borders on all windows. riverctl rule-add ssd Set the layout generator and start it. All defaults shown here, none are required. Log file is strongly recommended. # set layout manager riverctl default-layout wideriver # start layout manager wideriver \ --layout left \ --layout-alt monocle \ --stack dwindle \ --count-master 1 \ --ratio-master 0.50 \ --count-wide-left 0 \ --ratio-wide 0.35 \ --no-smart-gaps \ --inner-gaps 0 \ --outer-gaps 0 \ --border-width 2 \ --border-width-monocle 0 \ --border-width-smart-gaps 0 \ --border-color-focused "0x93a1a1" \ --border-color-focused-monocle "0x586e75" \ --border-color-unfocused "0x586e75" \ --log-threshold info \ > "/tmp/wideriver.${XDG_VTNR}.${USER}.log" 2>&1 & Create some command mappings e.g. riverctl map normal $mod1 up send-layout-cmd wideriver "--layout monocle" riverctl map normal $mod1 down send-layout-cmd wideriver "--layout wide" riverctl map normal $mod1 left send-layout-cmd wideriver "--layout left" riverctl map normal $mod1 right send-layout-cmd wideriver "--layout right" riverctl map normal $mod1 Space send-layout-cmd wideriver "--layout-toggle" riverctl map normal $mod1 plus send-layout-cmd wideriver "--ratio +0.025" riverctl map normal $mod1 equal send-layout-cmd wideriver "--ratio 0.35" riverctl map normal $mod1 minus send-layout-cmd wideriver "--ratio -0.025" riverctl map normal $mod2 plus send-layout-cmd wideriver "--count +1" riverctl map normal $mod2 equal send-layout-cmd wideriver "--count 1" riverctl map normal $mod2 minus send-layout-cmd wideriver "--count -1" riverctl map normal $mod2 e send-layout-cmd wideriver "--stack even" riverctl map normal $mod2 w send-layout-cmd wideriver "--stack dwindle" riverctl map normal $mod2 i send-layout-cmd wideriver "--stack diminish" EXAMPLE LAYOUTS AND STACKS Left, Dwindle riverctl send-layout-cmd wideriver "--layout left --stack dwindle --count 1 --ratio 0.5" Master Stack ____________________________________________________________ | | | | | | | | 2 | | | | | | | | 1 |_____________________________| | | | | | | | 4 | | | 3 |______________| | | | | | | | | 5 | 6 | |____________________________|______________|______|_______| The master area occupies half of the available space and contains one view. The stack is filled in a diminishing manner in a downward then rightward directions. 2 may be moved into the master area with riverctl send-layout-cmd wideriver "--count +1" and will be evenly placed below 1. Right, Even riverctl send-layout-cmd wideriver "--layout right --stack even --count 2 --ratio 0.55" Stack Master ____________________________________________________________ | | | | | | | 3 | 1 | |_________________________| | | | | | |________________________________| | 4 | | |_________________________| | | | 2 | | | | | 5 | | |_________________________|________________________________| The master area occupies 55% of the available width and contains two views split evenly. The stack is split evenly and is filled in a downwards direction. Wide, Diminish riverctl send-layout-cmd wideriver "--layout wide --stack diminish --count 3 --ratio 0.4" Left Stack Master Right Stack ________________________________________________________________________________ | 1 | | | |______________________| | | | | | 5 | | 2 | | | | | |_______________________| |______________________| | | | | 4 | 6 | | | | | | | |_______________________| | 3 | | 7 | | | |_______________________| |______________________|_______________________________|__________8____________| The master area occupies 40% of the available with and contains one view. The left stack contains 3 views, the right stack the remainder. The left and right stacks each occupy 30% of the available width. 5 may be moved into the master area with riverctl send-layout-cmd wideriver "--count +1". 4 will be placed at the "top" of the stack, below 3. Monocle riverctl send-layout-cmd wideriver "--layout monocle" ____________________________________________________________ | | | | | | | | | | | 1 | | 2 | | 3 | | 4 | | 5 | | 6 | |__________________________________________________________| Only the currently focused view will be visible. LAYOUTS The symbol is the layout name which may be shown in a status bar such as Waybar's river/layout module. Dynamic settings are available via COMMANDS ratio and count are persisted per tag and shared by all layouts except wide, which has its own values. stack is persisted per tag and shared by all layouts. When multiple tags are focused, the state is persisted for only the lowest tag. Left / Right One master area occupying the full height of the available area with a stack area to the left or right. ratio is the proportion of the available area occupied by master. count is the number of evenly evenly stacked views in the master area. Left: a aaax when count > 0 otherwise aaaaax Right: aaax a when count > 0 otherwise aaaaxa Wide One master area occupying the full height of the available area with a stack area to the left and the right. ratio is the proportion of the available area occupied by master. Stacks occupy half of the remaining area. count is the number of views in the left stack. Master is centred when there are left and right stacks, otherwise it ex- pands into the area that would be occupied the empty stacks. aaax aaax when count > 0 otherwise aa aaax Monocle Only one view is focused, occupying all of the available space. a n a with n showing number of views only when greater than 1. STACK ARRANGEMENTS 3 arrangements are available for the stack area. It is persisted per tag and applied to all layouts for that tag. See above for an example of each arrangement. Stacks follow one or two directions determined by the layout. Even This is the "traditional" arrangement with uniformly sized stack views. Arranged in a column or row in the first stack direction only. Diminish Arranged in a column or row in the first stack direction only. Height or width diminishes according to the view's position in the stack: 2p / (n^2 + n) n number of views in the stack p position in the stack Dwindle Arranged in a dwindling manner alternating in both stack directions. Each view occupies half the available / remaining area. GAPS Gaps, in pixels, between windows may be injected. They are off by default. --inner-gaps (i) are between windows. --outer-gaps (o) are between the edge of the screen and windows. --smart-gaps automatically hides the gaps when there is only one view or monocle layout. --border-width-smart-gaps the border width for when smart gaps hides the gaps, excluding monocle layout. For a seamless experience, set this to the same value as --border-width-monocle ---------------------------------------------------------- | o o o o o o o o o o o o | | ---------------------- ----------------------- | | o | | i | | o | | | | | | | | o | | i | | o | | | | ----------------------- | | o | | i i i i i i i o | | | | ----------------------- | | o | | i | | o | | | | | | | | o | | i | | o | | ---------------------- ----------------------- | | o o o o o o o o o o o o | ---------------------------------------------------------- OPTIONS --layout monocle|left|right|top|bottom|wide Initial layout, default left. --layout-alt monocle|left|right|top|bottom|wide Initial alternate layout, default monocle. Use --layout-toggle to switch to alternate layout. --stack even|diminish|dwindle Initial stacking method, default dwindle. --count-master count Initial number of views in the master area, default 1, minimum 0. Does not apply to wide layout. --ratio-master ratio Initial proportion of the width or height the master area occupies, default 0.5, minimum 0.1, maximum 0.9. Does not apply to wide lay- out. --count-wide-left count Initial number of views in the wide layout's left stack area, de- fault 1, minimum 0. You may wish to set this to 0 for a more nat- ural or intuitive feel when launching the first two views. --ratio-wide ratio Initial proportion of the width the wide layout's master area occu- pies, default 0.35, minimum 0.1, maximum 0.9. The default value is best suited to ultrawide monitors, a value of 0.5 may be more useful for 16:9 monitors. --(no-)smart-gaps Automatically hides the gaps when there is only one view or monocle layout. --inner-gaps pixels Inner gaps width, default 0, minimum 0. --outer-gaps pixels Outer gaps width, default 0, minimum 0. --border-width pixels Border width for all layouts except monocle, default 2, minimum 0. --border-width-monocle pixels Border width for monocle layout, default 0, minimum 0. --border-width-smart-gaps pixels Border width for when smart gaps hides the gaps for all layouts ex- cept monocle, default 0, minimum 0. Has no effect if --no-smart-gaps. --border-color-focused 0xRRGGBB[AA] Border color for focused views in all layouts excluding monocle, de- fault 0x93a1a1. Set to an empty string leave border colors un- changed: --border-color-focused "" --border-color-focused-monocle 0xRRGGBB[AA] Border color for focused view in monocle layout, default 0x586e75. It is recommended to set this to the unfocused color or a darker colour as an always focused border can be distracting. Set to an empty string leave border colors unchanged: --border-color-fo- cused-monocle "" --border-color-unfocused 0xRRGGBB[AA] Border color for unfocused views in all layouts, default 0x586e75. Does not apply for monocle layout. Set to an empty string leave border colors unchanged: --border-color-unfocused "" --log-threshold debug|info|warning|error|fatal Minimum log level, default info. COMMANDS When multiple tags are focused, the command is applied to and persisted for only the lowest tag. --layout monocle|left|right|top|bottom|wide Set layout persistently for the tag, updating the alternate layout. --layout-toggle Set layout to the alternate (previous) for the tag. --stack even|diminish|dwindle Set stacking method persistently for the tag. Applies to all lay- outs for the tag. --count [+-]count Increment, decrement or set the master count, minimum 0. For wide layout this is instead the left stack count. Discrete value for wide and all other layouts are persisted per tag. Prefix with + to increment, - to decrement, or an absolute value. --ratio [+-]pixels Increase, decrease or set the master ratio: the proportion of the width or height the master area occupies, minimum 0.1, maximum 0.9. Discrete tiling and wide values persisted per tag. Prefix with + to increase, - to decrease, or an absolute value. RECIPES Wide Shuffling You can "shuffle" views through master, focusing the new master using: riverctl send-layout-cmd wideriver '--count +1' && riverctl focus-view next" riverctl send-layout-cmd wideriver '--count -1' && riverctl focus-view pre- vious" FAQ Name Does Not Always Update The layout name will not update when there are no views for the selected tags. This can occurs when setting a tag with no views or changing the layout for a tag with no views. This may be resolved with a river enhancement: #1004 Borders Are Not Shown Please ensure you have enabled server side decorations i.e. the borders: riverctl rule-add ssd You can still use client side decorations for specific applications e.g.: riverctl rule-add -app-id audacity csd Random Pixels In Gaps When Using Fractional Scaling This is a known river and wlroots issue: https://code- berg.org/river/river/issues/816 Workaround: set a river background colour other than default black 0x000000 riverctl background-color "0x010101" is sufficiently close. ISSUES Problems Please raise a Bug Report Ideas Please create a Feature Request Questions or Discussions Please raise an Issue Contributions CONTRIBUTING.md is most gratefully appreciated. SEE ALSO https://github.com/alex-courtis/wideriver AUTHORS Alexander Courtis. wideriver 2025/07/15 WIDERIVER(1)
NAME | SYNOPSIS | DESCRIPTION | QUICK START | EXAMPLE LAYOUTS AND STACKS | LAYOUTS | STACK ARRANGEMENTS | GAPS | OPTIONS | COMMANDS | RECIPES | FAQ | ISSUES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=wideriver&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>