ScrollOverview

https://github.com/yayuuu/hyprland-scroll-overview
Admin
ScrollOverview is an overview and workspace switching plugin for Hyprland that provides a scrollable...
Tokens:16,215
Snippets:125
Trust Score:8.6
License:BSD-3-Clause
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install ScrollOverview with Hyprpm

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/README.md

Installation steps using Hyprpm: add the plugin repository (use the new-release branch for Git builds), update to fetch dependencies, and enable the plugin.

```bash
hyprpm add https://github.com/yayuuu/hyprland-scroll-overview.git
```

```bash
hyprpm add https://github.com/yayuuu/hyprland-scroll-overview origin/new-release
```

```bash
hyprpm update
```

```bash
hyprpm enable scrolloverview
```

--------------------------------

### Auto-load plugins via Lua hyprland.start event

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Installation.md

Lua configuration to load enabled plugins automatically when Hyprland starts by calling 'hyprpm reload' from the 'hyprland.start' event handler.

```lua
hl.on("hyprland.start", function()
    hl.exec_cmd("hyprpm reload")
end)
```

--------------------------------

### CMake configuration for scrolloverview plugin

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/CMakeLists.txt

Defines the project and build settings for the scrolloverview Hyprland plugin. Sets C++ standard 23, globs all .cpp files, and creates a shared library target. Generates a version header via a custom target and script, then finds and links required dependencies (Lua, Hyprland, libdrm, etc.) and installs the library.

```cmake
cmake_minimum_required(VERSION 3.27)

project(scrolloverview
    DESCRIPTION "scrolloverview plugin for Hyprland"
    VERSION 0.1
)

set(CMAKE_CXX_STANDARD 23)

file(GLOB_RECURSE SRC "*.cpp")

add_library(scrolloverview SHARED ${SRC})

set(VERSION_HEADER_DIR "${CMAKE_CURRENT_BINARY_DIR}/generated")
set(VERSION_HEADER "${VERSION_HEADER_DIR}/PluginVersion.hpp")
add_custom_target(scrolloverview-version ALL
    COMMAND "${CMAKE_COMMAND}" -E make_directory "${VERSION_HEADER_DIR}"
    COMMAND sh "${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate-plugin-version.sh" "${VERSION_HEADER}" "${CMAKE_CURRENT_SOURCE_DIR}"
    BYPRODUCTS "${VERSION_HEADER}"
    VERBATIM
)
add_dependencies(scrolloverview scrolloverview-version)
target_include_directories(scrolloverview PRIVATE "${VERSION_HEADER_DIR}")

find_package(PkgConfig REQUIRED)
pkg_search_module(lua REQUIRED IMPORTED_TARGET "lua5.4>=5.4" "lua>=5.4")
pkg_check_modules(deps REQUIRED IMPORTED_TARGET
    hyprland
    libdrm
    libinput
    libudev
    pangocairo
    pixman-1
    wayland-server
    xkbcommon
)
target_link_libraries(scrolloverview PRIVATE rt PkgConfig::deps PkgConfig::lua)

install(TARGETS scrolloverview)
```

--------------------------------

### Build plugin with make

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Installation.md

Builds the plugin from the source directory.

```bash
make
```

--------------------------------

### Build and fetch dependencies with hyprpm update

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Installation.md

Builds and fetches dependencies for the plugin after adding the repository.

```bash
hyprpm update
```

--------------------------------

### Clone repository for source build

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Installation.md

Clones the repository and changes into its directory to prepare for building from source.

```bash
git clone https://github.com/yayuuu/hyprland-scroll-overview.git
cd hyprland-scroll-overview
```

--------------------------------

### Load plugin into Hyprland with hyprctl

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Installation.md

Loads the built plugin into the running Hyprland instance using hyprctl.

```bash
hyprctl plugin load "$(pwd)/scrolloverview.so"
```

--------------------------------

### Configure global and per-monitor ScrollOverview settings

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Per-monitor-configuration

Sets global ScrollOverview options and per-monitor overrides for DP-1 and HDMI-A-2. The output field must match a connector name from hyprctl monitors. Missing fields inherit global values; repeated calls merge fields. Also binds a key to toggle the overview.

