diff options
| author | Don Williams <don.e.williams@gmail.com> | 2025-11-30 20:04:02 -0500 |
|---|---|---|
| committer | Don Williams <don.e.williams@gmail.com> | 2025-11-30 20:04:02 -0500 |
| commit | ca0c23cce006ea3f7d793c5fa8eee6acff196470 (patch) | |
| tree | 092a7446c0f494c958b11b1af09474d99718a74e /config/quickshell/overview/README.md | |
| parent | 510eafbe0560cff6e459b64fcb778d645cd43ab3 (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.md | 214 |
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. + + + + + + +</div> + +--- + +## 📸 Preview + + + +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> |
