Skip to content

USER_GUIDE.md

Latest commit

 

History

History
1539 lines (1136 loc) · 32.4 KB

USER_GUIDE.md

File metadata and controls

1539 lines (1136 loc) · 32.4 KB

FloatWM User Guide

Complete user manual for FloatWM - An innovative floating window manager for X11 with XReal glasses integration.

Table of Contents

  1. Installation
  2. Quick Start
  3. Configuration Guide
  4. Keybinding Reference
  5. Spatial Mode Setup
  6. XReal Glasses Pairing Guide
  7. Advanced Features
  8. Troubleshooting
  9. FAQ

Installation

System Requirements

  • Operating System: Linux with X11 server
  • Rust Toolchain: Stable or nightly Rust (1.70+)
  • Memory: Minimum 512MB RAM
  • Display: X11-compatible display server

Prerequisites

1. Install X11 Development Libraries

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install libx11-dev libxext-dev libxrandr-dev libxinerama-dev

Fedora/RHEL:

sudo dnf install libX11-devel libXext-devel libXrandr-devel libXinerama-devel

Arch Linux:

sudo pacman -S libx11 libxext libxrandr libxinerama

2. Install Rust Toolchain

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

3. Optional: Bluetooth/USB Libraries (for XReal glasses)

Debian/Ubuntu:

sudo apt-get install libusb-1.0-0-dev bluez libbluetooth-dev

Fedora/RHEL:

sudo dnf install libusb1-devel bluez-libs-devel

Building FloatWM

Option 1: Basic Build (Window Management Only)

git clone https://github.com/floatwm/floatwm.git
cd floatwm
cargo build --release --no-default-features

Option 2: Standard Build (Window Management + Configuration)

cargo build --release

This includes:

  • Window management features
  • Configuration file support
  • Keybindings system
  • Window rules

Option 3: Full Build (All Features Including XReal Support)

cargo build --release --features full

This includes everything in standard build plus:

  • XReal glasses sensor integration
  • Device discovery (Bluetooth + USB)
  • Spatial window positioning
  • Head tracking

Installation

After building, install the binaries:

sudo cp target/release/floatwm /usr/local/bin/
sudo cp target/release/floatwmctl /usr/local/bin/

Verify Installation

floatwm --version
floatwmctl --version

Quick Start

Basic Setup

  1. Create Configuration Directory:
mkdir -p ~/.config/floatwm
  1. Copy Example Configuration:
cp docs/floatwm.toml.example ~/.config/floatwm/floatwm.toml
  1. Edit Configuration (Optional):
nano ~/.config/floatwm/floatwm.toml

  1. Start FloatWM:

    Option A: From existing X session (testing)

    floatwm &

    Option B: From display manager (production)

    Create /usr/share/xsessions/floatwm.desktop:

    [Desktop Entry]
Name=FloatWM
Comment=Float Window Manager
Exec=/usr/local/bin/floatwm
Type=Application

    Then select FloatWM from your display manager's login screen.

    Option C: From .xinitrc (manual startx)

    echo "exec /usr/local/bin/floatwm" >> ~/.xinitrc
startx

Your First Actions

Once FloatWM is running:

  1. Open Terminal: Press Super+Return
  2. Close Window: Press Super+Shift+q
  3. Move Windows: Use Super+Shift+h/j/k/l (left/down/up/right)
  4. Enable Spatial Mode (if using XReal glasses): Press Super+s

Basic Usage

  • Focus Windows: Click on windows or move mouse over them (sloppy focus)
  • Move Windows: Drag with mouse or use keybindings
  • Resize Windows: Use window decorations or right-click menu
  • Switch Workspaces: Use Super+1/2/3/... for workspace 1, 2, 3, etc.

Configuration Guide

Configuration File Location

FloatWM looks for configuration in this order:

  1. ~/.config/floatwm/floatwm.toml (default)
  2. $XDG_CONFIG_HOME/floatwm/floatwm.toml (if XDG_CONFIG_HOME is set)

Configuration Structure

Focus Behavior

Control how window focus works:

