### Complete Hyprspace Configuration Example

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/configuration.md

A comprehensive example of a Hyprspace configuration file, covering colors, dimensions, layout, gaps, behavior, animation, and keyboard shortcuts.

```conf
# Colors
plugin:overview:panelColor = 0x80000000
plugin:overview:panelBorderColor = 0xFF4040FF
plugin:overview:workspaceActiveBackground = 0x40FFFFFF
plugin:overview:workspaceInactiveBackground = 0x80808080
plugin:overview:workspaceActiveBorder = 0x4DFFFFFF
plugin:overview:workspaceInactiveBorder = 0x00FFFFFF
plugin:overview:dragAlpha = 0.5

# Dimensions
plugin:overview:panelHeight = 300
plugin:overview:panelBorderWidth = 3
plugin:overview:workspaceMargin = 15
plugin:overview:reservedArea = 0
plugin:overview:workspaceBorderSize = 2

# Layout
plugin:overview:centerAligned = 1
plugin:overview:onBottom = 0
plugin:overview:hideBackgroundLayers = 0
plugin:overview:hideTopLayers = 0
plugin:overview:hideOverlayLayers = 0
plugin:overview:hideRealLayers = 1
plugin:overview:drawActiveWorkspace = 1
plugin:overview:affectStrut = 1
plugin:overview:disableBlur = 0

# Gaps
plugin:overview:overrideGaps = 1
plugin:overview:gapsIn = 20
plugin:overview:gapsOut = 60

# Behavior
plugin:overview:autoDrag = 1
plugin:overview:autoScroll = 1
plugin:overview:exitOnClick = 1
plugin:overview:switchOnDrop = 0
plugin:overview:exitOnSwitch = 0
plugin:overview:showNewWorkspace = 1
plugin:overview:showEmptyWorkspace = 1
plugin:overview:showSpecialWorkspace = 0
plugin:overview:disableGestures = 0
plugin:overview:reverseSwipe = 0

# Animation
plugin:overview:overrideAnimSpeed = 0.0

# Keyboard
plugin:overview:exitKey = "Escape"
```

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

### Install Hyprspace via Hyprpm

Source: https://github.com/kzdkm/hyprspace/blob/main/README.md

Install and enable the Hyprspace plugin using the Hyprpm package manager.

```bash
hyprpm add https://github.com/KZDKM/Hyprspace
hyprpm enable Hyprspace
```

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

### Triggering Dispatchers via Hyprctl

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/endpoints.md

Command-line examples demonstrate how to invoke dispatcher actions using `hyprctl`. The `all` argument can be used to target all monitors.

```bash
# Toggle overview on current monitor
hyprctl dispatch overview:toggle

# Toggle overview on all monitors
hyprctl dispatch overview:toggle all

# Open overview
hyprctl dispatch overview:open

# Close overview
hyprctl dispatch overview:open all
```

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

### Build Hyprspace Plugin

Source: https://github.com/kzdkm/hyprspace/blob/main/README.md

Compile the Hyprspace plugin manually. Ensure Hyprland headers are installed before running.

```bash
make all
```

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

### Retrieve Integer Configuration Value

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/plugin-initialization.md

Use this to get an integer configuration value from Hyprland. It provides a fallback value if the key is not found or the type is incorrect.

```cpp
int height = getConfigValueOr<Hyprlang::INT>("plugin:overview:panelHeight", 250);
float speed = getConfigValueOr<Hyprlang::FLOAT>("plugin:overview:overrideAnimSpeed", 0.0);
```

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

### CHyprspaceWidget Public Methods

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/README.md

This section details the public methods available on the CHyprspaceWidget class. Each method includes its signature, parameter descriptions, return values, and usage examples.

```APIDOC
## CHyprspaceWidget Class

This class provides the main interface for interacting with the Hyprspace widget.

### Public Methods

This documentation covers 15+ public methods. For each method, you will find:

- **Full Method Signature**: Including parameter names and types.
- **Parameter Tables**: Detailing each parameter's type and description.
- **Return Values**: Explaining what the method returns.
- **Error Conditions**: Outlining potential errors and their causes.
- **Usage Examples**: Demonstrating how to call the method.

*Note: Specific method signatures and details are not provided in this overview but are fully documented within the source code analysis.*
```

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

### Get Configuration Value with Fallback (C++)

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/helper-functions.md

Safely retrieves a configuration value by its name, returning a fallback value if the key is not found or if there's a type mismatch. Use for integer, float, or string configurations.

```cpp
int height = getConfigValueOr<Hyprlang::INT>(
    "plugin:overview:panelHeight", 
    250);

float speed = getConfigValueOr<Hyprlang::FLOAT>(
    "plugin:overview:overrideAnimSpeed", 
    0.0f);

bool enabled = getConfigValueOr<Hyprlang::INT>(
    "plugin:overview:autoDrag", 
    1) != 0;
```

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

