From 25fcd37930e97d67557d0995db25c30e439b349b Mon Sep 17 00:00:00 2001 From: Leon Henrik Plickat Date: Sat, 30 Dec 2023 09:01:52 +0100 Subject: [PATCH] update documentation for new API --- README.md | 33 ++++++--------------------------- doc/riverguile.1 | 1 + 2 files changed, 7 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 6b6db48..8c1c32a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Layout generator for the [river](https://github.com/riverwm/river) Wayland server which uses [Guile Scheme](https://www.gnu.org/software/guile/) for layouts. Its layout namespace is `riverguile`. -Uppon launch, riverguile tries to eval a scheme script and checks the following +Uppon launch, riverguile tries to load a scheme script and checks the following paths for it in the given order: * `layout.scm` @@ -12,30 +12,9 @@ paths for it in the given order: * `$HOME/.config/river/layout.scm` * `/etc/riverguile/layout.scm` -This script must contain the definition of a function -`(layout-demand-handler view-count usable-width usable-height)` and -may contain any other code the user desires. The function must return -a list containing exactly as many lists as `view-count`. 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. - -Example of valid output: - -```scheme -scheme@(guile-user)> (display (layout-demand-handler 3 1080 1920)) -((0 0 594.0 1920) (594.0 0 486.0 960) (594.0 960 486.0 960)) -``` - -Note that the numerical values do not need to be exact, riverguile takes care -of rounding and casting for you. - -You can send riverguile layout-commands, which it will try to eval as scheme code. - -```sh -riverctl map normal Super U send-layout-cmd riverguile "(define gaps 20)" -``` +In the context of this script, a special procedure `(install-handler key proc)` +is available, which can be used to install handlers to certain events. +Check the man page for more information. Here is an example `layout.scm` file replicating rivertiles behavior of having a main window and a stack of windows aside: @@ -61,6 +40,6 @@ a main window and a stack of windows aside: (append (list (list x y left h)) (layout:rows (- n 1) (+ x left) y right h))))) -(define (layout-demand-handler view-count width height) - (layout:split view-count 0 0 width height)) +(install-handler 'layout-demand (lambda (view-count width height tags output) + (layout:split view-count 0 0 width height))) ``` diff --git a/doc/riverguile.1 b/doc/riverguile.1 index 1eba733..842d0c3 100644 --- a/doc/riverguile.1 +++ b/doc/riverguile.1 @@ -50,6 +50,7 @@ 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.