```lua
-- Global settings inherited by all monitors.
hl.plugin.scrolloverview.configure({
    layout = "auto",
    scale = 0.5,
    workspace_gap = 100,
    shadow = { enabled = true, range = 50 },
})

-- Only these fields differ on DP-1.
hl.plugin.scrolloverview.configure({
    output = "DP-1",
    layout = "vertical",
    input = { scrolling_mode = 2 },
})

-- HDMI-A-2 still inherits workspace_gap and shadow.range from global settings.
hl.plugin.scrolloverview.configure({
    output = "HDMI-A-2",
    layout = "horizontal",
    scale = 0.4,
    shadow = { enabled = false },
})

hl.bind("SUPER + g", function()
    overview.overview("toggle all")
end)
```

--------------------------------

### Auto-load plugin via Lua with absolute path

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Installation.md

Lua configuration to load the plugin automatically at Hyprland startup, using an absolute path to the compiled plugin file.

```lua
local pluginPath = "/absolute/path/to/hyprland-scroll-overview/scrolloverview.so"
hl.plugin.load(pluginPath)
```

--------------------------------

### Load module and bind keys (hyprland.lua)

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/ALT-Tab-overview.md

Loads the alttab module and binds ALT+Tab to open the overview, and ALT+Alt_L/ALT+Alt_R to close it. The close binds use release and transparent flags to trigger when the modifier is released.

```lua
local altTab = require("scripts.alttab")

hl.bind("ALT + Tab", altTab.next, { submap_universal = true })
hl.bind("ALT + Alt_L", altTab.close, { release = true, transparent = true })
hl.bind("ALT + Alt_R", altTab.close, { release = true, transparent = true })
```

--------------------------------

### hl.plugin.scrolloverview.configure(options)

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Per-monitor-configuration

Configures the ScrollOverview plugin globally or per-monitor. The `output` parameter selects a monitor for overrides; without it, global settings are applied.

```APIDOC
## `hl.plugin.scrolloverview.configure(options)`

### Description
Configures the ScrollOverview plugin. Without `output`, it sets global settings; with `output`, it stores monitor-specific overrides.

### Parameters
- **options** (table) - Required - A table of ScrollOverview properties. See [Basic configuration](Basic-configuration).
  - **output** (string) - Optional - Exact connector name (e.g., `DP-1`, `HDMI-A-2`). Must be a non-empty string matching `hyprctl monitors`. Does not accept `all`, wildcards, or monitor-description selectors.
  - **layout** (string) - Optional - Overview layout. Possible values: `auto`, `horizontal`, `vertical`.
  - **scale** (number) - Optional - Overview scale.
  - **workspace_gap** (number) - Optional - Gap between workspaces.
  - **shadow** (table) - Optional - Shadow settings.
    - **enabled** (boolean) - Optional - Whether shadow is enabled.
    - **range** (number) - Optional - Shadow range.
  - **input** (table) - Optional - Input settings.
    - **scrolling_mode** (number) - Optional - Scrolling mode.

### Behavior
- Without `output`, it is shorthand for `hl.config({ plugin = { scrolloverview = options } })` and keeps global configuration behavior.
- With `output`, it stores overrides for that monitor. Missing fields inherit the current global value.
- Repeated calls for the same output merge fields; the last supplied value for a field wins. An empty subtable leaves previous overrides unchanged.
- On config reload, monitor overrides are cleared and rebuilt from the config. Remove an override and reload to return that field to its global setting.
- Monitor-specific values use Hyprland's value parsers and the option ranges listed below. Unknown fields or invalid values reject the entire monitor-specific call without applying any of its changes.
- These settings are used for keybinds, gestures, and overviews opened during window dragging. `cross_monitor_drag` is read from the monitor where the drag starts; it does not block dropping into an overview that is already open.
- Layout is chosen when an overview is created. Close and reopen existing overviews after changing configuration to apply the complete new setup. `auto` retains its usual behavior: horizontal on portrait monitors, vertical on landscape monitors.

### Example
```lua
-- Global settings inherited by all monitors.
hl.plugin.scrolloverview.configure({
    layout = "auto",
    scale = 0.5,
    workspace_gap = 100,
    shadow = { enabled = true, range = 50 },
})