### Get Color Configuration Value with Fallback (C++)

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/helper-functions.md

Retrieves a color configuration value, returning a fallback color if the key is not found or the value is invalid. Colors are represented as 32-bit hex integers (0xAARRGGBB).

```cpp
CHyprColor panelColor = getConfigColorOr(
    "plugin:overview:panelColor",
    CHyprColor(0, 0, 0, 0));

CHyprColor borderColor = getConfigColorOr(
    "plugin:overview:panelBorderColor",
    CHyprColor(1, 1, 1, 0.5));
```

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

### Get Widget for Monitor

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/helper-functions.md

Retrieves the overview widget instance associated with a specific monitor. Call this to find the correct widget for event routing. The owner monitor can become null if the monitor is unplugged.

```cpp
std::shared_ptr<CHyprspaceWidget> getWidgetForMonitor(PHLMONITORREF pMonitor)
{
    // ... implementation details ...
    return nullptr;
}
```

```cpp
auto widget = getWidgetForMonitor(pMonitor);
if (widget) {
    widget->show();
}
```

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

### Plugin Initialization Flow

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/architecture.md

Illustrates the sequence of operations during plugin loading and initialization, including configuration, event listener, and dispatcher registration.

```text
Plugin Load
    ↓
PLUGIN_INIT()
    ├─ Register config values with defaults
    ├─ Register event listeners
    │  ├─ Render events
    │  ├─ Input events
    │  ├─ Workspace events
    │  └─ Monitor events
    ├─ Register dispatchers
    │  ├─ overview:toggle
    │  ├─ overview:open
    │  └─ overview:close
    ├─ reloadConfig()
    │  └─ Populate Config namespace
    └─ registerMonitors()
       └─ Create CHyprspaceWidget for each monitor
```

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

### show()

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Activates and displays the overview panel on the monitor. Unfullscreens all windows and hides top layer surfaces if configured.

```APIDOC
## show()

### Description
Activates and displays the overview panel on the monitor. Unfullscreens all windows and hides top layer surfaces if configured.

### Parameters
None

### Returns
Nothing (void)

### Behavior
- Unfullscreens all windows in workspaces on this monitor (preserves fullscreen intent internally)
- Hides top and overlay layer surfaces if `Config::hideRealLayers` is enabled
- Triggers layout recalculation via `updateLayout()`
- Animates the panel into view

### Example
```cpp
widget->show();
```
```

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

### Get Owning Monitor

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Retrieves a handle to the monitor that owns this widget. The handle may be null if the monitor is no longer available.

```cpp
auto owner = widget->getOwner();
if (owner) {
    Vector2D monitorSize = owner->m_transformedSize;
}
```

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

### Bind Overview Actions to Keyboard Shortcuts

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Configure Hyprland keybindings to control the Hyprspace overview.

```conf
bind = SUPER, Tab, dispatch, overview:toggle
bind = SUPER, o, dispatch, overview:open
bind = SUPER, c, dispatch, overview:close
```

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

### Initialize Hyprspace Plugin

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/plugin-initialization.md

Main plugin initialization entry point. Registers configuration, event listeners, dispatcher commands, and creates widget instances. This function is called when Hyprland loads the plugin.

```cpp
APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE inHandle)
```

```cpp
return {
    "Hyprspace",        // Plugin name
    "Workspace overview",  // Description
    "KZdkm",            // Author
    "0.1"               // Version
};
```

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

### Retrieve Color Configuration Value

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/plugin-initialization.md

Use this to get a color configuration value from Hyprland. It returns a CHyprColor object and provides a fallback color.

```cpp
CHyprColor panelColor = getConfigColorOr("plugin:overview:panelColor", 
                                          CHyprColor(0, 0, 0, 0));
```

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

### PLUGIN_INIT(HANDLE inHandle)

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/plugin-initialization.md

Main plugin initialization entry point, called when Hyprland loads the plugin. It registers configuration, event listeners, and dispatcher commands.

```APIDOC
## PLUGIN_INIT(HANDLE inHandle)

### Description
Main plugin initialization entry point, called when Hyprland loads the plugin. It registers configuration, event listeners, and dispatcher commands.

### Signature
```cpp
APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE inHandle)
```

### Parameters
#### Path Parameters
- **inHandle** (HANDLE) - Required - Handle to the plugin system, used to register dispatchers and config values

### Returns
`PLUGIN_DESCRIPTION_INFO` - Plugin metadata including name, description, authors, and version

### Side Effects
- Registers all configuration options with Hyprland
- Attaches event listeners for render, input, gesture, and workspace events
- Registers three dispatcher commands (overview:toggle, overview:open, overview:close)
- Creates widget instances for each monitor
- Triggers initial configuration loading

### Initialization Order
1. Register all configuration values with defaults
2. Register config reload listener that calls `reloadConfig()`
3. Register start event listener that calls `reloadConfig()` and `registerMonitors()`
4. Register render stage listeners for panel drawing
5. Register layer open/close listeners for layout refresh
6. Register mouse button and axis (scroll) listeners
7. Register touch input listeners (down, move, up)
8. Register swipe gesture listeners (begin, update, end)
9. Register keyboard key press listener for exit key
10. Register workspace switch listener for panel refresh
11. Register monitor added listener to create widgets for new monitors
12. Find and cache function pointers to `renderWindow` and `renderLayer` functions
13. Create widget instances for all currently connected monitors
14. Reload configuration to populate Config namespace

### Request Example
```cpp
return {
    "Hyprspace",        // Plugin name
    "Workspace overview",  // Description
    "KZdkm",            // Author
    "0.1"               // Version
};
```
```

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

