diff options
| -rw-r--r-- | build.zig | 1 | ||||
| -rw-r--r-- | doc/river-layouts.1.scd | 74 | ||||
| -rw-r--r-- | doc/riverctl.1.scd | 9 |
3 files changed, 82 insertions, 2 deletions
@@ -210,6 +210,7 @@ const ScdocStep = struct { const scd_paths = [_][]const u8{ "doc/river.1.scd", "doc/riverctl.1.scd", + "doc/river-layouts.1.scd", }; builder: *std.build.Builder, diff --git a/doc/river-layouts.1.scd b/doc/river-layouts.1.scd new file mode 100644 index 0000000..92fc2db --- /dev/null +++ b/doc/river-layouts.1.scd @@ -0,0 +1,74 @@ +RIVER-LAYOUTS(7) "github.com/ifreund/river" + +# NAME +river-layouts - Details on layout generators for river + +# DESCRIPTION +River can use external window management layouts. To get such a layout, river +will run an executable and parse its output. This document outlines how such +a layout generator interacts with river. + +# INPUT +When running the executable, river will provide it with five parameters which +are appended to the end of the command in the following order: + +. The amount of visible clients (integer) +. The amount of views dedicated as master (integer) +. The screen size multiplier for the master area (float between 0.0 and 1.0) +. The useable width of the output (integer) +. The useable height of the output (integer) + +A layout generator may choose to ignore any of these values except +for the first one. + +# OUTPUT +River expects four integer values for each window: The x position, the y +position, the width and the height. These must be separated by spaces. A +window configuration having fewer or more than four values is an error and will +cause river to fall back the full layout. + +A layout generator needs to output position and size for every visible window. +The window configurations are separated by a newline. Too few or too many +outputted window configurations is an error and will cause river to fall back +to the full layout. + +River will apply the position and dimensions in the order they are outputted to +the visible windows in the stack from top to bottom. + +The output of a layout generator is not required to remain the same when called +with identical parameters. Layouts are allowed to also depend on external +factors or be completely random. + +# WINDOW DIMENSIONS and POSITION +Layout generators are not supposed to include padding or leave space for window +borders. The window dimensions will be shrunk by river to make space for these. +River enforces a minimal window width and height of 50. + +Layout generators operate on a special coordinate grid from 0 to the maximum +useable width or height of an output with the coordinate 0-0 being positioned at +the top-left corner of the useable area of an output. While layout generators +are free to place windows everywhere (including coordinates below zero or above +the maximum width or height of an output), beware that the relative positioning +of this grid on the screen can not be expected to remain constant. River applies +an offset to window positions, depending on outer padding and the presence of +desktop widgets like bars. Layout generators can therefore not position windows +at exact screen coordinates. + +Layout generators are not required to make use of the entire available space. +Windows may overlap. + +# EXAMPLE +Below is an example output of a layout generator for four visible windows. In +this example layout all four windows have a size of 500 by 500 and are arranged +in a grid. + +``` +0 0 500 500 +500 0 500 500 +0 500 500 500 +500 500 500 500 +``` + +# SEE ALSO +*river*(1), *riverctl*(1) + diff --git a/doc/riverctl.1.scd b/doc/riverctl.1.scd index d5fe7ee..98fb583 100644 --- a/doc/riverctl.1.scd +++ b/doc/riverctl.1.scd @@ -31,8 +31,13 @@ used to control and configure river. *focus-view* *next*|*previous* Focus next or previous view in the stack. -*layout* *top-master*|*right-master*|*bottom-master*|*left-master*|*full* - Change the view layout. +*layout* *full*|_command_ + Provide a command which river will use for generating the layout of + non-floating windows on the currently focused output. See + *river-layouts*(1) for details on the expected formatting of the output + of layout commands. Alternatively, "full"can be given instead of a + command to cause river to use its single internal layout, in which + windows span the entire width and height of the output. *mod-master-count* _integer_ Increase or decrease the number of master views. _integer_ can be |