-- Only these fields differ on DP-1.
hl.plugin.scrolloverview.configure({
    output = "DP-1",
    layout = "vertical",
    input = { scrolling_mode = 2 },
})

-- HDMI-A-2 still inherits workspace_gap and shadow.range from global settings.
hl.plugin.scrolloverview.configure({
    output = "HDMI-A-2",
    layout = "horizontal",
    scale = 0.4,
    shadow = { enabled = false },
})
```
```

--------------------------------

### Add plugin repository via hyprpm

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Installation.md

Adds the plugin repository using Hyprpm. For stable Hyprland releases, use the first command without a branch. For Git builds, use the second command to add the plugin from the 'new-release' branch instead.

```bash
hyprpm add https://github.com/yayuuu/hyprland-scroll-overview.git
```

```bash
hyprpm add https://github.com/yayuuu/hyprland-scroll-overview origin/new-release
```

--------------------------------

### Enable scrolloverview plugin with hyprpm

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Installation.md

Enables the scrolloverview plugin in Hyprland.

```bash
hyprpm enable scrolloverview
```

--------------------------------

### hl.plugin.scrolloverview.navigate

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Dispatchers

Moves the overview selection/focus between windows in the current workspace. Options are left, right, up, and down.

```APIDOC
## hl.plugin.scrolloverview.navigate

### Description
Moves the overview selection/focus between windows in the current workspace. If there are no more windows in that direction, it selects the next workspace when the direction matches the configured overview layout.

### Method
Lua function call or hyprctl dispatch

### Parameters
#### Options
- `left` - Move selection left.
- `right` - Move selection right.
- `up` - Move selection up.
- `down` - Move selection down.

### Usage Examples
```bash
hyprctl dispatch 'hl.plugin.scrolloverview.navigate("left")'
```

```

--------------------------------

### hl.plugin.scrolloverview.overview

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Dispatchers

Controls the overview state. Options include toggle, select, close, off, open, and on, with optional monitor or 'all' targets.

```APIDOC
## hl.plugin.scrolloverview.overview

### Description
Controls the overview state. Options include toggle, select, close, off, open, and on, with optional monitor or 'all' targets.

### Method
Lua function call or hyprctl dispatch

### Parameters
#### Options
- `toggle [monitor|all]` - Toggle the active monitor, a named monitor, or every monitor.
- `select` - Select the workspace under the cursor.
- `close [monitor|all]` - Close every overview by default, or only the named monitor.
- `off [monitor|all]` - Same as `close`.
- `open [monitor|all]` - Open on the active monitor, a named monitor, or every monitor.
- `on [monitor|all]` - Same as `open`.

### Usage Examples
```lua
hl.plugin.scrolloverview.overview("toggle all")
```
```bash
hyprctl dispatch 'hl.plugin.scrolloverview.overview("toggle")'
```

```

--------------------------------

### Define last workspace state and creation helpers

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Dynamic-workspaces.md

Add these state and helper functions to your Lua configuration. They determine whether the active workspace is the last populated one on the monitor, ignoring special and empty workspaces, and create a new workspace by focusing 'emptynm' when scrolling down at the end.

