NWM - A Scrollable Tiling Window Manager

• X11 (libX11): Core X Window System library
• Xft (libXft): X FreeType library for font rendering
• FreeType2 (libfreetype): Font rendering engine
• Fontconfig (libfontconfig): Font configuration and customization library
• Xrender (libXrender): X Rendering Extension library

• C++ compiler with C++14 support (GCC 5+ or Clang 3.4+)
• GNU Make

First, clone the NWM repository from GitHub:

git clone https://github.com/xsoder/nwm.git
cd nwm

NWM uses a simple Makefile for building. The Makefile includes:

• Compiler flags for optimization (-O3) and warnings (-Wall -Wextra)
• Proper linking of required libraries
• Installation targets for the binary and desktop entry

You can examine the Makefile to understand exactly what's being compiled and how.

To compile NWM:

make

This will:

1. Compile each source file (src/nwm.cpp, src/bar.cpp, src/tiling.cpp, src/systray.cpp) into object files
2. Link all object files together with the required libraries
3. Produce the nwm binary in the current directory

To install NWM system-wide (requires root privileges):

sudo make install

This will:

1. Install the nwm binary to /usr/local/bin/nwm
2. Install the desktop entry to /usr/share/xsessions/nwm.desktop

The desktop entry allows display managers (like LightDM, GDM, SDDM) to show NWM as a session option at login.

If you want to install to a different location:

make PREFIX=/custom/path install

For example, to install to your home directory:

make PREFIX=$HOME/.local install

To remove compiled object files and the binary:

make clean

To remove NWM from your system:

sudo make uninstall

To enter a development environment with all dependencies:

nix develop

This provides a shell with all build tools, libraries, and useful utilities pre-installed.

If you use a display manager (LightDM, GDM, SDDM, etc.), NWM will appear in the session list after installation. Simply:

1. Log out or restart
2. At the login screen, look for a session selector (usually a gear icon or dropdown menu)
3. Select "NWM" from the list
4. Enter your password and log in

This is the recommended method as it properly sets up the X session and environment variables.

If you prefer to use startx:

1. Create or edit ~/.xinitrc:

   exec nwm
   

   Note: The exec command is important - it replaces the shell process with NWM. When NWM exits, the X session ends properly.

2. Start X:

   startx
   

A more complete ~/.xinitrc that sets up a full environment:

#!/bin/sh

# Load X resources
[ -f ~/.Xresources ] && xrdb -merge ~/.Xresources

# Set keyboard repeat rate (delay, rate)
xset r rate 200 30

# Disable screen blanking
xset s off -dpms

# Set wallpaper (requires feh)
feh --bg-fill ~/Pictures/wallpaper.jpg &

# Start compositor for transparency/shadows (requires picom)
picom --config ~/.config/picom/picom.conf &

# System tray applications
nm-applet &          # NetworkManager
volumeicon &         # Volume control
blueman-applet &     # Bluetooth manager

# Auto-lock screen after 10 minutes (requires xautolock and slock)
xautolock -time 10 -locker slock &

# Start window manager (exec replaces the shell process with NWM)
# When NWM exits, the X session ends
exec nwm

For testing or debugging:

xinit /usr/local/bin/nwm -- :1

This starts NWM on display :1.

For development or testing without affecting your main session, use Xephyr (a nested X server):

# Start Xephyr on display :1
Xephyr -screen 1280x720 -ac :1 &

# Run NWM in that display
DISPLAY=:1 nwm

NWM includes a test script (test.sh) that automates this process.

Press Super + Return to open a terminal. By default, NWM tries to launch st (Simple Terminal). If you don't have st installed, you'll need to either:

1. Install st:

   # Arch
   sudo pacman -S st
   
   # Build from source
   git clone https://git.suckless.org/st
   cd st
   make && sudo make install
   

2. Or change the terminal in src/config.hpp (see Configuration section)

Press Super + d to open dmenu, an application launcher. Start typing the name of an application and press Enter to launch it.

If dmenu isn't installed:

# Arch
sudo pacman -S dmenu

# Build from source
git clone https://git.suckless.org/dmenu
cd dmenu
make && sudo make install

Open several windows (e.g., press Super + Return three times). Notice how NWM automatically tiles them:

• The first window occupies the left half (master area)
• Additional windows stack on the right half