### Get Hyprland API Version

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/plugin-initialization.md

Exported function that returns the Hyprland API version this plugin targets. Ensure this matches the HYPRLAND_API_VERSION constant.

```cpp
APICALL EXPORT std::string PLUGIN_API_VERSION()
```

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

### beginSwipe

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Initiates a touchpad swipe gesture by recording the initial state and initializing swipe tracking variables.

```APIDOC
## beginSwipe

### Description
Initiates a touchpad swipe gesture. Records the current active state before swiping and initializes swipe tracking variables.

### Method
bool

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **e** (IPointer::SSwipeBeginEvent) - Yes - Event data from Hyprland's gesture handler

### Request Example
```cpp
IPointer::SSwipeBeginEvent event{...};
widget->beginSwipe(event);
```

### Response
#### Success Response (bool)
- **Return Value** (bool) - False to allow event propagation, true to cancel

#### Response Example
None explicitly provided, but returns a boolean indicating event consumption.
```

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

### Accessing CHyprspaceWidget Animation Variables

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Demonstrates how to get the current value and animation status of the curYOffset animation variable. This is useful for checking the panel's visibility and animation state.

```cpp
float currentOffset = widget->curYOffset->value();
bool isAnimating = widget->curYOffset->isBeingAnimated();
```

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

### Keyboard Bindings for Overview Dispatchers

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/endpoints.md

These configuration lines show how to bind keyboard shortcuts to trigger the overview dispatchers. The `all` argument can be appended to apply the action to all monitors.

```conf
# Open/close overview with Super+Tab
bind = SUPER, Tab, dispatch, overview:toggle

# Open with Super+O
bind = SUPER, o, dispatch, overview:open

# Close with Super+C
bind = SUPER, c, dispatch, overview:close

# Toggle on all monitors with Super+Shift+Tab
bind = SUPER_SHIFT, Tab, dispatch, overview:toggle all
```

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

### overview:open

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/endpoints.md

Opens the workspace overview panel. This command has no effect if the overview is already open.

```APIDOC
## overview:open

### Description
Opens the workspace overview panel (no effect if already open).

### Method
dispatch

### Endpoint
overview:open [all]

### Parameters
#### Path Parameters
- **all** (string) - Optional - If present, opens overview on all monitors instead of current monitor

### Request Example
```conf
bind = SUPER, o, dispatch, overview:open
```

### Response
#### Success Response (200)
- **result** (SDispatchResult) - Empty result

#### Response Example
```json
{}
```
```

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

### Track Touched Monitor

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/helper-functions.md

Tracks which monitor is currently receiving touch input. This ensures that subsequent touch events (move, up) are correctly delivered to the same monitor, especially in multi-monitor setups.

```cpp
g_pTouchedMonitor = nullptr; // Initial state or after touch ends
```

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

### Setting up a Signal Listener

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/types.md

Shows how to create a signal listener using `CHyprSignalListener` to subscribe to Hyprland events. The listener is automatically unregistered when the object goes out of scope, ensuring proper resource management.

```cpp
CHyprSignalListener myHook = Event::bus()->m_events.render.stage
    .listen([](eRenderStage stage) { /* ... */ });
// Automatically unsubscribed when myHook is destroyed
```

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

### Accessing Global Configuration Options

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/types.md

Demonstrates how to access various global configuration options for Hyprspace. These options control aspects like panel appearance, workspace layout, and visual effects. Ensure necessary headers are included.

```cpp
#include "Globals.hpp"
float panelH = Config::panelHeight;
CHyprColor color = Config::panelBaseColor;
bool centered = Config::centerAligned;
```

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

### CBox Initialization and Point Containment Check

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/types.md

Shows how to initialize a CBox with position and dimensions, and then check if a given point (Vector2D) is contained within it. Also demonstrates scaling the box.

```cpp
CBox widgetBox = {owner->m_position.x, owner->m_position.y, width, height};
if (widgetBox.containsPoint(coords)) {
    // Point is inside the box
}
widgetBox.scale(1.0 / monitor_scale);
```

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