```lua
local lastWorkspaceScrollBind

local function table_value(value, ...)
    if value == nil then
        return nil
    end

    for _, key in ipairs({ ... }) do
        local ok, item = pcall(function()
            return value[key]
        end)

        if ok and item ~= nil then
            return item
        end
    end

    return nil
end

local function last_workspace_state()
    local monitor = hl.get_monitor_at_cursor() or hl.get_active_monitor()
    if not monitor then
        return false, nil
    end

    local activeWorkspace = table_value(monitor, "active_workspace")
    local activeWorkspaceId = table_value(activeWorkspace, "id")
    if type(activeWorkspaceId) ~= "number" or activeWorkspaceId <= 0 then
        return false, nil
    end

    local activeWorkspaceWindows = table_value(activeWorkspace, "windows")
    if type(activeWorkspaceWindows) ~= "number" or activeWorkspaceWindows == 0 then
        return false, nil
    end

    local lastWorkspaceId
    for _, workspace in ipairs(hl.get_workspaces()) do
        local id = table_value(workspace, "id")

        if type(id) == "number"
            and id > 0
            and table_value(workspace, "special") ~= true
            and table_value(workspace, "monitor") == monitor then
            lastWorkspaceId = math.max(lastWorkspaceId or id, id)
        end
    end

    return activeWorkspaceId == lastWorkspaceId, monitor
end

local function create_workspace_at_end()
    local isLastWorkspace, monitor = last_workspace_state()
    if not isLastWorkspace or not monitor then
        return
    end

    hl.dispatch(hl.dsp.focus({ monitor = table_value(monitor, "name") }))
    hl.dispatch(hl.dsp.focus({ workspace = "emptynm" }))
end

local function update_last_workspace_scroll_bind()
    if not lastWorkspaceScrollBind then
        return
    end

    local enabled = false
    if hl.get_current_submap() == "scrolloverview" then
        enabled = last_workspace_state()
    end

    lastWorkspaceScrollBind:set_enabled(enabled)
end
```

--------------------------------

### Define scrolloverview submap with keybindings and mouse actions

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Keybind-submap

Defines the 'scrolloverview' submap with arrow keys for navigation, Enter/Escape for select/close, and mouse bindings for clicking and closing windows. Also shows a loop binding ALT+number to focus workspaces with submap_universal so they remain active while the submap is active.

```lua
-- hyprland.lua
hl.define_submap("scrolloverview", function()
    hl.bind("left",   hl.plugin.scrolloverview.navigate("left"))
    hl.bind("right",  hl.plugin.scrolloverview.navigate("right"))
    hl.bind("up",     hl.plugin.scrolloverview.navigate("up"))
    hl.bind("down",   hl.plugin.scrolloverview.navigate("down"))
    hl.bind("return", hl.plugin.scrolloverview.overview("select"))
    hl.bind("escape", hl.plugin.scrolloverview.overview("off"))
    hl.bind("mouse:272", function()
        -- Select the clicked window, or just the workspace if no window was clicked, then close the overview. This is the default behaviour if submap is not defined.
        hl.plugin.scrolloverview.overview("select")
        hl.plugin.scrolloverview.window("select")
        hl.plugin.scrolloverview.overview("off")
    end, { mouse = true })
    hl.bind("mouse:274", hl.plugin.scrolloverview.window("close"), { mouse = true })
end)

-- Example Hyprland bind that keeps working inside the submap:
for i = 1, 10 do
    local key = i % 10
    hl.bind("ALT + " .. key, hl.dsp.focus({ workspace = i }), { submap_universal = true })
end
```

--------------------------------

### Configure ScrollOverview in Hyprlang

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/README.md

Hyprlang configuration for ScrollOverview in hyprland.conf, including gesture_distance, scale, workspace_gap, layout, wallpaper, blur, and shadow settings, plus a keybind to toggle the overview with SUPER+g.

```ini
# .config/hypr/hyprland.conf
plugin {
    scrolloverview {
        gesture_distance = 300 # how far is the "max" for the gesture
        scale = 0.5 # preferred overview scale
        workspace_gap = 100
        layout = vertical # vertical, horizontal, or auto (per-monitor orientation)
        wallpaper = 2 # 0: global only, 1: per-workspace only, 2: both
        blur = true # blur only the main overview wallpaper

        shadow {
            enabled = true
            range = 50
        }
    }
}

# Toggle ScrollOverview with SUPER+g
bind = SUPER, g, scrolloverview:overview, "toggle all"
```

--------------------------------

### Bind mouse_down to create workspace at end

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Dynamic-workspaces.md

Add this bind inside your existing 'scrolloverview' submap. Do not define the same submap a second time; merge this with the configuration from Keybind submap. The bind is initially disabled and only enabled when the last workspace is active.