Press Super + j and Super + k to cycle through windows. The focused window has a colored border (default: pink #FF5577).

Press Super + q to close the currently focused window. Most applications will ask you to save any unsaved work.

Press Super + t to toggle between tile mode and scroll mode. In scroll mode, windows are arranged side-by-side. Use Super + Left/Right arrow or Super + Mouse Wheel to scroll through them.

The screen is divided into two areas:

1. Master Area: The left side, typically occupied by your main window (e.g., your code editor)
2. Stack Area: The right side, where additional windows are stacked vertically

With one window:

┌──────────────────────┐
│                      │
│                      │
│      Window 1        │
│    (Fullscreen)      │
│                      │
│                      │
└──────────────────────┘

With two windows:

┌─────────────┬────────┐
│             │        │
│             │        │
│  Window 1   │  Win 2 │
│  (Master)   │        │
│             │        │
│             │        │
└─────────────┴────────┘

With three or more windows:

┌─────────────┬────────┐
│             │  Win 2 │
│             ├────────┤
│  Window 1   │  Win 3 │
│  (Master)   ├────────┤
│             │  Win 4 │
│             ├────────┤
│             │  Win 5 │
└─────────────┴────────┘

The master area occupies 50% of the screen width by default. You can adjust this:

• Super + h: Decrease master width
• Super + l: Increase master width

The adjustment is made in increments defined by RESIZE_STEP (default: 40 pixels).

The "master" window is simply the first window in the window list. To make any window the master:

1. Focus the window you want to make master
2. Press Super + Shift + h repeatedly until it's in the first position

This layout is ideal for:

• Coding with a large editor and smaller auxiliary windows (terminal, browser, etc.)
• Writing with a document on the left and references on the right
• Any workflow with one primary application and several supporting ones

Windows are arranged side-by-side in a horizontal row. Each window occupies 50% of the screen width. You scroll horizontally to see windows that don't fit on the screen.

With windows 1, 2, 3 visible (viewport can show 2 windows):

┌──────────┬──────────┬──────────┐
│          │          │          │
│ Window 1 │ Window 2 │ Window 3 │
│          │          │          │
└──────────┴──────────┴──────────┘
└─ Visible ─┘          └─ Scroll right to see

After scrolling right:

┌──────────┬──────────┬──────────┐
│          │          │          │
│ Window 1 │ Window 2 │ Window 3 │
│          │          │          │
└──────────┴──────────┴──────────┘
           └─ Visible ─┘

You can scroll through windows using:

• Super + Left arrow: Scroll left
• Super + Right arrow: Scroll right
• Super + Mouse Wheel: Scroll with mouse

The scroll amount is defined by SCROLL_STEP (default: 500 pixels, but divided by 3 in practice).

When you focus a window that's off-screen, NWM automatically scrolls to make it visible. This happens when:

• Using Super + j or Super + k to change focus
• Clicking on a window in the bar
• Opening a new window

This layout is ideal for:

• Comparing multiple files side-by-side
• Working with many terminals simultaneously
• Any task where you want to see exactly two things at once
• Presentations where you switch between different views

Gaps are the spaces between windows and between windows and screen edges. NWM includes gaps by default (defined by GAP_SIZE, default: 6 pixels).

To toggle gaps on/off: Super + a

With gaps disabled, windows will be directly adjacent to each other and screen edges.

Each window has a border that indicates focus:

• Unfocused border: Dark gray (#181818 by default, defined by BORDER_COLOR)
• Focused border: Pink (#FF5577 by default, defined by FOCUS_COLOR)

Border width is defined by BORDER_WIDTH (default: 3 pixels).

Floating and fullscreen windows have reduced or no borders.

#define BORDER_WIDTH        3         // Width in pixels
#define BORDER_COLOR        0x181818  // Unfocused border (dark gray)
#define FOCUS_COLOR         0xFF5577  // Focused border (pink)

Colors are in hexadecimal RGB format: 0xRRGGBB

• 0xFF0000 = Pure red
• 0x00FF00 = Pure green
• 0x0000FF = Pure blue
• 0xFFFFFF = White
• 0x000000 = Black

#define GAP_SIZE            6         // Gap in pixels between windows

Set to 0 for no gaps by default.

#define FONT                "DejaVu Sans Mono:size=10"

Font format follows Xft font specification:

• "Family Name:size=SIZE"
• "Family Name:size=SIZE:style=Bold"
• "Family Name:size=SIZE:antialias=true"

To list available fonts:

fc-list
# Or for monospace fonts only:
fc-list :mono

Common choices:

• "monospace:size=10" (uses system default monospace font)
• "Liberation Mono:size=10"
• "Inconsolata:size=11"
• "Fira Code:size=10"
• "JetBrains Mono:size=10"

static const std::vector<std::string> WIDGET = {
    "1","2","3","4","5","6","7","8","9"
};

You can customize these to any strings:

static const std::vector<std::string> WIDGET = {
    "web", "code", "term", "chat", "mail", "media", "7", "8", "9"
};

Or use Unicode symbols:

static const std::vector<std::string> WIDGET = {
    "一", "二", "三", "四", "五", "六", "七", "八", "九"  // Chinese numerals
};

#define MODKEY Mod4Mask  // Super/Windows key (default)

Available modifiers:

• Mod1Mask = Alt key
• Mod4Mask = Super/Windows key
• ShiftMask = Shift key
• ControlMask = Ctrl key
• LockMask = Caps Lock

Combine modifiers with |:

MODKEY | ShiftMask           // Super + Shift
MODKEY | ControlMask         // Super + Ctrl
MODKEY | ShiftMask | Mod1Mask  // Super + Shift + Alt

To change the main modifier to Alt:

#define MODKEY Mod1Mask

Key symbols are X11 keysyms defined in <X11/keysym.h>. Common ones:

Functions you can bind to keys:

Located in src/bar.cpp:

#define BAR_HEIGHT 30
#define BAR_BG_COLOR        0x181818  // Background
#define BAR_FG_COLOR        0xCCCCCC  // Normal text
#define BAR_ACTIVE_COLOR    0xFF5577  // Active workspace
#define BAR_INACTIVE_COLOR  0x666666  // Inactive workspace
#define BAR_ACCENT_COLOR    0x88AAFF  // Accent (layout mode)
#define BAR_WARNING_COLOR   0xFFAA00  // Warning (high CPU/RAM)
#define BAR_CRITICAL_COLOR  0xFF5555  // Critical (very high usage)
#define BAR_HOVER_COLOR     0x333333  // Hover background

The bar updates system information every 2 seconds. To change this, modify src/bar.cpp:

void nwm::bar_update_system_info(Base &base) {
    auto now = std::chrono::steady_clock::now();
    auto elapsed = std::chrono::duration_cast<std::chrono::seconds>(
        now - base.bar.sys_info.last_update).count();

    if (elapsed < 2) return;  // Change this value
    // ...
}

• Default state for most windows
• Managed by the active layout (master-stack or horizontal scroll)
• Cannot be moved or resized directly with the mouse
• Position and size determined by the layout algorithm

• Window can be freely moved and resized
• Always drawn on top of tiled windows
• Useful for dialogs, utility windows, or when you need precise positioning
• Toggle with Mod + Shift + Space

• Window covers the entire screen, including the bar
• All other windows are hidden
• Border is removed
• Toggle with Mod + f

• Dialog windows (_NET_WM_WINDOW_TYPE_DIALOG)
• Splash screens (_NET_WM_WINDOW_TYPE_SPLASH)
• Utility windows (_NET_WM_WINDOW_TYPE_UTILITY)
• Windows with _NET_WM_STATE_MODAL state
• Windows with _NET_WM_STATE_ABOVE state
• Transient windows (windows with WM_TRANSIENT_FOR hint)
• Windows with fixed size (min_size == max_size and < 800x600)

• Firefox's "Save As" dialog
• GIMP's tool windows
• Application preferences windows
• File picker dialogs
• Error/warning dialogs

If a window auto-floats and you want it tiled, press Mod + Shift + Space to toggle it.

• Desktop windows (_NET_WM_WINDOW_TYPE_DESKTOP)
• Dock windows (_NET_WM_WINDOW_TYPE_DOCK)
• Notification windows (_NET_WM_WINDOW_TYPE_NOTIFICATION)
• Tooltip windows (_NET_WM_WINDOW_TYPE_TOOLTIP)
• Menu windows (dropdown, popup, combo)
• Windows with override_redirect flag

• Desktop environment panels (if any)
• Notification daemons (Dunst, notify-osd)
• Tooltip popups
• Dropdown menus

These windows appear and disappear as needed and are always on top.

In tile mode:

• Mod + Shift + h: Swap focused window with previous
• Mod + Shift + l: Swap focused window with next

In scroll mode:

• Same keybindings work
• When you swap, the scroll position adjusts to keep the focused window visible

Floating windows:

• Mod + Left Click and drag

• Mod + Shift + [1-9]: Move focused window to workspace [1-9]
• The window disappears from current workspace and appears in target workspace
• Focus remains on current workspace (window moves but you don't follow)

• Mod + h: Decrease master area width (increases stack area)
• Mod + l: Increase master area width (decreases stack area)

This affects the master/stack split ratio. All tiled windows are then resized to fit the new ratio.

Window sizes in scroll mode are fixed at 50% screen width and full height (minus bar and gaps). Manual resizing isn't available in scroll mode.

• Mod + Right Click and drag: Resize from bottom-right corner
• Minimum size enforced: 100x100 pixels

Fullscreen windows cannot be resized while in fullscreen mode. Exit fullscreen first (Mod + f).

NWM sends a WM_DELETE_WINDOW message to the window, which is the polite way to ask an X11 application to close. This allows the application to:

• Save unsaved work
• Show a "Are you sure?" dialog
• Clean up resources
• Close gracefully

Some misbehaving applications may ignore the close request. In that case:

# Find the window's process
xprop _NET_WM_PID | grep -o '[0-9]*'
# Click on the window when cursor changes

# Kill the process
kill <PID>

# Or force kill
kill -9 <PID>

Or use xkill:

xkill
# Click on the window to kill it

• Moving the mouse cursor over a window automatically focuses it
• You don't need to click to focus
• The focused window receives keyboard input
• Only one window can be focused at a time

• Focused window has a colored border (default: pink #FF5577)
• Unfocused windows have a dark gray border (default: #181818)
• Focused workspace in bar is highlighted

• Mod + j: Focus next window (cycles through all windows)
• Mod + k: Focus previous window (cycles in reverse)

When you manually change focus, the mouse cursor doesn't move. To avoid accidentally refocusing when moving the mouse, some users prefer click-to-focus. This would require modifying the source code to remove EnterWindowMask from window event masks.

• Tiled windows don't overlap, so stacking order doesn't matter much
• Floating windows are always drawn above tiled windows
• Fullscreen window is drawn above everything (except ignored windows like notifications)

• Same as tile mode
• Windows are arranged in a horizontal row
• Order in the row matches the order in the window list

• The "master" window is the first window in the workspace's window list
• It's not a special property, just the position in the list
• Any window can become master by being swapped to position 0

• Mod + Shift + h: Move current window earlier in list (toward position 0)
• Mod + Shift + l: Move current window later in list

Think of workspaces as separate desktops, each with its own set of windows. Only one workspace is visible at a time. Switching workspaces is instant.

• Independent window list
• Independent layout mode (each workspace can be in tile or scroll mode)
• Independent scroll offset (for scroll mode)
• Independent master area size (for tile mode)
• Independent focused window

Common ways to organize workspaces:

• Workspace 1: Web browser
• Workspace 2: Code editor and terminals
• Workspace 3: Email client
• Workspace 4: Chat applications (Slack, Discord, etc.)
• Workspace 5: Music player
• Workspace 6-9: Additional tasks

Or by project:

• Workspace 1: Project A (editor, terminals, browser)
• Workspace 2: Project B
• Workspace 3: Project C
• etc.

• Mod + 1: Switch to workspace 1
• Mod + 2: Switch to workspace 2
• …
• Mod + 9: Switch to workspace 9

Switching workspaces:

1. Unmaps (hides) all windows in current workspace
2. Changes current workspace to target
3. Maps (shows) all windows in target workspace
4. Restores focus to the last focused window in target workspace

• Click on a workspace indicator (the numbers in the bar)
• Scroll the mouse wheel over the bar to cycle through workspaces

The status bar shows all workspaces:

• Active workspace: Highlighted background (default: darker gray)
• Workspaces with windows: Normal background
• Empty workspaces: Dimmed

1. Window is removed from current workspace's window list
2. Window is added to target workspace's window list
3. Window is unmapped (hidden)
4. Focus moves to next window in current workspace (if any)
5. Window will be visible when you switch to target workspace

• Moving a window doesn't switch workspaces
• You stay in the current workspace after moving a window
• If you move the only window, the workspace becomes empty
• You can move floating and fullscreen windows (they exit fullscreen first)

• Shows the desktop (wallpaper if set)
• Shows only the status bar
• Pressing Mod + j/k (focus next/prev) does nothing
• Opening a new window automatically places it in the current workspace

• Window positions in the window list
• Layout mode (tile vs scroll)
• Master area size
• Scroll offset

• Workspaces are not saved between sessions
• When you quit NWM, all workspace information is lost
• On next startup, all existing windows go to workspace 0

For persistence across reboots, you'd need session management (not currently implemented in NWM). Most users simply reopen their applications and reorganize.

Alternative: Use a session manager like tmux for terminals, and browser session restore for web browsers.

• Active workspace: Dark background, pink text
• Workspace with windows: Medium background, white text
• Empty workspace: No background, gray text
• Hover: Light background when mouse is over it

• Click: Switch to that workspace
• Scroll wheel: Cycle through workspaces
• Hover: Highlights to show it's clickable

• CPU: CPU usage percentage
• RAM: Memory usage percentage
• DISK: Disk usage percentage for root partition (~/)
• DOWN: Download speed (KB/s or MB/s)
• UP: Upload speed (KB/s or MB/s)
• BAT: Battery percentage (if present)
• CHG: Shows when charging

• System info updates every 2 seconds
• Network speeds are calculated since last update

• Normal: Light gray text
• Warning: Orange text (CPU or RAM > 75%)
• Critical: Red text (CPU or RAM > 90%)

• NetworkManager icon
• Volume control icon
• Bluetooth icon
• Notification icons
• Any application that uses the system tray protocol

Icons are 20×20 pixels by default with 4px padding between them.

• Windows expand to use the full vertical space
• All bar functionality is lost (can't click workspaces, see time, etc.)
• System tray icons are also hidden

• Presentations or screen recordings
• Maximizing screen space for reading/viewing
• Playing fullscreen games (though fullscreen mode already covers the bar)

• Bar at top, windows below
• Traditional placement
• Easier to see when focused on top of screen

• Bar at bottom, windows above
• Default in NWM
• Keeps bar near taskbar location in other DEs
• Easier to access with mouse (less distance to move)

After changing, recompile and restart NWM.

• Network managers: NetworkManager (nm-applet), ConnMan, wicd
• Volume controls: volumeicon, pasystray
• Bluetooth: blueman-applet, blueberry
• Cloud storage: Dropbox, Nextcloud, Google Drive
• Messaging: Slack, Discord, Telegram (minimized)
• Media players: Spotify, VLC (with tray plugin)
• System monitors: CPU/memory monitors, battery monitors

Start applications normally, and they'll add their icon to the tray:

nm-applet &
volumeicon &
blueman-applet &

Add these to your ~/.xinitrc to start automatically:

#!/bin/sh
# ... other startup commands
nm-applet &
volumeicon &
blueman-applet &
exec nwm

• Left click: Usually shows the main window or menu
• Right click: Usually shows a context menu
• Middle click: Application-specific action

Each application defines its own behavior.

• Icons are 20×20 pixels
• Background matches bar background
• Icons are raised above the bar
• 4px padding between icons

• Multiple tray icons
• Icon removal and addition
• Dynamic reordering
• 32-bit ARGB visuals (transparency support)
• Horizontal orientation

• Single system tray per X screen
• No icon size customization per icon (all icons are same size)
• No icon tooltips (applications may implement their own)

1. Check if another tray is running:

   xprop -root _NET_SYSTEM_TRAY_S0
   

   If this shows a window ID, another tray owns the selection.

2. Start the application after NWM: System tray applications need the tray to exist before they start. If you start the app before NWM, it won't see the tray.

3. Restart the application:

   killall nm-applet && nm-applet &
   

Icon size is hardcoded in src/systray.cpp:

#define TRAY_ICON_SIZE 20

Change this value and recompile to adjust icon size.

This is normal if you have many tray icons. The system info shifts left to make room. If it's a problem:

• Close some tray applications
• Hide less important system info (requires code modification)
• Use a longer bar by increasing screen width (not really a solution)

1. Add function declaration in src/nwm.hpp:

   void toggle_opacity(void *arg, Base &base);
   

2. Implement in src/nwm.cpp:

   void nwm::toggle_opacity(void *arg, Base &base) {
       (void)arg;
       if (!base.focused_window) return;
   
       // Toggle between opaque and semi-transparent
       static bool is_transparent = false;
       is_transparent = !is_transparent;
   
       unsigned long opacity = is_transparent ? 0xDDFFFFFF : 0xFFFFFFFF;
       Atom opacity_atom = XInternAtom(base.display, "_NET_WM_WINDOW_OPACITY", False);
   
       XChangeProperty(base.display, base.focused_window->window,
                      opacity_atom, XA_CARDINAL, 32,
                      PropModeReplace, (unsigned char*)&opacity, 1);
   }
   

3. Add keybinding in src/config.hpp:

   { MODKEY,           XK_o,           toggle_opacity,   NULL },
   

4. Recompile and install

Add a function to cycle through multiple layouts (not just two):

void nwm::cycle_layouts(void *arg, Base &base) {
    (void)arg;
    static int current_layout = 0;
    current_layout = (current_layout + 1) % 3;

    switch(current_layout) {
        case 0:
            base.horizontal_mode = false;
            tile_windows(base);
            break;
        case 1:
            base.horizontal_mode = true;
            tile_horizontal(base);
            break;
        case 2:
            // Implement a grid layout or monocle layout here
            break;
    }

    bar_draw(base);
}

Monocle layout shows one window at a time, fullscreen (but with bar visible):

void nwm::tile_monocle(Base &base) {
    auto &current_ws = get_current_workspace(base);

    if (current_ws.windows.empty()) return;

    int screen_width = WIDTH(base.display, base.screen);
    int screen_height = HEIGHT(base.display, base.screen);
    int bar_height = base.bar_visible ? base.bar.height : 0;
    int usable_height = screen_height - bar_height;
    int y_start = (base.bar_position == 0) ? bar_height : 0;

    // Hide all windows except focused
    for (auto &w : current_ws.windows) {
        if (w.window == base.focused_window->window) {
            w.x = 0;
            w.y = y_start;
            w.width = screen_width;
            w.height = usable_height;
            XMoveResizeWindow(base.display, w.window, w.x, w.y, w.width, w.height);
            XMapWindow(base.display, w.window);
        } else {
            XUnmapWindow(base.display, w.window);
        }
    }

    XFlush(base.display);
}

Then add this to a layout cycle or bind it to a key.

Grid layout arranges windows in a grid:

void nwm::tile_grid(Base &base) {
    auto &current_ws = get_current_workspace(base);

    std::vector<ManagedWindow*> tiled_windows;
    for (auto &w : current_ws.windows) {
        if (!w.is_floating && !w.is_fullscreen) {
            tiled_windows.push_back(&w);
        }
    }

    if (tiled_windows.empty()) return;

    int screen_width = WIDTH(base.display, base.screen);
    int screen_height = HEIGHT(base.display, base.screen);
    int bar_height = base.bar_visible ? base.bar.height : 0;
    int usable_height = screen_height - bar_height;
    int y_start = (base.bar_position == 0) ? bar_height : 0;

    // Calculate grid dimensions
    int cols = std::ceil(std::sqrt(tiled_windows.size()));
    int rows = std::ceil((float)tiled_windows.size() / cols);

    int win_width = screen_width / cols - 2 * base.gaps;
    int win_height = usable_height / rows - 2 * base.gaps;

    for (size_t i = 0; i < tiled_windows.size(); ++i) {
        int col = i % cols;
        int row = i / cols;

        tiled_windows[i]->x = col * (win_width + 2 * base.gaps) + base.gaps;
        tiled_windows[i]->y = row * (win_height + 2 * base.gaps) + base.gaps + y_start;
        tiled_windows[i]->width = win_width;
        tiled_windows[i]->height = win_height;

        XMoveResizeWindow(base.display, tiled_windows[i]->window,
                         tiled_windows[i]->x, tiled_windows[i]->y,
                         tiled_windows[i]->width, tiled_windows[i]->height);
    }

    XFlush(base.display);
}

# List monitors
xrandr

# Arrange monitors
xrandr --output HDMI-1 --auto --left-of eDP-1

Add to ~/.xinitrc to make permanent (before exec nwm).

NWM will treat the combined area as one screen. You can use workspaces to separate monitors logically (e.g., workspaces 1-5 on left monitor, 6-9 on right).

Implementing true multi-monitor support would require:

1. Detecting monitors with Xinerama or RandR
2. Creating separate workspaces per monitor
3. Modifying tiling algorithms to work per-monitor
4. Handling focus across monitors

This is a significant undertaking and not currently planned, but contributions are welcome.

Create ~/.config/systemd/user/nwm-startup.service:

[Unit]
Description=NWM Startup Tasks
After=graphical-session.target

[Service]
Type=oneshot
ExecStart=/home/yourusername/.config/nwm/startup.sh

[Install]
WantedBy=graphical-session.target

Enable:

systemctl --user enable nwm-startup.service

1. Create a function to fetch weather:

   std::string get_weather() {
       // Use curl or libcurl to fetch from weather API
       // Parse JSON response
       // Return formatted string like "☀️ 72°F"
       return "☀️ 72°F";
   }
   

2. Add to bar in bar_draw:

   std::string weather = get_weather();
   XftDrawStringUtf8(base.bar.xft_draw, &base.bar.xft_fg, base.xft_font,
                    weather_x, y_offset,
                    (XftChar8*)weather.c_str(), weather.length());
   

3. Call periodically (every 10 minutes) in the main event loop

Create a socket in init that listens for commands:

// Pseudo-code
void nwm::init_ipc(Base &base) {
    int sock = socket(AF_UNIX, SOCK_STREAM, 0);
    // Bind to /tmp/nwm-socket
    // Listen for connections
    // Handle commands in event loop
}

Then you could create a client program:

#!/bin/bash
# nwm-msg - Send message to NWM
echo "$1" | nc -U /tmp/nwm-socket

Usage:

nwm-msg "workspace 2"
nwm-msg "toggle-layout"

Simpler approach: set X properties on root window:

void nwm::check_commands(Base &base) {
    Atom command_atom = XInternAtom(base.display, "NWM_COMMAND", False);
    // Read property
    // Execute command
    // Delete property
}

Call periodically or on PropertyNotify events.

Client:

xprop -root -f NWM_COMMAND 8s -set NWM_COMMAND "workspace 2"

Possible causes and solutions:

1. Missing dependencies

   # Verify X11 libraries
   ldd /usr/local/bin/nwm
   # Should show no "not found"
   

2. Font not found
   • Check ~/.xsession-errors or /var/log/Xorg.0.log

   • Change FONT in src/config.hpp to a font you have:

     fc-list | grep -i mono
     

3. Another WM is running
   • Only one window manager can control the X server at a time
   • Kill other WM: killall openbox or killall i3

4. X server not running

   echo $DISPLAY
   # Should show :0 or :1
   

Run NWM from a terminal to see error messages:

# In an existing X session
nwm

# Or in Xephyr for testing
Xephyr -screen 1280x720 :1 &
DISPLAY=:1 nwm

Check logs:

cat ~/.xsession-errors
tail -f /var/log/Xorg.0.log

1. Bar hidden
   • Press Mod + r to toggle bar visibility
2. Font rendering issue

   • Install required font:

     sudo pacman -S ttf-dejavu
     # or
     sudo apt install fonts-dejavu
     

   • Or change FONT in config

3. Xft library missing

   ldd /usr/local/bin/nwm | grep Xft
   

4. Bar colors same as background
   • Check BAR_FGCOLOR and BAR_BGCOLOR are different

1. Wrong modifier key
   • Verify Super key works: xev and press Super key
   • Check output for Mod4
   • If not, change to Alt: #define MODKEY Mod1Mask
2. Key conflict
   • Another program may be grabbing the key
   • Check with: xev (press key and see if events appear)
3. NumLock/CapsLock interference
   • NWM tries to handle this, but some keyboards are tricky
   • Try disabling NumLock
4. Keybinding not compiled in
   • Check src/config.hpp for the keybinding
   • Recompile: make clean && make && sudo make install

Use xev:

xev
# Press keys and observe output
# Look for KeyPress events with keysym names

1. Window is meant to float
   • Dialogs, splash screens, etc. auto-float
   • Toggle: Mod + Shift + Space
2. Only one window
   • A single window fills the screen
   • Open more windows to see tiling
3. In scroll mode with one window visible
   • Scroll to see other windows: Mod + Left/Right
4. Window manager not actually managing the window
   • Window might be override-redirect (like dmenu)
   • Check with: xprop (click on window, look for override redirect: True)

Likely causes:

1. Frequent bar updates
   • The bar redraws and updates system info every 2 seconds
   • Normal CPU usage: 0-2%
   • If higher, check for bugs in system info gathering
2. Many tray icons
   • Each tray icon is a separate X window
   • More icons = more overhead
3. X11 performance
   • Some X drivers are slow
   • Try different compositor settings or disable compositor
4. Infinite loop or bug
   • If CPU is constantly high (>50%), there's a bug
   • Check with: top or htop
   • Report bug with details

• Increase bar update interval (edit src/bar.cpp)
• Close unused tray applications
• Disable picom/compositor

1. Started before NWM

   • Solution: Restart the application

     killall nm-applet && nm-applet &
     

2. Another tray is running
   • Only one system tray can run at a time

   • Check:

     xprop -root | grep SYSTEM_TRAY
     

   • Kill other tray or quit other WM
3. Application doesn't support system tray
   • Not all applications have tray icons
   • Check application documentation

1. Wrong modifier key
   • Must hold Mod (Super) key while dragging/resizing
   • Try Alt if Super doesn't work
2. Window is tiled
   • Tiled windows can't be moved/resized with mouse
   • Toggle floating: Mod + Shift + Space
3. Mouse bindings not grabbed
   • Check src/nwm.cpp for XGrabButton calls
   • Should grab Button1 and Button3 with MODKEY

1. Mouse outside window
   • Focus follows mouse
   • Move mouse over the window you want focused
2. Window is unmapped
   • Check if window is on current workspace
   • Switch workspaces: Mod + 1-9
3. Window is behind floating window
   • Floating windows are always on top
   • Close or move floating window

Java applications may not recognize NWM. Add to ~/.xinitrc before exec nwm:

export _JAVA_AWT_WM_NONREPARENTING=1

Or before starting the application:

_JAVA_AWT_WM_NONREPARENTING=1 idea.sh

Some Electron apps have issues with tiling WMs. Try:

# For VS Code
code --disable-gpu

Fullscreen games should work with Mod + f for fullscreen mode. If not:

# Force window mode
game-binary -windowed

Wine apps may need:

# In wine config
winetricks settings
# Enable "Emulate a virtual desktop"

1. Recompile with debug info

   make clean
   CXXFLAGS = "-std=c++14 -O3 -Wall -Wextra -Wpedantic -Werror -Wstrict-aliasing -g" make
   

2. Run with gdb

   gdb /usr/local/bin/nwm
   (gdb) run
   # Wait for crash
   (gdb) backtrace
   

3. Report bug
   • Copy backtrace
   • Note what you were doing when it crashed
   • Open issue on GitHub with details

Found a bug? Please open an issue on GitHub with:

• Operating system and version
• NWM version (git commit hash)
• Steps to reproduce the bug
• Expected behavior vs actual behavior
• Relevant log output from ~/.xsession-errors
• Screenshots if applicable

Have an idea? Open an issue with the "enhancement" label.

Please note: NWM aims to stay relatively simple and focused. Not all feature requests will be accepted. Features that significantly increase complexity or add many dependencies are less likely to be included.

Preferred features:

• Improvements to existing functionality
• Bug fixes
• Performance optimizations
• Better documentation
• Cleaner code organization

Less likely to be accepted:

• Multi-monitor support (complex, better handled by other WMs)
• External configuration files (goes against suckless philosophy)
• Built-in application launchers (use dmenu/rofi)
• Extensive theming system (just edit the source)

Pull requests are welcome! Please:

1. Fork the repository

   # On GitHub, click "Fork"
   git clone https://github.com/YOUR_USERNAME/nwm.git
   cd nwm
   

2. Create a branch

   git checkout -b feature/my-new-feature
   # or
   git checkout -b fix/bug-description
   

3. Make your changes
   • Follow existing code style
   • Add comments for complex logic
   • Test thoroughly
4. Test your changes
   • Use the included test.sh script
   • Test in Xephyr before testing on main session
   • Ensure existing functionality still works

5. Commit with clear messages

   git commit -m "Add feature: description of feature"
   # or
   git commit -m "Fix bug: description of bug and solution"
   

6. Push and create pull request

   git push origin feature/my-new-feature
   # Then open PR on GitHub
   

Documentation is always in need of improvement:

• Fix typos and grammatical errors
• Clarify confusing sections
• Add examples
• Translate to other languages
• Create tutorials or guides
• Make video walkthroughs

Documentation contributions are just as valuable as code!

Help others discover NWM:

• Star the repository on GitHub
• Share on social media or forums
• Write blog posts about your experience
• Create rice/showcase posts with NWM

• Indentation: 4 spaces (no tabs)

• Braces: Opening brace on same line

  if (condition) {
      // code
  }
  

• Naming:
  • Functions: snake_case
  • Variables: snake_case
  • Classes/Structs: PascalCase
  • Constants: UPPER_CASE
• Comments: Use // for single-line, /* */ for multi-line
• Includes: System headers first, then local headers

• Header files: .hpp
• Implementation: .cpp
• Keep headers minimal (declarations only)
• Implementation in .cpp files

Follow these conventions:

• First line: Brief summary (50 chars or less)
• Blank line
• Detailed explanation if needed

Add horizontal scroll layout

Implements a new layout mode where windows are arranged side-by-side
and can be scrolled through horizontally. This provides an alternative
to the traditional master-stack layout.

• Git
• C++ compiler (GCC 5+ or Clang 3.4+)
• Make
• X11 development libraries
• Text editor (vim, emacs, VS Code, etc.)
• Xephyr (for testing)

Compile with debug symbols:

make clean
CXXFLAGS = "-std=c++14 -O3 -Wall -Wextra -Wpedantic -Werror -Wstrict-aliasing -g" make

Run in gdb:

Xephyr -screen 1280x720 :1 &
DISPLAY=:1 gdb ./nwm
(gdb) run

Or with valgrind for memory leaks:

DISPLAY=:1 valgrind --leak-check=full ./nwm

Understanding the codebase:

NWM is inspired by dwm but differs in:

• Language: C++14 vs C
• Patches: Direct source editing vs patch system
• Layouts: Includes horizontal scroll layout
• Bar: Built-in status bar with system info
• System Tray: Built-in support

Similar to dwm:

• Configuration through source
• Minimal by default
• Master-stack layout
• Keyboard-focused
• Fast and lightweight

i3 is more feature-complete but:

• Configuration: i3 uses config file, NWM uses source
• Layouts: i3 has more layout modes, NWM has scroll mode
• IPC: i3 has comprehensive IPC, NWM doesn't (yet)
• Multi-monitor: i3 supports multiple monitors natively

NWM is simpler and more hackable, i3 is more powerful and configurable without recompiling.

bspwm is also minimal but:

• Configuration: bspwm uses external config (bspc), NWM uses source
• Layout: bspwm uses binary tree, NWM uses master-stack/scroll
• Philosophy: bspwm is more Unix-philosophy (separate concerns)

xmonad is configured in Haskell:

• Language: Haskell vs C++
• Flexibility: xmonad is extremely flexible, NWM is simpler
• Learning curve: xmonad requires Haskell knowledge

awesome is configured in Lua:

• Language: Lua for config vs C++ for NWM
• Features: awesome has more widgets and features
• Complexity: awesome is more complex

NWM is simpler and more focused on core tiling functionality.

• ArchWiki: Window Manager
• ArchWiki: Xorg
• EWMH Specification
• Xlib Manual

• dwm - Dynamic Window Manager
• i3 - Improved Tiling WM
• bspwm - Binary Space Partitioning WM
• xmonad - Haskell-based WM
• Qtile - Python-based WM

### Suckless Tools

• st - Simple Terminal
• dmenu - Dynamic Menu
• slock - Simple Screen Locker

• Xlib Programming Manual
• X Window System User HOWTO
• Xlib Tutorial

• NWM GitHub Repository
• NWM Issues
• NWM Discussions
• r/unixporn - For showcasing your setup

• Master-stack tiling layout
• Horizontal scroll layout
• 9 workspaces
• Built-in status bar with system information
• System tray support
• Fullscreen and floating window support
• Mouse support for moving/resizing
• Configurable through source code
• Basic EWMH compliance

Edit src/config.hpp:

static const char *termcmd[] = { "alacritty", NULL };

Then recompile.

Edit src/config.hpp:

#define MODKEY Mod1Mask  // For Alt key

Edit src/nwm.hpp:

#define NUM_WORKSPACES 12

Then add labels and keybindings in src/config.hpp.

No, NWM is an X11 window manager and requires Xorg.

Multi-monitor support is complex and not currently a priority. You can use xrandr to combine monitors into one large screen.

Use feh or nitrogen:

feh --bg-fill ~/Pictures/wallpaper.jpg

Add to ~/.xinitrc for persistence.

This is the suckless philosophy: configuration is code. It ensures:

• Type safety
• No runtime parsing overhead
• Full power of C++
• Explicit configuration
• Forces you to understand what you're changing

NWM is relatively simple compared to many window managers, but it does require:

• Comfort with command line
• Basic understanding of X11
• Willingness to edit C++ code
• Ability to compile from source

If you've never used a tiling window manager, you might want to start with i3 (no compilation needed) then try NWM.

Check:

• The default src/config.hpp
• GitHub issues for user-shared configs
• r/unixporn posts using NWM