____                 _ _        __        __  __  __         [\
  / ___|  ___ _ __ ___ | | |_   _  \ \      / / |  \/  |        [ \
  \___ \ / __| '__/ _ \| | | | | |  \ \ /\ / /  | |\/| |        |  \
   ___) | (__| | | (_) | | | |_| |   \ V  V /   | |  | |        |   \
  |____/ \___|_|  \___/|_|_|\__, |    \_/\_/    |_|  |_|        L-||->
                            |___/                                  L]

A high-performance, backend-agnostic Linux Auto-Scroll utility. It provides a "Middle-click to scroll" experience similar to Windows/Web browsers, featuring a smooth, accelerated scrolling algorithm and a non-intrusive X11 overlay.

---

Usage Demo: Middle-click to trigger auto-scroll

Interface Screenshot: The auto-scroll anchor overlay

The Motivation: Why ScrollyWM?

As a qutebrowser user, I value a minimalist and keyboard-driven workflow. However, the absence of a standard middle-click auto-scrolling feature frequently interrupted the browsing experience.

After recognizing that many Linux applications beyond qutebrowser lack native support for this fluid scrolling method, I developed ScrollyWM as a system-wide solution. By intercepting input at the kernel level, ScrollyWM provides professional, accelerated auto-scrolling to every application on the Linux desktop, including terminals, IDEs, and document viewers.

Features

• Universal Input Proxy: Uses evdev to intercept physical mouse/keyboard events at the kernel level.
• Virtual Input Injection: Uses uinput to create a virtual mouse device, ensuring compatibility across X11, Wayland, and TTY.
• Smart X11 Overlay: A shaped, transparent anchor window that uses XFixes for input passthrough, preventing it from blocking user clicks.
• Accelerated Velocity Logic: Sophisticated scrolling algorithm that scales speed based on distance from the anchor point.
• Configurable: Fully customizable via a TOML configuration file.

How It Works

ScrollyWM operates as a low-level input proxy between your hardware and the operating system:

1. Interception: Upon startup, the utility identifies and "grabs" (claims exclusive access to) all physical mouse devices using evdev. This prevents the original middle-click from reaching X11, effectively suppressing the default "paste" action.
2. Virtualization: It creates a high-fidelity virtual mouse device via uinput. All standard mouse events (movement, left/right clicks) are transparently forwarded to this virtual device to maintain normal system operation.
3. State Detection: When a middle-click is detected, ScrollyWM toggles its internal state to Active. It records the current pointer coordinates and triggers the X11 backend to display an anchor overlay at that position.
4. Calculated Injection: While in the Active state, the utility monitors the relative vertical distance between the current pointer and the recorded anchor. It applies a parabolic acceleration curve to calculate scroll velocity and injects synthetic scroll-wheel events into the kernel via the virtual device.
5. Non-Intrusive UI: The X11 anchor is rendered using XShape for transparency and XFixes to ensure it is "input-transparent," allowing you to click through it if necessary.

Installation and Setup

1. Requirements

• Rust: Latest stable toolchain.
• System Dependencies:
  • libx11-dev, libxext-dev, libxfixes-dev.
  • Kernel support for uinput and evdev.

2. Building

cargo build --release

3. Permissions (Running without sudo)

By default, access to /dev/input/ and /dev/uinput requires root privileges. To run ScrollyWM as a standard user:

Step A: Add user to the input group

sudo usermod -aG input $USER

Step B: Create a udev rule for uinput

Create a new rule file at /etc/udev/rules.d/99-uinput.rules:

echo 'KERNEL=="uinput", GROUP="input", MODE="0660", OPTIONS+="static_node=uinput"' | sudo tee /etc/udev/rules.d/99-uinput.rules

Step C: Reload udev rules and re-login

sudo udevadm control --reload-rules && sudo udevadm trigger
# A logout and login is required for group changes to take effect.

Configuration

The configuration file is located at ~/.config/scrolly-wm/config.toml. It is generated automatically on the first execution.

Recommended Configuration

For optimal fluidity, the following values are recommended:

deadzone = 20           # Pixel radius where no scrolling occurs
sensitivity = 0.002     # Base scroll speed multiplier
acceleration = 1.2      # Parabolic scaling (1.0 = linear, >1.0 = faster curves)
scroll_interval_ms = 10 # Update frequency (10ms = 100Hz)

File Permissions

If the application was previously executed with sudo, the configuration file may be owned by root. Correct this with:

sudo chown -R $USER:$USER ~/.config/scrolly-wm

Usage

Run the binary:

./target/release/scrolly-wm

• Middle-Click: Toggle the auto-scroll anchor.
• Mouse Movement: Scroll up or down relative to the anchor.

Architecture

• src/input_provider.rs: Low-level event monitoring and device grabbing.
• src/scroll_executor.rs: Virtual mouse creation and event injection.
• src/backend_x11.rs: X11-specific window management and overlays.
• src/core_logic.rs: Main state machine and velocity calculations.
• src/config.rs: TOML configuration management.

Roadmap

• X11 Core: Full support for X11 environments with shaped anchors.
• Input Proxy: kernel-level event grabbing to suppress default button actions.
• Config System: Robust TOML-based configuration with sudo-aware path detection.
• Wayland Implementation: Support for Wayland compositors via layer-shell.
• Horizontal Scrolling: Enable side-to-side scrolling based on horizontal distance.
• Visual Customization: Support for custom anchor colors and shapes via config.
• Desktop Entry: Integrated installer to add ScrollyWM to system autostart.

License

This project is licensed under the MIT License - see the LICENSE file for details./home/tiw/Public/scroll