121 lines
4.3 KiB
Groff
121 lines
4.3 KiB
Groff
.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.
|
|
A layout demand handler must be installed, otherwise riverguile will exit.
|
|
.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.
|
|
.P
|
|
The key \fBidle:X\fR installs a handler which is called when the system has been
|
|
idle for \fIX\fR seconds.
|
|
As an example, use \fBidle:300\fR if you wish to be notified of your system
|
|
being idle for five minutes.
|
|
Idle in this case relates to user interaction;
|
|
The system being idle for five minutes usually means there has been no input
|
|
from the user in five minutes.
|
|
Idle status however can also be influenced by other factors, for example by
|
|
other programs inhibiting it (like video players), special sensors (user
|
|
presence sensors) and is generally server-specific policy.
|
|
The handler procedure must accept one argument, a symbol indicating the type
|
|
of idle event.
|
|
This symbol is either \fBidle\fR, indicating the system has been idle for the
|
|
configured amount of time, or \fBresume\fR, indicating that the time intervall
|
|
of the system being idle is over.
|
|
Multiple idle handlers can be installed.
|
|
Note: All idle events relate to the first advetised seat.
|
|
As of now, river only supports a single seat anyway.
|
|
.P
|
|
The key \fBexit\fR installs a handler which is called when riverguile exits.
|
|
The procedure takes no arguments.
|
|
.
|
|
.
|
|
.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
|