scroll

<img width="256" height="256" src="https://github.com/dawsers/scroll/blob/master/scroll.png" />

scroll is a Wayland compositor forked from sway. The main difference is scroll only supports one layout, a scrolling layout similar to PaperWM, niri or hyprscroller.

video.mp4

scroll works very similarly to hyprscroller, and it is also mostly compatible with sway configurations aside from the window layout. It supports some added features:

• Animations: scroll supports very customizable animations.

• scroll supports rounded borders and title bars, dimming of inactive windows, and dynamic shadows with blur.

• Content scaling: The content of individual windows can be scaled independently of the general output scale.

• Overview and Jump modes: You can see an overview of the desktop and work with the windows at that scale. Jump allows you to move to any window with just some key presses, like easymotion in some editors. There is also a jump mode to preview and switch to any available workspace.

• Workspace scaling: Apart from overview, you can scale the workspace to any scale, and continue working.

• Lua scripting: scroll provides a lua API to script the window manager.

• Several full screen modes: workspace, global, application and layout.

• Trackpad/Mouse scrolling: You can use the trackpad or mouse dragging to navigate/scroll the workspace windows.

• Portrait and Landscape monitor support: The layout works and adapts to both portrait or landscape monitors. You can define the layout orientation per output (monitor).

• For ultra-wide displays, you can split a workspace in two and show them both at the same time (workspace split command).

• Optionally, minimize windows to scratchpad.

For more videos explaining the different features, check the TUTORIAL.

Documentation

This README explains the basic differences between sway/i3 and scroll. For people unfamiliar with i3 or sway, it is advised to read their documentation, as compatibility is very high.

Documentation for i3

Documentation for sway

scroll TUTORIAL

Example configuration

scroll's man pages are the best source of documentation for details on all the commands. They are up to date. Read man 5 scroll for reference on any command or the Lua API. If you haven't installed scroll yet, you can find the source for the manual here.

man 5 scroll
man 1 scroll
man 1 scrollmsg
man 7 scroll-ipc
man scroll-output
man scroll-bar
man scrollnag

The example configuration includes key bindings for most commands, so it is a good source of documentation to see what scroll can do. If you have time, read it carefully with the manual side by side (man 5 scroll), and experiment while customizing it.

Building and Installing

scroll is a stable fork of sway; the build tree is basically the same and the executables are renamed to scroll, "scrollmsg", "scrollnag" and "scrollbar".

scroll uses a modified version of wlroots which is included in the source tree and linked statically. So if you want to build scroll, you will need to install its dependencies plus wlroots's dependencies.

Arch Linux

If you are using Arch Linux, there are two AUR package you can install:

• Stable version: sway-scroll. Currently at 1.12. It corresponds to the development version of sway. You should be able to have any version of sway and scroll installed on the same system and start any of them without problems, as scroll doesn't need any version of wlroots installed on the system, and its executable and file names are different (scroll vs sway).

paru -S sway-scroll

• Unstable, development version: sway-scroll-git. This has all the newest changes and features.

paru -S sway-scroll-git

NOTE: The package sway-scroll-stable has been discontinued and renamed sway-scroll. Please uninstall it and install sway-scroll if you want the stable version.

NixOS

Thanks to @Diax170 for maintaining a nix flake of scroll in his repository, here.

Artix Linux and Arch-derived Distributions not Using systemd

Artix uses elogind instead of systemd's login daemon to provide some services. That means the AUR packages for scroll won't work out of the box. Artix doesn't have a package for scroll in their repository, so if you want to install it, you can either do it manually, or modify the AUR package as explained here.

git clone https://aur.archlinux.org/sway-scroll.git
cd sway-scroll

Apply this patch:

--- a/PKGBUILD
+++ b/PKGBUILD
@@ -19,7 +19,7 @@
 	"libliftoff"
 	"libglvnd"
 	"lcms2"
-	"systemd-libs"
+	"elogind"
 	"opengl-driver"
 	"xcb-util-errors"
 	"xcb-util-renderutil"
