maomaowm/USAGE.md

MangoWC Usage Guide

A practical guide to using MangoWC in your daily workflow.

Table of Contents

• Getting Started
• Understanding Tags
• Working with Layouts
• Window Management Patterns
• Using the Scratchpad
• Overview Mode
• Multi-Monitor Workflows
• Customization Tips
• Common Workflows

---

Getting Started

Your First Session

1. Launch MangoWC from your display manager or run mango from TTY
2. Open a terminal: Press Alt + Return
3. Open an application: Press Alt + Space for the launcher
4. Navigate windows: Use Alt + Arrow Keys
5. Close a window: Press Alt + Q

Essential First-Day Shortcuts

These are the absolute minimum you need to be productive:

Alt + Return         → Terminal
Alt + Space          → App launcher
Alt + Q              → Close window
Alt + Arrow Keys     → Focus different window
Ctrl + 1-9           → Switch tags (workspaces)
Alt + \              → Toggle floating
Super + R            → Reload config
Super + M            → Exit MangoWC

---

Understanding Tags

What Are Tags?

Tags are like workspaces, but more flexible. Think of them as labels you can apply to windows.

Key differences from workspaces:

• A window can have multiple tags
• You can view multiple tags at once
• Each tag can have its own layout

Basic Tag Usage

Switch to a tag:

Ctrl + 1    → View tag 1
Ctrl + 2    → View tag 2
... and so on

Move window to a tag:

Alt + 1     → Move current window to tag 1 (and switch to it)
Alt + 2     → Move current window to tag 2 (and switch to it)

Navigate through tags:

Super + Left/Right         → Previous/next tag
Ctrl + Left/Right          → Previous/next tag that has windows

Advanced Tag Techniques

View multiple tags simultaneously:

1. Switch to tag 1: Ctrl + 1
2. Toggle tag 2 visibility: Super + 2 (if configured)
3. Now you see windows from both tags

Silent tag movement (move window without following):

# In config.conf
bind=Alt+Shift,1,tagsilent,1

Organizing Your Workflow with Tags

Example organization:

Tag 1: Browsers          (monocle layout)
Tag 2: Code editors      (tile or center_tile layout)
Tag 3: Terminals         (scroller layout)
Tag 4: Communication     (grid layout)
Tag 5: Media             (monocle layout)
Tag 6-9: Project-specific

Setting layouts per tag in config.conf:

tagrule=id:1,layout_name:monocle
tagrule=id:2,layout_name:center_tile
tagrule=id:3,layout_name:scroller
tagrule=id:4,layout_name:grid
tagrule=id:5,layout_name:monocle

---

Working with Layouts

Available Layouts

MangoWC includes 9 built-in layouts:

1. Tile (Master-Stack)

┌────────┬────┐
│        │ 1  │
│ Master ├────┤
│        │ 2  │
└────────┴────┘

Best for: General multitasking, coding with docs Switch to: Cycle with Super + N (or add bind=Super,t,setlayout,tile to config)

2. Scroller (Horizontal)

┌───┬────┬───┬───┐
│ 1 │  2 │ 3 │ 4 │...
└───┴────┴───┴───┘

Best for: Terminals, wide content, many windows Switch to: Cycle with Super + N (or add bind=Super,s,setlayout,scroller to config)

Scroller-specific controls:

• Alt + E - Set current window to full width
• Alt + X - Cycle through width presets (0.5, 0.8, 1.0)

3. Monocle (Fullscreen Stack)

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

Best for: Focus work, browsing, media Switch to: Cycle with Super + N Navigate: Use Super + Tab to cycle through windows

4. Grid

┌─────┬─────┐
│  1  │  2  │
├─────┼─────┤
│  3  │  4  │
└─────┴─────┘

Best for: Viewing many windows simultaneously Switch to: Cycle with Super + N

5. Deck (Card Stack)

┌──────────────┐
│  Window 1    │  ← Visible
│ (2, 3 hidden)│
└──────────────┘

Best for: Cycling through options Switch to: Cycle with Super + N

