mirror of
https://github.com/AvengeMedia/DankMaterialShell.git
synced 2026-01-24 21:42:51 -05:00
meta: monorepo updates
This commit is contained in:
bbedward
@@ -1,219 +1,238 @@
|
||||
# DankMaterialShell (dms)
|
||||
# DMS Quickshell Interface
|
||||
|
||||
<div align="center">
|
||||
<a href="https://danklinux.com">
|
||||
<img src="assets/danklogo2.svg" alt="DankMaterialShell Logo" width="200">
|
||||
</a>
|
||||
QML-based desktop shell interface for DankMaterialShell providing panels, widgets, and overlays.
|
||||
|
||||
### A modern Wayland desktop shell
|
||||
**See [root README](../README.md) for project overview and installation.**
|
||||
|
||||
Built with [Quickshell](https://quickshell.org/) and [Go](https://go.dev/)
|
||||
## Architecture
|
||||
|
||||
[](https://danklinux.com/docs)
|
||||
[](https://github.com/AvengeMedia/DankMaterialShell/stargazers)
|
||||
[](https://github.com/AvengeMedia/DankMaterialShell/blob/master/LICENSE)
|
||||
[](https://github.com/AvengeMedia/DankMaterialShell/releases)
|
||||
[](https://aur.archlinux.org/packages/dms-shell-bin)
|
||||
[)](https://aur.archlinux.org/packages/dms-shell-git)
|
||||
[](https://ko-fi.com/avengemediallc)
|
||||
**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
|
||||
|
||||
</div>
|
||||
**Technology Stack**
|
||||
- [Quickshell](https://quickshell.org/) - QML-based shell framework
|
||||
- Qt/QtQuick - UI rendering and controls
|
||||
- Material Design 3 - Design system and theming
|
||||
|
||||
DankMaterialShell is a complete desktop shell for [niri](https://github.com/YaLTeR/niri), [Hyprland](https://hypr.land), [MangoWC](https://github.com/DreamMaoMao/mangowc), [Sway](https://swaywm.org), and other Wayland compositors. It replaces waybar, swaylock, swayidle, mako, fuzzel, polkit, and everything else you'd normally stitch together to make a desktop - all in one cohesive package with a gorgeous interface.
|
||||
## Development
|
||||
|
||||
**Run the shell:**
|
||||
```bash
|
||||
quickshell -p quickshell/
|
||||
```
|
||||
|
||||
**Code formatting:**
|
||||
```bash
|
||||
qmlfmt -t 4 -i 4 -b 250 -w path/to/file.qml
|
||||
qmllint **/*.qml
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
DankMaterialShell combines two main 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
|
||||
|
||||
- **[QML/UI Layer](https://github.com/AvengeMedia/DankMaterialShell)** (this repo) - All the visual components, widgets, and shell interface built with Quickshell
|
||||
- **[Go Backend](https://github.com/AvengeMedia/danklinux)** - System integration, IPC, process management, and core services
|
||||
**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
|
||||
|
||||
## See it in Action
|
||||
**Utilities**
|
||||
- `Modules/ProcessList/` - System monitoring and process management
|
||||
- `Modules/Calendar/` - Calendar widget with event sync
|
||||
- `Modules/Weather/` - Weather display
|
||||
|
||||
<div align="center">
|
||||
## Services
|
||||
|
||||
https://github.com/user-attachments/assets/1200a739-7770-4601-8b85-695ca527819a
|
||||
Singletons providing system integration:
|
||||
|
||||
</div>
|
||||
**Media & Audio**
|
||||
- `AudioService` - PipeWire/PulseAudio volume and device control
|
||||
- `MprisController` - Media player integration
|
||||
|
||||
<details><summary><strong>More Screenshots</strong></summary>
|
||||
**Network**
|
||||
- `NetworkService` - NetworkManager WiFi control
|
||||
- `BluetoothService` - BlueZ Bluetooth management
|
||||
|
||||
<div align="center">
|
||||
**Display**
|
||||
- `DisplayService` - Brightness control and night mode
|
||||
- `WallpaperService` - Wallpaper management and effects
|
||||
|
||||
<img src="https://github.com/user-attachments/assets/203a9678-c3b7-4720-bb97-853a511ac5c8" width="600" alt="Desktop" />
|
||||
**System**
|
||||
- `BatteryService` - Battery status and power profiles
|
||||
- `IdleService` - Idle detection and inhibit locks
|
||||
- `ClipboardService` - Clipboard history with images
|
||||
- `DgopService` - System metrics (CPU, RAM, GPU)
|
||||
|
||||
<img src="https://github.com/user-attachments/assets/a937cf35-a43b-4558-8c39-5694ff5fcac4" width="600" alt="Dashboard" />
|
||||
**Integration**
|
||||
- `NiriService` - Niri workspace integration
|
||||
- `HyprlandService` - Hyprland workspace integration
|
||||
- `PluginService` - Plugin discovery and lifecycle
|
||||
|
||||
<img src="https://github.com/user-attachments/assets/2da00ea1-8921-4473-a2a9-44a44535a822" width="450" alt="Launcher" />
|
||||
## Widgets
|
||||
|
||||
<img src="https://github.com/user-attachments/assets/732c30de-5f4a-4a2b-a995-c8ab656cecd5" width="600" alt="Control Center" />
|
||||
Reusable Material Design 3 components in `Widgets/`:
|
||||
|
||||
</div>
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
curl -fsSL https://install.danklinux.com | sh
|
||||
```
|
||||
|
||||
That's it. One command installs dms and all dependencies on Arch, Fedora, Debian, Ubuntu, openSUSE, or Gentoo.
|
||||
|
||||
**[Manual Installation Guide →](https://danklinux.com/docs/dankmaterialshell/installation)**
|
||||
|
||||
---
|
||||
|
||||
## What You Get
|
||||
|
||||
**Dynamic Theming**
|
||||
Wallpaper-based color schemes that automatically theme GTK, Qt, terminals, editors (like vscode, vscodium), and more with [matugen](https://github.com/InioX/matugen) and [dank16](https://github.com/AvengeMedia/danklinux/blob/master/internal/dank16/dank16.go).
|
||||
|
||||
**System Monitoring**
|
||||
Real-time CPU, RAM, GPU metrics and temps with [dgop](https://github.com/AvengeMedia/dgop). Full process list with search and management.
|
||||
|
||||
**Powerful Launcher**
|
||||
Spotlight-style search for apps, files (via [dsearch](https://github.com/AvengeMedia/danksearch)), emojis, running windows, calculator, commands - extensible with plugins.
|
||||
|
||||
**Control Center**
|
||||
Network, Bluetooth, audio devices, display settings, night mode - all in one clean interface.
|
||||
|
||||
**Smart Notifications**
|
||||
Notification center with grouping, rich text support, and keyboard navigation.
|
||||
|
||||
**Media Integration**
|
||||
MPRIS player controls, calendar sync, weather widgets, clipboard history with image previews.
|
||||
|
||||
**Complete Session Management**
|
||||
Lock screen, idle detection, auto-lock/suspend with separate AC/battery settings, greeter support.
|
||||
|
||||
**Plugin System**
|
||||
Endless customization with the [plugin registry](https://plugins.danklinux.com).
|
||||
|
||||
**TL;DR** - One shell replaces waybar, swaylock, swayidle, mako, fuzzel, polkit and everything else you normally piece together to create a linux desktop.
|
||||
|
||||
---
|
||||
|
||||
## Supported Compositors
|
||||
|
||||
DankMaterialShell works best with **[niri](https://github.com/YaLTeR/niri)**, **[Hyprland](https://hyprland.org/)**, **[sway](https://swaywm.org/)**, and **[dwl/MangoWC](https://github.com/DreamMaoMao/mangowc)**. - with full workspace switching, overview integration, and monitor management.
|
||||
|
||||
Other Wayland compositors work too, just with a reduced feature set.
|
||||
|
||||
**[Compositor configuration guide →](https://danklinux.com/docs/dankmaterialshell/compositors)**
|
||||
|
||||
---
|
||||
|
||||
## Keybinds & IPC
|
||||
|
||||
Control everything from the command line or keybinds:
|
||||
|
||||
```bash
|
||||
dms ipc call spotlight toggle
|
||||
dms ipc call audio setvolume 50
|
||||
dms ipc call wallpaper set /path/to/image.jpg
|
||||
dms ipc call theme toggle
|
||||
```
|
||||
|
||||
**[Full keybind and IPC documentation →](https://danklinux.com/docs/dankmaterialshell/keybinds-ipc)**
|
||||
|
||||
---
|
||||
- `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
|
||||
|
||||
DankMaterialShell automatically generates color schemes from your wallpaper or theme and applies them to GTK, Qt, terminals, and more.
|
||||
**Dynamic Color Schemes**
|
||||
|
||||
DMS is not opinionated or forcing these themes - they are created as optional themes you can enable. You can refer to the documentation if you want to use them:
|
||||
Wallpaper-based theming using [matugen](https://github.com/InioX/matugen):
|
||||
|
||||
**Application theming:** [GTK, Qt, Firefox, terminals, vscode+vscodium →](https://danklinux.com/docs/dankmaterialshell/application-themes)
|
||||
```qml
|
||||
import qs.Common
|
||||
|
||||
**Custom themes:** [Create your own color schemes →](https://danklinux.com/docs/dankmaterialshell/custom-themes)
|
||||
|
||||
---
|
||||
|
||||
## Plugins
|
||||
|
||||
Extend dms with the plugin system. Browse community plugins at [plugins.danklinux.com](https://plugins.danklinux.com).
|
||||
|
||||
**[Plugin development guide →](https://danklinux.com/docs/dankmaterialshell/plugins-overview)**
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
**Website:** [danklinux.com](https://danklinux.com)
|
||||
|
||||
**Docs:** [danklinux.com/docs](https://danklinux.com/docs)
|
||||
|
||||
**Support:** [Ko-fi](https://ko-fi.com/avengemediallc)
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions welcome! Bug fixes, new widgets, theme improvements, or docs - it all helps.
|
||||
|
||||
**Contributing Code:**
|
||||
1. Fork the repository
|
||||
2. Set up the development environment
|
||||
3. Make your changes
|
||||
4. Open a pull request
|
||||
|
||||
**Contributing Documentation:**
|
||||
1. Fork the [DankLinux-Docs](https://github.com/AvengeMedia/DankLinux-Docs) repository
|
||||
2. Update files in the `docs/` folder
|
||||
3. Open a pull request
|
||||
|
||||
### Development Setup
|
||||
|
||||
**Requirements:**
|
||||
- `python3` - Translation management
|
||||
|
||||
**Git Hooks:**
|
||||
|
||||
Enable the pre-commit hook to check translation sync status:
|
||||
|
||||
```bash
|
||||
git config core.hooksPath .githooks
|
||||
Rectangle {
|
||||
color: Theme.container
|
||||
border.color: Theme.outline
|
||||
}
|
||||
```
|
||||
|
||||
**Translation Workflow**
|
||||
Theme singleton provides Material Design 3 color system, spacing, fonts, and elevation.
|
||||
|
||||
Set POEditor credentials:
|
||||
**Application Themes**
|
||||
|
||||
```bash
|
||||
export POEDITOR_API_TOKEN="your_api_token"
|
||||
export POEDITOR_PROJECT_ID="your_project_id"
|
||||
Templates in `scripts/templates/` generate themes for:
|
||||
- GTK 3/4
|
||||
- Qt5/Qt6
|
||||
- Alacritty, Kitty, Foot terminals
|
||||
- VSCode/VSCodium
|
||||
- Firefox
|
||||
|
||||
## Multi-Monitor Support
|
||||
|
||||
Per-monitor panel instances using Quickshell `Variants`:
|
||||
|
||||
```qml
|
||||
Variants {
|
||||
model: Quickshell.screens
|
||||
PanelWindow {
|
||||
screen: modelData
|
||||
// Per-screen configuration
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Sync translations before committing:
|
||||
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
|
||||
```
|
||||
|
||||
This script:
|
||||
- Extracts strings from QML files
|
||||
- Uploads changed English terms to POEditor
|
||||
- Downloads updated translations from POEditor
|
||||
- Stages all changes for commit
|
||||
Pre-commit hook checks translation sync status.
|
||||
|
||||
The pre-commit hook will block commits if translations are out of sync and remind you to run the sync script.
|
||||
## License
|
||||
|
||||
Without POEditor credentials, the hook is skipped and commits proceed normally.
|
||||
|
||||
Check the [issues](https://github.com/AvengeMedia/DankMaterialShell/issues) or join the community.
|
||||
|
||||
---
|
||||
|
||||
## Credits
|
||||
|
||||
- [quickshell](https://quickshell.org/) the core of what makes a shell like this possible.
|
||||
- [niri](https://github.com/YaLTeR/niri) for the awesome scrolling compositor.
|
||||
- [Ly-sec](http://github.com/ly-sec) for awesome wallpaper effects among other things from [Noctalia](https://github.com/noctalia-dev/noctalia-shell)
|
||||
- [soramanew](https://github.com/soramanew) who built [caelestia](https://github.com/caelestia-dots/shell) which served as inspiration and guidance for many dank widgets.
|
||||
- [end-4](https://github.com/end-4) for [dots-hyprland](https://github.com/end-4/dots-hyprland) which also served as inspiration and guidance for many dank widgets.
|
||||
MIT License - See [LICENSE](../LICENSE) for details.
|
||||
|
||||
Reference in New Issue
Block a user