Projects / dwn

git clone https://molodetz.nl/retoor/dwn.git

Files

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:

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 |

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. 

{"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.

Files

  • Makefile 7.6 KB raw
  • README.md 9.9 KB raw
  • bin
  • build
  • config
  • include
  • scripts
  • site
  • src