6. Center Tile

┌──┬──────┬──┐
│1 │      │2 │
│  │Master│  │
│3 │      │4 │
└──┴──────┴──┘

Best for: Symmetrical workflow, coding Switch to: Cycle with Super + N

7. Vertical Tile

┌──────────────┐
│    Master    │
├──┬───┬───┬───┤
│1 │ 2 │ 3 │ 4 │
└──┴───┴───┴───┘

Best for: Ultra-wide monitors Switch to: Cycle with Super + N

Layout Controls

Cycle through all layouts:

Super + N    → Next layout

Adjust layout parameters:

For tile/center_tile layouts:

Super + H       → Decrease master size  (add to config)
Super + L       → Increase master size  (add to config)
Super + Equal   → More windows in master (add to config)
Super + Minus   → Fewer windows in master (add to config)

Add to config.conf:

bind=Super,h,setmfact,-0.05
bind=Super,l,setmfact,+0.05
bind=Super,equal,incnmaster,+1
bind=Super,minus,incnmaster,-1

For scroller layout:

Alt + E      → Set window to full width
Alt + X      → Cycle width presets

---

Window Management Patterns

Focus Management

Directional focus:

Alt + ←→↑↓   → Focus window in direction

Stack focus:

Super + Tab          → Next window in stack
Super + Shift + Tab  → Previous window in stack

Focus last window:

Super + `    → Focus previously focused window (add to config)

Moving Windows

Swap with neighbors:

Super + Shift + ←→↑↓   → Swap positions

Move to master:

Super + Return   → Move focused window to master position (add to config)

Add to config:

bind=Super,Return,zoom,

Move between tags:

Alt + 1-9              → Move to tag (and follow)
Ctrl + Super + ←→      → Move to prev/next tag

Floating Windows

Toggle floating:

Alt + \    → Toggle floating/tiling

Move floating windows:

Ctrl + Shift + ←→↑↓   → Move by pixels
Super + Left-drag      → Move with mouse

Resize floating windows:

Ctrl + Alt + ←→↑↓     → Resize by pixels
Super + Right-drag     → Resize with mouse

Center floating window:

Super + C    → Center window (add to config)

Add to config:

bind=Super,c,centerwin,

Window States

Common states:

Alt + \              → Floating
Alt + F              → Fullscreen
Alt + Shift + F      → Fake fullscreen
Alt + A              → Maximized
Super + G            → Global (visible all tags)
Super + O            → Overlay (always on top)

Minimize/Restore:

Super + I            → Minimize window
Super + Shift + I    → Restore minimized

---

Using the Scratchpad

What is the Scratchpad?

The scratchpad is a hidden workspace for temporary windows. It's perfect for:

• Calculator
• Music player
• Notes/Todo list
• System monitor
• Password manager

Basic Scratchpad Usage

1. Open an application (e.g., terminal with calculator)

   Alt + Return
   # Then run: qalc (or any calculator)
   

2. Move to scratchpad

   Alt + Z
   

3. Window disappears - it's now in the scratchpad

4. Toggle scratchpad to show/hide

   Alt + Z    → Shows scratchpad over current work
   Alt + Z    → Hides it again
   

Named Scratchpads

You can have multiple named scratchpads:

Setup in config.conf:

bind=Super,p,toggle_named_scratchpad,music
bind=Super,n,toggle_named_scratchpad,notes
bind=Super,c,toggle_named_scratchpad,calc

Usage:

1. Open application (e.g., spotify)
2. Press Super + P - assigns it to "music" scratchpad
3. Press Super + P again - shows/hides music scratchpad
4. Other scratchpads are independent

Scratchpad Tips

Automatic scratchpad applications:

Create a script to launch apps directly into scratchpad:

#!/bin/bash
# ~/.config/mango/scripts/scratchpad-calc.sh

# Open calculator in scratchpad
foot -e qalc &
sleep 0.5
mmsg -d toggle_scratchpad

Bind it:

bind=Super,equal,spawn_shell,~/.config/mango/scripts/scratchpad-calc.sh

Customize scratchpad appearance:

In config.conf:

scratchpad_width_ratio=0.8    # 80% of screen width
scratchpad_height_ratio=0.9   # 90% of screen height
scratchpadcolor=0x516c93ff    # Border color for scratchpad windows

---

Overview Mode

What is Overview?

Overview mode shows all windows at once, similar to GNOME's Activities or macOS Mission Control.

Using Overview

Toggle overview:

Alt + Tab    → Toggle overview mode

In overview mode:

• Click any window to focus it
• Drag windows to rearrange
• Windows are organized visually
• All tags are shown

Hotarea trigger: Move your mouse cursor to the top edge of the screen to automatically trigger overview.

Configure hotarea:

# In config.conf
hotarea_size=10        # Pixels from edge to trigger
enable_hotarea=1       # 1=enabled, 0=disabled

Overview Settings

# In config.conf
ov_tab_mode=0          # Show windows as tabs (0=off, 1=on)
overviewgappi=5        # Gap between windows in overview
overviewgappo=30       # Gap from screen edges

---

Multi-Monitor Workflows

Basic Multi-Monitor Commands

Focus different monitor:

Alt + Shift + ←→    → Focus adjacent monitor

Move window to other monitor:

Super + Alt + ←→    → Move window to adjacent monitor

Multi-Monitor Strategies

Strategy 1: Dedicated monitors per task

• Monitor 1: Development (Tag 1-3)
• Monitor 2: Communication (Tag 4-6)
• Monitor 3: Media/Reference (Tag 7-9)

Strategy 2: Mirror similar tags

• Both monitors show same tags
• Each monitor has different layouts
• Use global windows to span both

Strategy 3: Independent workspaces

• Each monitor is independent
• Use monitor focus shortcuts frequently
• Keep related work on same monitor

Monitor Configuration

MangoWC auto-detects monitors. For custom setup:

Disable a monitor:

mmsg -d disable_monitor HDMI-A-1

Enable a monitor:

mmsg -d enable_monitor HDMI-A-1

Find monitor names:

mmsg -o

---

Customization Tips

Modify Keybindings

Edit ~/.config/mango/config.conf:

# Change default terminal
bind=Alt,Return,spawn,alacritty        # Instead of foot

# Add custom application shortcuts
bind=Super,f,spawn,firefox
bind=Super,c,spawn,chromium
bind=Super,e,spawn,thunar

# Add focus last window
bind=Super,grave,focuslast,

# Add center window
bind=Super,c,centerwin,

After editing, press Super + R to reload.

Customize Animations

# In config.conf

# Speed up animations
animation_duration_open=200     # Faster (default: 400)
animation_duration_close=400    # Faster (default: 800)

# Disable animations
animations=0

# Change animation type
animation_type_open=zoom        # Or "slide"
animation_type_close=zoom

Customize Appearance

# In config.conf

# Colors (RGBA hex: 0xRRGGBBAA)
focuscolor=0x89b4faff          # Blue focused border
bordercolor=0x313244ff         # Dark unfocused border

# Borders and gaps
borderpx=3                     # Border width
gappih=10                      # Inner horizontal gap
gappiv=10                      # Inner vertical gap
gappoh=15                      # Outer horizontal gap
gappov=15                      # Outer vertical gap

# Rounded corners
border_radius=10               # Corner radius

# Window effects
blur=1                         # Enable blur
shadows=1                      # Enable shadows
focused_opacity=1.0            # Focused window opacity
unfocused_opacity=0.95         # Unfocused window opacity

Custom Scripts

Create ~/.config/mango/scripts/ directory:

Example: Screenshot script

#!/bin/bash
# ~/.config/mango/scripts/screenshot.sh

grim -g "$(slurp)" - | satty --filename - --fullscreen

Bind it:

bind=Print,none,spawn_shell,~/.config/mango/scripts/screenshot.sh

Example: Volume control

#!/bin/bash
# ~/.config/mango/scripts/volume.sh

case $1 in
    up) pamixer -i 5 ;;
    down) pamixer -d 5 ;;
    mute) pamixer -t ;;
esac

Bind it:

bind=NONE,XF86AudioRaiseVolume,spawn_shell,~/.config/mango/scripts/volume.sh up
bind=NONE,XF86AudioLowerVolume,spawn_shell,~/.config/mango/scripts/volume.sh down
bind=NONE,XF86AudioMute,spawn_shell,~/.config/mango/scripts/volume.sh mute

---

Common Workflows

Workflow 1: Web Development

Setup:

Tag 1: Browser (monocle)        → Testing
Tag 2: Code editor (center_tile) → Development
Tag 3: Terminals (scroller)      → Commands
Scratchpad: Documentation, notes

Workflow:

1. Start on Tag 2, write code
2. Ctrl + 1 → View in browser
3. Ctrl + 3 → Run build/dev server
4. Alt + Z → Toggle docs when needed
5. Use Super + Left/Right to cycle between tags

Workflow 2: Writing and Research

Setup:

Tag 1: Writing app (monocle)
Tag 2: Research browser (tile)
Tag 3: Reference PDFs (grid)
Scratchpad: Notes, citations

Workflow:

1. Research on Tags 2-3
2. Ctrl + 1 → Switch to writing
3. Super + G on notes window → Make it global
4. Notes now visible on all tags

Workflow 3: Communication and Work

Setup:

Tag 1: Email (monocle)
Tag 2: Slack/Discord (tile)
Tag 3: Work documents (tile)
Tag 4: Calendar (monocle)
Global: Music player

Workflow:

1. Open music player → Super + G (make global)
2. Start each app on its tag
3. Use Ctrl + Left/Right to jump between active tags
4. Alt + Tab for quick overview

Workflow 4: System Administration

Setup:

Tag 1: Terminals (scroller)     → Multiple SSH sessions
Tag 2: Monitoring (grid)         → htop, iotop, etc.
Tag 3: Browser (monocle)         → Documentation
Scratchpad: Calculator, quick commands

Workflow:

1. Open terminals in scroller layout
2. Alt + X to adjust column widths
3. Ctrl + 2 for monitoring overview
4. Alt + Z for quick calculations

Workflow 5: Video/Audio Editing

Setup:

Tag 1: Editor (monocle)          → Full-screen editing
Tag 2: File browser (tile)       → Asset management
Tag 3: Preview (monocle)         → Testing output

Workflow:

1. Edit on Tag 1 in monocle (maximum space)
2. Ctrl + 2 → Grab assets
3. Ctrl + 3 → Preview output
4. Use Alt + F for true fullscreen when needed

---

Quick Reference Card

Essential Shortcuts

Alt + Return         Terminal
Alt + Space          Launcher
Alt + Q              Close window
Super + R            Reload config
Super + M            Exit

Alt + ←→↑↓           Focus direction
Super + Shift + ←→↑↓ Swap windows
Alt + \              Toggle floating
Alt + F              Fullscreen
Super + N            Change layout

Ctrl + 1-9           View tag
Alt + 1-9            Move to tag
Super + ←→           Prev/next tag

Alt + Tab            Overview
Alt + Z              Scratchpad
Super + G            Global window

When Things Go Wrong

Super + R            Reload config (fixes most issues)
Super + M            Exit MangoWC
Ctrl + Alt + F2      Switch to TTY (if GUI breaks)

---

Next Steps

Now that you understand the basics:

1. Customize your config - Edit ~/.config/mango/config.conf
2. Set up autostart - Create ~/.config/mango/autostart.sh
3. Explore layouts - Find what works for your workflow
4. Learn IPC - Automate with mmsg (see COMMANDS.md)
5. Join the community - Discord

Additional Resources:

• COMMANDS.md - Complete command reference
• config.conf - Commented configuration file
• MangoWC Wiki - Comprehensive documentation
• Website - Online documentation

---

Happy tiling! 🥭