### Plugin Initialization Functions

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Reference for functions related to Hyprspace plugin initialization, versioning, and configuration management.

```APIDOC
## Plugin Initialization

### Description
Functions for plugin lifecycle, API versioning, and configuration loading.

### Functions
- `PLUGIN_API_VERSION()` - Returns the API version.
- `PLUGIN_INIT()` - The initialization entry point for the plugin.
- `PLUGIN_EXIT()` - The cleanup entry point for the plugin.
- `reloadConfig()` - Reloads the plugin configuration.
- `registerMonitors()` - Creates widgets for monitors.
```

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

### CHyprspaceWidget Constructor

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Initializes a new workspace overview widget for a specific monitor.

```APIDOC
## CHyprspaceWidget(uint64_t inOwnerID)

### Description
Initializes a new workspace overview widget for a specific monitor.

### Parameters
#### Path Parameters
- **inOwnerID** (uint64_t) - Required - The ID of the monitor that owns this widget

### Example
```cpp
#include "Overview.hpp"
uint64_t monitorId = 0;
auto widget = std::make_shared<CHyprspaceWidget>(monitorId);
```
```

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

### Initialize CHyprspaceWidget

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Initializes a new workspace overview widget for a specific monitor. Requires the monitor's ID.

```cpp
#include "Overview.hpp"
uint64_t monitorId = 0;
auto widget = std::make_shared<CHyprspaceWidget>(monitorId);
```

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

### Toggle Overview with Hyprctl

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Use hyprctl to toggle, open, or close the Hyprspace overview.

```bash
hyprctl dispatch overview:toggle
hyprctl dispatch overview:open
hyprctl dispatch overview:close
```

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

### Open Overview Dispatcher

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/helper-functions.md

Use this dispatcher to open the overview widget. It can open the widget for a specific monitor or for all monitors if 'all' is specified.

```cpp
static SDispatchResult dispatchOpenOverview(std::string arg)
```

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

### Open Workspace Overview

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/endpoints.md

Opens the workspace overview panel on the current or all monitors. This command has no effect if the overview is already open.

```conf
bind = SUPER, o, dispatch, overview:open
```

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

### Configure Overview Panel Colors

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/configuration.md

Set the background and border colors for the overview panel and workspace boxes. Also configures the opacity of windows during drag operations.

```hyprlang
plugin:overview:panelColor = 0x80000000
plugin:overview:workspaceActiveBackground = 0x40FFFFFF
plugin:overview:dragAlpha = 0.5
```

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

### draw()

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Renders the entire overview panel, including workspace boxes, windows, and layer surfaces.

```APIDOC
## draw()

### Description
Renders the entire overview panel, including workspace boxes, windows, and layer surfaces.

### Parameters
None

### Returns
Nothing (void)

### Behavior
- Only renders if `isActive()` is true or the panel is currently animating
- Renders panel background with optional blur
- Renders panel border (if configured)
- Calculates and renders scaled workspace boxes with window thumbnails
- Renders layer surfaces (background, bottom, top, overlay) based on configuration
- Stores workspace box positions for input hit detection
- Damages the monitor to trigger compositor redraw

### Example
```cpp
widget->draw();
```
```

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

### dispatchOpenOverview

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/helper-functions.md

Dispatcher implementation for the `overview:open` command. It opens overview widgets on the current or all monitors.

```APIDOC
## dispatchOpenOverview(std::string arg)

### Description
Dispatcher implementation for `overview:open` command. Opens overview widgets.

### Parameters
#### Path Parameters
- **arg** (std::string) - Optional - Optional "all" argument for all monitors

### Behavior
- If `arg.contains("all")`:
  - Opens all widgets that are not already active
- Otherwise:
  - Gets current monitor and opens widget if not active
```

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

### Configure Overview Behavior

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/configuration.md

Set various boolean options to control the behavior of the overview mode, such as drag behavior, scrolling, and exit conditions. Use 0 for false and 1 for true.

```conf
plugin:overview:autoDrag = 0
plugin:overview:exitOnClick = 0
plugin:overview:switchOnDrop = 1
plugin:overview:exitOnSwitch = 1
plugin:overview:showNewWorkspace = 0
```

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

### Show Overview Panel

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Activates and displays the overview panel. This action unfullscreens windows and may hide certain layer surfaces based on configuration.

```cpp
widget->show();
```

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

### renderWindowStub

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/rendering.md

Renders a scaled thumbnail of a window into the current workspace box. It handles scaling, translation, and clipping to fit the destination rectangle within the workspace.

```APIDOC
## renderWindowStub

### Description
Renders a scaled thumbnail of a window into the current workspace box. It handles scaling, translation, and clipping to fit the destination rectangle within the workspace.

### Method
void

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (void)
Nothing (void)

#### Response Example
None
```

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

### Rendering System Functions

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Documentation for low-level rendering functions used by Hyprspace.