```lua
lastWorkspaceScrollBind = hl.bind("mouse_down", create_workspace_at_end)
lastWorkspaceScrollBind:set_enabled(false)
```

--------------------------------

### Configure scroll-overview gesture with hl.plugin.scrolloverview.gesture

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Basic-configuration

Registers or removes a trackpad swipe gesture for opening/closing the overview. The first call registers a 3-finger vertical swipe; the second adds a 4-finger vertical swipe with SUPER modifier and a scale of 1.5; the third enables the gesture even when an app inhibits gestures; the fourth removes the 3-finger vertical gesture. The `fingers` field is required (2–9), `direction` is required, and `action` defaults to `overview`.

```lua
hl.plugin.scrolloverview.gesture({ fingers = 3, direction = "vertical" })
hl.plugin.scrolloverview.gesture({ fingers = 4, direction = "vertical", mod = "SUPER", scale = 1.5 })
hl.plugin.scrolloverview.gesture({ fingers = 4, direction = "vertical", disable_inhibit = true })
hl.plugin.scrolloverview.gesture({ fingers = 3, direction = "vertical", action = "unset" })
```

--------------------------------

### hl.plugin.scrolloverview.gesture

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Basic-configuration.md

Documentation for the gesture configuration function used to register or remove trackpad swipe gestures for the overview.

```APIDOC
## hl.plugin.scrolloverview.gesture

### Description
Registers or removes a trackpad swipe gesture to open and close the overview. Call this function from your Lua configuration.

### Method
Function call

### Endpoint
`hl.plugin.scrolloverview.gesture({ ... })`

### Parameters
#### Request Body
- **fingers** (number) - Required - Finger count (2–9)
- **direction** (string) - Required - Swipe direction (`up`, `down`, `left`, `right`, …)
- **action** (string) - Optional - `overview` to register, `unset` to remove. Default: `overview`
- **mod** (string) - Optional - Modifier mask held during the gesture (e.g. `SUPER`). Default: none
- **scale** (number) - Optional - Gesture delta scale, [0.1–10]. Default: `1.0`
- **disable_inhibit** (bool) - Optional - Fire the gesture even when an app inhibits gestures. Default: `false`

### Request Example
```lua
hl.plugin.scrolloverview.gesture({ fingers = 3, direction = "vertical" })
hl.plugin.scrolloverview.gesture({ fingers = 4, direction = "vertical", mod = "SUPER", scale = 1.5 })
hl.plugin.scrolloverview.gesture({ fingers = 4, direction = "vertical", disable_inhibit = true })
hl.plugin.scrolloverview.gesture({ fingers = 3, direction = "vertical", action = "unset" })
```

### Response
No return value is documented.
```

--------------------------------

### Bind SUPER + g to toggle overview

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Dispatchers

Binds SUPER + g to toggle the overview on all monitors using the hl.plugin.scrolloverview.overview dispatcher. The dispatcher can be called from any Lua function, not just keybinds.

```lua
-- hyprland.lua
hl.bind("SUPER + g", function()
    hl.plugin.scrolloverview.overview("toggle all")
end)
```

--------------------------------

### hl.plugin.scrolloverview.window

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Dispatchers

Acts on the window under the mouse cursor. Options are select and close.

```APIDOC
## hl.plugin.scrolloverview.window

### Description
Acts on the window under the mouse cursor. Options are select and close.

### Method
Lua function call or hyprctl dispatch

### Parameters
#### Options
- `select` - Focus/select the window under the mouse cursor.
- `close` - Close the window under the mouse cursor.

### Usage Examples
```bash
hyprctl dispatch 'hl.plugin.scrolloverview.window("close")'
```

```

--------------------------------

### Lua keybindings for Shift_L and Shift_R to toggle scrolling mode

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Toggle-scroll-direction

Add these bindings inside your existing scrolloverview submap. They track both left and right Shift keys, using transparent and non_consuming options. The release binds are universal (submap_universal) so they work even if the overview closes before Shift is released. Do not redefine the submap; merge these into the existing callback.

