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

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

make run       # Launch in nested Xephyr window (safe testing)

Build Targets

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

[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

[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

[layout]
default = tiling                # tiling, floating, monocle
master_ratio = 0.55             # 0.1-0.9
master_count = 1                # 1-10

Panels

[panels]
top = true
bottom = true

Colors

[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

[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:

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

[autostart]
enabled = true
xdg_autostart = true            # Scan /etc/xdg/autostart and ~/.config/autostart
path = ~/.config/dwn/autostart.d

WebSocket API

[api]
enabled = true
port = 8777

Demo Mode

[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

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.

{"command": "get_status"}

get_workspaces

Returns array of workspace objects.

{"command": "get_workspaces"}

get_clients

Returns array of all managed windows.

{"command": "get_clients"}

Response includes window ID, title, class, workspace, geometry, focus state.

switch_workspace

Change active workspace.

{"command": "switch_workspace", "workspace": 2}

run_command

Execute shell command.

{"command": "run_command", "exec": "firefox"}

focus_client

Focus specific window by ID.

{"command": "focus_client", "window": 12345678}

Python Example

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

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.

DWN - Desktop Window Manager

Architecture

Core Features

Layout Management

Workspace System

Integrated Components

News Ticker

AI Integration

Interactive Features

Automation

Installation

Dependencies

Build Process

Testing

Build Targets

Configuration

General Settings

Appearance

Layout

Panels

Colors

AI Integration

Autostart

WebSocket API

Demo Mode

Keyboard Shortcuts

Application Launchers

Window Management

Workspace Navigation

Layout Control

Window Snapping

AI Features

News & Help

WebSocket API

Commands

get_status

get_workspaces

get_clients

switch_workspace

run_command

focus_client

Python Example

Module Architecture

Core Modules (src/)

Design Patterns

Development

Standards

Code Style

Project Structure

License