diff --git a/README.md b/README.md index 2e1f15a..51d50b4 100644 --- a/README.md +++ b/README.md @@ -36,94 +36,100 @@ ## Quick Start ```bash -curl -fsSL https://raw.githubusercontent.com/S4NKALP/Modus/macos/install.sh -o install.sh && bash install.sh +git clone https://github.com/S4NKALP/Modus ~/.config/Modus +cd ~/.config/Modus +./install.sh ``` -> [!TIP] -> -> ## Post Installation -> -> - Install recommended [Icon theme](https://github.com/vinceliuice/MacTahoe-icon-theme) , [GTK theme](https://github.com/vinceliuice/MacTahoe-gtk-theme) and [Cursor Theme](https://github.com/vinceliuice/MacTahoe-icon-theme/tree/main/cursors)
-> - Check `config/hypr/modus.lua` edit it according to your device and copy it to your hyprland config -> - For Lock Screen Bind keys to `uv run lock` +The interactive installer handles dependencies, builds C-extensions, and configures Hyprland. ## Manual Installation -```bash -paru -S uv fabric-cli-git uwsm cliphist slurp grim swappy wl-clipboard wtype libnotify playerctl matugen-bin hypridle hyprsunset hyprpicker hyprshot gtk-session-lock awww apple-fonts webp-pixbuf-loader cinnamon-desktop libmediaart acpi brightnessctl power-profiles-daemon ddcutil at-spi2-core networkmanager network-manager-applet blueman pipewire libpulse gcc make pkgconf meson ninja wayland-protocols gobject-introspection gtk-layer-shell librsvg libqalculate appmenu-gtk-module libdbusmenu-gtk3 libdbusmenu-qt5 pciutils wf-recorder ffmpeg --needed -git clone https://github.com/S4NKALP/Modus ~/.config/Modus -cd ~/.config/Modus -uv sync +
+Click to expand manual install steps -# Compile App Switcher C-backend -cd src/window/switcher/app-capture -meson setup builddir -meson compile -C builddir -cd ../../../.. +1. **Install dependencies:** + ```bash + paru -S uv fabric-cli-git uwsm cliphist slurp grim swappy wl-clipboard wtype libnotify playerctl matugen-bin hypridle hyprsunset hyprpicker hyprshot gtk-session-lock awww apple-fonts webp-pixbuf-loader cinnamon-desktop libmediaart acpi brightnessctl power-profiles-daemon ddcutil at-spi2-core networkmanager network-manager-applet blueman pipewire libpulse gcc make pkgconf meson ninja wayland-protocols gobject-introspection gtk-layer-shell librsvg libqalculate appmenu-gtk-module libdbusmenu-gtk3 libdbusmenu-qt5 pciutils wf-recorder ffmpeg --needed + ``` -# Compile Global Menu shim -cd src/window/globalmenu -gcc -shared -fPIC -O2 -o libmenu_button_shim.so libmenu_button_shim.c $(pkg-config --cflags --libs gtk+-3.0) -ldl -cd ../../.. +2. **Clone and sync:** + ```bash + git clone https://github.com/S4NKALP/Modus ~/.config/Modus + cd ~/.config/Modus + uv sync + ``` -uv run start -``` +3. **Build App Switcher backend:** + ```bash + cd src/window/switcher/app-capture + meson setup builddir + meson compile -C builddir + ``` -## Global Menu Compatibility +4. **Build Global Menu shim:** + ```bash + cd src/window/globalmenu + gcc -shared -fPIC -O2 -o libmenu_button_shim.so libmenu_button_shim.c $(pkg-config --cflags --libs gtk+-3.0) -ldl + ``` -MODUS injects the GTK3 menu-button shim (`libmenu_button_shim.so`) **only into -GTK3 apps**, and only when launched through MODUS (dock, spotlight, panel). -GTK4 apps are never touched, so they launch normally — a global `LD_PRELOAD` -of this shim would otherwise crash every GTK4 process. +5. **Start Modus:** + ```bash + cd ~/.config/Modus + uv run start + ``` -### Terminal-launched GTK3 apps +
-Apps you start directly from a terminal don't go through MODUS, so they don't -get the shim. They still work fine; they just miss the synthetic -button-release fix the shim provides. To get it back without a dangerous -system-wide `LD_PRELOAD`, use a thin wrapper that detects GTK3 and injects the -shim only for that process: +## Post Installation -```bash -#!/usr/bin/env bash -# ~/.local/bin/modus-launch — GTK3-aware launcher for the global menu shim -SHIM=~/.config/Modus/src/window/globalmenu/libmenu_button_shim.so -BIN="$(command -v "$1")" -if [[ -n "$BIN" ]] && readelf -d "$BIN" 2>/dev/null | grep -q 'libgtk-3\.so\.0'; then - LD_PRELOAD="$SHIM" "$@" -else - "$@" -fi -``` +- Install recommended [Icon theme](https://github.com/vinceliuice/MacTahoe-icon-theme), [GTK theme](https://github.com/vinceliuice/MacTahoe-gtk-theme), and [Cursor theme](https://github.com/vinceliuice/MacTahoe-icon-theme/tree/main/cursors) +- Source `config/hypr/modus.lua` in your Hyprland config +- Lock screen bind: set to `uv run lock` -Make it executable (`chmod +x ~/.local/bin/modus-launch`) and run GTK3 apps as -`modus-launch gedit` from the terminal. GTK4 apps fall through to a normal -launch. +## Keybinds -## Documentation - -| Doc | What's inside | -| --------------------------------------------- | --------------------------------------------------- | -| [Installation Guide](docs/installation.md) | Automated & manual install, dependencies | -| [Configuration Guide](docs/configuration.md) | `config.toml`, `mods.toml`, `dock.toml`, keybinds | -| [Styling Guide](docs/styling.md) | Matugen colors, CSS customization | -| [Architecture Overview](docs/architecture.md) | App Switcher C-backend, Spotlight engine, Services | -| [Spotlight Plugins](docs/plugins.md) | Install/customize plugins, write your own, examples | -| [FAQs & Tips](docs/faqs_tips.md) | Troubleshooting, shortcuts, live reload | -| [Contributing](CONTRIBUTING.md) | Setup, code style, commit conventions | +| Key | Action | +|-----|--------| +| `Super + D` | Spotlight search | +| `Super + E` | Emoji picker | +| `Super + V` | Clipboard history | +| `Super + W` | Wallpaper browser | +| `Super + I` | Settings | +| `Super + L` | Lock screen | +| `Super + Z` | Screencapture toggle | +| `Super + S` | Screenshot region | +| `Alt + Tab` | Window switcher | +| `Alt + Space` | Keyboard layout switch | +| `Super + Shift + R` | Reload Modus | +| `Super + Shift + Y` | Reload CSS | +| `Alt + Shift + W` | Random wallpaper | ## Configuration -Config files in `config/`, using TOML format: +Three TOML files in `config/`: -| File | Purpose | -| ------------- | -------------------------------------------------- | -| `config.toml` | Main settings (switcher, wallpaper, notifications) | -| `mods.toml` | Custom panel buttons | -| `dock.toml` | Pinned dock apps | +| File | Purpose | Reload | +|------|---------|--------| +| `config.toml` | Main settings (features, widgets, paths) | Restart | +| `mods.toml` | Custom panel buttons | Instant | +| `dock.toml` | Pinned dock apps | Restart | + +You can also toggle most settings from the **Settings window** (`Super + I`). See [Configuration Guide](docs/configuration.md) for full reference. +## Documentation + +| Doc | What's inside | +|-----|---------------| +| [Installation Guide](docs/installation.md) | Automated & manual install, dependencies | +| [Configuration Guide](docs/configuration.md) | `config.toml`, `mods.toml`, `dock.toml`, keybinds | +| [Styling Guide](docs/styling.md) | Matugen colors, CSS customization | +| [Architecture Overview](docs/architecture.md) | App Switcher C-backend, Spotlight engine, Services | +| [Spotlight Plugins](docs/plugins.md) | Install/customize plugins, write your own | +| [FAQs & Tips](docs/faqs_tips.md) | Troubleshooting, shortcuts, live reload | + ## Custom Mods Define panel buttons in `config/mods.toml`: @@ -142,28 +148,45 @@ on-clicked = "kitty" - `on-clicked` — shell command on click - `on-left`, `on-middle`, `on-right` — per-mouse-button commands - `options` — dropdown menu entries (each with `label` + `on-clicked`) -- Full shell syntax (`&&`, `|`) via `sh -c` -- Live reload — edit and changes apply instantly +- Live reload — edits apply instantly ## Spotlight Plugins -The spotlight search (Super+D) is powered by plugins. Drop a `.py` file in -`config/plugins/` and it works instantly. +Drop a `.py` file in `config/plugins/` and it works instantly: ```bash -cp -r examples/plugins/hello.py config/plugins/hello.py +cp examples/plugins/hello.py config/plugins/hello.py # Hit Super+D, type "hi" — greeting appears ``` -Plugin development: +Plugin development with hot reload: ```bash nvim config/plugins/hello.py -fabric-cli exec modus1 'deep_reload hello' # no restart needed +fabric-cli exec modus 'deep_reload hello' # no restart needed ``` See [Spotlight Plugins](docs/plugins.md) for full docs and examples. +## Global Menu Compatibility + +Modus injects `libmenu_button_shim.so` only into GTK3 apps launched through Modus (dock, spotlight, panel). GTK4 apps are never touched. + +For terminal-launched GTK3 apps, use a wrapper: + +```bash +#!/usr/bin/env bash +SHIM=~/.config/Modus/src/window/globalmenu/libmenu_button_shim.so +BIN="$(command -v "$1")" +if [[ -n "$BIN" ]] && readelf -d "$BIN" 2>/dev/null | grep -q 'libgtk-3\.so\.0'; then + LD_PRELOAD="$SHIM" "$@" +else + "$@" +fi +``` + +Save as `~/.local/bin/modus-launch`, make executable, run GTK3 apps as `modus-launch gedit`. + ## Team - [SANKALP](https://github.com/S4NKALP/) @@ -171,11 +194,7 @@ See [Spotlight Plugins](docs/plugins.md) for full docs and examples. ## Special Thanks -A big thank you to the following people for their incredible help with code and creative ideas. Your help made a real difference! - - [darsh](https://github.com/its-darsh): for creating Fabric, which made everything possible. - [gummy bear album](https://github.com/muhchaudhary): for sharing fantastic code snippets that saved me time and effort. - [axenide](https://github.com/Axenide): for the amazing config that not only inspired parts of mine but also provided some gems I couldn't resist borrowing. - [E3nviction](https://github.com/E3nviction/): for code snippets and ideas that were incredibly helpful. - -I truly appreciate your support diff --git a/config/hypr/modus.lua b/config/hypr/modus.lua index 3e79b38..6350ee4 100644 --- a/config/hypr/modus.lua +++ b/config/hypr/modus.lua @@ -28,6 +28,7 @@ for key, method in pairs({ ["SUPER + S"] = "screencapture.toggle(ss='region')", -- Screenshot Region ["ALT + SPACE"] = "switch_keyboard_layout()", -- KB_Layout Switcher ["SUPER + L"] = "lock_screen.lock()", -- Lockscren + ["SUPER + I"] = "settings.toggle()", -- Settings }) do hl.bind(key, hl.dsp.exec_cmd(fabricSend .. ' "' .. method .. '"')) end diff --git a/docs/architecture.md b/docs/architecture.md index 37e9345..d83eec8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -17,6 +17,7 @@ Entry point is `start.py`, delegates to `src/main.py`. `main.py` instantiates - **Spotlight Search**: Super+D search overlay (`src/window/spotlight/`) - **Notification Center**: Notification popups and history (`src/window/notification/`) - **OSD**: Volume/brightness overlays (`src/window/osd/`) +- **Settings**: Configuration GUI (`src/window/settings/`) - **Wallpaper Picker**: Wallpaper browser and management (`src/window/wallpaper/`) ## 2. Spotlight Search Engine diff --git a/docs/configuration.md b/docs/configuration.md index e0b1f0c..afe520b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,78 +1,116 @@ # Configuration Guide -Modus is highly configurable using TOML files located in the `config/` directory. +Modus is configured via TOML files in the `config/` directory, plus a graphical Settings window. ## File Overview -| File | Purpose | -|------|---------| -| `config.toml` | Main application configuration (modules, features, toggles). | -| `mods.toml` | Custom panel button definitions (menus, shell commands). | -| `dock.toml` | Pinned applications for the dock. | +| File | Purpose | Reload | +|------|---------|--------| +| `config.toml` | Main settings (features, widgets, paths) | Restart | +| `mods.toml` | Custom panel buttons (menus, shell commands) | Instant | +| `dock.toml` | Pinned dock apps | Restart | + +## Settings Window + +Press `Super + I` to open the Settings window. It provides a GUI for most `config.toml` options organized into tabs: + +- **General**: Debug mode, weather location, keyboard layouts, night light, switcher preview +- **Dock**: Enable/disable, auto-hide, icon size, special workspace apps +- **Panel**: All panel widgets (global menu, systray, control center, etc.), wallpapers directory +- **Notifications**: Timeout, ignored apps, limited history apps + +Changes save to `config.toml` immediately. Some settings require a restart. + +You can also toggle settings from the terminal: + +```bash +fabric-cli exec modus "settings.toggle()" +``` --- ## `config.toml` (Main Settings) -The `config.toml` file controls which widgets and services are enabled. Most changes here require restarting Modus (`uv run start`). +Auto-generated on first run with sensible defaults. Most changes require restarting Modus (`uv run start`). -**Key Settings:** -- `wallpapers_dir`: Path to the directory where your wallpapers are stored. -- `dock_enabled`: Toggle the dock widget (`true`/`false`). -- `dock_auto_hide`: Whether the dock hides automatically when windows overlap it. -- `dock_always_occluded`: Whether the dock remains visible even when windows overlap it. -- `dock_icon_size`: Size of dock icons in pixels (default: `52`). -- `debug`: Enable debug logging (`true`/`false`). -- `hide_special_workspace`: Whether to hide the special workspace from the workspace indicator. -- `dock_hide_special_workspace_apps`: Hide apps from the special workspace in the dock. -- `notification_timeout`: Duration before a notification automatically dismisses (e.g., `"5s"`). -- `notification_ignored_apps`: Array of app names whose notifications should be suppressed. -- `notification_limited_apps_history`: Array of app names whose notification history is limited. -- `weather_location`: Set your city for the weather widget (e.g., `"Patan, Nepal"`). +### General -**Panel Module Toggles:** -- `imac_button`: Enable the Apple logo button in the panel. -- `systray`: Enable the system tray. -- `control_center`: Enable the control center widget. -- `search`: Enable the search/spotlight widget. -- `global_menu`: Enable the global menu (app menus appear in the panel). -- `network`: Enable the network indicator in the panel. -- `battery`: Enable the battery indicator in the panel. -- `notification_center`: Enable the notification center. -- `workspace_indicator`: Enable the workspace indicator. -- `bluetooth`: Enable the bluetooth indicator. -- `date_time`: Enable the date/time indicator. -- `osd`: Enable on-screen displays for volume and brightness changes. -- `custom_mods`: Enable custom panel buttons from `mods.toml`. -- `night_light_temperature`: Night light color temperature in Kelvin (e.g., `4500`). -- `keyboard_layouts`: Array of keyboard layout codes (e.g., `["us", "np"]`). -- `systray_ignore`: Array of app names to hide from the system tray. +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `debug` | bool | `false` | Enable verbose logging | +| `weather_location` | string | `""` | City for weather widget (e.g., `"London, UK"`) | +| `keyboard_layouts` | array | `["us"]` | Active keyboard layouts | +| `night_light_temperature` | int | `4500` | Night light color temp in Kelvin | +| `wallpapers_dir` | string | `"src/assets/wallpaper_example/"` | Path to wallpapers folder | +| `switcher_live_preview` | bool | `true` | Live window previews in switcher | +| `switcher_live_preview_delay_ms` | int | `200` | Preview framerate delay (lower = smoother) | -**App Switcher & Screencapture:** -- `window_switcher`: Enables the custom Alt-Tab window switcher. -- `switcher_live_preview`: Enables real-time Wayland video previews of running applications. -- `switcher_live_preview_delay_ms`: Framerate delay for previews (e.g., `200` = ~5fps). Lower is smoother but uses more CPU. -- `osd`: Enables on-screen displays for volume and brightness changes. +### Dock -**Spotlight Search Keybinds** (defined in `config/hypr/modus.lua`): +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `dock_enabled` | bool | `true` | Show the dock | +| `dock_auto_hide` | bool | `true` | Hide when windows overlap | +| `dock_always_occluded` | bool | `false` | Keep dock behind windows | +| `dock_icon_size` | int | `52` | Icon size in pixels | +| `dock_hide_special_workspace_apps` | bool | `true` | Hide special workspace apps | + +### Panel Widgets + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `imac_button` | bool | `true` | Apple logo button | +| `systray` | bool | `true` | System tray | +| `control_center` | bool | `true` | Control center widget | +| `search` | bool | `true` | Search/spotlight button | +| `global_menu` | bool | `true` | App menus in panel | +| `network` | bool | `true` | Network indicator | +| `battery` | bool | `true` | Battery indicator | +| `bluetooth` | bool | `true` | Bluetooth indicator | +| `date_time` | bool | `true` | Date/time indicator | +| `workspace_indicator` | bool | `true` | Workspace indicator | +| `notification_center` | bool | `true` | Notification center | +| `custom_mods` | bool | `true` | Custom panel buttons from `mods.toml` | +| `window_switcher` | bool | `true` | Alt-Tab window switcher | +| `osd` | bool | `true` | Volume/brightness on-screen display | +| `hide_special_workspace` | bool | `true` | Hide special workspace from indicators | + +### Notifications + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `notification_timeout` | string | `"5s"` | Auto-dismiss duration | +| `notification_ignored_apps` | array | `["Hyprshot"]` | Apps with suppressed notifications | +| `notification_limited_apps_history` | array | `["Spotify"]` | Apps with limited history | +| `systray_ignore` | array | `["blueman", "network"]` | Icons hidden from system tray | + +--- + +## Keybinds + +Defined in `config/hypr/modus.lua`: | Key | Action | |-----|--------| -| `Super + D` | Open spotlight search (default) | -| `Super + E` | Open emoji picker | -| `Super + V` | Open clipboard history | -| `Super + W` | Open wallpaper browser | -| `Alt + Shift + W` | Set random wallpaper | - -These can be customized in `config/hypr/modus.lua`. The spotlight `.toggle()` -method accepts optional arguments to pre-fill keywords: `toggle('em')` opens -the emoji picker directly. +| `Super + D` | Spotlight search | +| `Super + E` | Emoji picker | +| `Super + V` | Clipboard history | +| `Super + W` | Wallpaper browser | +| `Super + I` | Settings window | +| `Super + L` | Lock screen | +| `Super + Z` | Screencapture toggle | +| `Super + S` | Screenshot region | +| `Alt + Tab` | Window switcher | +| `Alt + Space` | Keyboard layout switch | +| `Super + Shift + R` | Reload Modus | +| `Super + Shift + Y` | Reload CSS | +| `Alt + Shift + W` | Random wallpaper | --- ## `mods.toml` (Custom Panel Buttons) -You can define custom buttons for the top panel that run shell commands or show dropdown menus. **Changes to this file reload instantly!** +Define custom buttons for the top panel. **Changes reload instantly!** ```toml [Mods.terminal] @@ -96,17 +134,18 @@ on-left = "wlogout" ``` **Properties:** -- `icon`: The name of an SVG icon placed in `src/assets/icons/`. -- `icon-size`: Defaults to 16. -- `order`: Determines left-to-right position (lower numbers appear first). -- `on-clicked`, `on-left`, `on-right`, `on-middle`: Shell commands executed via `sh -c`. Supports complex piping `|` and `&&`. -- `on-scroll-up`, `on-scroll-down`: Commands executed on scroll events. +- `icon` — SVG filename in `src/assets/icons/` +- `icon-size` — defaults to 16 +- `order` — left-to-right position (lower = first) +- `on-clicked`, `on-left`, `on-right`, `on-middle` — shell commands via `sh -c` +- `on-scroll-up`, `on-scroll-down` — scroll event commands +- `options` — dropdown menu entries (each with `label` + `on-clicked`) +- Full shell syntax (`&&`, `|`) supported --- ## `dock.toml` (Pinned Apps) -Controls which applications are permanently pinned to the dock. ```toml pinned = [ "firefox", @@ -114,4 +153,5 @@ pinned = [ "org.gnome.Nautilus" ] ``` -Ensure you use the exact `.desktop` file name or application ID. + +Use the exact `.desktop` file name or application ID. diff --git a/docs/faqs_tips.md b/docs/faqs_tips.md index d8037c7..5eb914b 100644 --- a/docs/faqs_tips.md +++ b/docs/faqs_tips.md @@ -65,7 +65,7 @@ Update `weather_location` in `config.toml` (e.g., `"London, UK"` or - **Theme Updates**: Modus uses Matugen tied to your wallpaper. Set a new wallpaper and the shell recolors automatically -- **Spotlight Keyboard Shortcuts** (from `config/hypr/modus.lua`): +- **Keyboard Shortcuts** (from `config/hypr/modus.lua`): | Key | Action | |-----|--------| @@ -73,7 +73,12 @@ Update `weather_location` in `config.toml` (e.g., `"London, UK"` or | `Super + E` | Open emoji picker | | `Super + V` | Open clipboard history | | `Super + W` | Open wallpaper browser | - | `Alt + Shift + W` | Set random wallpaper | + | `Super + I` | Open settings | + | `Super + L` | Lock screen | + | `Super + Z` | Screencapture toggle | + | `Super + S` | Screenshot region | + | `Alt + Tab` | Window switcher | + | `Alt + Shift + W` | Random wallpaper | - **Deep Reload a Plugin**: After editing `config/plugins/hello.py`: diff --git a/src/main.py b/src/main.py index 82fecf3..e12c681 100644 --- a/src/main.py +++ b/src/main.py @@ -37,6 +37,7 @@ from window.notification.notification import ModusNoti from window.osd.main import OSDWindow from window.panel.main import Panel from window.screencapture import ScreenCaptureWindow +from window.settings.main import get_settings_window from window.spotlight.main import SpotlightWindow from window.switcher import ApplicationSwitcher @@ -78,6 +79,7 @@ def main(): dock = Dock() osd = OSDWindow() screencapture = ScreenCaptureWindow() + settings = get_settings_window() # Monitor CSS files and subdirectories for changes css_monitors = [] @@ -132,6 +134,7 @@ def main(): __main__.screencapture = screencapture __main__.lock_screen = LockScreenWrapper() __main__.switch_keyboard_layout = KeyboardLayout.switch_keyboard_layout + __main__.settings = settings app.run() diff --git a/src/shared/data.py b/src/shared/data.py index f7ef3e2..91a1113 100644 --- a/src/shared/data.py +++ b/src/shared/data.py @@ -13,13 +13,19 @@ CONFIG_DIR = os.path.expanduser(f"~/.config/{APP_NAME}") SYSTEM_CACHE_DIR = GLib.get_user_cache_dir() +_PROJECT_ROOT = str(__import__("pathlib").Path(__file__).resolve().parent.parent.parent) + + def _get_wallpaper_path() -> str: try: from services.config import get_config custom = get_config("wallpapers_dir") if custom: - return os.path.expanduser(str(custom)) + expanded = os.path.expanduser(str(custom)) + if not os.path.isabs(expanded): + expanded = os.path.join(_PROJECT_ROOT, expanded) + return expanded except Exception as e: logger.warning(f"[data] Failed to load wallpapers_dir from config: {e}") return f"{HOME_DIR}/Pictures/Wallpapers" diff --git a/src/utils/constants.py b/src/utils/constants.py index 9aec4d8..9b95844 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -26,7 +26,8 @@ DEFAULT = { "switcher_live_preview": True, "switcher_live_preview_delay_ms": 200, "systray_ignore": ["blueman", "network"], - "wallpapers_dir": "~/Pictures/Wallpapers", + "wallpapers_dir": "src/assets/wallpaper_example/", "osd": True, "window_switcher": True, + "weather_location": "", }