diff options
Diffstat (limited to 'config/quickshell/overview/README.md')
| -rw-r--r-- | config/quickshell/overview/README.md | 550 |
1 files changed, 519 insertions, 31 deletions
diff --git a/config/quickshell/overview/README.md b/config/quickshell/overview/README.md index c32e7ac5..64dd8b68 100644 --- a/config/quickshell/overview/README.md +++ b/config/quickshell/overview/README.md @@ -9,6 +9,7 @@ A standalone workspace overview module for Hyprland using Quickshell - shows all   + </div> --- @@ -17,7 +18,7 @@ A standalone workspace overview module for Hyprland using Quickshell - shows all  -https://github.com/user-attachments/assets/79ceb141-6b9e-4956-8e09-aaf72b66550c +https://github.com/user-attachments/assets/e8f392d7-d831-4dec-9cd3-fb93d1ccc21c > *Workspace overview showing live window previews with drag-and-drop support* @@ -26,40 +27,85 @@ https://github.com/user-attachments/assets/79ceb141-6b9e-4956-8e09-aaf72b66550c ## ✨ Features - 🖼️ Visual workspace overview showing all workspaces and windows +- 🖥️ Multi-monitor support with proper scaling and vertical/rotated monitors [in experimental branch] +- 📐 Smart row hiding - optionally hide empty workspace rows - 🎯 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) +- ⌨️ Keyboard navigation (Arrow keys, vim keys, number shortcuts) +- 🖱️ Auto-close on focus loss / outside click - 💡 Hover tooltips showing window information - 🎨 Material Design 3 theming - ⚡ Smooth animations and transitions ## 📦 Installation +### Arch Linux (AUR) + +For Arch Linux users, you can install directly from the AUR: + +```bash +# Using yay +yay -S quickshell-overview-git + +# Using paru +paru -S quickshell-overview-git +``` + +On AUR installs, module files are package-managed under: + +```text +/etc/xdg/quickshell/overview/ +``` + +Put your custom settings in: + +```text +~/.config/quickshell/overview/config.json +``` + +Then add the keybind and auto-start to your Hyprland config (see Setup steps 2-4 below). + ### 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 +- **Qt 6** with modules: QtQuick, QtQuick.Controls ### Setup -1. **Clone this repository** to your Quickshell config directory: +1. **Install module files** (choose one): + - **Git clone (manual install):** ```bash git clone https://github.com/Shanu-Kumawat/quickshell-overview ~/.config/quickshell/overview ``` + - **AUR package:** use the command above (`yay -S quickshell-overview-git` or `paru -S ...`) -2. **Add keybind** to your Hyprland config (`~/.config/hypr/hyprland.conf`): +2. **Add keybind** to your Hyprland config: + + *For Hyprland 0.55+ (`~/.config/hypr/hyprland.lua`):* + ```lua + hl.bind("SUPER + TAB", hl.dsp.exec_cmd("qs ipc -c overview call overview toggle")) + ``` + *For Hyprland 0.54 and older (`~/.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): +4. **Auto-start** the overview (add to Hyprland config): + + *For Hyprland 0.55+ (`~/.config/hypr/hyprland.lua`):* + ```lua + hl.on("hyprland.start", function () + hl.exec_cmd("qs -c overview") + end) + ``` + *For Hyprland 0.54 and older (`~/.config/hypr/hyprland.conf`):* ```conf exec-once = qs -c overview ``` -4. **Reload Hyprland**: +6. **Reload Hyprland**: ```bash hyprctl reload ``` @@ -70,36 +116,116 @@ https://github.com/user-attachments/assets/79ceb141-6b9e-4956-8e09-aaf72b66550c qs -c overview & ``` +### NixOS + +For NixOS users, ensure Quickshell has access to required Qt6 modules: + +```nix +# In your configuration.nix or home-manager config +environment.systemPackages = with pkgs; [ + quickshell + qt6.qtwayland +]; +``` + +If you're using home-manager: + +```nix +home.packages = with pkgs; [ + quickshell + qt6.qtwayland +]; +``` + ## 🎮 Usage | Action | Description | |--------|-------------| | **Super + Tab** | Toggle the overview | -| **Left/Right Arrow Keys** | Navigate between workspaces horizontally | -| **Up/Down Arrow Keys** | Navigate between workspace rows | +| **Arrow Keys / h/l** | Navigate left/right within current row* | +| **Up/Down / j/k** | Navigate between workspace rows | +| **1-9, 0** | Jump to Nth workspace in current group (0 = 10th) | +| **Mouse wheel on grid** | Move across all normal workspaces, wrapping from last to first | | **Escape / Enter** | Close the overview | +| **Click outside overview** | Close the overview when `overview.closeOnFocusLoss` is enabled (default) | | **Click workspace** | Switch to that workspace | | **Click window** | Focus that window | | **Middle-click window** | Close that window | | **Drag window** | Move window to different workspace | +> *When `hideEmptyRows` is enabled, left/right navigation wraps within the current visible row for better UX + --- ## ⚙️ Configuration -> **⚠️ Want to change the size, position, or number of workspaces?** -> Edit `~/.config/quickshell/overview/common/Config.qml` - it's all there! +> **⚠️ Want to change size, position, workspace count, or toggles?** +> Create/edit `~/.config/quickshell/overview/config.json`. + +`Config.qml` inside the module is now treated as defaults. User overrides are read from: + +- `$XDG_CONFIG_HOME/quickshell/overview/config.json` +- fallback: `~/.config/quickshell/overview/config.json` + +> **Note:** After editing `config.json`, manually restart overview for changes to apply: +> `qs ipc -c overview call overview close && qs -c overview` + +### Quick Start + +```bash +mkdir -p ~/.config/quickshell/overview +cp /etc/xdg/quickshell/overview/config.example.json ~/.config/quickshell/overview/config.json +``` + +If you installed from git clone instead of AUR, copy from your repo path: + +```bash +cp ~/.config/quickshell/overview/config.example.json ~/.config/quickshell/overview/config.json +``` ### Workspace Grid -Edit `~/.config/quickshell/overview/common/Config.qml`: +Edit `~/.config/quickshell/overview/config.json`: -```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 +```json +{ + "overview": { + "rows": 2, + "columns": 5, + "scale": 0.16, + "enable": true, + "hideEmptyRows": true, + "closeOnFocusLoss": true, + "useWorkspaceMap": false, + "workspaceMap": [0, 10], + "orderRightLeft": false, + "orderBottomUp": false, + "previewsEnabled": true, + "previewMode": "live", + "includeInactiveMonitorPreviews": true, + "previewRecaptureDelayMs": 60, + "showSpecialWorkspaces": true, + "specialWorkspaces": [], + "specialWorkspaceColumns": 5, + "emptyWorkspaceWallpaper": "", + "specialEmptyWorkspaceWallpaper": "", + "effects": { + "enableBackdrop": false, + "backdropOpacity": 0.28, + "panelOpacity": 0.92, + "workspaceOpacity": 0.86, + "emptyWorkspaceWallpaperOverlayOpacity": 0.18, + "windowOverlayOpacity": 0.22, + "enableBlur": false, + "glassMode": false, + "glassTintStrength": 0.35, + "glassBorderOpacity": 0.72, + "glassShineOpacity": 0.14 + }, + "workspaceSpacing": 5, + "backgroundPadding": 10, + "workspaceNumberBaseSize": 250 + } } ``` @@ -107,26 +233,382 @@ property QtObject overview: QtObject { - **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) +- **Reverse order?** Set `orderRightLeft` and/or `orderBottomUp` to `true` +- **Prefer the overview to stay open after outside clicks/focus changes?** Set `closeOnFocusLoss` to `false` +- **Per-monitor workspace groups?** Enable `useWorkspaceMap` and set `workspaceMap` (e.g. `[0,10]`) +- **Show special workspaces below grid?** Keep `showSpecialWorkspaces: true` and optionally prefill `specialWorkspaces` +- **Lower memory use?** Set `previewMode` to `event` and `includeInactiveMonitorPreviews` to `false` +- **Transparency / blur?** Tune `overview.effects.*` (details below) + +**Hide empty workspace rows:** +- Set `hideEmptyRows: true` to automatically hide rows that have no windows +- Keeps your overview clean by only showing rows with active workspaces +- The current workspace row is always visible, even if empty +- Arrow key navigation (left/right) stays within the current row when enabled +- Great for 2-row setups where you rarely use workspaces 6-10 + +**Close on focus loss / outside click:** +- `closeOnFocusLoss` defaults to `true` +- When enabled, clicking outside the overview closes it, similar to menus, dropdowns, and launchers +- The overview also closes when its Hyprland focus grab is cleared +- Set `closeOnFocusLoss: false` if you want the previous behavior where the overview can remain open after focus changes ### Position -Edit `~/.config/quickshell/overview/modules/overview/Overview.qml` (line ~111): +Edit `~/.config/quickshell/overview/config.json`: + +```json +{ + "position": { + "topMargin": 100 + } +} +``` + +Increase `topMargin` to move the overview down. Decrease it to move up. + +### Window Preview + +```json +{ + "windowPreview": { + "showIcons": true, + "iconToWindowRatio": 0.25, + "iconToWindowRatioCompact": 0.45, + "xwaylandIndicatorToIconRatio": 0.35, + "inactiveMonitorOpacity": 0.4, + "cropToFill": false + } +} +``` + +- `cropToFill`: crop full-screen windows to fill the workspace preview when `true`; keep the full window in preview with possible horizontal/vertical "padding" bars when `false` + +### Performance Tuning + +```json +{ + "overview": { + "previewsEnabled": true, + "previewMode": "live", + "includeInactiveMonitorPreviews": true, + "previewRecaptureDelayMs": 60 + }, + "hacks": { + "hyprlandEventDebounceMs": 40 + } +} +``` + +- `overview.previewsEnabled`: turn all window screencopy previews on/off +- `overview.previewMode`: `live` (best visuals, more RAM) or `event` (lower RAM, refreshes on window events) +- `overview.includeInactiveMonitorPreviews`: when `false`, only current monitor windows get preview capture +- `overview.previewRecaptureDelayMs`: delay used for event-mode snapshot refresh (lower = faster updates) +- `hacks.hyprlandEventDebounceMs`: coalesces Hyprland event refreshes to reduce command churn + +### Special Workspaces + +```json +{ + "overview": { + "showSpecialWorkspaces": true, + "specialWorkspaces": ["stash", "music", "scratch"], + "specialWorkspaceColumns": 5 + } +} +``` + +- `showSpecialWorkspaces`: renders special workspaces in a strip under the normal grid +- `specialWorkspaces`: optional preconfigured special workspace names (without the `special:` prefix) +- `specialWorkspaceColumns`: how many special tiles per row before wrapping +- `emptyWorkspaceWallpaper`: optional image path used as the background for normal workspace tiles +- `specialEmptyWorkspaceWallpaper`: optional image path used as the background for special workspace tiles + +Interaction behavior: +- Preconfigured special workspaces appear in the overview even when they are empty +- The special strip shows active special workspaces plus any names you preconfigure +- This is useful for fixed workflows like `stash`, `music`, or `scratch` +- Click a special tile to run `togglespecialworkspace <name>` +- Click the `+` tile to create and open a new special workspace +- Drag a window onto a special tile to move it with `movetoworkspacesilent special:<name>` +- Drag a window onto the `+` tile to auto-create a new special workspace (`stash`, `stash-2`, ...), even when no special workspace is currently open or preconfigured +- Special windows are visible directly in those tiles +- Restart Quickshell after changing `config.json`, otherwise the special workspace list will not refresh immediately + +Normal workspace scrolling: +- Scroll on the normal workspace grid to move the active workspace/highlighter across all normal workspaces +- Scrolling wraps from the last workspace back to `1`, and from `1` back to the last + +### Workspace Wallpaper + +```json +{ + "overview": { + "emptyWorkspaceWallpaper": "/home/your-user/Pictures/wallpaper.png", + "specialEmptyWorkspaceWallpaper": "/home/your-user/Pictures/special-wallpaper.png", + "effects": { + "emptyWorkspaceWallpaperOverlayOpacity": 0.12 + } + } +} +``` + +- Normal workspaces can use a wallpaper as their background +- Special workspaces can use a different wallpaper as their background +- The wallpaper remains visible behind floating or partially covered windows +- If no special workspaces exist yet, that special wallpaper is also used for the `+` create tile +- `emptyWorkspaceWallpaperOverlayOpacity` controls how much tint is applied over that wallpaper +- Use an absolute path for the image for the most reliable behavior +- Restart Quickshell after changing `config.json`, otherwise the wallpaper path will not refresh immediately + +Demo: + + + +### Transparency & Blur + +```json +{ + "overview": { + "effects": { + "enableBackdrop": false, + "backdropOpacity": 0.28, + "panelOpacity": 0.92, + "workspaceOpacity": 0.86, + "emptyWorkspaceWallpaperOverlayOpacity": 0.18, + "windowOverlayOpacity": 0.22, + "enableBlur": false, + "glassMode": false, + "glassTintStrength": 0.35, + "glassBorderOpacity": 0.72, + "glassShineOpacity": 0.14 + } + } +} +``` + +- `enableBackdrop`: show/hide full-screen dim backdrop behind overview +- `backdropOpacity`: opacity of backdrop dim layer (`0` to `1`) +- `panelOpacity`: opacity of overview panel container (`0` to `1`) +- `workspaceOpacity`: opacity of each workspace tile (`0` to `1`) +- `emptyWorkspaceWallpaperOverlayOpacity`: tint strength over empty-workspace wallpaper (`0` to `1`) +- `windowOverlayOpacity`: opacity of the color tint over window previews (`0` to `1`) +- `enableBlur`: switches layer namespace to `quickshell:overview-blur` +- `glassMode`: enables a glass-like tint + softer transparency preset for panel/workspaces/windows +- `glassTintStrength`: tint mixing strength for glass mode (`0` to `1`) +- `glassBorderOpacity`: border alpha used by glass mode (`0` to `1`) +- `glassShineOpacity`: top highlight strength for glass reflections (`0` to `1`) + +Stronger glass preset: + +```json +{ + "overview": { + "effects": { + "enableBackdrop": true, + "enableBlur": true, + "panelOpacity": 0.55, + "workspaceOpacity": 0.48, + "emptyWorkspaceWallpaperOverlayOpacity": 0.10, + "windowOverlayOpacity": 0.08, + "glassMode": true, + "glassTintStrength": 0.55, + "glassBorderOpacity": 0.85, + "glassShineOpacity": 0.32 + } + } +} +``` -```qml -anchors { - horizontalCenter: parent.horizontalCenter - top: parent.top - topMargin: 100 // Change this value to move up/down +For Hyprland blur, add layer rules (example): + +```ini +layerrule = blur true, match:namespace quickshell:overview-blur +layerrule = ignore_alpha 0.2, match:namespace quickshell:overview-blur +``` + +If `enableBlur` is `false`, namespace remains `quickshell:overview`. + +Low-memory preset: + +```json +{ + "overview": { + "previewMode": "event", + "includeInactiveMonitorPreviews": false + }, + "hacks": { + "hyprlandEventDebounceMs": 80 + } +} +``` + +### Full Example + +```json +{ + "appearance": { + "colorSource": "default", + "caelestia": { + "autoRefresh": true, + "refreshInterval": 2000, + "accentProfile": "vibrant" + }, + "rounding": { + "unsharpen": 2, + "verysmall": 8, + "small": 12, + "normal": 17, + "large": 23, + "full": 9999, + "screenRounding": 23, + "windowRounding": 18 + }, + "font": { + "family": { + "main": "sans-serif", + "title": "sans-serif", + "expressive": "sans-serif" + }, + "pixelSize": { + "smaller": 12, + "small": 15, + "normal": 16, + "larger": 19, + "huge": 22 + } + }, + "animation": { + "duration": { + "elementMove": 500, + "elementMoveEnter": 400, + "elementMoveFast": 200 + } + }, + "sizes": { + "elevationMargin": 10 + } + }, + "overview": { + "rows": 2, + "columns": 5, + "scale": 0.16, + "enable": true, + "hideEmptyRows": true, + "closeOnFocusLoss": true, + "useWorkspaceMap": false, + "workspaceMap": [0, 10], + "orderRightLeft": false, + "orderBottomUp": false, + "previewsEnabled": true, + "previewMode": "live", + "includeInactiveMonitorPreviews": true, + "previewRecaptureDelayMs": 60, + "showSpecialWorkspaces": true, + "specialWorkspaces": [], + "specialWorkspaceColumns": 5, + "emptyWorkspaceWallpaper": "", + "specialEmptyWorkspaceWallpaper": "", + "effects": { + "enableBackdrop": false, + "backdropOpacity": 0.28, + "panelOpacity": 0.92, + "workspaceOpacity": 0.86, + "emptyWorkspaceWallpaperOverlayOpacity": 0.18, + "windowOverlayOpacity": 0.22, + "enableBlur": false, + "glassMode": false, + "glassTintStrength": 0.35, + "glassBorderOpacity": 0.72, + "glassShineOpacity": 0.14 + }, + "workspaceSpacing": 5, + "backgroundPadding": 10, + "workspaceNumberBaseSize": 250 + }, + "position": { + "topMargin": 100 + }, + "windowPreview": { + "showIcons": true, + "iconToWindowRatio": 0.25, + "iconToWindowRatioCompact": 0.45, + "xwaylandIndicatorToIconRatio": 0.35, + "inactiveMonitorOpacity": 0.4, + "cropToFill": false + }, + "hacks": { + "arbitraryRaceConditionDelay": 150, + "hyprlandEventDebounceMs": 40 + } } ``` ### 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 +Most theme sizing/timing options are now configurable via `config.json`: +- `appearance.colorSource` (`default`, `matugen`, `caelestia`) +- `appearance.caelestia.*` (`autoRefresh`, `refreshInterval`, `accentProfile`) +- `appearance.rounding.*` +- `appearance.font.*` +- `appearance.animation.duration.*` +- `appearance.sizes.elevationMargin` + +For full color palette customization, edit `~/.config/quickshell/overview/common/Appearance.qml`. + +### Matugen (Dynamic Colors from Wallpaper) + +[Matugen](https://github.com/InioX/matugen) lets you generate Material You colors from your wallpaper and apply them to the overview automatically. + +**1. Install matugen** - follow [matugen's install guide](https://github.com/InioX/matugen?tab=readme-ov-file#installation) + +**2. Copy the template** from this repo to matugen's templates folder: +```bash +mkdir -p ~/.config/matugen/templates +cp ~/.config/quickshell/overview/quickshell-overview.qml ~/.config/matugen/templates/ +``` + +**3. Add this to `~/.config/matugen/config.toml`** (create the file if it doesn't exist): +```toml +[templates.quickshell_overview] +input_path = "./templates/quickshell-overview.qml" +output_path = "~/.config/quickshell/overview/common/Appearance.colors.qml" +``` + +**4. Enable it** in `~/.config/quickshell/overview/config.json`: +```json +{ + "appearance": { + "colorSource": "matugen" + } +} +``` + +**5. Run matugen** with your wallpaper to generate colors: +```bash +matugen image /path/to/your/wallpaper.jpg +``` + +This generates `Appearance.colors.qml` which the overview loads automatically. Re-run step 5 whenever you change your wallpaper. + +### Caelestia + +If you use Caelestia, set the source to `caelestia`: + +```json +{ + "appearance": { + "colorSource": "caelestia", + "caelestia": { + "autoRefresh": true, + "refreshInterval": 2000, + "accentProfile": "vibrant" + } + } +} +``` + +Overview reads the active palette from `caelestia scheme get` and refreshes it live when `autoRefresh` is enabled, so wallpaper/scheme changes can apply without restarting overview. --- @@ -138,7 +620,6 @@ Edit `~/.config/quickshell/overview/common/Appearance.qml` to customize: - QtQuick - QtQuick.Controls - QtQuick.Layouts - - Qt5Compat.GraphicalEffects - Quickshell.Wayland - Quickshell.Hyprland @@ -158,10 +639,11 @@ The following features were removed to make it standalone: ~/.config/quickshell/overview/ ├── shell.qml # Main entry point ├── README.md # This file +├── config.example.json # User override template ├── hyprland-config.conf # Configuration reference ├── common/ │ ├── Appearance.qml # Theme and styling -│ ├── Config.qml # Configuration options +│ ├── Config.qml # Default config + user override loader │ ├── functions/ │ │ └── ColorUtils.qml # Color manipulation utilities │ └── widgets/ @@ -197,6 +679,12 @@ qs ipc -c overview call overview close - 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 +## 💖 Support + +If this project helps your setup and you want to support continued maintenance, you can sponsor here: + +https://github.com/sponsors/Shanu-Kumawat + ## Credits Extracted from the overview feature in [illogical-impulse](https://github.com/end-4/dots-hyprland) by [end-4](https://github.com/end-4). |