From a6b9fa3469d91048c4aac0a0e0c6c4efb8438d64 Mon Sep 17 00:00:00 2001 From: retoor Date: Sun, 28 Dec 2025 04:34:24 +0100 Subject: [PATCH] docs: add comprehensive readme with installation, features, and usage guide --- README.md | 392 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 392 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..be118dd --- /dev/null +++ b/README.md @@ -0,0 +1,392 @@ +# DWN - Desktop Window Manager + +Author: retoor + +A lightweight, AI-enhanced window manager for Linux with tiling, floating, and fullscreen layouts. + +## Quick Start (Copy & Paste These Commands) + +```bash +# 1. Install dependencies (enter your password when asked) +make deps + +# 2. Build DWN +make + +# 3. Test it (opens in a safe window - won't affect your desktop) +make run +``` + +That's it! Press `Super+Backspace` to exit the test window. + +--- + +## What is DWN? + +DWN is a **window manager** - the program that controls how windows look and behave on your screen. It replaces your current desktop environment (like GNOME, KDE, or XFCE) with a faster, keyboard-driven alternative. + +**Features:** +- 3 window layouts: Tiling (windows don't overlap), Floating (like normal), Monocle (fullscreen) +- 9 virtual workspaces to organize your windows +- Built-in panels with clock, taskbar, and system tray +- WiFi network selector with dropdown menu (like XFCE) +- Audio volume indicator with scroll-to-adjust +- Desktop notifications +- Optional AI assistant (can launch apps by command!) +- Very fast and lightweight + +--- + +## Installation + +### Step 1: Install Dependencies + +Run this command (works on Ubuntu, Debian, Fedora, and Arch): + +```bash +make deps +``` + +This installs everything DWN needs. You'll need to enter your password. + +**If `make deps` doesn't work**, install manually: +- Ubuntu/Debian: `sudo apt install build-essential pkg-config libx11-dev libxext-dev libxinerama-dev libxrandr-dev libdbus-1-dev libcurl4-openssl-dev xserver-xephyr dmenu network-manager alsa-utils` +- Fedora: `sudo dnf install gcc make pkg-config libX11-devel libXext-devel libXinerama-devel libXrandr-devel dbus-devel libcurl-devel xorg-x11-server-Xephyr dmenu NetworkManager alsa-utils` +- Arch: `sudo pacman -S base-devel pkg-config libx11 libxext libxinerama libxrandr dbus curl xorg-server-xephyr dmenu networkmanager alsa-utils` + +### Step 2: Build + +```bash +make +``` + +You should see "Build successful!" at the end. + +### Step 3: Test (Recommended!) + +Before installing, test DWN in a safe window: + +```bash +make run +``` + +This opens DWN inside a window on your current desktop. You can try it out without changing anything. Press `Super+Backspace` to close it. + +### Step 4: Install + +```bash +sudo make install +``` + +### Step 5: Use DWN + +1. Log out of your current session +2. At the login screen, click the **gear icon** (or session selector) near your username +3. Select **"DWN"** from the list +4. Log in! + +--- + +## Basic Controls + +### Essential Shortcuts (Memorize These!) + +| Keys | What it does | +|------|--------------| +| `Ctrl + Alt + T` | Open a terminal | +| `Super` or `Alt + F2` | Open app launcher | +| `Super + E` | Open file manager | +| `Super + B` | Open web browser | +| `Alt + Tab` | Switch between windows | +| `Alt + F4` | Close current window | +| `Super + Backspace` | **Exit DWN** (important!) | +| `Super + S` | **Show all shortcuts** | +| `Super + T` | **Start interactive tutorial** | + +### Workspaces + +| Keys | What it does | +|------|--------------| +| `Ctrl + Alt + Right` | Next workspace | +| `Ctrl + Alt + Left` | Previous workspace | +| `F1` to `F9` | Switch to workspace 1-9 | +| `Shift + F1` to `Shift + F9` | Move window to workspace 1-9 | + +### Window Management + +| Keys | What it does | +|------|--------------| +| `Super + F9` | Toggle floating mode | +| `Alt + F10` | Toggle maximize | +| `Alt + F11` | Toggle fullscreen | +| `Alt + Tab` | Cycle windows forward | +| `Alt + Shift + Tab` | Cycle windows backward | + +### Layout Control (Super key shortcuts) + +| Keys | What it does | +|------|--------------| +| `Super + Space` | Change layout mode (tiling → floating → monocle) | +| `Super + H` | Shrink main area | +| `Super + L` | Expand main area | +| `Super + I` | Add window to main area | +| `Super + D` | Remove window from main area | + +### AI Features (Optional) + +| Keys | What it does | +|------|--------------| +| `Super + A` | Show AI context info | +| `Super + Shift + A` | Ask AI to do something (e.g., "open firefox") | +| `Super + Shift + E` | Exa semantic web search | + +### News Ticker + +The bottom panel displays a scrolling news ticker. Navigate articles with these shortcuts: + +| Keys | What it does | +|------|--------------| +| `Super + Down` | Next news article | +| `Super + Up` | Previous news article | +| `Super + Return` | Open current article in browser | + +### Other Shortcuts + +| Keys | What it does | +|------|--------------| +| `Print` | Take screenshot (xfce4-screenshooter) | + +--- + +## System Tray + +The top panel includes a system tray on the right side with battery, audio, and WiFi indicators. + +### Battery Indicator + +Shows battery percentage on laptops with color coding: +- **Green**: > 50% +- **Yellow**: 20-50% +- **Red**: < 20% +- **Blue**: Charging + +### WiFi Indicator + +Located in the top-right corner of the panel, showing your current connection status. + +| Action | What it does | +|--------|--------------| +| **Click** on WiFi icon | Open dropdown with available networks | +| **Click** on a network | Connect to that network | +| **Click** on connected network | Disconnect | + +The dropdown shows: +- Available WiFi networks with signal strength +- `●` marker next to the currently connected network +- Networks are sorted and updated automatically + +**Note:** Requires NetworkManager (`nmcli`) to be installed. + +### Audio Indicator + +Shows current volume level next to the WiFi indicator. + +| Action | What it does | +|--------|--------------| +| **Left-click** | Toggle mute/unmute | +| **Scroll up** | Increase volume by 5% | +| **Scroll down** | Decrease volume by 5% | + +**Note:** Requires ALSA utilities (`amixer`) to be installed. + +--- + +## Configuration + +DWN can be customized by editing a config file. + +### Create Your Config + +```bash +mkdir -p ~/.config/dwn +cp /etc/dwn/config.example ~/.config/dwn/config +``` + +### Edit Your Config + +Open `~/.config/dwn/config` in any text editor. Here are common changes: + +**Change terminal:** +```ini +[general] +terminal = gnome-terminal +``` +Options: `xfce4-terminal`, `gnome-terminal`, `konsole`, `alacritty`, `xterm` + +**Change app launcher:** +```ini +[general] +launcher = rofi -show run +``` + +**Change layout:** +```ini +[layout] +default = floating +``` +Options: `tiling`, `floating`, `monocle` + +**Change window gaps:** +```ini +[appearance] +gap = 10 +border_width = 2 +``` + +--- + +## AI Features (Optional) + +DWN has an AI assistant that can run commands for you. For example, you can press `Super+Shift+A`, type "open chrome", and it will launch Chrome. + +### AI Command Setup (OpenRouter) + +1. Go to [openrouter.ai](https://openrouter.ai) and create a free account +2. Get your API key +3. Add it to your shell config: + +```bash +echo 'export OPENROUTER_API_KEY="your-key-here"' >> ~/.bashrc +source ~/.bashrc +``` + +4. Make sure dmenu is installed: `sudo apt install dmenu` + +### Exa Semantic Search Setup + +1. Go to [dashboard.exa.ai](https://dashboard.exa.ai/api-keys) and create an account +2. Get your API key +3. Add it to your shell config: + +```bash +echo 'export EXA_API_KEY="your-key-here"' >> ~/.bashrc +source ~/.bashrc +``` + +### Usage + +- Press `Super + A` to see AI context info about your current task +- Press `Super + Shift + A` to ask the AI to do something: + - "open firefox" - launches Firefox + - "run terminal" - opens a terminal + - "what time is it" - answers your question +- Press `Super + Shift + E` to search the web semantically: + - Type a question like "how to configure nginx" + - Select a result to open in browser + +--- + +## Troubleshooting + +### "make: command not found" + +Install build tools: +```bash +sudo apt install build-essential +``` + +### "X11 libraries not found" or build errors + +Install dependencies: +```bash +make deps +``` + +### Can't find DWN at login screen + +Make sure you ran `sudo make install`, then: +```bash +ls /usr/share/xsessions/dwn.desktop +``` + +If missing: +```bash +sudo cp scripts/dwn.desktop /usr/share/xsessions/ +``` + +### Terminal shortcut doesn't work + +Install the default terminal: +```bash +sudo apt install xfce4-terminal +``` + +Or change terminal in config (see Configuration section). + +### Screen is blank after login + +DWN started but there's nothing to show. Press `Ctrl+Alt+T` to open a terminal. + +### How do I get back to my normal desktop? + +1. Press `Super+Backspace` to exit DWN +2. At login screen, select your previous desktop (GNOME, KDE, etc.) + +### AI says "dmenu not found" + +```bash +sudo apt install dmenu +``` + +### WiFi indicator not working + +Make sure NetworkManager is installed and running: +```bash +sudo apt install network-manager +sudo systemctl enable --now NetworkManager +``` + +### Audio indicator not working + +Make sure ALSA utilities are installed: +```bash +sudo apt install alsa-utils +``` + +--- + +## Uninstall + +```bash +sudo make uninstall +``` + +Then select a different desktop at the login screen. + +--- + +## All Make Commands + +| Command | What it does | +|---------|--------------| +| `make help` | Show all commands | +| `make deps` | Install dependencies | +| `make` | Build DWN | +| `make debug` | Build with debug symbols | +| `make run` | Test in a window | +| `make install` | Install system-wide | +| `make uninstall` | Remove from system | +| `make clean` | Delete build files | +| `make format` | Format source code | +| `make check` | Run static analysis | + +--- + +## License + +MIT License - do whatever you want with it. + +## Credits + +- Inspired by [dwm](https://dwm.suckless.org/) and [XFCE](https://xfce.org/) +- AI powered by [OpenRouter](https://openrouter.ai/)