# Options: "click", "followmouse", "sloppy"
# - click: Click on a window to focus it
# - followmouse: Window under mouse pointer gets focus
# - sloppy: Focus follows mouse, but click to raise window (default)
focus_behavior = "sloppy"

Recommendations:

  • New users: sloppy - most intuitive
  • Traditional tiling WM users: followmouse
  • Click-focused users: click

Spatial Settings

Configure head tracking and spatial window movement:

[spatial_settings]
# Enable spatial window movement based on head tracking
enabled = false

# Sensitivity multiplier for head movement (0.0 - 10.0)
# Higher values make windows move more with head movement
sensitivity = 1.0

# Maximum movement range in pixels (1 - 2000)
# Windows won't move beyond this distance from original position
max_range = 200

# Smoothing factor (0.0 - 1.0)
# Lower values = smoother but slower response
# Higher values = faster but more jittery response
smoothing = 0.5

Tuning Tips:

  • First time setup: Start with enabled = false, sensitivity = 1.0
  • Too sensitive: Reduce sensitivity to 0.5-0.7
  • Not responsive: Increase sensitivity to 1.5-2.0
  • Too jittery: Reduce smoothing to 0.3-0.4
  • Too slow: Increase smoothing to 0.7-0.8
  • Limited movement: Increase max_range to 300-500

Keybindings

Define keyboard shortcuts:

[keybindings]
# Spawn terminal emulator
spawn_terminal = ["Super+Return"]

# Close the focused window
close_window = ["Super+Shift+q"]

# Move windows
move_left = ["Super+Shift+h"]
move_right = ["Super+Shift+l"]
move_up = ["Super+Shift+k"]
move_down = ["Super+Shift+j"]

# Toggle spatial mode on/off
toggle_spatial = ["Super+s"]

Keybinding Format:

  • Use "Modifier+Key" format
  • Multiple modifiers: "Super+Shift+q"
  • Valid modifiers: Super, Control, Shift, Alt, Mod1, Mod4
  • Valid keys: Letters (a-z), numbers (0-9), function keys (F1-F12), special keys (Return, Space, Tab, Escape)

Window Rules

Automatically manage specific applications:

[[window_rules]]
class = "Termite"
size = [800, 600]
float = true

[[window_rules]]
class = "Firefox"
position = [50, 50]
size = [1920, 1080]
float = true

[[window_rules]]
class = "Gimp"
float = true

[[window_rules]]
class = "TelegramDesktop"
workspace = 2

[[window_rules]]
class = "Spotify"
workspace = 3
sticky = false

Window Rule Properties:

  • class: Window class/application name (WM_CLASS) - Required
  • title: Window title pattern with wildcards (optional)
  • position: Initial position [x, y] in pixels (optional)
  • size: Initial size [width, height] in pixels (optional)
  • workspace: Workspace number (1-indexed) (optional)
  • float: Force floating mode true/false (optional)
  • sticky: Show on all workspaces true/false (optional)

Example Configurations

Minimal Configuration

# Just the essentials
focus_behavior = "sloppy"

[keybindings]
spawn_terminal = ["Super+Return"]
close_window = ["Super+Shift+q"]

Developer Configuration

focus_behavior = "sloppy"

[spatial_settings]
enabled = true
sensitivity = 1.2
max_range = 150
smoothing = 0.6

[keybindings]
spawn_terminal = ["Super+Return"]
close_window = ["Super+Shift+q"]
move_left = ["Super+Shift+h"]
move_right = ["Super+Shift+l"]
move_up = ["Super+Shift+k"]
move_down = ["Super+Shift+j"]
toggle_spatial = ["Super+s"]

# Terminal windows always float
[[window_rules]]
class = "Termite"
float = true

# Browser on main workspace
[[window_rules]]
class = "Firefox"
workspace = 1
float = true

# Code editor on workspace 2
[[window_rules]]
class = "code"
workspace = 2

# Communication on workspace 3
[[window_rules]]
class = "TelegramDesktop"
workspace = 3

[[window_rules]]
class = "Discord"
workspace = 3

