Hyprscroller

⚠️ Archived

I am no longer using Hyprland.

I am moving from Hyprland/hyprscroller to scroll. I decided to fork sway and create a compatible compositor with hyprscroller layout and features.

Hyprland was starting to limit what I could add through a plugin. Updating hyprscroller because of Hyprland changes, and working around API limitations to implement new features was delaying development more than I wanted. Hyprscroller became too brittle and dependant on hacks. Changes upstream could break it very easily.

I chose sway because it is a stable platform, well written, implements all the standard features and it is relatively easy to modify.

Now Hyprscroller is completely integrated, and this allows some quite exciting features to work very easily.

If you are curious about the current state of the project, click here.

Hyprscroller

Hyprscroller is a Hyprland layout plugin that creates a window layout similar to PaperWM.

The plugin is quite feature complete and supports gaps, borders, decorations, special workspace, full screen modes, overview, marks, pinned columns, touchpad gestures, copying/pasting windows, trails/trailmarks, quick jump mode, and installation through hyprpm.

Check the Tutorial for a quick overview of hyprscroller's main features.

I use hyprscroller on my main machine and will support it for as long as I keep on using Hyprland. However, I will only add new features that I find interesting, and support two Hyprland versions: the one my distribution uses, and the latest tagged one. I have found problematic compiling trunk versions of Hyprland on a system that already has a system-wide version of it installed, so I will not make an extra effort there until things improve in that front.

Requirements

hyprscroller supports the version of Hyprland I use, which should be the same as the Arch Linux hyprland package (v0.48.1). You can try your luck with the latest git changes, but I will be slower to keep up with those, as there are too many API changes going on upstream.

Aside from those two versions, even though the feature set will be frozen for them, hyprscroller also supports most official Hyprland releases from v0.35 to the current one.

Building and installing

The easiest and recommended mode to install hyprscroller is through hyprpm

hyprpm

hyprpm add https://github.com/dawsers/hyprscroller
# verify it installed correctly
hyprpm list

You can enable or disable it via hyprpm enable hyprscroller and hyprpm disable hyprscroller or update it using hyprpm update hyprscroller.

Adding exec-once = hyprpm reload -n to your hyprland.conf will ensure all your hyprpm managed plugins will be loaded at startup.

Manually

If you want to build the plugin manually, it should be as simple as running

# builds a shared object hyprscroller.so
make all
# installs the shared library in ~/.config/hypr/plugins
make install

then you can add the plugin to your hyprland.conf

# path must be absolute
plugin = /home/xxxx/.config/hypr/plugins/hyprscroller.so

or load it temporarily using hyprctl plugin

# path must be absolute
hyprctl plugin load /home/xxxx/.config/hypr/plugins/hyprscroller.so

NixOS

hyprscroller is now an official unstable package in nixpkgs, so you can install it from there. I don't maintain flakes any more because they were usually very out of date and I don't know enough about NixOS to keep them alive. If you need a newer version than the NixOS package, I recommend you temporarily use hyprpm.

Configuration

If you are not using hyprpm, to make Hyprland load the plugin, add this to your configuration.

# path must be absolute
plugin = /home/xxxx/.config/hypr/plugins/hyprscroller.so

Instead, if you use hyprpm, it should be as simple as adding this to your ~/.config/hypr/hyprland.conf :

exec-once = hyprpm reload -n

To turn on the layout, use

general {
    ...

    layout = scroller

    ...
}

Dispatchers

The plugin adds the following dispatchers:

| Dispatcher | Description | |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | scroller:movefocus | An optional replacement for movefocus, takes a direction as argument. | | scroller:movewindow | An optional replacement for movewindow, takes a direction and a movement mode as arguments. | | scroller:setmode | Set mode: r/row (default), c/col/column. Sets the working mode. Affects most dispatchers and new window creation. | | scroller:setmodemodifier | Assigns modifiers to the current mode for window creation: position, focus/nofocus, manual/auto. Description below | | scroller:cyclesize | Resize the focused column width (row mode), or the active window height (column mode). | | scroller:cyclewidth | Resize the focused column width. | | scroller:cycleheight | Resize the active window height. | | scroller:setsize | Set the focused column width (row mode), or the active window height (column mode) to one of the standard sizes. | | scroller:setwidth | Set the focused column width to one of column_widths. Takes an int value (0-based idx of the size in column_widths), or a string indicating the desired width | | scroller:setheight | Set the active window height to one of window_heights. Parameter similar to setwidth | | scroller:alignwindow | Align window on the screen, l/left, c/center, r/right (row mode), c/center, u/up, d/down (col mode), m/middle | | scroller:admitwindow | Accepts an optional direction parameter (l/left (default) or r/right). Push the current window below the active one of the column in that direction. | | scroller:expelwindow | Accepts an optional direction parameter (l/left or r/right (default)). Pop the current window out of its column and place it on a new column to the right or left. | | scroller:fitsize | Resize columns (row mode) or windows (col mode) so they fit on the screen: active, visible, all, toend, tobeg | | scroller:fitwidth | Resize columns so they fit on the screen: active, visible, all, toend, tobeg | | scroller:fitheight | Resize windows for the active column so they fit on the screen: active, visible, all, toend, tobeg | | scroller:toggleoverview | Toggle an overview of the workspace where all the windows are temporarily scaled to fit the monitor | | scroller:marksadd | Add a named mark. Argument is the name of the mark | | scroller:marksdelete | Delete a named mark. Argument is the name of the mark | | scroller:marksvisit | Visit a named mark. Argument is the name of the mark | | scroller:marksreset | Delete all marks | | scroller:pin | Toggle pin a column to its current position. The rest will adapt when changing focus etc. | | scroller:selectiontoggle | Toggle on/off the selection status of a window | | scroller:selectionworkspace | Select every window in the current workspace | | scroller:selectionreset | Resets selection (deselects all windows) | | scroller:selectionmove | Moves the selected windows/columns to the current workspace and location, takes a direction as argument (keeps sizes etc.) | | scroller:trailnew | Creates a new trail | | scroller:traildelete | Deletes the active trail | | scroller:trailclear | Clears all the trailmarks of the current trail | | scroller:trailnext | Moves to next trail | | scroller:trailprevious | Moves to previous trail