.TH RIVERGUILE 1 2023-11-25 "git.sr.ht/~leon_plickat/riverguile" "General Commands Manual"
.
.SH NAME
.P
riverguile \- scheme powered layout generator for river
.
.
.SH SYNOPSIS
.SY riverguile
.YS
.
.
.SH DESCRIPTION
.P
Layout generator for the
.BR river (1)
Wayland server which allows users to define layouts using guile scheme functions.
.
.P
The layout namespace is \fBriverguile\fB.
.
.P
Uppon launch, riverguile tries to eval a scheme script and checks the following
paths for it in the given order:
.IP  \(bu 2
\fBlayout.scm\fR
.IP  \(bu 2
\fB$XDG_CONFIG_HOME/river/layout.scm\fR
.IP  \(bu 2
\fB$HOME/.config/river/layout.scm\fR
.IP  \(bu 2
\fB/etc/riverguile/layout.scm\fR
.
.P
In the context of this script, a special procedure
\fB(install-handler \fR\fIkey\fR \fIproc\fR\fB)\fR is available, which can be
used to install handlers to certain events.
The parameter \fIkey\fR is a symbol indicating for which event to install
the procedure \fIproc\fR.
.P
The key \fBlayout-demand\fR installs a handler for layout demands, which must
accept five required arguments, which are, in order: The amount of views in the
layout (integer), the available width (integer), the available height (integer),
the currently active tag set (integer representing a bitfield of size 32)
and the global name of the output the layout is needed for (integer).
The procedure must return a list containing exactly as many lists as there are
views in the layout.
Each of those sublists must contains exactly four numerical values, which are
the x and y coordinates of the window as well as its width and height.
Window positions and dimensions get applied to rivers window list top to bottom.
Note that the numerical values do not need to be exact, riverguile takes care
of rounding and casting for you.
.P
The key \fBuser-command\fR install a handler for user commands, which are the
strings a user can send to layout generators.
This handler procedure must accept three arguments, which are, in order:
The command (string), the currently active tags (integer representing a
bitfield of size 32) and the global name of the output (integer).
This event can be used to change paramters of the layout.
A new layout demand will be send right after this event.
.
.
.SH EXAMPLE
.P
This is an example configuration, which installs a layout that simply assigns
each window all usable space and a user command handler that tries to evaluate
all send commands as scheme code.
.
.P
.RS
.EX
(install-handler 'user-command (lambda (cmd tags output)
                                 (eval-string cmd)))

(install-handler 'layout-demand (lambda (view-count width height tags output)
                                  (letrec ((iter (lambda (n)
                                                   (if (eq? 0 n)
                                                       '()
                                                       (append (list (list 0 0 width height))
                                                               (iter (1- n)))))))
                                    (iter view-count))))
.EE
.RE
.
.
.SH SEE ALSO
.BR river (1),
.BR riverctl (1),
.BR rivertile (1),
.BR guile (1)
.
.
.SH AUTHOR
.P
.MT leonhenrik.plickat@stud.uni-goettingen.de
Leon Henrik Plickat
.ME