Content Creator Configuration

focus_behavior = "followmouse"

[spatial_settings]
enabled = true
sensitivity = 0.8
max_range = 100
smoothing = 0.4

[keybindings]
spawn_terminal = ["Super+Return"]
close_window = ["Super+Shift+q"]
toggle_spatial = ["Super+s"]

# Creative tools float by default
[[window_rules]]
class = "Gimp"
float = true

[[window_rules]]
class = "Inkscape"
float = true

[[window_rules]]
class = "Blender"
float = true

[[window_rules]]
class = "kdenlive"
float = true

Reloading Configuration

After editing your configuration:

# Send SIGHUP to reload config
killall -HUP floatwm

# Or use floatwmctl
floatwmctl reload-config

Keybinding Reference

Default Keybindings

Keybinding Action Description
Super+Return spawn_terminal Launch terminal emulator
Super+Shift+q close_window Close focused window
Super+Shift+h move_left Move window left
Super+Shift+l move_right Move window right
Super+Shift+k move_up Move window up
Super+Shift+j move_down Move window down
Super+s toggle_spatial Toggle spatial mode

Common Modifier Keys

Modifier Description Alternative Names
Super Windows/Command key Mod4, Windows, Command
Control Ctrl key Ctrl
Shift Shift key -
Alt Alt key Mod1

Customizing Keybindings

To change keybindings, edit your configuration file:

[keybindings]
# Change terminal shortcut to Ctrl+Alt+t
spawn_terminal = ["Control+Alt+t"]

# Add multiple shortcuts for the same action
close_window = ["Super+Shift+q", "Super+F4"]

# Use vim-style keys
move_left = ["Super+Shift+h"]
move_right = ["Super+Shift+l"]
move_up = ["Super+Shift+k"]
move_down = ["Super+Shift+j"]

Keybinding Tips

  1. Avoid Conflicts: Check that your keybindings don't conflict with application shortcuts
  2. Memorable Patterns: Use consistent patterns (e.g., vim-style hjkl for movement)
  3. Accessibility: Consider using one-handed keybindings for frequently used actions
  4. Testing: Test keybindings in a safe environment before relying on them

Finding Window Classes

To find the window class for rules:

# Use xprop
xprop | grep WM_CLASS

# Click on the window you want to identify
# Output will be like: WM_CLASS(STRING) = "firefox", "Firefox"
# Use the second value: class = "Firefox"

Spatial Mode Setup

What is Spatial Mode?

Spatial mode uses XReal glasses sensor data to control window positioning through head movements. When you look left, windows shift left. When you look right, windows shift right. This creates an immersive, natural computing experience.

Enabling Spatial Mode

  1. Ensure XReal glasses are paired (see XReal Glasses Pairing Guide)

  2. Enable in Configuration:

[spatial_settings]
enabled = true
  1. Restart FloatWM or reload config:
killall -HUP floatwm
  1. Toggle Spatial Mode: Press Super+s to enable/disable spatial mode while running.

Calibration

Before using spatial mode, you should calibrate:

  1. Sit in your normal working position
  2. Look straight at your monitor
  3. Run calibration command:
floatwmctl calibrate

This sets your current head orientation as the "neutral" position.

Tuning Spatial Settings

Sensitivity

Controls how much windows move with head movement:

sensitivity = 1.0  # Default
sensitivity = 0.5  # Half movement (subtle)
sensitivity = 1.5  # 1.5x movement (responsive)
sensitivity = 2.0  # 2x movement (very responsive)

When to adjust:

  • Windows move too much: Decrease to 0.5-0.7
  • Windows barely move: Increase to 1.5-2.0
  • Normal use: Keep at 1.0

Maximum Range

Limits how far windows can move from original position:

max_range = 200   # Default: 200 pixels
max_range = 100   # More constrained
max_range = 500   # More freedom

When to adjust:

  • Small monitor: Use 100-150
  • Large monitor: Use 250-400
  • Multi-monitor: Use 300-500

Smoothing

Controls response speed vs jitter:

