mirrors/maomaowm
1
0
Fork 0
mirror of https://github.com/DreamMaoMao/maomaowm.git synced 2026-05-02 06:46:29 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Add comprehensive documentation: COMMANDS.md, USAGE.md, and enhanced README.md

Browse source 
Co-authored-by: squassina <8495707+squassina@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot] 2026-02-18 09:01:16 +00:00
parent 7df8631fa3
commit df6b10f331
3 changed files with 2191 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

431
README.md
View file

@ -27,20 +27,348 @@ This project's development is based on [dwl](https://codeberg.org/dwl/dwl/).
https://github.com/user-attachments/assets/bb83004a-0563-4b48-ad89-6461a9b78b1f
# Quick Start Guide
## What is MangoWC?
MangoWC is a **Wayland compositor** - a program that manages windows and displays on modern Linux systems using the Wayland protocol. If you're familiar with window managers like i3, dwm, or awesome, MangoWC provides similar tiling window management functionality but for Wayland instead of X11.
## First Steps After Installation
1. **Copy the default configuration:**
```bash
mkdir -p ~/.config/mango
cp /usr/share/mango/config.conf ~/.config/mango/config.conf
```
2. **Launch MangoWC:**
- From a display manager: Select "Mango" session
- From TTY: Run `mango`
3. **Essential first keybindings to know:**
- `Alt + Return` - Open terminal (foot)
- `Alt + Space` - Open application launcher (rofi)
- `Alt + Q` - Close focused window
- `Super + M` - Exit MangoWC
- `Super + R` - Reload configuration (after making changes)
4. **Create an autostart script** (optional):
```bash
# Create ~/.config/mango/autostart.sh
#!/bin/bash
# Set wallpaper
swaybg -i ~/Pictures/wallpaper.jpg &
# Start status bar
waybar &
# Start notification daemon
swaync &
```
Make it executable: `chmod +x ~/.config/mango/autostart.sh`
## Key Concepts
### Tags vs Workspaces
Unlike traditional workspaces, **tags** are more flexible:
- **Workspaces**: A window belongs to one workspace. Switching workspaces shows a different set of windows.
- **Tags**: A window can have multiple tags. You can view multiple tags at once or filter to specific tags.
Think of tags as labels you can attach to windows. You can view windows with tag 1, or tag 2, or both tags 1 and 2 simultaneously.
**Default behavior:**
- `Ctrl + 1-9` - View tag 1-9
- `Alt + 1-9` - Move current window to tag 1-9
- Each tag can have its own layout (tile, scroller, grid, etc.)
### Window Layouts
MangoWC supports 9 different layouts:
| Layout | Description | Best For |
|--------|-------------|----------|
| **tile** | Master-stack tiling (left master, right stack) | General multitasking |
| **scroller** | Horizontal scrolling columns | Wide content, terminals |
| **monocle** | One window fullscreen at a time | Focus, presentations |
| **grid** | Windows arranged in grid | Many small windows |
| **deck** | Stack of windows, one visible | Cycling through tasks |
| **center_tile** | Master centered, stack on sides | Symmetrical layout |
| **vertical_tile** | Master top, stack bottom | Wide monitors |
| **vertical_scroller** | Vertical scrolling rows | Document review |
| **vertical_grid** | Vertical grid arrangement | Vertical content |
**Switch layouts:**
- `Super + N` - Cycle through layouts for current tag
- Each tag can have its own default layout (set in `config.conf`)
### Scratchpad
The **scratchpad** is a hidden workspace for temporary windows:
- `Alt + Z` - Toggle scratchpad (hide/show)
- Windows in scratchpad are hidden but not closed
- Perfect for calculator, music player, notes, etc.
- Scratchpad windows float centered on screen
**Usage example:**
1. Open a terminal (`Alt + Return`)
2. Move it to scratchpad (`Alt + Z`)
3. It disappears
4. Press `Alt + Z` again - it appears over your current work
5. Press `Alt + Z` again - it hides again
### Overview Mode
**Overview** mode shows all windows at once (like Alt+Tab visualization):
- `Alt + Tab` - Toggle overview mode
- See all windows across all tags
- Click a window to focus it
- Move windows in overview
- Hotarea: Move mouse to top edge of screen to trigger overview
### Window States
Windows can have multiple states:
- **Floating**: Window floats above tiled windows, can be moved/resized freely
- `Alt + \` - Toggle floating
- `Super + Left-drag` - Move floating window
- `Super + Right-drag` - Resize floating window
- **Fullscreen**: Window covers entire screen, hides all others
- `Alt + F` - Toggle fullscreen
- `Alt + Shift + F` - Toggle fake fullscreen (fullscreen but stays in layout)
- **Maximized**: Window fills screen but shows borders/gaps
- `Alt + A` - Toggle maximize
- **Minimized**: Window hidden but not in scratchpad
- `Super + I` - Minimize current window
- `Super + Shift + I` - Restore last minimized window
- **Global**: Window visible on all tags
- `Super + G` - Toggle global state
- **Overlay**: Window stays on top of others
- `Super + O` - Toggle overlay state
## Day-to-Day Usage
### Typical Workflow
1. **Open applications:**
```
Alt + Space → Application launcher
Alt + Return → Terminal
```
2. **Navigate windows:**
```
Alt + Arrow Keys → Focus window in direction
Super + Tab → Focus next window in stack
```
3. **Organize windows:**
```
Super + Shift + Arrows → Swap window positions
Alt + \ → Toggle floating
Alt + 1-9 → Move to specific tag
```
4. **Adjust layout:**
```
Super + N → Change layout
Alt + Shift + X/Z → Increase/decrease gaps
```
5. **Multi-monitor:**
```
Alt + Shift + Left/Right → Focus other monitor
Super + Alt + Left/Right → Move window to other monitor
```
### Common Use Cases
**Web browsing + Terminal:**
- Open browser on tag 1, terminal on tag 2
- Use `Ctrl + 1` and `Ctrl + 2` to switch between them
**Development workflow:**
- Tag 1: Code editor (center_tile layout)
- Tag 2: Browser (monocle layout)
- Tag 3: Terminals (tile or scroller layout)
- Scratchpad: Calculator, notes
**Keeping a window visible everywhere:**
- Open music player or chat app
- Press `Super + G` to make it global
- It now appears on all tags
## IPC Control with mmsg
MangoWC includes `mmsg` - a command-line tool to control the compositor:
### Get Information
```bash
# Get current tag info
mmsg -t
# Get layout information
mmsg -L
# Get output (monitor) information
mmsg -o
# Watch for changes (real-time updates)
mmsg -w -t # Watch tags
```
### Send Commands
```bash
# Switch to tag 3
mmsg -d view 3
# Move window to tag 5
mmsg -d tag 5
# Change layout
mmsg -d setlayout tile
# Reload configuration
mmsg -d reload_config
# Spawn application
mmsg -d spawn firefox
```
### Scripting Examples
**Auto-save workspace state:**
```bash
#!/bin/bash
# Save current tags to file
mmsg -t > ~/mango-state.txt
```
**Tag-specific wallpapers:**
```bash
#!/bin/bash
# In a loop, change wallpaper based on active tag
while true; do
TAG=$(mmsg -t | grep "seltag" | cut -d: -f2)
swaybg -i ~/wallpapers/tag${TAG}.jpg &
sleep 1
done
```
**Quick window layout toggle:**
```bash
#!/bin/bash
# Toggle between tile and monocle layouts
CURRENT=$(mmsg -L | grep "layout_name:" | head -1)
if [[ $CURRENT == *"tile"* ]]; then
mmsg -d setlayout monocle
else
mmsg -d setlayout tile
fi
```
## Troubleshooting
### MangoWC won't start
1. **Check dependencies:**
```bash
# Verify wlroots and scenefx are installed
pkg-config --modversion wlroots scenefx
```
2. **Check logs:**
```bash
# Run from terminal to see error messages
mango
```
3. **XWayland issues:**
```bash
# If X11 apps won't start, rebuild with XWayland
meson configure build -Dxwayland=enabled
ninja -C build install
```
### Config changes not applying
- Run `Super + R` to reload config
- Some settings (trackpad, mouse) require logout/login
- Check config syntax: `mango --validate-config` (if available)
### Keybindings not working
1. **Find correct key name:**
```bash
# Install wev to see key names
wev
# Press keys and see their names
```
2. **Check for conflicts:**
- Look for duplicate bindings in `config.conf`
- Some apps capture keys (browsers, terminals)
### Applications not starting
1. **Missing required tools:**
```bash
# Install suggested applications
sudo pacman -S rofi foot waybar swaybg
```
2. **Check autostart script:**
```bash
# Test autostart manually
bash ~/.config/mango/autostart.sh
```
### Performance issues
1. **Disable effects:**
```conf
# In config.conf
animations=0
blur=0
shadows=0
```
2. **Check GPU drivers:**
```bash
# Ensure proper graphics drivers are installed
glxinfo | grep "OpenGL"
```
### Screen sharing not working
Install portal packages:
```bash
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-wlr
```
## Getting Help
- **Discord**: [MangoWC Community](https://discord.gg/CPjbDxesh5)
- **Wiki**: [Full documentation](https://github.com/DreamMaoMao/mango/wiki/)
- **Website**: [mangowc.vercel.app/docs](https://mangowc.vercel.app/docs)
- **Issues**: [GitHub Issues](https://github.com/DreamMaoMao/mangowc/issues)
# Our discord
[mangowc](https://discord.gg/CPjbDxesh5)
# Supported layouts
- tile
- scroller
- monocle
- grid
- deck
- center_tile
- vertical_tile
- vertical_grid
- vertical_scroller
---
# Installation
@ -162,13 +490,82 @@ sudo ninja -C build install
- Gamma control/night light (wlsunset, gammastep)
- Miscellaneous (xfce-polkit, wlogout)
## Some Common Default Keybindings
## Default Keybindings Reference
- alt+return: open foot terminal
- alt+space: open rofi launcher
- alt+q: kill client
- alt+left/right/up/down: focus direction
- super+m: quit mango
> **Note**: All keybindings can be customized in `~/.config/mango/config.conf`
### Essential Shortcuts
| Keybinding | Action | Description |
|------------|--------|-------------|
| `Alt + Return` | Open terminal | Launches foot terminal emulator |
| `Alt + Space` | Open launcher | Launches rofi application launcher |
| `Alt + Q` | Close window | Kill focused window |
| `Super + M` | Exit | Quit MangoWC |
| `Super + R` | Reload config | Apply config changes without restart |
### Window Management
| Keybinding | Action |
|------------|--------|
| `Alt + ←/→/↑/↓` | Focus window in direction |
| `Super + Tab` | Focus next window |
| `Super + Shift + ←/→/↑/↓` | Swap window with neighbor |
| `Alt + \` | Toggle floating/tiling |
| `Alt + F` | Toggle fullscreen |
| `Alt + Shift + F` | Toggle fake fullscreen |
| `Alt + A` | Toggle maximize |
| `Super + I` | Minimize window |
| `Super + Shift + I` | Restore minimized window |
| `Super + G` | Toggle global (visible all tags) |
| `Super + O` | Toggle overlay (always on top) |
### Tag (Workspace) Management
| Keybinding | Action |
|------------|--------|
| `Ctrl + 1-9` | Switch to tag 1-9 |
| `Alt + 1-9` | Move window to tag 1-9 (and follow) |
| `Super + ←/→` | Previous/next tag |
| `Ctrl + ←/→` | Previous/next tag with windows |
| `Ctrl + Super + ←/→` | Move window to previous/next tag |
### Layout Control
| Keybinding | Action |
|------------|--------|
| `Super + N` | Cycle through layouts |
| `Alt + E` | Set window to full width (scroller) |
| `Alt + X` | Cycle width presets (scroller) |
| `Alt + Shift + X/Z` | Increase/decrease gaps |
| `Alt + Shift + R` | Toggle gaps on/off |
### Special Features
| Keybinding | Action |
|------------|--------|
| `Alt + Tab` | Toggle overview mode |
| `Alt + Z` | Toggle scratchpad |
| `Super + Scroll Up/Down` | Switch tags with scroll wheel |
### Multi-Monitor
| Keybinding | Action |
|------------|--------|
| `Alt + Shift + ←/→` | Focus adjacent monitor |
| `Super + Alt + ←/→` | Move window to adjacent monitor |
### Floating Window Adjustment
| Keybinding | Action |
|------------|--------|
| `Ctrl + Shift + ←/→/↑/↓` | Move floating window by pixels |
| `Ctrl + Alt + ←/→/↑/↓` | Resize floating window by pixels |
| `Super + Left-drag` | Move floating window with mouse |
| `Super + Right-drag` | Resize floating window with mouse |
| `Middle-click` | Maximize window |
> **Tip**: Press `Super + R` after editing your config to reload without restarting!
## My Dotfiles