aboutsummaryrefslogtreecommitdiffstats
path: root/config/quickshell/overview/README.md
diff options
context:
space:
mode:
authorDon Williams <don.e.williams@gmail.com>2025-11-30 20:04:02 -0500
committerDon Williams <don.e.williams@gmail.com>2025-11-30 20:04:02 -0500
commitca0c23cce006ea3f7d793c5fa8eee6acff196470 (patch)
tree092a7446c0f494c958b11b1af09474d99718a74e /config/quickshell/overview/README.md
parent510eafbe0560cff6e459b64fcb778d645cd43ab3 (diff)
Integrate Quickshell-Overview with Qt6 fixes and automation scripts
## Overview This commit integrates the corrected Quickshell-Overview feature across all installation and update workflows. The overview provides an AGS alternative with live window previews toggled via Super+TAB keybind. ## Changes ### 1. Quickshell Overview QML Files - Added config/quickshell/overview/ subdirectory with Qt6-compatible QML - Includes 20+ files covering: * OverviewWindow.qml with proper clipping (no OpacityMask, uses QtQuick.Effects) * OverviewWidget.qml for window handling * Overview.qml main component with Hyprland integration * Common utilities and styling * Services for Hyprland data and global state management ### 2. copy.sh Updates - Removes default shell.qml that blocks quickshell named config detection - Auto-copies config/quickshell/overview to ~/.config/quickshell/overview/ - Updates old 'qs' startup commands to 'qs -c overview' - Handles both fresh installs and config overwrite scenarios ### 3. upgrade.sh Updates - Added config/quickshell/ to upgrade directory list - Excludes shell.qml to preserve overview config detection capability - Enables seamless upgrades without losing quickshell settings ### 4. IPC Command Fixes - Corrected OverviewToggle.sh to use proper 'qs ipc -c overview call overview toggle' - Fixed startup commands from old 'qs' to 'qs -c overview' - Hyprland-Dots now uses corrected toggle script ## Qt6 Compatibility - Replaced Qt5Compat.GraphicalEffects with QtQuick.Effects - Removed OpacityMask in favor of Qt6-compatible clipping technique - All QML properly imports Qt6 modules ## Release Script - release.sh automatically uses copy.sh, inheriting all quickshell updates ## Testing - Verified on target systems (Fedora 43 VM, jak-nixos) - qs -c overview successfully launches overview config when shell.qml is removed - IPC toggle commands work correctly within Wayland sessions ## Files Modified - config/quickshell/overview/* (20 new files) - copy.sh (enhanced QS handling) - upgrade.sh (added quickshell to upgrade paths)
Diffstat (limited to 'config/quickshell/overview/README.md')
-rw-r--r--config/quickshell/overview/README.md214
1 files changed, 214 insertions, 0 deletions
diff --git a/config/quickshell/overview/README.md b/config/quickshell/overview/README.md
new file mode 100644
index 00000000..c32e7ac5
--- /dev/null
+++ b/config/quickshell/overview/README.md
@@ -0,0 +1,214 @@
+# Quickshell Overview for Hyprland
+
+<div align="center">
+
+A standalone workspace overview module for Hyprland using Quickshell - shows all workspaces with live window previews, drag-and-drop support, and Super+Tab keybind.
+
+![Quickshell](https://img.shields.io/badge/Quickshell-0.2.0-blue?style=flat-square)
+![Hyprland](https://img.shields.io/badge/Hyprland-Compatible-purple?style=flat-square)
+![Qt6](https://img.shields.io/badge/Qt-6-green?style=flat-square)
+![License](https://img.shields.io/badge/License-GPL-orange?style=flat-square)
+
+</div>
+
+---
+
+## 📸 Preview
+
+![Overview Screenshot](assets/image.png)
+
+https://github.com/user-attachments/assets/79ceb141-6b9e-4956-8e09-aaf72b66550c
+
+> *Workspace overview showing live window previews with drag-and-drop support*
+
+---
+
+## ✨ Features
+
+- 🖼️ Visual workspace overview showing all workspaces and windows
+- 🎯 Click windows to focus them
+- 🖱️ Middle-click windows to close them
+- 🔄 Drag and drop windows between workspaces
+- ⌨️ Keyboard navigation (Arrow keys to switch workspaces, Escape/Enter to close)
+- 💡 Hover tooltips showing window information
+- 🎨 Material Design 3 theming
+- ⚡ Smooth animations and transitions
+
+## 📦 Installation
+
+### Prerequisites
+
+- **Hyprland** compositor
+- **Quickshell** ([installation guide](https://quickshell.org/docs/v0.1.0/guide/install-setup/))
+- **Qt 6** with modules: QtQuick, QtQuick.Controls, Qt5Compat.GraphicalEffects
+
+### Setup
+
+1. **Clone this repository** to your Quickshell config directory:
+ ```bash
+ git clone https://github.com/Shanu-Kumawat/quickshell-overview ~/.config/quickshell/overview
+ ```
+
+2. **Add keybind** to your Hyprland config (`~/.config/hypr/hyprland.conf`):
+ ```conf
+ bind = Super, TAB, exec, qs ipc -c overview call overview toggle
+ ```
+
+3. **Auto-start** the overview (add to Hyprland config):
+ ```conf
+ exec-once = qs -c overview
+ ```
+
+4. **Reload Hyprland**:
+ ```bash
+ hyprctl reload
+ ```
+
+### Manual Start (if needed)
+
+```bash
+qs -c overview &
+```
+
+## 🎮 Usage
+
+| Action | Description |
+|--------|-------------|
+| **Super + Tab** | Toggle the overview |
+| **Left/Right Arrow Keys** | Navigate between workspaces horizontally |
+| **Up/Down Arrow Keys** | Navigate between workspace rows |
+| **Escape / Enter** | Close the overview |
+| **Click workspace** | Switch to that workspace |
+| **Click window** | Focus that window |
+| **Middle-click window** | Close that window |
+| **Drag window** | Move window to different workspace |
+
+---
+
+## ⚙️ Configuration
+
+> **⚠️ Want to change the size, position, or number of workspaces?**
+> Edit `~/.config/quickshell/overview/common/Config.qml` - it's all there!
+
+### Workspace Grid
+
+Edit `~/.config/quickshell/overview/common/Config.qml`:
+
+```qml
+property QtObject overview: QtObject {
+ property int rows: 2 // Number of workspace rows
+ property int columns: 5 // Number of workspace columns (10 total workspaces)
+ property real scale: 0.16 // Overview scale factor (0.1-0.3, smaller = more compact)
+ property bool enable: true
+}
+```
+
+**Common adjustments:**
+- **Too small?** Increase `scale` (try 0.20 or 0.25)
+- **Too big?** Decrease `scale` (try 0.12 or 0.14)
+- **More workspaces?** Change `rows` and `columns` (e.g., 3 rows × 4 columns = 12 workspaces)
+
+### Position
+
+Edit `~/.config/quickshell/overview/modules/overview/Overview.qml` (line ~111):
+
+```qml
+anchors {
+ horizontalCenter: parent.horizontalCenter
+ top: parent.top
+ topMargin: 100 // Change this value to move up/down
+}
+```
+
+### Theme & Colors
+
+Edit `~/.config/quickshell/overview/common/Appearance.qml` to customize:
+- Colors (m3colors and colors objects)
+- Font families and sizes
+- Animation curves and durations
+- Border radius values
+
+---
+
+## 📋 Requirements
+
+- **Hyprland** compositor (tested on latest versions)
+- **Quickshell** (Qt6-based shell framework)
+- **Qt 6** with the following modules:
+ - QtQuick
+ - QtQuick.Controls
+ - QtQuick.Layouts
+ - Qt5Compat.GraphicalEffects
+ - Quickshell.Wayland
+ - Quickshell.Hyprland
+
+## 🚫 Removed Features (from original illogical-impulse)
+
+The following features were removed to make it standalone:
+
+- App search functionality
+- Emoji picker
+- Clipboard history integration
+- Search widget
+- Integration with the full illogical-impulse shell ecosystem
+
+## 📁 File Structure
+
+```
+~/.config/quickshell/overview/
+├── shell.qml # Main entry point
+├── README.md # This file
+├── hyprland-config.conf # Configuration reference
+├── common/
+│ ├── Appearance.qml # Theme and styling
+│ ├── Config.qml # Configuration options
+│ ├── functions/
+│ │ └── ColorUtils.qml # Color manipulation utilities
+│ └── widgets/
+│ ├── StyledText.qml # Styled text component
+│ ├── StyledRectangularShadow.qml
+│ ├── StyledToolTip.qml
+│ └── StyledToolTipContent.qml
+├── services/
+│ ├── GlobalStates.qml # Global state management
+│ └── HyprlandData.qml # Hyprland data provider
+└── modules/
+ └── overview/
+ ├── Overview.qml # Main overview component
+ ├── OverviewWidget.qml # Workspace grid widget
+ └── OverviewWindow.qml # Individual window preview
+```
+
+## 🎯 IPC Commands
+
+```bash
+# Toggle overview
+qs ipc -c overview call overview toggle
+
+# Open overview
+qs ipc -c overview call overview open
+
+# Close overview
+qs ipc -c overview call overview close
+```
+
+## 🐛 Known Issues
+
+- Window icons may fallback to generic icon if app class name doesn't match icon theme
+- Potential crashes during rapid window state changes due to Wayland screencopy buffer management
+
+## Credits
+
+Extracted from the overview feature in [illogical-impulse](https://github.com/end-4/dots-hyprland) by [end-4](https://github.com/end-4).
+
+Adapted as a standalone component for Hyprland + Quickshell users who want just the overview functionality.
+
+---
+
+<div align="center">
+
+**Note:** Maintenance will be limited due to time constraints, but **PRs and code improvements are welcome!** Feel free to contribute or fork for your own needs.
+
+Made with ❤️ for the Hyprland community
+
+</div>
send patches to the email below
yukais@pinapelz.com
include the subject [PATCH repo_name]
pinapelz.com
homepage