From 5d94c0a7d44a2255b81815a52a7056a94a39842d Mon Sep 17 00:00:00 2001 From: nippy Date: Sat, 18 Apr 2026 13:49:56 +0200 Subject: update Raveos themes --- .../DankMaterialShell/quickshell/README.md | 241 +++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 raveos-theme/hyprland/theme-data/DankMaterialShell/quickshell/README.md (limited to 'raveos-theme/hyprland/theme-data/DankMaterialShell/quickshell/README.md') diff --git a/raveos-theme/hyprland/theme-data/DankMaterialShell/quickshell/README.md b/raveos-theme/hyprland/theme-data/DankMaterialShell/quickshell/README.md new file mode 100644 index 0000000..df85295 --- /dev/null +++ b/raveos-theme/hyprland/theme-data/DankMaterialShell/quickshell/README.md @@ -0,0 +1,241 @@ +# DMS Quickshell Interface + +QML-based desktop shell interface for DankMaterialShell providing panels, widgets, and overlays. + +**See [root README](../README.md) for project overview and installation.** + +## Architecture + +**Modular QML Structure** +- `Modules/` - UI components (panels, widgets, overlays) +- `Services/` - System integration singletons (audio, network, bluetooth) +- `Widgets/` - Reusable UI controls +- `Common/` - Shared resources and themes + +**Technology Stack** +- [Quickshell](https://quickshell.org/) - QML-based shell framework +- Qt/QtQuick - UI rendering and controls +- Material Design 3 - Design system and theming + +## Development + +**Run the shell:** +```bash +quickshell -p quickshell/ +``` + +**Code formatting:** +```bash +qmlfmt -t 4 -i 4 -b 250 -w path/to/file.qml +make lint-qml # Run from repo root; requires quickshell/.qmlls.ini (generated by `qs -p quickshell/`) + # Uses Qt 6 qmllint. Override path with QMLLINT=/path/to/qmllint if needed. + # Auto-detects `qmllint6`, Fedora's `qmllint-qt6`, `/usr/lib/qt6/bin/qmllint`, then `qmllint`. +``` + +## Components + +**Panels & Bars** +- `Modules/TopBar/` - Multi-monitor status bars with workspace switching +- `Modules/DankBar/` - Customizable widget bar with plugin support +- `Modules/Dock/` - Application dock with window management + +**System Controls** +- `Modules/ControlCenter/` - WiFi, Bluetooth, audio, display settings +- `Modules/Notifications/` - Notification center with popups +- `Modules/Greetd/` - Login greeter interface + +**Overlays** +- `Modules/Spotlight/` - Application and file launcher +- `Modules/Overview/` - Workspace overview +- `Modules/Lock/` - Screen lock system + +**Utilities** +- `Modules/ProcessList/` - System monitoring and process management +- `Modules/Calendar/` - Calendar widget with event sync +- `Modules/Weather/` - Weather display + +## Services + +Singletons providing system integration: + +**Media & Audio** +- `AudioService` - PipeWire/PulseAudio volume and device control +- `MprisController` - Media player integration + +**Network** +- `NetworkService` - NetworkManager WiFi control +- `BluetoothService` - BlueZ Bluetooth management + +**Display** +- `DisplayService` - Brightness control and night mode +- `WallpaperService` - Wallpaper management and effects + +**System** +- `BatteryService` - Battery status and power profiles +- `IdleService` - Idle detection and inhibit locks +- `ClipboardService` - Clipboard history with images +- `DgopService` - System metrics (CPU, RAM, GPU) + +**Integration** +- `NiriService` - Niri workspace integration +- `HyprlandService` - Hyprland workspace integration +- `PluginService` - Plugin discovery and lifecycle + +## Widgets + +Reusable Material Design 3 components in `Widgets/`: + +- `DankIcon` - Icon component with Material font +- `DankSlider` - Enhanced slider with animations +- `DankToggle` - Toggle switch component +- `DankTabBar` - Tab bar implementation +- `DankGridView` - Grid layout with adaptive columns +- `DankListView` - Scrollable list view +- `DankTextField` - Text input with validation +- `DankDropdown` - Dropdown selection +- `DankPopout` - Base for overlay components +- `StateLayer` - Material interaction states + +## Theming + +**Dynamic Color Schemes** + +Wallpaper-based theming using [matugen](https://github.com/InioX/matugen): + +```qml +import qs.Common + +Rectangle { + color: Theme.container + border.color: Theme.outline +} +``` + +Theme singleton provides Material Design 3 color system, spacing, fonts, and elevation. + +**Application Themes** + +Templates in `scripts/templates/` generate themes for: +- GTK 3/4 +- Qt5/Qt6 +- Alacritty, Kitty, Ghostty, Foot, Wezterm terminals +- Neovim +- VSCode/VSCodium +- Firefox + +## Multi-Monitor Support + +Per-monitor panel instances using Quickshell `Variants`: + +```qml +Variants { + model: Quickshell.screens + PanelWindow { + screen: modelData + // Per-screen configuration + } +} +``` + +Workspace switchers adapt to compositor (Niri/Hyprland). + +## Plugin System + +External plugins in `~/.config/DankMaterialShell/plugins/`: + +**Widget plugins** - UI components in DankBar +**Daemon plugins** - Background processes without UI + +Plugin manifest (`plugin.json`): +```json +{ + "id": "pluginId", + "name": "Plugin Name", + "version": "1.0.0", + "type": "widget", + "component": "./Widget.qml", + "settings": "./Settings.qml", + "permissions": ["settings_read", "settings_write"] +} +``` + +Plugins access `pluginService` for persistent data: +```qml +pluginService.savePluginData("pluginId", "key", value) +pluginService.loadPluginData("pluginId", "key", defaultValue) +``` + +## IPC Integration + +Backend IPC socket communication: + +```qml +import Quickshell.Io + +Process { + command: ["dms", "ipc", "call", "spotlight", "toggle"] + running: true +} +``` + +Common IPC commands exposed through services for reactive property bindings. + +## Code Conventions + +**Component Structure:** +```qml +import QtQuick +import Quickshell +import qs.Common +import qs.Services + +Item { + id: root + + property type name: value + + signal customSignal(type param) + + Component { /* children */ } +} +``` + +**Services (Singletons):** +```qml +import QtQuick +import Quickshell +pragma Singleton +pragma ComponentBehavior: Bound + +Singleton { + id: root + + property bool featureAvailable: false + property type currentValue: defaultValue + + function performAction(param) { /* implementation */ } +} +``` + +**Guidelines:** +- Use `Theme.propertyName` for consistent styling +- Bind directly to service properties for reactivity +- Use `DankIcon` for all icons +- Implement feature detection and graceful degradation +- 4-space indentation, no unnecessary comments + +## Translation + +Internationalization using POEditor: + +```bash +export POEDITOR_API_TOKEN="token" +export POEDITOR_PROJECT_ID="id" +python3 scripts/i18nsync.py sync +``` + +Pre-commit hook checks translation sync status. + +## License + +MIT License - See [LICENSE](../LICENSE) for details. -- cgit v1.3