Hyprtasking

Powerful workspace management plugin, packed with features.

Important

• Supports Hyprland releases v0.46.2 through v0.54.3, v0.55.3 through v0.55.4, and v0.56.0.

demo_small.mp4

Jump To Installation

See Configuration

Roadmap

• Modular Layouts
  • Grid layout
  • Linear layout
  • Minimap layout
• Mouse controls
  • Exit into workspace (hover, click)
  • Drag and drop windows
• Keyboard controls
  • Switch workspaces with direction
  • Switch workspaces with jump labels
• Multi-monitor support (tested)
• Monitor scaling support (tested)
• Animation support
• Configurability
  • Overview exit behavior
  • Number of visible workspaces
  • Custom workspace layouts
  • Toggle behavior
  • Toggle keybind
• Touchpad gesture support
• Touchscreen support
• Overview layers

Installation

Hyprpm

hyprpm add https://github.com/raybbian/hyprtasking
hyprpm enable hyprtasking

Hyprland plugins must match the compositor ABI exactly. For tagged Hyprland releases, Hyprpm uses the compatibility pins in hyprpm.toml to select the corresponding hyprtasking revision.

Nix

Add hyprtasking to your flake inputs

# flake.nix
{
  inputs = {
    hyprland.url = "github:hyprwm/Hyprland/v0.56.0";

    hyprtasking = {
      url = "github:raybbian/hyprtasking";
      inputs.hyprland.follows = "hyprland";
    };
  };
  # ...
}

Include the plugin in the hyprland home manager options

# home.nix
{ inputs, pkgs, ... }:
{
  wayland.windowManager.hyprland = {
    plugins = [
      inputs.hyprtasking.packages.${pkgs.system}.hyprtasking
    ];
  }
}

Manual

To build, install Hyprland headers from the exact compositor commit you are running and then:

meson setup build
cd build && meson compile

Then use hyprctl plugin load to load the absolute path to the .so file:

hyprctl plugin load "$(realpath libhyprtasking.so)"

Usage

Opening Overview

• Bind hyprtasking:toggle, all to a keybind to open/close the overlay on all monitors.
• Bind hyprtasking:toggle, cursor to a keybind to open the overlay on one monitor and close on all monitors.
• Swipe up/down on a touchpad device to open/close the overlay on one monitor.
• See below for configuration options.

Interaction

• Workspace Transitioning:
  • Open the overlay, then use right click to switch to a workspace
  • Use the directional dispatchers hyprtasking:move to switch to a workspace
  • With jump.enabled enabled, press the label shown over a workspace to jump to it (1-9, 0, then a-z)
• Window management:
  • Left click to drag and drop windows around

Configuration

Example below:

hl.bind("SUPER + TAB", function() hl.plugin.hyprtasking.toggle("cursor") end)
hl.bind("SUPER + SPACE", function() hl.plugin.hyprtasking.toggle("all") end)

-- escape closes the overview if it's open
hl.bind("escape", function()
  if hl.plugin.hyprtasking.is_active() then
    hl.plugin.hyprtasking.toggle('all')
  end
end, { non_consuming = true })

hl.bind("SUPER + X", function() hl.plugin.hyprtasking.killhovered() end)

hl.bind("SUPER + H", function() hl.plugin.hyprtasking.move("left") end)
hl.bind("SUPER + J", function() hl.plugin.hyprtasking.move("down") end)
hl.bind("SUPER + K", function() hl.plugin.hyprtasking.move("up") end)
hl.bind("SUPER + L", function() hl.plugin.hyprtasking.move("right") end)

hl.bind("SUPER + A", function() hl.plugin.hyprtasking.move("out") end)
hl.bind("SUPER + SHIFT + A", function() hl.plugin.hyprtasking.movewindow("out") end)

hl.bind("SUPER + CTRL + 1", function() hl.plugin.hyprtasking.setlayer(1) end)
hl.bind("SUPER + CTRL + 2", function() hl.plugin.hyprtasking.setlayer(2) end)

hl.config({
  plugin = {
    hyprtasking = {
      layout = "grid",

      gap_size = 10,
      bg_color = 0xff26233a,
      border_size = 2,
      exit_on_hovered = false,
      warp_on_move_window = 1,
      close_overview_on_reload = false,

      -- for other mouse buttons see <linux/input-event-codes.h>
      drag_button = 0x110,   -- left mouse button
      select_button = 0x111, -- right mouse button

      jump = {
        enabled = false,
        label_color = 0xffffffff,
        label_background = 0x000000cc,
        label_size = 32,
      },

      gestures = {
        enabled = true,
        move_fingers = 3,
        move_distance = 300,
        open_fingers = 4,
        open_distance = 300,
        open_positive = true,
      },

      grid = {
        rows = 3,
        cols = 3,
        loop = false,
        layers = 2,
        loop_layers = true,
        gaps_use_aspect_ratio = true,
      },

      linear = {
        top = false,
        height = 400,
        scroll_speed = 1.0,
        blur = false,
      }
    }
  },
})

Click here to see the old hyprlang syntax

bind = SUPER, tab, hyprtasking:toggle, cursor
bind = SUPER, space, hyprtasking:toggle, all
# NOTE: the lack of a comma after hyprtasking:toggle!
bind = , escape, hyprtasking:if_active, hyprtasking:toggle cursor


bind = SUPER, X, hyprtasking:killhovered

bind = SUPER, H, hyprtasking:move, left
bind = SUPER, J, hyprtasking:move, down
bind = SUPER, K, hyprtasking:move, up
bind = SUPER, L, hyprtasking:move, right

