riverguile/doc/riverguile.1

.TH RIVERGUILE 1 2023-11-25 "git.sr.ht/~leon_plickat/riverguile" "General Commands Manual"
.
.SH NAME
.P
riverguile \- scheme powered scripting layer for river
.
.
.SH SYNOPSIS
.SY riverguile
.YS
.
.
.SH DESCRIPTION
.P
Scripting layer for the
.BR river (1)
Wayland server.
Allows the user to send commands to the Wayland server (probably river) and
install handlers for events from a scheme script.
.P
By default, riverguile will exit after the script has been loaded and evaluated.
If certain handlers are installed it will run continously.
.P
Uppon launch, riverguile tries to load the script from the following paths
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
.
.
.SH EVENT HANDLERS
.P
In the context of the script, a special procedure
\fB(install-handler \fR\fIkey\fR \fIproc\fR\fB)\fR is available, which can be
used to install event handlers.
The parameter \fIkey\fR is a symbol indicating for which event to install
the procedure \fIproc\fR.
The following keys are currently evailable:
.
.P
\fBlayout-demand\fR
.P
.RS
Installing a handler for this key allows the user to provide window layouts.
All limitations of the river-layout-v3 protocol apply.
The server will trigger this event when a new layout is required ("demanded").
.P
Installing a layout-demand handler will cause riverguile to run continously.
.P
The handler procedure 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 the window list top to bottom.
.P
Note that the numerical values do not need to be exact, riverguile takes care
of rounding and casting for you.
.P
Here is an example of a simple layout-demand handler which simply makes all
windows use all available space:
.P
.RS
.EX
(\fBinstall-handler\fR 'layout-demand
  (\fBlambda\fR (view-count width height tags output)
    (\fBletrec\fR ((iter (\fBlambda\fR (n)
                     (if (eq? 0 n)
                         '()
                         (\fBappend\fR (\fBlist\fR (\fBlist\fR 0 0 width height))
                                 (iter (1- n)))))))
      (iter view-count))))
.EE
.RE
.RE
.
.P
\fBuser-command\fR
.P
.RS
User commands are intended to send commands to layout generators, allowing the
user to update parameters of the layout live.
Of course, nothing is stopping you from (ab-)using this event to trigger
arbitrary scheme code on keypresses or on outside events, or from simply not
using it at all.
After a user-command has been received, the server can will trigger a
layout-demand if there are visible windows.
.P
Installing a user-command handler will \fInot\fR cause riverguile to run continously.
This event is an extension to the layout-demand event and as such it is invalid
to install a user-command handler without also installing a layout-demant
handler.
.P
The 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).
.P
Here is an example of a simple user-command handler which simply evaluates the
string as scheme code:
.P
.RS
.EX
(\fBinstall-handler\fR 'user-command
  (\fBlambda\fR (cmd tags output)
    (\fBeval-string\fR cmd)))
.EE
.RE
.P
Note that this is not necessarily good practice, but serves as a decent example.
.RE
.
.P
\fBidle:X\fR
.P
.RS
A handler installed for this key will be triggered after the system has been
idle for \fIX\fR seconds and once more once the system is no longer idle.
.P
Installing a layout-demand handler will cause riverguile to run continously.
Multiple idle handlers can be installed.
.P
Idle state is server policy and may depend on a multitude of factors, but
usually maps directly to the usage activity of input devices by the user.
Certain programs may inhibit idle state, like for example video players.
.P
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 system is no
longer idle.
.P
Here is an example which will dim the screen after two minutes of inactiviy
and lock it after fice:
.P
.RS
.EX
(\fBinstall-handler\fR 'idle:120
  (\fBlambda\fR (event)
    (\fBcond\fR ((\fBeq?\fR event 'idle) (\fBsystem\fR "light -S 20"))
          ((\fBeq?\fR event 'resume) (\fBsystem\fR "light -S 100")))))

(\fBinstall-handler\fR 'idle:300
  (\fBlambda\fR (event)
    (if (\fBeq?\fR event 'idle) (\fBsystem\fR "swaylock &"))))
.EE
.RE
.P
Note: All idle events relate to the first advetised seat.
As of now, river only supports a single seat anyway.
.RE
.
.P
\fBexit\fR
.RE
.RS
This key allows you to installs a handler which is called when riverguile exits.
.P
The procedure takes no arguments.
.P
Here is an example which adds a message to the system log on exit:
.P
.RS
.EX
(\fBinstall-handler\fR 'exit
  (\fBlambda\fR ()
    (\fBsystem\fR "logger 'goodbye from riverguile'")))
.EE
.RE
.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