```APIDOC
## Rendering System

### Description
Low-level rendering functions and the main draw pipeline.

### Functions
- `renderRect()` - Renders a solid rectangle.
- `renderRectWithBlur()` - Renders a rectangle with a blur effect.
- `renderBorder()` - Renders a border.
- `renderWindowStub()` - Renders a placeholder for a window thumbnail.
- `renderLayerStub()` - Renders a layer surface.
- `CHyprspaceWidget::draw()` - Orchestrates the main rendering process.
```

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

### View and Search Files in Hyprspace

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/README.md

Use these bash commands to list all files, read specific markdown files, and search for content within the output directory.

```bash
# View all files
ls -la /workspace/home/output/

# Start reading
cat /workspace/home/output/INDEX.md
cat /workspace/home/output/architecture.md
cat /workspace/home/output/configuration.md

# Search for something
grep -r "panelHeight" /workspace/home/output/
```

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

### Toggle Hyprspace Overview

Source: https://github.com/kzdkm/hyprspace/blob/main/README.md

Use the 'overview:toggle' dispatcher to open or close the Hyprspace overview panel on the current monitor. This can also be triggered by a vertical workspace swipe.

```bash
overview:toggle
```

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

### Initiate Touchpad Swipe Gesture

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Begins tracking a touchpad swipe gesture. This method initializes swipe-related variables and records the initial state.

```cpp
IPointer::SSwipeBeginEvent event{...};
widget->beginSwipe(event);
```

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

### Vector2D Operations with Hyprland Types

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/types.md

Demonstrates obtaining mouse coordinates and scaling them by monitor scale using Hyprland's Vector2D type. Ensure Hyprland's input manager and monitor scale are accessible.

```cpp
Vector2D pos = g_pInputManager->getMouseCoordsInternal();
Vector2D scaled = pos * owner->m_scale;
```

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

### Render Overview Panel

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Renders the entire overview panel, including workspaces, windows, and layer surfaces. This method only executes if the panel is active or animating.

```cpp
widget->draw();
```

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

### Configure Overview Layout and Display

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/configuration.md

Control the alignment, position, and visibility of elements within the overview. Options include centering, bottom placement, and hiding various layer types.

```hyprlang
plugin:overview:centerAligned = 0
plugin:overview:onBottom = 1
plugin:overview:hideBackgroundLayers = 1
plugin:overview:affectStrut = 0
```

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

### Register Monitors for Widgets

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/plugin-initialization.md

Creates widget instances for all connected monitors. This function is idempotent and called during plugin initialization and when new monitors are added.

```cpp
void registerMonitors(){
    // Iterates through all monitors in g_pCompositor->m_monitors
    // Checks if a widget already exists for each monitor via getWidgetForMonitor()
    // Creates new CHyprspaceWidget instances for monitors without widgets
    // Adds new widgets to g_overviewWidgets global vector
}
```

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

### Widget State Transitions

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/architecture.md

Visualizes the lifecycle of a Hyprspace widget, from hidden to showing, active, hiding, and back to hidden.

```text
Widget Lifecycle:
┌─────────────┐
│   Hidden    │  (active = false)
│  curYOffset │  animates to (height * scale)
└──────┬──────┘
       │ user presses toggle or swipes up
       ▼
┌─────────────┐
│  Showing    │  (active = true)
│  Animating  │  curYOffset animates to 0
└──────┬──────┘
       │ animation completes
       ▼
┌─────────────┐
│   Active    │  (active = true)
│   Visible   │  ready for interaction
└──────┬──────┘
       │ user clicks outside or presses key
       ▼
┌─────────────┐
│  Hiding     │  (active = false)
│  Animating  │  curYOffset animates to (height * scale)
└──────┬──────┘
       │ animation completes
       ▼
┌─────────────┐
│   Hidden    │
└─────────────┘
```

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

### Event System Handlers

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Overview of event listeners and input handlers available in Hyprspace.

```APIDOC
## Event System

### Description
Handles various events including render, input, gesture, and system events.

### Event Handlers
#### Render Events
- `onRender()`

#### Input Events
- `onMouseButton()`
- `onMouseAxis()`
- `onTouchDown/Move/Up()`
- `onKeyPress()`

#### Gesture Events
- `onSwipeBegin()`
- `onSwipeUpdate()`
- `onSwipeEnd()`

#### System Events
- Config reload
- Workspace switch
- Monitor add

### Widget Input Methods
- `buttonEvent()` - Handles mouse and touch clicks.
- `axisEvent()` - Handles scroll wheel input.
- `beginSwipe()`, `updateSwipe()`, `endSwipe()` - Manages gesture recognition.
```

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

### overview:toggle

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/endpoints.md

Toggles the workspace overview panel visibility on the current monitor or all monitors if the 'all' argument is provided.

