sankalp/Modus
1
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: add settings window to fabric-cli and update docs

Browse Source
This commit is contained in:
sankalp committed 2026-07-19 10:37:12 +05:45
1 parent a7d4358cef
commit 96412dda47
8 files changed
+217 -141
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+96 -77
View File
@@ -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) <br>
> - 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
<details>
<summary>Click to expand manual install steps</summary>
# 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
</details>
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
config/hypr/modus.lua
+1
View File
@@ -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
docs/architecture.md
+1
View File
@@ -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
docs/configuration.md
+100 -60
View File
@@ -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.
docs/faqs_tips.md
+7 -2
View File
@@ -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`:
src/main.py
+3
View File
@@ -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()
src/shared/data.py
+7 -1
View File
@@ -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"
src/utils/constants.py
+2 -1
View File
@@ -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": "",
}