bind = SUPER, A, hyprtasking:move, out
bind = SUPER SHIFT, A, hyprtasking:movewindow, out

bind = SUPER CTRL, 1, hyprtasking:setlayer, 1
bind = SUPER CTRL, 2, hyprtasking:setlayer, 2

plugin {
    hyprtasking {
        layout = grid

        gap_size = 10
        bg_color = 0xff26233a
        border_size = 2
        exit_on_hovered = false
        warp_on_move_window = 1
        close_overview_on_reload = false

        drag_button = 0x110 # left mouse button
        select_button = 0x111 # right mouse button
        # for other mouse buttons see <linux/input-event-codes.h>

        jump {
            enabled = false
            label_color = 0xffffffff
            label_background = 0x000000cc
            label_size = 32
        }

        gestures {
            enabled = true
            move_fingers = 3
            move_distance = 300
            open_fingers = 4
            open_distance = 300
            open_positive = true
        }

        grid {
            rows = 3
            cols = 3
            loop = false
            layers = 2
            loop_layers = true
            gaps_use_aspect_ratio = true
        }

        linear {
            top = false
            height = 400
            scroll_speed = 1.0
            blur = false
        }
    }
}

Dispatchers

• hyprtasking:if_active, ARG takes in a dispatch command (one that would be used after hyprctl dispatch ...) that will be dispatched only if the cursor overview is active.

  • Allows you to use e.g. escape to close the overview when it is active. See the example config for more info.

• hyprtasking:if_not_active, ARG same as above, but if the overview is not active.

• hyprtasking:toggle [, ARG] takes 1 optional argument that is either cursor or all

  • if the argument is all, then
    • if all overviews are hidden, then all overviews will be shown
    • otherwise all overviews will be hidden
  • if the argument is cursor or no argument is given, then
    • if current monitor's overview is hidden, then it will be shown
    • otherwise all overviews will be hidden

• hyprtasking:move, ARG takes in 1 argument that is one of up, down, left, right, in, out

  • when dispatched, hyprtasking will switch workspaces with a nice animation

• hyprtasking:movewindow, ARG takes in 1 argument that is one of up, down, left, right, in, out

  • when dispatched, hyprtasking will 1. move the hovered window to the workspace in the given direction relative to the window, and 2. switch to that workspace.

Click here to see the coordinate space

• hyprtasking:setlayer, ARG takes in 1 optional argument that specifies the direction of movement across layers.

  • if provided, the argument has to start with + or - to take effect. For example: +1, -3
  • no arguments has the same effect as +1
  • when dispatched, hyprtasking will move you through the layers in the specified direction
  • if plugin option grid:loop_layers is enabled, will loop the layers if next requested layer is out of bounds (not in the range form 0 to grid:layers)

• hyprtasking:setlayerwindow, ARG takes in 1 optional argument that specifies the direction of movement across layers.

  • when dispatched, hyprtasking will do the same as hyprtasking:setlayer, ARG and also move the window through layers

• hyprtasking:killhovered behaves similarly to the standard killactive dispatcher with focus on hover

  • when dispatched, hyprtasking will close the currently hovered window, useful when the overview is active.
  • this dispatcher is designed to replace hl.dsp.close(), it will work even when the overview is not active.

Config Options

All options are prefixed with plugin:hyprtasking:.

Option	Type	Description	Default
layout	string	The layout to use, either grid or linear	grid
bg_color	int	The color of the background of the overlay	0x000000FF
gap_size	float	The width in logical pixels of the gaps between workspaces	8.f
border_size	float	The width in logical pixels of the borders around workspaces	4.f
exit_on_hovered	int	If true, hiding the workspace will exit to the hovered workspace instead of the active workspace.	false
warp_on_move_window	int	Works the same as cursor:warp_on_change_workspace (see wiki) but with the hyprtasking:movewindow dispatcher. cursor:warp_on_change_workspace works only with the hyprtasking:move dispatcher	1
close_overview_on_reload	int	Whether to close the overview if its layout type did not change after a Hyprland config reload	true
drag_button	int	The mouse button to use to drag windows around	0x110
select_button	int	The mouse button to use to select a workspace	0x111
gestures:enabled	int	Whether or not to enable gestures	true
gestures:move_fingers	int	The number of fingers to use for the "move" gesture	3
gestures:move_distance	float	How large of a swipe on the touchpad corresponds to the width of a workspace	300.f
gestures:open_fingers	int	The number of fingers to use for the "open" gesture	4
gestures:open_distance	float	How large of a swipe on the touchpad is needed for the "open" gesture	300.f
gestures:open_positive	int	true if swiping up should open the overlay, false otherwise	true
grid:rows	int	The number of rows to display on the grid overlay	3
grid:cols	int	The number of columns to display on the grid overlay	3
grid:loop	int	When enabled, moving right at the far right of the grid will wrap around to the leftmost workspace, etc.	false
grid:layers	int	The number of layers for grid layout, the third dimension	1
grid:loop_layers	int	When enabled, moving back on the first layer will wrap around to the last layer. The reverse also works	true
grid:gaps_use_aspect_ratio	int	When enabled, vertical gaps will be scaled to match the monitor's aspect ratio	false
linear:top	int	Whether or not to position the overview on top of the screen	false
linear:blur	int	Whether or not to blur the dimmed area	true
linear:height	float	The height of the linear overlay in logical pixels	300.f
linear:scroll_speed	float	Scroll speed modifier. Set negative to flip direction	1.f

^{FYI, "ARG" does not refer to any minecraft ARG. Why would you even ask that? Eww}