smoothing = 0.5  # Default: balanced
smoothing = 0.3  # Smoother, slower response
smoothing = 0.7  # Faster, more responsive

When to adjust:

  • Too jittery: Decrease to 0.3-0.4
  • Too slow/laggy: Increase to 0.7-0.8

Spatial Mode Best Practices

  1. Start Subtle: Begin with low sensitivity (0.7-0.8) and increase gradually
  2. Recalibrate Often: Recalibrate if you change position or monitor setup
  3. Use Toggle: Keep spatial mode off (Super+s) for precise tasks, on for immersive work
  4. Monitor Your Comfort: Take breaks if you experience neck strain
  5. Adjust Lighting: Good lighting improves head tracking accuracy

Disabling Spatial Mode Per-Window

Some windows shouldn't move spatially (e.g., video players):

[[window_rules]]
class = "vlc"
# This window won't move spatially

Set spatial_ignore = true in window rules (if supported in your version).

XReal Glasses Pairing Guide

Supported XReal Models

  • ✅ XReal Air 2
  • ✅ XReal Air 2 Ultra
  • ✅ XReal Air 2 Pro
  • ✅ Future XReal models with standard USB/Bluetooth protocols

Connection Methods

FloatWM supports two connection methods:

  1. USB Connection (Recommended)

    • More reliable
    • Lower latency
    • Simpler setup
    • Wired connection

  2. Bluetooth Connection

    • Wireless freedom
    • Slightly higher latency
    • More complex pairing
    • Battery drain on glasses

USB Connection Setup

1. Connect via USB Cable

Use the provided USB-C cable to connect XReal glasses to your computer.

2. Check Device Recognition

# Check if device is detected
lsusb | grep 3318

# Expected output:
# Bus 001 Device 005: ID 3318:0416

3. Set Up Permissions (Linux)

Create udev rule for automatic permission:

# Create udev rules file
sudo nano /etc/udev/rules.d/99-xreal.rules

Add this line:

SUBSYSTEM=="usb", ATTR{idVendor}=="3318", MODE="0666"

Reload rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

Reconnect your glasses.

4. Test Connection

# Run device discovery test
cargo test --features device-discovery discover_usb

# Or use floatwmctl
floatwmctl discover-usb

Bluetooth Connection Setup

1. Enable Bluetooth

# Start Bluetooth service
sudo systemctl start bluetooth
sudo systemctl enable bluetooth

# Ensure Bluetooth is running
systemctl status bluetooth

2. Put Glasses in Pairing Mode

  1. Turn on XReal glasses
  2. Hold the button until LED flashes blue/green
  3. Glasses are now in pairing mode

3. Pair with BlueZ

# Start bluetoothctl
sudo bluetoothctl

# In bluetoothctl:
scan on
# Wait for "XReal Air 2" to appear
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
exit

4. Verify Connection

# Check connected devices
bluetoothctl devices Connected

# Test with FloatWM
cargo test --features device-discovery discover_bluetooth

FloatWM Device Discovery

FloatWM can automatically discover and connect to XReal glasses:

# Discover all devices (USB + Bluetooth)
floatwmctl discover-all

# Connect to discovered device
floatwmctl connect <device-id>

# Check connection status
floatwmctl status

# Disconnect
floatwmctl disconnect

Troubleshooting Pairing

Device Not Found (USB)

  1. Check cable: Use original USB-C cable or certified USB 3.0+ cable
  2. Try different port: Some USB ports have limited power
  3. Check device: 
    lsusb
# Look for ID 3318:xxxx
  4. Check permissions: 
    # Check if device is accessible
ls -l /dev/bus/usb/001/005
# Should be readable by your user

Device Not Found (Bluetooth)

  1. Enable pairing mode: Hold button until LED flashes
  2. Reset Bluetooth: 
    sudo systemctl restart bluetooth
  3. Remove old pairings: 
    bluetoothctl
remove XX:XX:XX:XX:XX:XX
  4. Check interference: Move away from other 2.4GHz devices