```lua
hl.bind("Shift_L", function()
    set_shift_pressed("left", true)
end, { transparent = true, non_consuming = true })

hl.bind("Shift_R", function()
    set_shift_pressed("right", true)
end, { transparent = true, non_consuming = true })

hl.bind("SHIFT + Shift_L", function()
    set_shift_pressed("left", false)
end, {
    release = true,
    transparent = true,
    non_consuming = true,
    submap_universal = true,
})

hl.bind("SHIFT + Shift_R", function()
    set_shift_pressed("right", false)
end, {
    release = true,
    transparent = true,
    non_consuming = true,
    submap_universal = true,
})
```

--------------------------------

### Configure ScrollOverview in Lua

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/README.md

Lua configuration for ScrollOverview in hyprland.lua, mirroring the Hyprlang options and binding SUPER+g to toggle the overview.

```lua
-- .config/hypr/hyprland.lua
hl.config({
    plugin = {
        scrolloverview = {
            gesture_distance = 300, -- how far is the "max" for the gesture
            scale = 0.5, -- preferred overview scale
            workspace_gap = 100,
            layout = "vertical", -- vertical, horizontal, or auto (per-monitor orientation)
            wallpaper = 2, -- 0: global only, 1: per-workspace only, 2: both
            blur = true, -- blur only the main overview wallpaper

            shadow = {
                enabled = true,
                range = 50,
            },
        },
    },
})

-- Toggle ScrollOverview with SUPER+g
hl.bind("SUPER + g", function()
    hl.plugin.scrolloverview.overview("toggle all")
end)
```

--------------------------------

### ALT+Tab switcher module (alttab.lua)

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/ALT-Tab-overview.md

Lua module that opens a horizontal overview and navigates to the next column. It tracks whether the overview was opened by ALT+Tab and closes it when the modifier is released. The module handles non-wrapping navigation by detecting when the selection doesn't change and navigating back to the first column.

```lua
local M = {}

local openedByAltTab = false

local function object_value(value, key)
    if value == nil then
        return nil
    end

    local ok, result = pcall(function()
        return value[key]
    end)

    return ok and result or nil
end

local function selection_state()
    local workspaceId = object_value(hl.get_active_workspace(), "id")
    local windowAddress = object_value(hl.get_active_window(), "address")
    return tostring(workspaceId) .. ":" .. tostring(windowAddress)
end

local function navigate_to_first_column()
    local previousState
    local maxSteps = #(hl.get_windows() or {}) + #(hl.get_workspaces() or {}) + 1

    for _ = 1, maxSteps do
        local currentState = selection_state()
        if currentState == previousState then
            return
        end

        previousState = currentState
        hl.plugin.scrolloverview.navigate("left")
    end
end

local function navigate_next_column()
    local previousState = selection_state()
    hl.plugin.scrolloverview.navigate("right")

    if selection_state() == previousState then
        navigate_to_first_column()
    end
end

function M.next()
    hl.config({
        plugin = {
            scrolloverview = {
                layout = "horizontal",
                scale = 0.3,
            },
        },
    })
    hl.plugin.scrolloverview.overview("on")
    openedByAltTab = true
    navigate_next_column()
end

function M.close()
    if openedByAltTab then
        hl.plugin.scrolloverview.overview("off")
        openedByAltTab = false
    end
end

return M
```

--------------------------------

### Invoke dispatchers via hyprctl dispatch

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Dispatchers

Invokes the overview, navigate, and window dispatchers externally via hyprctl dispatch. Useful for shell scripts, status bars, launchers, and other automation.

```bash
hyprctl dispatch 'hl.plugin.scrolloverview.overview("toggle")'
hyprctl dispatch 'hl.plugin.scrolloverview.navigate("left")'
hyprctl dispatch 'hl.plugin.scrolloverview.window("close")'
```

--------------------------------

### Update bind on workspace, window, monitor, and submap changes

Source: https://github.com/yayuuu/hyprland-scroll-overview/blob/main/docs/wiki/Dynamic-workspaces.md