```APIDOC
## overview:toggle

### Description
Toggles the workspace overview panel visibility on the current monitor (or all monitors if `all` argument is used).

### Method
dispatch

### Endpoint
overview:toggle [all]

### Parameters
#### Path Parameters
- **all** (string) - Optional - If present, toggles overview on all monitors instead of current monitor

### Request Example
```conf
# Bind to toggle overview on current monitor
bind = SUPER, Tab, dispatch, overview:toggle

# Bind to toggle overview on all monitors
bind = SUPER_SHIFT, Tab, dispatch, overview:toggle all
```

### Response
#### Success Response (200)
- **result** (SDispatchResult) - Empty result

#### Response Example
```json
{}
```
```

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

### Control Hyprspace Overview on All Monitors

Source: https://github.com/kzdkm/hyprspace/blob/main/README.md

Dispatchers to control the Hyprspace overview across all monitors. Use 'all' argument to toggle, open, or close the overview on every connected display.

```bash
overview:toggle all
overview:close all
overview:open all
```

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

### Touch Up Event Handler

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/event-system.md

Completes the touch input sequence by simulating a mouse button release. It identifies the widget on the previously touched monitor, calls its `buttonEvent` method with the release state, and clears the reference to the touched monitor.

```cpp
void onTouchUp(const ITouch::SUpEvent& event, SCallbackInfo& info)
{
    // ... behavior details ...
    widget->buttonEvent(false, coords);
    // ... more behavior ...
}
```

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

### Configure Hyprspace with Nix

Source: https://github.com/kzdkm/hyprspace/blob/main/README.md

Integrate Hyprspace as a Hyprland plugin within a Nix flake configuration. This ensures Hyprspace and Hyprland versions are synchronized.

```nix
{ 
  inputs = { 
    # Hyprland is **such** eye candy
    hyprland = {
      type = "git";
      url = "https://github.com/hyprwm/Hyprland";
      submodules = true;
      inputs.nixpkgs.follows = "nixpkgs";
    };
    Hyprspace = {
      url = "github:KZDKM/Hyprspace";

      # Hyprspace uses latest Hyprland. We declare this to keep them in sync.
      inputs.hyprland.follows = "hyprland";
    };
  };

... # your normal setup with hyprland

  wayland.windowManager.hyprland.plugins = [
    # ... whatever
    inputs.Hyprspace.packages.${pkgs.system}.Hyprspace
  ];
}
```

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

### Hyprspace Plugin Lifecycle Flowchart

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Illustrates the sequence of events and actions during the Hyprspace plugin's lifecycle, from user loading to unloading.

```text
User loads plugin
    ↓
PLUGIN_INIT()
    ├─ Register configs
    ├─ Register dispatchers
    ├─ Attach event listeners
    ├─ Load initial config
    └─ Create widgets for monitors
    ↓
Event loop (render, input, etc.)
    ├─ onRender() each frame
    ├─ onMouseButton/Axis on input
    ├─ onKeyPress on keyboard
    ├─ onWorkspaceChange on workspace switch
    ├─ onConfigReload on config change
    └─ registerMonitors() on monitor add
    ↓
User unloads plugin
    ↓
PLUGIN_EXIT()
    ├─ Unregister all event listeners
    ├─ Clear widgets vector
    ├─ Clean up function pointers
    └─ Reset global state
```

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

### Hyprspace Render Integration Stages

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Outlines the stages in Hyprland's render pipeline where Hyprspace integrates to refresh layouts, manage windows, and draw its overview.

```text
RENDER_PRE → RENDER_PRE_WINDOWS → Hyprland Render → RENDER_POST_WINDOWS
   ↓               ↓                   ↓                    ↓
Refresh       Hide Dragged        Normal Windows      Draw Overview
Layout        Window              and Content         Restore Dragged
```

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

### Configure Overview Panel Dimensions

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/configuration.md

Adjust the height, border width, and margins for the overview panel and workspace boxes. Allows for reserved area padding at the top.

```hyprlang
plugin:overview:panelHeight = 300
plugin:overview:workspaceMargin = 20
plugin:overview:reservedArea = 25
```

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

### Monitor Addition Event Processing Flow

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/architecture.md

Explains the process when a new monitor is connected, leading to the creation of a new Hyprspace widget instance for it.

```text
New Monitor Connected
    ↓
Hyprland Monitor Added Event
    ↓
registerMonitors()
    └─ Create new CHyprspaceWidget for new monitor
```

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

### Configure Overview Exit Key

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/configuration.md

Set the key binding to close the overview. Leave the value empty to disable the key binding. Valid key names include standard keys, modifiers, letters, numbers, function keys, and special keys.

```conf
plugin:overview:exitKey = "Escape"
```

```conf
plugin:overview:exitKey = ""
```

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

### Hyprspace High-Level Architecture Diagram

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/architecture.md