Connection Drops Frequently

  1. USB: Check cable connection, try different cable
  2. Bluetooth: Check battery level on glasses
  3. Both: Check system logs: 
    dmesg | grep -i xreal
journalctl -f | grep -i bluetooth

Permission Denied (USB)

  1. Check udev rules: 
    cat /etc/udev/rules.d/99-xreal.rules
  2. Reload rules: 
    sudo udevadm control --reload-rules
sudo udevadm trigger
  3. Manual permission: 
    # Find device bus/device
lsusb | grep 3318
# Output: Bus 001 Device 005
sudo chmod 666 /dev/bus/usb/001/005

Advanced Configuration

Automatic Connection

Configure FloatWM to auto-connect on startup:

[xreal]
auto_connect = true
prefer_connection = "usb"  # or "bluetooth"
device_id = "XReal Air 2"  # optional: specific device

Connection Priority

If both USB and Bluetooth are available, FloatWM prefers USB by default (lower latency).

Battery Management

For Bluetooth connections:

# Check battery level
floatwmctl battery

# Enable power saving
floatwmctl power-save on

# Disable power saving
floatwmctl power-save off

Firmware Updates

XReal glasses firmware updates are done through the XReal app, not FloatWM. After updating, you may need to re-pair your device.

Advanced Features

Workspace Management

FloatWM supports multiple workspaces for organizing windows:

# Assign windows to workspaces
[[window_rules]]
class = "Firefox"
workspace = 1

[[window_rules]]
class = "code"
workspace = 2

[[window_rules]]
class = "TelegramDesktop"
workspace = 3

Workspace Keybindings (customize in config):

[keybindings]
# Switch to workspace N
workspace_1 = ["Super+1"]
workspace_2 = ["Super+2"]
workspace_3 = ["Super+3"]
# etc.

# Move window to workspace N
move_to_workspace_1 = ["Super+Shift+1"]
move_to_workspace_2 = ["Super+Shift+2"]
move_to_workspace_3 = ["Super+Shift+3"]
# etc.

Scratchpad

FloatWM includes a scratchpad for temporary windows:

# Send window to scratchpad
floatwmctl scratchpad

# Toggle scratchpad visibility
floatwmctl toggle-scratchpad

Docking System

FloatWM supports a docking system for organizing windows:

# Dock window to edge
floatwmctl dock left
floatwmctl dock right
floatwmctl dock top
floatwmctl dock bottom

# Undock window
floatwmctl undock

Tabbed Windows

Group windows together in tabs:

# Tab window with next window
floatwmctl tab-with-next

# Tab window with previous window
floatwmctl tab-with-prev

# Untab window
floatwmctl untab

Spawn Commands

FloatWM can automatically launch applications:

[spawn_commands]
# Launch applications on startup
[[spawn_commands]]
command = "firefox"
keybindings = ["Super+b"]

[[spawn_commands]]
command = "code"
keybindings = ["Super+c"]

[[spawn_commands]]
command = "telegram-desktop"
keybindings = ["Super+t"]

IPC Control

Control FloatWM programmatically:

# List all windows
floatwmctl list-windows

# Focus window by ID
floatwmctl focus <window-id>

# Move window
floatwmctl move <window-id> 100 200

# Resize window
floatwmctl resize <window-id> 800 600

# Get focused window
floatwmctl get-focused

Multi-Monitor Support

FloatWM automatically detects and manages multiple monitors:

# List monitors
floatwmctl list-monitors

# Move window to monitor
floatwmctl move-to-monitor <window-id> <monitor-id>

# Set primary monitor
floatwmctl set-primary <monitor-id>

Configure per-monitor spatial behavior:

[spatial_settings]
enabled = true
# Each monitor has independent spatial tracking
per_monitor_spatial = true

Troubleshooting

Common Issues

FloatWM Won't Start

Symptoms: Nothing happens when running floatwm

Solutions:

  1. Check if another WM is running:

    ps aux | grep -i "gnome-shell|kwin|i3|awesome"
# Kill existing WM or logout first

  2. Check X11 display:

    echo $DISPLAY