Register event handlers and a repeating timer to keep the bind state current. The timer (50 ms repeat) also updates when the pointer moves between monitors without triggering one of the listed events. Call update_last_workspace_scroll_bind() once at the end.

```lua
hl.on("workspace.active", update_last_workspace_scroll_bind)
hl.on("workspace.created", update_last_workspace_scroll_bind)
hl.on("workspace.removed", update_last_workspace_scroll_bind)
hl.on("workspace.move_to_monitor", update_last_workspace_scroll_bind)
hl.on("window.open", update_last_workspace_scroll_bind)
hl.on("window.close", update_last_workspace_scroll_bind)
hl.on("window.move_to_workspace", update_last_workspace_scroll_bind)
hl.on("monitor.focused", update_last_workspace_scroll_bind)
hl.on("keybinds.submap", update_last_workspace_scroll_bind)

local lastWorkspaceScrollTimer = hl.timer(update_last_workspace_scroll_bind, {
    timeout = 50,
    type = "repeat",
})

update_last_workspace_scroll_bind()
```

--------------------------------

### Bind native drag with cross_monitor_drag

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Keybind-submap

Optional submap bind for native drag adoption when cross_monitor_drag is enabled. Binds SUPER + mouse:272 to the window drag action with mouse=true.

```lua
hl.bind("SUPER + mouse:272", hl.dsp.window.drag(), { mouse = true })
```

--------------------------------

### hl.plugin.scrolloverview.gesture

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Basic-configuration

Registers or unregisters a trackpad swipe gesture to open/close the overview. Call this function from your Lua configuration.

```APIDOC
## hl.plugin.scrolloverview.gesture

### Description
Registers or unregisters a trackpad swipe gesture to open/close the overview. Call this function from your Lua configuration.

### Method
Lua function call

### Endpoint
`hl.plugin.scrolloverview.gesture({ ... })`

### Parameters
#### Request Body
- **fingers** (number) - Required - Finger count (2–9).
- **direction** (string) - Required - Swipe direction (`up`, `down`, `left`, `right`, …).
- **action** (string) - Optional - `overview` to register, `unset` to remove. Default: `overview`.
- **mod** (string) - Optional - Modifier mask held during the gesture (e.g. `SUPER`). Default: none.
- **scale** (number) - Optional - Gesture delta scale, [0.1–10]. Default: `1.0`.
- **disable_inhibit** (bool) - Optional - Fire the gesture even when an app inhibits gestures. Default: `false`.

### Request Example
```lua
hl.plugin.scrolloverview.gesture({ fingers = 3, direction = "vertical" })
hl.plugin.scrolloverview.gesture({ fingers = 4, direction = "vertical", mod = "SUPER", scale = 1.5 })
hl.plugin.scrolloverview.gesture({ fingers = 4, direction = "vertical", disable_inhibit = true })
hl.plugin.scrolloverview.gesture({ fingers = 3, direction = "vertical", action = "unset" })
```

### Response
No response is documented.
```

--------------------------------

### Lua state and helper functions for runtime scrolling_mode toggle

Source: https://github.com/yayuuu/hyprland-scroll-overview/wiki/Toggle-scroll-direction

Add these state variables and helper functions to your Lua configuration. The set_scrolling_mode function updates the plugin's scrolling_mode via hl.config. The reset_scrolling_mode and set_shift_pressed functions manage the shift key state and set the mode to 0 (normal) or 1 (inverted) based on whether any Shift key is pressed. The final call to reset_scrolling_mode() initializes the mode.

```lua
local shiftPressed = {
    left = false,
    right = false,
}

local function set_scrolling_mode(mode)
    hl.config({
        plugin = {
            scrolloverview = {
                input = {
                    scrolling_mode = mode,
                },
            },
        },
    })
end

local function reset_scrolling_mode()
    shiftPressed.left = false
    shiftPressed.right = false
    set_scrolling_mode(0)
end

local function set_shift_pressed(side, pressed)
    shiftPressed[side] = pressed
    set_scrolling_mode((shiftPressed.left or shiftPressed.right) and 1 or 0)
end

reset_scrolling_mode()
```
Tokens:
Raw