This diagram illustrates the integration of the Hyprspace plugin within the Hyprland compositor. It shows the flow of events and data between Hyprland's core systems and the Hyprspace plugin's components, including global state, event listeners, and the rendering of overview widgets.

```text
┌─────────────────────────────────────────────────────────────┐
│                    Hyprland Compositor                       │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │           Event Bus System                             │ │
│  │  (Render, Input, Workspace, Monitor, Config)          │ │
│  └────────────────────────────────────────────────────────┘ │
│                         ▲                                    │
│                         │                                    │
│                         ▼                                    │
│  ┌────────────────────────────────────────────────────────┐ │
│  │       Hyprspace Plugin (main.cpp)                      │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │  Global State                                    │ │ │
│  │  │  • g_overviewWidgets: Vec<CHyprspaceWidget>      │ │ │
│  │  │  • Config namespace: Static values              │ │ │
│  │  │  • Event listeners: CHyprSignalListener array    │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────────────────┘ │
│                         │                                    │
│            ┌────────────┼────────────┐                       │
│            ▼            ▼            ▼                       │
│  ┌──────────────┐  ┌──────────┐  ┌──────────────┐          │
│  │ CHyprspace   │  │ Render   │  │ Input Event  │          │
│  │ Widget       │  │ System   │  │ Handler      │          │
│  │              │  │          │  │              │          │
│  │ One per      │  │Rendering │  │Processes:    │          │
│  │ monitor      │  │logic     │  │• Mouse       │          │
│  │              │  │          │  │• Keyboard    │          │
│  │Methods:      │  │          │  │• Touch       │          │
│  │• show/hide   │  │          │  │• Swipe       │          │
│  │• draw        │  │          │  │              │          │
│  │• button/axis │  │          │  │              │          │
│  │• swipe       │  │          │  │              │          │
│  └──────────────┘  └──────────┘  └──────────────┘          │
│         │                               │                    │
│         └───────────────┬───────────────┘                    │
│                         ▼                                    │
│         ┌──────────────────────────────┐                    │
│         │  Hyprland Manager APIs       │                    │
│         │  • Compositor                │                    │
│         │  • Renderer                  │                    │
│         │  • Layout Manager            │                    │
│         │  • Input Manager             │                    │
│         └──────────────────────────────┘                    │
└─────────────────────────────────────────────────────────────┘
```

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

### Hyprspace Event Flow Diagram

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Illustrates the sequence of events from user action to state change within the Hyprspace plugin.

```text
User Action → Hyprland Event Bus → Plugin Handler → Widget Method → State Change/Redraw
```

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

### registerMonitors()

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/plugin-initialization.md

Creates widget instances for all connected monitors. This function is called during plugin initialization and whenever a new monitor is added. It is designed to be idempotent.

```APIDOC
## registerMonitors()

### Description
Creates widget instances for all connected monitors. This function is called during plugin initialization and whenever a new monitor is added. It is designed to be idempotent.

### Signature
```cpp
void registerMonitors()
```

### Parameters
None

### Returns
Nothing (void)

### Behavior
- Iterates through all monitors in `g_pCompositor->m_monitors`
- Checks if a widget already exists for each monitor via `getWidgetForMonitor()`
- Creates new `CHyprspaceWidget` instances for monitors without widgets
- Adds new widgets to `g_overviewWidgets` global vector
```

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

### Toggle Workspace Overview

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/endpoints.md

Toggles the visibility of the workspace overview panel on the current or all monitors. Use the `all` argument to affect all monitors.

```conf
bind = SUPER, Tab, dispatch, overview:toggle

# Bind to toggle overview on all monitors
bind = SUPER_SHIFT, Tab, dispatch, overview:toggle all
```

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

### User-Callable Dispatcher Commands

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/INDEX.md

Commands that can be invoked by users to control the Hyprspace overview panel.

```APIDOC
## Dispatchers Reference

### Description
User-callable dispatcher commands to control the Hyprspace overview panel.

### Commands
- `overview:toggle [all]` - Toggles the visibility of the overview panel.
- `overview:open [all]` - Opens the overview panel.
- `overview:close [all]` - Closes the overview panel.

### Usage
- Can be bound to keyboard shortcuts.
- Can be invoked via the `hyprctl` command-line interface.
```

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

### Register Swipe Begin Listener

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/event-system.md

Registers a listener for the swipe begin event. It initiates swipe gesture processing, returning early if gestures are disabled and ensuring single-monitor gestures.

```cpp
Event::bus()->m_events.gesture.swipe.begin.registerCallback(onSwipeBegin);
```

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

### Render Window Thumbnail

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/rendering.md

Renders a scaled thumbnail of a window into the current workspace box. Used for both tiled and floating windows, it requires a valid mapped surface and positive scale factor. Early returns prevent rendering degenerate cases.