# Should be :0 or similar
# If empty, run: export DISPLAY=:0

  3. Check logs:

    # Enable debug logging
FLOATWM_LOG_LEVEL=debug floatwm

# Or check journal
journalctl -xe | grep floatwm

  4. Verify installation:

    which floatwm
floatwm --version

Windows Don't Appear

Symptoms: Windows open but aren't visible

Solutions:

  1. Check if windows are off-screen:

    # Move all windows to center
floatwmctl reset-positions

  2. Check workspace:

    # List windows on all workspaces
floatwmctl list-windows --all-workspaces

# Switch to workspace 1
floatwmctl workspace 1

  3. Check window rules:

    # Validate config
floatwmctl --validate-config

Keybindings Don't Work

Symptoms: Pressing keys does nothing

Solutions:

  1. Check configuration:

    # Validate config syntax
floatwmctl --validate-config

# Check loaded keybindings
floatwmctl list-keybindings

  2. Check for conflicts:

    # Run with verbose logging
FLOATWM_LOG_LEVEL=debug floatwm 2>&1 | grep keybind

  3. Check keyboard grab:

    # Use xev to check if keys are being grabbed
xev
# If keys show as "keycode 0", another app is grabbing them

  4. Reload config:

    killall -HUP floatwm

Spatial Mode Not Working

Symptoms: Windows don't move with head tracking

Solutions:

  1. Check if spatial is enabled:

    floatwmctl status
# Look for "spatial_enabled: true"

  2. Check device connection:

    floatwmctl status
# Look for "xreal_connected: true"

# Or discover devices
floatwmctl discover-all

  3. Recalibrate:

    floatwmctl calibrate

  4. Check sensor data:

    # Enable debug logging
FLOATWM_LOG_LEVEL=debug floatwm 2>&1 | grep sensor

  5. Verify glasses are paired: See XReal Glasses Pairing Guide

High CPU Usage

Symptoms: FloatWM uses excessive CPU

Solutions:

  1. Check what's consuming CPU:

    top -p $(pgrep floatwm)

  2. Reduce spatial update rate:

    [spatial_settings]
update_rate_ms = 16  # Default: ~60fps
# Lower for slower updates but less CPU
update_rate_ms = 33  # ~30fps

  3. Disable unused features:

    [spatial_settings]
enabled = false  # If not using XReal glasses

  4. Check for event storms:

    # Enable debug logging
FLOATWM_LOG_LEVEL=debug floatwm 2>&1 | head -100
# Look for repeated events

Configuration Not Loading

Symptoms: Changes to config file don't take effect

Solutions:

  1. Verify config location:

    # Check default location
ls ~/.config/floatwm/floatwm.toml

# Check if using custom path
echo $XDG_CONFIG_HOME

  2. Validate config syntax:

    # Use FloatWM's validator
floatwmctl --validate-config

# Or use TOML linter
taplo check ~/.config/floatwm/floatwm.toml

  3. Check for syntax errors:

    # Common errors:
# - Missing quotes around strings
# - Invalid boolean (use true/false, not yes/no)
# - Mismatched brackets [ ]
# - Missing commas in arrays

  4. Reload config:

    killall -HUP floatwm
# Or
floatwmctl reload-config

Performance Issues

Symptoms: Laggy window movement, slow response

Solutions:

  1. Adjust spatial smoothing:

    [spatial_settings]
smoothing = 0.3  # Lower for smoother but slower

  2. Reduce render frequency:

    [performance]
target_fps = 30  # Default: 60

  3. Disable compositing:

    [rendering]
enable_compositing = false

  4. Profile performance:

    # Enable profiling
floatwm --profile > profile.log
# Analyze with performance tools

Debug Mode

Enable comprehensive debugging:

# Full debug logging
FLOATWM_LOG_LEVEL=debug \
FLOATWM_LOG_FORMAT=terminal \
floatwm

# Debug to file
FLOATWM_LOG_LEVEL=debug \
FLOATWM_LOG_TARGET=file \
FLOATWM_LOG_FILE=/tmp/floatwm-debug.log \
floatwm