@@ -62,7 +62,7 @@

 build() {
   mkdir -p build
-  arch-meson build scroll -D sd-bus-provider=libsystemd -D werror=false -D b_ndebug=true
+  arch-meson build scroll -D sd-bus-provider=libelogind -D werror=false -D b_ndebug=true
   ninja -C build
 }

And make and install the package.

makepkg -si

Void Linux

Thanks to @brihadeesh for setting up a Void linux template for the stable version of scroll on his repo, here.

Post-Installation

After installing either package, prepare a configuration file ~/.config/scroll/config using the provided example (/etc/scroll/config), and you can start scroll from a tty. You can also start scroll from your display manager using the provided /usr/share/wayland-sessions/scroll.desktop.

Building Requirements

If you want to compile scroll yourself, sway compiling instructions apply to scroll. You will also need to install the lua package (version >= 5.4) to enable lua scripting. wlroots is no longer a requirement, as the source is included in the scroll source tree, but you will need its dependencies to be able to build scroll.

meson setup build/
ninja -C build/
sudo ninja -C build/ install

Useful Tips after Installation

Aside from the dependencies listed in the package for your distribution, scroll works best with some additional software to make your life easier, and some extra system configuration for the best possible experience.

XDG Portals

Wayland compositors use portals for added functionality. It is recommended to install xdg-desktop-portal, xdg-desktop-portal-gtk and xdg-desktop-portal-wlr to use with scroll. The last one adds specific functionality for screencasting and video recording. You should also install pipewire if you plan on recording desktop videos or do screencasting.

scroll's AUR package by default installs the file /usr/share/xdg-desktop-portal/scroll-portals.conf which configures what portal to use for each situation. If you install scroll manually, or your distribution package doesn't include that file, you can create it either in the location mentioned above, or in ~/.config/xdg-desktop-portal/scroll-portals.conf, with the following content:

[preferred]
default=gtk
org.freedesktop.impl.portal.ScreenCast=wlr
org.freedesktop.impl.portal.Screenshot=wlr
org.freedesktop.impl.portal.Inhibit=none

Environment Variables

Some application frameworks use special environment variables to decide whether to run in Wayland or X11 mode. Even though scroll is compatible with X11 applications out of the box, running Wayland applications should always be preferred; they will provide a better experience. Try to find Wayland alternatives to your favorite X11 applications, and if you have doubts, use the Discussions board to ask for good alternatives. Any application that works well with sway will also work with scroll.

scroll doesn't let you define environment variables in its configuration file, so you will need to set them before launching scroll, for example in your ~/.bash_profile or the one your shell uses.

# Sway/Scroll needs its environment variables here
# Set GTK theme
export GTK_THEME=Adwaita-dark
# Tell QT, GDK and others to use the Wayland backend by default, X11 if not available
export QT_QPA_PLATFORM="wayland;xcb"
export GDK_BACKEND="wayland,x11"
export SDL_VIDEODRIVER=wayland
export CLUTTER_BACKEND=wayland
# So GTK4 applications work when sending dead keys
export GTK_IM_MODULE=simple

# XDG desktop variables to set scroll as the desktop
export XDG_CURRENT_DESKTOP=scroll
export XDG_SESSION_TYPE=wayland
export XDG_SESSION_DESKTOP=scroll

# Configure Electron to use Wayland instead of X11
export ELECTRON_OZONE_PLATFORM_HINT=wayland

export QT_WAYLAND_DISABLE_WINDOWDECORATION=1 # Disables window decorations on Qt applications
export QT_QPA_PLATFORMTHEME=qt6ct
# This is to (temporarily) fix font rendering on QWebEngineView 6
# (qutebrowser, goldendict etc.)
# https://bugreports.qt.io/browse/QTBUG-113574
export QT_SCALE_FACTOR_ROUNDING_POLICY=RoundPreferFloor

# If you use a Nvidia card
# NVIDIA environment variables
export LIBVA_DRIVER_NAME=nvidia
export GBM_BACKEND=nvidia-drm
export __GLX_VENDOR_LIBRARY_NAME=nvidia

export XCURS