|
# DWN - Desktop Window Manager
|
|
|
|
retoor <retoor@molodetz.nl>
|
|
|
|
A production-ready X11 window manager written in ANSI C. DWN implements EWMH and ICCCM protocols for cross-compatibility while providing tiling-first workflow management with integrated desktop components.
|
|
|
|
## Architecture
|
|
|
|
DWN uses a modular architecture with specialized subsystems for window management, layout algorithms, panel rendering, system tray, notifications, and optional AI integration. All state is managed through a global singleton with strict encapsulation patterns.
|
|
|
|
The window manager operates with zero window borders and zero gaps between tiles, providing a seamless, professional appearance. Title bars remain at 28px height for window controls.
|
|
|
|
## Core Features
|
|
|
|
### Layout Management
|
|
- **Tiling Mode**: Master-stack layout with configurable ratios
|
|
- **Floating Mode**: Traditional overlapping windows
|
|
- **Monocle Mode**: Single fullscreen window
|
|
- **Composable Snapping**: Quarter-screen, half-screen, and full-screen snapping via Super+Arrow keys
|
|
|
|
### Workspace System
|
|
- 9 independent virtual workspaces (F1-F9)
|
|
- Per-workspace layout persistence
|
|
- Workspace indicators in panel
|
|
- Fast workspace switching with Shift+F1-F9 to move windows
|
|
|
|
### Integrated Components
|
|
- **Top Panel**: Workspace indicators, taskbar, system tray, clock
|
|
- **Bottom Panel**: Additional status information
|
|
- **System Tray**: XEmbed protocol implementation supporting external applications
|
|
- **System Widgets**: Battery indicator, volume control, WiFi manager
|
|
- **Notification Daemon**: D-Bus org.freedesktop.Notifications implementation
|
|
|
|
### News Ticker
|
|
- Real-time news feed in panel
|
|
- Scrolling article titles
|
|
- Super+Return to open current article in browser
|
|
- Configurable news sources
|
|
|
|
### AI Integration
|
|
- **Command Palette** (Super+Shift+A): Natural language window management
|
|
- **Context Analysis** (Super+A): Workspace and task detection
|
|
- **Exa Semantic Search** (Super+Shift+E): Intelligent web search
|
|
- Powered by OpenRouter API (supports multiple LLM providers)
|
|
|
|
### Interactive Features
|
|
- **Tutorial System** (Super+T): Step-by-step keyboard shortcut training
|
|
- **Demo Mode** (Super+Shift+D): Automated feature showcase
|
|
- **Keyboard Shortcuts Help** (Super+S): Quick reference overlay
|
|
|
|
### Automation
|
|
- **XDG Autostart**: Automatic application launching from .desktop files
|
|
- **Service Manager**: Background process management
|
|
- **WebSocket API**: Remote control and state monitoring on port 8777
|
|
|
|
## Installation
|
|
|
|
### Dependencies
|
|
|
|
Required packages (via pkg-config):
|
|
- X11, Xext, Xinerama, Xrandr, Xft
|
|
- fontconfig
|
|
- libdbus-1
|
|
- libcurl
|
|
- libm
|
|
|
|
### Build Process
|
|
|
|
```bash
|
|
git clone https://github.com/your-repo/dwn.git
|
|
cd dwn
|
|
|
|
make deps # Auto-install dependencies (apt/dnf/pacman)
|
|
make # Build release version with -O2 optimization
|
|
make install # Install to /usr/local/bin
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
make run # Launch in nested Xephyr window (safe testing)
|
|
```
|
|
|
|
### Build Targets
|
|
|
|
```bash
|
|
make # Release build with optimization
|
|
make debug # Debug build with -g -DDEBUG
|
|
make clean # Remove build artifacts
|
|
make format # Run clang-format
|
|
make check # Run cppcheck static analysis
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Configuration file: `~/.config/dwn/config`
|
|
|
|
### General Settings
|
|
|
|
```ini
|
|
[general]
|
|
terminal = xfce4-terminal
|
|
launcher = dmenu_run
|
|
file_manager = thunar
|
|
focus_mode = click # click or follow
|
|
focus_follow_delay = 100 # 0-1000ms
|
|
decorations = true
|
|
```
|
|
|
|
### Appearance
|
|
|
|
```ini
|
|
[appearance]
|
|
border_width = 0 # 0-50px (0 for seamless)
|
|
title_height = 28 # 0-100px
|
|
panel_height = 32 # 0-100px
|
|
gap = 0 # 0-100px (0 for seamless)
|
|
font = fixed
|
|
```
|
|
|
|
### Layout
|
|
|
|
```ini
|
|
[layout]
|
|
default = tiling # tiling, floating, monocle
|
|
master_ratio = 0.55 # 0.1-0.9
|
|
master_count = 1 # 1-10
|
|
```
|
|
|
|
### Panels
|
|
|
|
```ini
|
|
[panels]
|
|
top = true
|
|
bottom = true
|
|
```
|
|
|
|
### Colors
|
|
|
|
```ini
|
|
[colors]
|
|
panel_bg = #080808
|
|
panel_fg = #00ff00
|
|
workspace_active = #ff00ff
|
|
workspace_inactive = #222222
|
|
workspace_urgent = #ff0000
|
|
title_focused_bg = #00ffff
|
|
title_focused_fg = #000000
|
|
title_unfocused_bg = #111111
|
|
title_unfocused_fg = #444444
|
|
border_focused = #00ff00
|
|
border_unfocused = #000000
|
|
notification_bg = #111111
|
|
notification_fg = #00ffff
|
|
```
|
|
|
|
### AI Integration
|
|
|
|
```ini
|
|
[ai]
|
|
model = google/gemini-2.0-flash-exp:free
|
|
openrouter_api_key = sk-or-v1-your-key
|
|
exa_api_key = your-exa-key
|
|
```
|
|
|
|
Environment variables:
|
|
```bash
|
|
export OPENROUTER_API_KEY=sk-or-v1-your-key
|
|
export EXA_API_KEY=your-exa-key
|
|
```
|
|
|
|
Get API keys:
|
|
- OpenRouter: https://openrouter.ai/keys
|
|
- Exa: https://dashboard.exa.ai/api-keys
|
|
|
|
### Autostart
|
|
|
|
```ini
|
|
[autostart]
|
|
enabled = true
|
|
xdg_autostart = true # Scan /etc/xdg/autostart and ~/.config/autostart
|
|
path = ~/.config/dwn/autostart.d
|
|
```
|
|
|
|
### WebSocket API
|
|
|
|
```ini
|
|
[api]
|
|
enabled = true
|
|
port = 8777
|
|
```
|
|
|
|
### Demo Mode
|
|
|
|
```ini
|
|
[demo]
|
|
step_delay = 4000 # 1000-30000ms between steps
|
|
ai_timeout = 15000 # 5000-60000ms for AI responses
|
|
window_timeout = 5000 # 1000-30000ms for window spawns
|
|
```
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
### Application Launchers
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Ctrl+Alt+T` | Terminal |
|
|
| `Super` / `Alt+F2` | Application launcher |
|
|
| `Super+E` | File manager |
|
|
| `Super+B` | Web browser |
|
|
| `Print` | Screenshot |
|
|
|
|
### Window Management
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Alt+F4` | Close window |
|
|
| `Alt+Tab` | Next window |
|
|
| `Alt+Shift+Tab` | Previous window |
|
|
| `Alt+F9` | Toggle minimize |
|
|
| `Alt+F10` | Toggle maximize |
|
|
| `Alt+F11` | Toggle fullscreen |
|
|
| `Super+F9` | Toggle floating |
|
|
|
|
### Workspace Navigation
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `F1` - `F9` | Switch to workspace 1-9 |
|
|
| `Shift+F1` - `Shift+F9` | Move window to workspace 1-9 |
|
|
| `Ctrl+Alt+Right` | Next workspace |
|
|
| `Ctrl+Alt+Left` | Previous workspace |
|
|
|
|
### Layout Control
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Super+Space` | Cycle layout (tiling/floating/monocle) |
|
|
| `Super+H` | Shrink master area |
|
|
| `Super+L` | Expand master area |
|
|
| `Super+I` | Increase master count |
|
|
| `Super+D` | Decrease master count |
|
|
|
|
### Window Snapping
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Super+Left` | Snap left (50% or 100% width) |
|
|
| `Super+Right` | Snap right (50% or 100% width) |
|
|
| `Super+Up` | Snap top (50% or 100% height) |
|
|
| `Super+Down` | Snap bottom (50% or 100% height) |
|
|
|
|
Snapping is composable: Super+Left then Super+Up snaps to top-left quarter.
|
|
|
|
### AI Features
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Super+A` | Show AI context analysis |
|
|
| `Super+Shift+A` | AI command palette |
|
|
| `Super+Shift+E` | Exa semantic search |
|
|
|
|
### News & Help
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Super+Return` | Open current news article |
|
|
| `Super+S` | Show shortcuts help |
|
|
| `Super+T` | Interactive tutorial |
|
|
| `Super+Shift+D` | Toggle demo mode |
|
|
| `Super+Backspace` | Quit DWN |
|
|
|
|
## WebSocket API
|
|
|
|
Connect to `ws://localhost:8777/ws` for programmatic control.
|
|
|
|
### Commands
|
|
|
|
#### get_status
|
|
Returns window manager state.
|
|
```json
|
|
{"command": "get_status"}
|
|
```
|
|
|
|
#### get_workspaces
|
|
Returns array of workspace objects.
|
|
```json
|
|
{"command": "get_workspaces"}
|
|
```
|
|
|
|
#### get_clients
|
|
Returns array of all managed windows.
|
|
```json
|
|
{"command": "get_clients"}
|
|
```
|
|
|
|
Response includes window ID, title, class, workspace, geometry, focus state.
|
|
|
|
#### switch_workspace
|
|
Change active workspace.
|
|
```json
|
|
{"command": "switch_workspace", "workspace": 2}
|
|
```
|
|
|
|
#### run_command
|
|
Execute shell command.
|
|
```json
|
|
{"command": "run_command", "exec": "firefox"}
|
|
```
|
|
|
|
#### focus_client
|
|
Focus specific window by ID.
|
|
```json
|
|
{"command": "focus_client", "window": 12345678}
|
|
```
|
|
|
|
### Python Example
|
|
|
|
```python
|
|
import websocket
|
|
import json
|
|
|
|
ws = websocket.create_connection("ws://localhost:8777/ws")
|
|
|
|
ws.send(json.dumps({"command": "switch_workspace", "workspace": 3}))
|
|
|
|
ws.send(json.dumps({"command": "get_clients"}))
|
|
print(json.loads(ws.recv()))
|
|
|
|
ws.close()
|
|
```
|
|
|
|
## Module Architecture
|
|
|
|
### Core Modules (src/)
|
|
|
|
| Module | Responsibility |
|
|
|--------|----------------|
|
|
| main.c | X11 initialization, event loop, signal handling |
|
|
| client.c | Window management, focus, frame creation |
|
|
| workspace.c | Virtual desktop management |
|
|
| layout.c | Tiling, floating, monocle algorithms |
|
|
| decorations.c | Title bars and borders |
|
|
| panel.c | Top and bottom panel rendering |
|
|
| systray.c | XEmbed system tray, battery/volume/WiFi widgets |
|
|
| notifications.c | D-Bus notification daemon |
|
|
| atoms.c | EWMH/ICCCM atom management |
|
|
| keys.c | Keyboard shortcut handling |
|
|
| config.c | INI configuration parser |
|
|
| ai.c | OpenRouter API, Exa search integration |
|
|
| news.c | News ticker with scrolling animation |
|
|
| autostart.c | XDG autostart implementation |
|
|
| services.c | Background service management |
|
|
| demo.c | Automated feature demonstration |
|
|
| api.c | WebSocket server and JSON handler |
|
|
| util.c | Logging, memory, string utilities |
|
|
|
|
### Design Patterns
|
|
|
|
- **Encapsulation**: Opaque pointer types hide internal structures
|
|
- **Error Handling**: Status codes with output parameters
|
|
- **Resource Management**: Goto cleanup pattern for multi-resource functions
|
|
- **Modularity**: Single responsibility per source file
|
|
- **Naming**: Module prefix convention (e.g., `client_focus()`, `workspace_switch()`)
|
|
|
|
## Development
|
|
|
|
### Standards
|
|
|
|
- ANSI C (C89/C90) for maximum compatibility
|
|
- Snake_case for functions and variables
|
|
- CamelCase for types and structs
|
|
- No external dependencies beyond X11 and standard libraries
|
|
- Defensive programming: validate inputs, check malloc, null-terminate strings
|
|
|
|
### Code Style
|
|
|
|
```bash
|
|
make format # Apply clang-format
|
|
make check # Run cppcheck
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
dwn/
|
|
├── src/ # Implementation
|
|
├── include/ # Headers
|
|
├── config/ # Configuration templates
|
|
├── scripts/ # Utilities and API examples
|
|
├── site/ # Documentation website
|
|
└── build/ # Build artifacts
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|