# JSON logging for parsing
FLOATWM_LOG_LEVEL=debug \
FLOATWM_LOG_FORMAT=json \
FLOATWM_LOG_FILE=/tmp/floatwm.json \
floatwm

Getting Help

If issues persist:

  1. Check existing issues: https://github.com/floatwm/floatwm/issues
  2. Create debug log: Run with debug logging enabled
  3. System information: 
    uname -a
floatwm --version
xrandr --verbose
lsusb
bluetoothctl --version
  4. Include in bug report:
    • FloatWM version
    • Linux distribution and version
    • XReal glasses model
    • Configuration file (sanitized)
    • Debug logs
    • Steps to reproduce

FAQ

General Questions

Q: Is FloatWM stable for daily use?

A: FloatWM is in active development. The core window management features are stable, but XReal glasses integration and spatial mode are experimental. Always backup your configuration before upgrading.

Q: Can I use FloatWM without XReal glasses?

A: Yes! FloatWM is a fully functional window manager even without XReal glasses. Simply disable spatial mode in the configuration or build without the sensor-support feature.

Q: How does FloatWM compare to i3, bspwm, etc.?

A: FloatWM is a floating window manager (like Openbox) with optional spatial features. It's not a tiling WM by default, though you can configure window rules for tiling-like behavior.

Q: Can I run FloatWM in a nested X server (Xephyr)?

A: Yes! This is great for testing:

Xephyr -br -ac -noreset -screen 1920x1080 :1 &
DISPLAY=:1 floatwm &
DISPLAY=:1 your-terminal &

XReal Glasses Questions

Q: Do XReal glasses work with FloatWM on macOS/Windows?

A: Currently, FloatWM only supports Linux due to X11 dependency. The XReal integration code is portable, but the window manager core requires X11.

Q: Can I use other AR/VR glasses with FloatWM?

A: FloatWM is designed for XReal glasses, but the sensor protocol is standardized. Other glasses using similar protocols may work with minor modifications.

Q: Does spatial mode work with multiple monitors?

A: Yes! Each monitor can have independent or shared spatial tracking depending on configuration. See the multi-monitor section for details.

Q: Will spatial mode drain my laptop battery faster?

A: Spatial mode adds minimal CPU overhead (~5-10% increase). The main battery drain comes from the XReal glasses themselves when using Bluetooth connection.

Configuration Questions

Q: How do I set FloatWM as my default window manager?

A: See the "Installation" section for display manager and .xinitrc setup instructions.

Q: Can I use multiple configuration files?

A: FloatWM uses one configuration file, but you can use includes (if supported) or switch between configs by:

floatwm --config /path/to/custom.toml

Q: Where are window properties like class and title stored?

A: Window properties are provided by the X11 server and applications themselves. Use xprop to inspect them:

xprop | grep WM_CLASS
xprop | grep WM_NAME

Troubleshooting Questions

Q: FloatWM crashed! How do I recover?

A: FloatWM will restart automatically if configured. If not, you can:

  1. Switch to a TTY (Ctrl+Alt+F2)
  2. Kill the crashed instance: killall floatwm
  3. Restart: floatwm &
  4. Switch back to X (Ctrl+Alt+F7)

Q: I'm stuck in a broken configuration. Help!

A: Emergency recovery:

# Start with default config
floatwm --no-config

# Or specify a known-good config
floatwm --config ~/.config/floatwm/floatwm.toml.backup

Q: Why do some windows not respond to keybindings?

A: Some applications grab global keys (e.g., media players). Check:

# Find what's grabbing keys
xev -event keyboard
# Look for KeyPress events

You may need to disable conflicting shortcuts in those applications.

Performance Questions

Q: Why is FloatWM using so much memory?

A: Normal memory usage is 20-50MB. Higher usage may indicate:

  • Memory leak (file a bug!)
  • Large number of windows
  • Cached spatial data
  • Debug logging enabled

Q: Can I reduce FloatWM's CPU usage?

A: Yes! See the "Performance Issues" section in Troubleshooting. Key tips:

  • Reduce spatial update rate
  • Disable unused features
  • Adjust smoothing parameters