```cpp
void renderWindowStub(PHLWINDOW pWindow, PHLMONITOR pMonitor, PHLWORKSPACE pWorkspaceOverride, CBox rectOverride, CBox clipBox, const Time::steady_tp& time)
```

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

### Convert Hyprland/libinput Key Codes to XKB Symbols

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/event-system.md

Adds an offset to Hyprland/libinput key codes to convert them to XKB symbols for use with xkb_state_key_get_one_sym.

```cpp
const auto keycode = event.keycode + 8;
const xkb_keysym_t keysym = xkb_state_key_get_one_sym(keyboard->m_xkbSymState, keycode);
```

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

### Render Flow per Frame

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/architecture.md

Details the rendering pipeline executed each frame, including pre-render checks, window handling, and widget drawing.

```text
Hyprland Render Loop (per frame)
    ↓
onRender(RENDER_PRE)
    ├─ Check g_layoutNeedsRefresh flag
    └─ If set, call refreshWidgets() → widget->show()
    ↓
onRender(RENDER_PRE_WINDOWS)
    ├─ Get dragged window from dragController
    └─ Hide dragged window (set alpha to 0)
    ↓
[Hyprland renders normal windows]
    ↓
onRender(RENDER_POST_WINDOWS)
    ├─ For current monitor's widget:
    │  └─ widget->draw()
    │     ├─ Calculate workspace box layout
    │     ├─ For each workspace:
    │     │  ├─ Render background/border
    │     │  ├─ Render layer surfaces
    │     │  └─ Render window thumbnails via renderWindowStub()
    │     └─ Store workspace boxes for hit detection
    ├─ Restore dragged window alpha
    └─ Render dragged window at dragAlpha
```

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

### renderLayerStub

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/rendering.md

Renders a scaled thumbnail of a layer surface (panel, background, etc.) into the current workspace box. It scales and translates the layer to fit within the specified workspace box boundaries.

```APIDOC
## renderLayerStub

### Description
Renders a scaled thumbnail of a layer surface (panel, background, etc.) into the current workspace box. It scales and translates the layer to fit within the specified workspace box boundaries.

### Method
void

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (void)
Nothing (void)

#### Response Example
None
```

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

### dispatchToggleOverview

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/helper-functions.md

Dispatcher implementation for the `overview:toggle` command. It toggles the visibility of overview widgets on the current or all monitors.

```APIDOC
## dispatchToggleOverview(std::string arg)

### Description
Dispatcher implementation for `overview:toggle` command. Toggles the visibility of overview widgets.

### Parameters
#### Path Parameters
- **arg** (std::string) - Optional - Optional "all" argument for all monitors

### Behavior
- If `arg.contains("all")`:
  - If current monitor widget is active, closes all widgets
  - If current monitor widget is inactive, opens all widgets
- Otherwise (single monitor):
  - Gets current monitor from cursor position
  - Toggles visibility of the widget for that monitor

### Request Example
```bash
hyprctl dispatch overview:toggle
hyprctl dispatch overview:toggle all
```
```

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

### Render Window Function Pointers

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/plugin-initialization.md

Defines function pointers used to manually render windows and layers. These are obtained via findFunctionBySymbol() during initialization.

```cpp
void* pRenderWindow;
void* pRenderLayer;
```

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

### Touch Down Event Handler

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/event-system.md

Converts touch down input into a mouse button press event. It determines the target monitor, finds the corresponding widget, converts touch coordinates, simulates a button press, and prepares for subsequent move/up events by saving the touched monitor.

```cpp
void onTouchDown(const ITouch::SDownEvent& event, SCallbackInfo& info)
{
    // ... behavior details ...
    widget->buttonEvent(true, pos);
    // ... more behavior ...
}
```

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

### Toggle Overview Dispatcher

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/helper-functions.md

Use this dispatcher to toggle the visibility of the overview widget. It can affect a single monitor based on cursor position or all monitors if 'all' is specified.

```cpp
static SDispatchResult dispatchToggleOverview(std::string arg)
```

```bash
hyprctl dispatch overview:toggle
hyprctl dispatch overview:toggle all
```

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

### getOwner()

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/api-reference/CHyprspaceWidget.md

Retrieves the monitor that owns this widget.

```APIDOC
## getOwner()

### Description
Retrieves the monitor that owns this widget.

### Parameters
None

### Returns
`PHLMONITOR` - A pointer/handle to the owning monitor, or nullptr if the monitor no longer exists

### Example
```cpp
auto owner = widget->getOwner();
if (owner) {
    Vector2D monitorSize = owner->m_transformedSize;
}
```
```

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

### Configure Overview Animation Speed

Source: https://github.com/kzdkm/hyprspace/blob/main/_autodocs/configuration.md

Override the default animation speed for panel transitions in the overview. A value of 0.0 uses Hyprland's default speed, while other values act as multipliers.

```conf
plugin:overview:overrideAnimSpeed = 1.5
```