Development Questions

Q: Can I contribute to FloatWM?

A: Absolutely! See CONTRIBUTING.md in the repository. Areas needing help:

  • Documentation improvements
  • Bug fixes
  • New features
  • Testing on more hardware

Q: How do I build FloatWM from source?

A: See the "Installation" section for detailed build instructions. The short version:

git clone https://github.com/floatwm/floatwm.git
cd floatwm
cargo build --release --features full

Appendix

Keyboard Reference

Complete list of valid key names for keybindings:

Letters: a through z

Numbers: 0 through 9

Function Keys: F1 through F12

Special Keys:

  • Return (Enter)
  • Space
  • Tab
  • Escape or Esc
  • BackSpace or BS
  • Delete or Del
  • Insert or Ins
  • Home
  • End
  • PageUp or Prior
  • PageDown or Next

Arrow Keys:

  • Left or LeftArrow
  • Right or RightArrow
  • Up or UpArrow
  • Down or DownArrow

Punctuation:

  • minus (-)
  • equal (=)
  • bracketleft ([)
  • bracketright (])
  • backslash ()
  • semicolon (;)
  • apostrophe (')
  • comma (,)
  • period (.)
  • slash (/)

Modifier Reference

Modifier X11 Name Description
Super Mod4 Windows/Command key
Alt Mod1 Alt key
Control Control Ctrl key
Shift Shift Shift key
CapsLock Lock Caps Lock
NumLock Mod2 Num Lock

Configuration File Template

Complete template with all options:

# FloatWM Configuration Template
# Copy to ~/.config/floatwm/floatwm.toml and customize

# Focus behavior: "click", "followmouse", "sloppy"
focus_behavior = "sloppy"

# Spatial settings for XReal glasses
[spatial_settings]
enabled = false
sensitivity = 1.0
max_range = 200
smoothing = 0.5

# Keybindings
[keybindings]
spawn_terminal = ["Super+Return"]
close_window = ["Super+Shift+q"]
move_left = ["Super+Shift+h"]
move_right = ["Super+Shift+l"]
move_up = ["Super+Shift+k"]
move_down = ["Super+Shift+j"]
toggle_spatial = ["Super+s"]

# Window rules
[[window_rules]]
class = "Termite"
size = [800, 600]
float = true

# Add more rules as needed

Useful Commands

# Window management
floatwmctl close                    # Close focused window
floatwmctl move 100 200            # Move window to x,y
floatwmctl resize 800 600          # Resize window to w,h
floatwmctl focus <window-id>       # Focus specific window

# Workspace management
floatwmctl workspace 1             # Switch to workspace 1
floatwmctl move-to-workspace 2     # Move window to workspace 2

# Spatial mode
floatwmctl calibrate               # Calibrate spatial tracking
floatwmctl toggle-spatial          # Toggle spatial mode

# Configuration
floatwmctl reload-config           # Reload configuration
floatwmctl validate-config         # Validate configuration syntax

# Information
floatwmctl status                  # Show status
floatwmctl list-windows            # List all windows
floatwmctl list-monitors           # List all monitors

# Device management
floatwmctl discover-all            # Discover XReal glasses
floatwmctl connect <device-id>     # Connect to device
floatwmctl disconnect              # Disconnect device

Resources

License

FloatWM is dual-licensed under MIT OR Apache-2.0. See LICENSE file for details.

Version History

Version 0.1.0 (Current)

  • Core window management
  • Configuration system
  • Keybinding system
  • Window rules
  • XReal glasses integration (experimental)
  • Spatial mode (experimental)
  • Multi-monitor support
  • Workspace management
  • IPC control via floatwmctl

Coming Soon

  • Enhanced spatial tracking algorithms
  • Motion prediction
  • More projection types
  • Per-window spatial configuration
  • GUI configuration tool
  • Performance profiling tools

Last Updated: 2025-01-13

FloatWM Version: 0.1.0

For the latest updates and documentation, visit the FloatWM GitHub repository.