diff --git a/.github/scripts/sync-wiki.py b/.github/scripts/sync-wiki.py new file mode 100644 index 0000000..ebf543c --- /dev/null +++ b/.github/scripts/sync-wiki.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +import json +import re +from pathlib import Path + +DOCS_DIR = Path("docs") +WIKI_DIR = Path("wiki-temp") + +FRONTMATTER_RE = re.compile(r"\A---\s*\n.*?^---\s*\n", re.DOTALL | re.MULTILINE) +DOCS_LINK_RE = re.compile(r"\[([^\]]+)\]\(/docs/(?:[^/)]+/)*([^/)#]+)(#[^)]+)?\)") + + +def collect_all_files() -> list[tuple[Path, str]]: + files = [] + + def from_dir(directory: Path) -> list[Path]: + meta = directory / "meta.json" + if meta.exists(): + data = json.loads(meta.read_text()) + return [directory / f"{p}.md" for p in data.get("pages", []) if (directory / f"{p}.md").exists()] + return sorted(directory.glob("*.md")) + + for src in from_dir(DOCS_DIR): + files.append((src, "Home" if src.stem == "index" else src.stem)) + + for subdir in sorted(DOCS_DIR.iterdir()): + if subdir.is_dir(): + for src in from_dir(subdir): + files.append((src, src.stem)) + + return files + + +def main() -> None: + files = collect_all_files() + + contents = {src: src.read_text() for src, _ in files} + + for src, dest_name in files: + text = FRONTMATTER_RE.sub("", contents[src], count=1).lstrip("\n") + text = DOCS_LINK_RE.sub(lambda m: f"[{m.group(1)}]({m.group(2)}{m.group(3) or ''})", text) + (WIKI_DIR / f"{dest_name}.md").write_text(text) + + lines: list[str] = [] + current_section = None + for src, dest_name in files: + section = "General" if src.parent == DOCS_DIR else src.parent.name.replace("-", " ").title() + if section != current_section: + if current_section is not None: + lines.append("") + lines.append(f"## {section}\n") + current_section = section + if dest_name != "Home": + title = dest_name.replace("-", " ").replace("_", " ").title() + lines.append(f"- [[{dest_name}|{title}]]") + + (WIKI_DIR / "_Sidebar.md").write_text("\n".join(lines)) + + +if __name__ == "__main__": + main() diff --git a/.github/workflows/sync-website.yml b/.github/workflows/sync-website.yml new file mode 100644 index 0000000..f641fb8 --- /dev/null +++ b/.github/workflows/sync-website.yml @@ -0,0 +1,42 @@ +name: Sync website + +on: + push: + branches: [main] + paths: + - docs/** + +concurrency: + group: sync-website + cancel-in-progress: true + +jobs: + sync-website: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + token: ${{ github.token }} + + - name: Checkout website + uses: actions/checkout@v4 + with: + repository: mangowm/mangowm.github.io + path: website + token: ${{ secrets.WEBSITE_SYNC_TOKEN }} + fetch-depth: 1 + + - name: Sync docs + run: | + rm -rf website/apps/web/content/docs + cp -r docs website/apps/web/content/docs + + - name: Commit and push + working-directory: website + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add apps/web/content/docs + git diff --staged --quiet || git commit -m "sync from mango @ ${{ github.sha }}" + git push diff --git a/.github/workflows/sync-wiki.yml b/.github/workflows/sync-wiki.yml new file mode 100644 index 0000000..ef30fe7 --- /dev/null +++ b/.github/workflows/sync-wiki.yml @@ -0,0 +1,40 @@ +name: Sync wiki + +on: + push: + branches: [main] + paths: + - docs/** + +concurrency: + group: sync-wiki + cancel-in-progress: true + +permissions: + contents: write + +jobs: + sync-wiki: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Clone wiki + run: | + git clone --depth 1 \ + https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.wiki.git \ + wiki-temp + + - name: Sync docs to wiki + run: | + find wiki-temp -not -path 'wiki-temp/.git*' -type f -delete + python3 .github/scripts/sync-wiki.py + + - name: Commit and push + working-directory: wiki-temp + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add -A + git diff --staged --quiet || git commit -m "sync from ${{ github.sha }}" + git push diff --git a/docs/bindings/keys.md b/docs/bindings/keys.md new file mode 100644 index 0000000..64ba64b --- /dev/null +++ b/docs/bindings/keys.md @@ -0,0 +1,204 @@ +--- +title: Key Bindings +description: Define keyboard shortcuts and modes. +--- + +## Syntax + +Key bindings follow this format: + +```ini +bind[flags]=MODIFIERS,KEY,COMMAND,PARAMETERS +``` + +- **Modifiers**: `SUPER`, `CTRL`, `ALT`, `SHIFT`, `NONE` (combine with `+`, e.g. `SUPER+CTRL+ALT`). +- **Key**: Key name (from `xev` or `wev`) or keycode (e.g., `code:24` for `q`). + +> **Info:** `bind` automatically converts keysym to keycode for comparison. This makes it compatible with all keyboard layouts, but the matching may not always be precise. If a key combination doesn't work on your keyboard layout, use a keycode instead (e.g., `code:24` instead of `q`). + +### Flags + +- `l`: Works even when screen is locked. +- `s`: Uses keysym instead of keycode to bind. +- `r`: Triggers on key release instead of press. +- `p`: Pass key event to client. + +**Examples:** + +```ini +bind=SUPER,Q,killclient +bindl=SUPER,L,spawn,swaylock + +# Using keycode instead of key name +bind=ALT,code:24,killclient + +# Combining keycodes for modifiers and keys +bind=code:64,code:24,killclient +bind=code:64+code:133,code:24,killclient + +# Bind with no modifier +bind=NONE,XF86MonBrightnessUp,spawn,brightnessctl set +5% + +# Bind a modifier key itself as the trigger key +bind=alt,shift_l,switch_keyboard_layout +``` + +## Key Modes (Submaps) + +You can divide key bindings into named modes. Rules: + +1. Set `keymode=` before a group of `bind` lines — those binds only apply in that mode. +2. If no `keymode` is set before a bind, it belongs to the `default` mode. +3. The special `common` keymode applies its binds **across all modes**. + +Use `setkeymode` to switch modes, and `mmsg -b` to query the current mode. + +```ini +# Binds in 'common' apply in every mode +keymode=common +bind=SUPER,r,reload_config + +# Default mode bindings +keymode=default +bind=ALT,Return,spawn,foot +bind=SUPER,F,setkeymode,resize + +# 'resize' mode bindings +keymode=resize +bind=NONE,Left,resizewin,-10,0 +bind=NONE,Right,resizewin,+10,0 +bind=NONE,Escape,setkeymode,default +``` + +### Single Modifier Key Binding + +When binding a modifier key itself, use `NONE` for press and the modifier name for release: + +```ini +# Trigger on press of Super key +bind=none,Super_L,spawn,rofi -show run + +# Trigger on release of Super key +bindr=Super,Super_L,spawn,rofi -show run +``` + +## Dispatchers List + +### Window Management + +| Command | Param | Description | +| :--- | :--- | :--- | +| `killclient` | - | Close the focused window. | +| `togglefloating` | - | Toggle floating state. | +| `togglefullscreen` | - | Toggle fullscreen. | +| `togglefakefullscreen` | - | Toggle "fake" fullscreen (remains constrained). | +| `togglemaximizescreen` | - | Maximize window (keep decoration/bar). | +| `toggleglobal` | - | Pin window to all tags. | +| `toggle_render_border` | - | Toggle border rendering. | +| `centerwin` | - | Center the floating window. | +| `minimized` | - | Minimize window to scratchpad. | +| `restore_minimized` | - | Restore window from scratchpad. | +| `toggle_scratchpad` | - | Toggle scratchpad. | +| `toggle_named_scratchpad` | `appid,title,cmd` | Toggle named scratchpad. Launches app if not running, otherwise shows/hides it. | + +### Focus & Movement + +| Command | Param | Description | +| :--- | :--- | :--- | +| `focusdir` | `left/right/up/down` | Focus window in direction. | +| `focusstack` | `next/prev` | Cycle focus within the stack. | +| `focuslast` | - | Focus the previously active window. | +| `exchange_client` | `left/right/up/down` | Swap window with neighbor in direction. | +| `exchange_stack_client` | `next/prev` | Exchange window position in stack. | +| `zoom` | - | Swap focused window with Master. | + +### Tags & Monitors + +| Command | Param | Description | +| :--- | :--- | :--- | +| `view` | `-1/0/1-9` or `mask [,synctag]` | View tag. `-1` = previous tagset, `0` = all tags, `1-9` = specific tag, mask e.g. `1\|3\|5`. Optional `synctag` (0/1) syncs the action to all monitors. | +| `viewtoleft` | `[synctag]` | View previous tag. Optional `synctag` (0/1) syncs to all monitors. | +| `viewtoright` | `[synctag]` | View next tag. Optional `synctag` (0/1) syncs to all monitors. | +| `viewtoleft_have_client` | `[synctag]` | View left tag and focus client if present. Optional `synctag` (0/1). | +| `viewtoright_have_client` | `[synctag]` | View right tag and focus client if present. Optional `synctag` (0/1). | +| `viewcrossmon` | `tag,monitor_spec` | View specified tag on specified monitor. | +| `tag` | `1-9 [,synctag]` | Move window to tag. Optional `synctag` (0/1) syncs to all monitors. | +| `tagsilent` | `1-9` | Move window to tag without focusing it. | +| `tagtoleft` | `[synctag]` | Move window to left tag. Optional `synctag` (0/1). | +| `tagtoright` | `[synctag]` | Move window to right tag. Optional `synctag` (0/1). | +| `tagcrossmon` | `tag,monitor_spec` | Move window to specified tag on specified monitor. | +| `toggletag` | `0-9` | Toggle tag on window (0 means all tags). | +| `toggleview` | `1-9` | Toggle tag view. | +| `comboview` | `1-9` | View multi tags pressed simultaneously. | +| `focusmon` | `left/right/up/down/monitor_spec` | Focus monitor by direction or [monitor spec](/docs/configuration/monitors#monitor-spec-format). | +| `tagmon` | `left/right/up/down/monitor_spec,[keeptag]` | Move window to monitor by direction or [monitor spec](/docs/configuration/monitors#monitor-spec-format). `keeptag` is 0 or 1. | + +### Layouts + +| Command | Param | Description | +| :--- | :--- | :--- | +| `setlayout` | `name` | Switch to layout (e.g., `scroller`, `tile`). | +| `switch_layout` | - | Cycle through available layouts. | +| `incnmaster` | `+1/-1` | Increase/Decrease number of master windows. | +| `setmfact` | `+0.05` | Increase/Decrease master area size. | +| `set_proportion` | `float` | Set scroller window proportion (0.0–1.0). | +| `switch_proportion_preset` | - | Cycle proportion presets of scroller window. | +| `scroller_stack` | `left/right/up/down` | Move window inside/outside scroller stack by direction. | +| `incgaps` | `+/-value` | Adjust gap size. | +| `togglegaps` | - | Toggle gaps. | + +### System + +| Command | Param | Description | +| :--- | :--- | :--- | +| `spawn` | `cmd` | Execute a command. | +| `spawn_shell` | `cmd` | Execute shell command (supports pipes `\|`). | +| `spawn_on_empty` | `cmd,tagnumber` | Open command on empty tag. | +| `reload_config` | - | Hot-reload configuration. | +| `quit` | - | Exit mangowm. | +| `toggleoverview` | - | Toggle overview mode. | +| `create_virtual_output` | - | Create a headless monitor (for VNC/Sunshine). | +| `destroy_all_virtual_output` | - | Destroy all virtual monitors. | +| `toggleoverlay` | - | Toggle overlay state for the focused window. | +| `toggle_trackpad_enable` | - | Toggle trackpad enable. | +| `setkeymode` | `mode` | Set keymode. | +| `switch_keyboard_layout` | `[index]` | Switch keyboard layout. Optional index (0, 1, 2...) to switch to specific layout. | +| `setoption` | `key,value` | Set config option temporarily. | +| `disable_monitor` | `monitor_spec` | Shutdown monitor. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). | +| `enable_monitor` | `monitor_spec` | Power on monitor. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). | +| `toggle_monitor` | `monitor_spec` | Toggle monitor power. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). | + +### Media Controls + +> **Warning:** Some keyboards don't send standard media keys. Run `wev` and press your key to check the exact key name. + +#### Brightness + +Requires: `brightnessctl` + +```ini +bind=NONE,XF86MonBrightnessUp,spawn,brightnessctl s +2% +bind=SHIFT,XF86MonBrightnessUp,spawn,brightnessctl s 100% +bind=NONE,XF86MonBrightnessDown,spawn,brightnessctl s 2%- +bind=SHIFT,XF86MonBrightnessDown,spawn,brightnessctl s 1% +``` + +#### Volume + +Requires: `wpctl` (WirePlumber) + +```ini +bind=NONE,XF86AudioRaiseVolume,spawn,wpctl set-volume @DEFAULT_SINK@ 5%+ +bind=NONE,XF86AudioLowerVolume,spawn,wpctl set-volume @DEFAULT_SINK@ 5%- +bind=NONE,XF86AudioMute,spawn,wpctl set-mute @DEFAULT_SINK@ toggle +bind=SHIFT,XF86AudioMute,spawn,wpctl set-mute @DEFAULT_SOURCE@ toggle +``` + +### Floating Window Movement + +| Command | Param | Description | +| :--- | :--- | :--- | +| `smartmovewin` | `left/right/up/down` | Move floating window by snap distance. | +| `smartresizewin` | `left/right/up/down` | Resize floating window by snap distance. | +| `movewin` | `(x,y)` | Move floating window. | +| `resizewin` | `(width,height)` | Resize window. | \ No newline at end of file diff --git a/docs/bindings/meta.json b/docs/bindings/meta.json new file mode 100644 index 0000000..f1b629b --- /dev/null +++ b/docs/bindings/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Bindings & Input", + "pages": ["keys", "mouse-gestures"] +} diff --git a/docs/bindings/mouse-gestures.md b/docs/bindings/mouse-gestures.md new file mode 100644 index 0000000..c4a3688 --- /dev/null +++ b/docs/bindings/mouse-gestures.md @@ -0,0 +1,116 @@ +--- +title: Mouse & Gestures +description: Configure mouse buttons, scrolling, gestures, and lid switches. +--- + +## Mouse Bindings + +Assign actions to mouse button presses with optional modifier keys. + +### Syntax + +```ini +mousebind=MODIFIERS,BUTTON,COMMAND,PARAMETERS +``` + +- **Modifiers**: `SUPER`, `CTRL`, `ALT`, `SHIFT`, `NONE`. Combine with `+` (e.g., `SUPER+CTRL`) +- **Buttons**: `btn_left`, `btn_right`, `btn_middle`, `btn_side`, `btn_extra`, `btn_forward`, `btn_back`, `btn_task` + +> **Warning:** When modifiers are set to `NONE`, only `btn_middle` works in normal mode. `btn_left` and `btn_right` only work in overview mode. + +### Examples + +```ini +# Window manipulation +mousebind=SUPER,btn_left,moveresize,curmove +mousebind=SUPER,btn_right,moveresize,curresize +mousebind=SUPER+CTRL,btn_right,killclient + +# Overview mode (requires NONE modifier) +mousebind=NONE,btn_left,toggleoverview,-1 +mousebind=NONE,btn_right,killclient,0 +mousebind=NONE,btn_middle,togglemaximizescreen,0 +``` + +--- + +## Axis Bindings + +Map scroll wheel movements to actions for workspace and window navigation. + +### Syntax + +```ini +axisbind=MODIFIERS,DIRECTION,COMMAND,PARAMETERS +``` + +- **Direction**: `UP`, `DOWN`, `LEFT`, `RIGHT` + +### Examples + +```ini +axisbind=SUPER,UP,viewtoleft_have_client +axisbind=SUPER,DOWN,viewtoright_have_client +``` + +--- + +## Gesture Bindings + +Enable touchpad swipe gestures for navigation and window management. + +### Syntax + +```ini +gesturebind=MODIFIERS,DIRECTION,FINGERS,COMMAND,PARAMETERS +``` + +- **Direction**: `up`, `down`, `left`, `right` +- **Fingers**: `3` or `4` + +> **Info:** Gestures require proper touchpad configuration. See [Input Devices](/docs/configuration/input) for touchpad settings like `tap_to_click` and `disable_while_typing`. + +### Examples + +```ini +# 3-finger: Window focus +gesturebind=none,left,3,focusdir,left +gesturebind=none,right,3,focusdir,right +gesturebind=none,up,3,focusdir,up +gesturebind=none,down,3,focusdir,down + +# 4-finger: Workspace navigation +gesturebind=none,left,4,viewtoleft_have_client +gesturebind=none,right,4,viewtoright_have_client +gesturebind=none,up,4,toggleoverview +gesturebind=none,down,4,toggleoverview +``` + +--- + +## Switch Bindings + +Trigger actions on hardware events like laptop lid open/close. + +### Syntax + +```ini +switchbind=FOLD_STATE,COMMAND,PARAMETERS +``` + +- **Fold State**: `fold` (lid closed), `unfold` (lid opened) + +> **Warning:** Disable system lid handling in `/etc/systemd/logind.conf`: +> +> ```ini +> HandleLidSwitch=ignore +> HandleLidSwitchExternalPower=ignore +> HandleLidSwitchDocked=ignore +> ``` + +### Examples + +```ini +switchbind=fold,spawn,swaylock -f -c 000000 +switchbind=unfold,spawn,wlr-dpms on +``` diff --git a/docs/configuration/basics.md b/docs/configuration/basics.md new file mode 100644 index 0000000..dbbe45f --- /dev/null +++ b/docs/configuration/basics.md @@ -0,0 +1,87 @@ +--- +title: Basic Configuration +description: Learn how to configure mangowm files, environment variables, and autostart scripts. +--- + +## Configuration File + +mangowm uses a simple configuration file format. By default, it looks for a configuration file in `~/.config/mango/`. + +1. **Locate Default Config** + + A fallback configuration is provided at `/etc/mango/config.conf`. You can use this as a reference. + +2. **Create User Config** + + Copy the default config to your local config directory to start customizing. + + ```bash + mkdir -p ~/.config/mango + cp /etc/mango/config.conf ~/.config/mango/config.conf + ``` + +3. **Launch with Custom Config (Optional)** + + If you prefer to keep your config elsewhere, you can launch mango with the `-c` flag. + + ```bash + mango -c /path/to/your_config.conf + ``` + +### Sub-Configuration + +To keep your configuration organized, you can split it into multiple files and include them using the `source` keyword. + +```ini +# Import keybindings from a separate file +source=~/.config/mango/bind.conf + +# Relative paths work too +source=./theme.conf + +# Optional: ignore if file doesn't exist (useful for shared configs) +source-optional=~/.config/mango/optional.conf +``` + +### Validate Configuration + +You can check your configuration for errors without starting mangowm: + +```bash +mango -p /path/to/config.conf +``` + +Use with `source-optional` for shared configs across different setups. + +## Environment Variables + +You can define environment variables directly within your config file. These are set before the window manager fully initializes. + +> **Warning:** Environment variables defined here will be **reset** every time you reload the configuration. + +```ini +env=GTK_THEME,Adwaita:dark +env=XCURSOR_SIZE,24 +``` + +## Autostart + +mangowm can automatically run commands or scripts upon startup. There are two modes for execution: + +| Command | Behavior | Usage Case | +| :--- | :--- | :--- | +| `exec-once` | Runs **only once** when mangowm starts. | Status bars, Wallpapers, Notification daemons | +| `exec` | Runs **every time** the config is reloaded. | Scripts that need to refresh settings | + +### Example Setup + +```ini +# Start the status bar once +exec-once=waybar + +# Set wallpaper +exec-once=swaybg -i ~/.config/mango/wallpaper/room.png + +# Reload a custom script on config change +exec=bash ~/.config/mango/reload-settings.sh +``` diff --git a/docs/configuration/input.md b/docs/configuration/input.md new file mode 100644 index 0000000..3ebc0f2 --- /dev/null +++ b/docs/configuration/input.md @@ -0,0 +1,150 @@ +--- +title: Input Devices +description: Configure keyboard layouts, mouse sensitivity, and touchpad gestures. +--- + +## Device Configuration + +mangowm provides granular control over different input devices. + +### Keyboard Settings + +Control key repeat rates and layout rules. + +| Setting | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `repeat_rate` | `int` | `25` | How many times a key repeats per second. | +| `repeat_delay` | `int` | `600` | Delay (ms) before a held key starts repeating. | +| `numlockon` | `0` or `1` | `0` | Enable NumLock on startup. | +| `xkb_rules_rules` | `string` | - | XKB rules file (e.g., `evdev`, `base`). Usually auto-detected. | +| `xkb_rules_model` | `string` | - | Keyboard model (e.g., `pc104`, `macbook`). | +| `xkb_rules_layout` | `string` | - | Keyboard layout code (e.g., `us`, `de`, `us,de`). | +| `xkb_rules_variant` | `string` | - | Layout variant (e.g., `dvorak`, `colemak`, `intl`). | +| `xkb_rules_options` | `string` | - | XKB options (e.g., `caps:escape`, `ctrl:nocaps`). | + +**Example:** + +```ini +repeat_rate=40 +repeat_delay=300 +numlockon=1 +xkb_rules_layout=us,de +xkb_rules_variant=dvorak +xkb_rules_options=caps:escape,ctrl:nocaps +``` + +--- + +### Trackpad Settings + +Specific settings for laptop touchpads. Some settings may require a relogin to take effect. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `disable_trackpad` | `0` | Set to `1` to disable the trackpad entirely. | +| `tap_to_click` | `1` | Tap to trigger a left click. | +| `tap_and_drag` | `1` | Tap and hold to drag items. | +| `trackpad_natural_scrolling` | `0` | Invert scrolling direction (natural scrolling). | +| `scroll_method` | `1` | `1` (Two-finger), `2` (Edge), `4` (Button). | +| `click_method` | `1` | `1` (Button areas), `2` (Clickfinger). | +| `drag_lock` | `1` | Lock dragging after tapping. | +| `disable_while_typing` | `1` | Disable trackpad while typing. | +| `left_handed` | `0` | Swap left/right buttons. | +| `middle_button_emulation` | `0` | Emulate middle button. | +| `swipe_min_threshold` | `1` | Minimum swipe threshold. | + +--- + +**Detailed descriptions:** + +- `scroll_method` values: + - `0` — Never send scroll events (no scrolling). + - `1` — Two-finger scrolling: send scroll events when two fingers are logically down on the device. + - `2` — Edge scrolling: send scroll events when a finger moves along the bottom or right edge. + - `4` — Button scrolling: send scroll events when a button is held and the device moves along a scroll axis. + +- `click_method` values: + - `0` — No software click emulation. + - `1` — Button areas: use software-defined areas on the touchpad to generate button events. + - `2` — Clickfinger: the number of fingers determines which button is pressed. + +- `accel_profile` values: + - `0` — No acceleration. + - `1` — Flat: no dynamic acceleration. Pointer speed = original input speed × (1 + `accel_speed`). + - `2` — Adaptive: slow movement results in less acceleration, fast movement results in more. + +- `button_map` values: + - `0` — 1/2/3 finger tap maps to left / right / middle. + - `1` — 1/2/3 finger tap maps to left / middle / right. + +- `send_events_mode` values: + - `0` — Send events from this device normally. + - `1` — Do not send events from this device. + - `2` — Disable this device when an external pointer device is plugged in. + +--- + +### Mouse Settings + +Configuration for external mice. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `mouse_natural_scrolling` | `0` | Invert scrolling direction. | +| `accel_profile` | `2` | `0` (None), `1` (Flat), `2` (Adaptive). | +| `accel_speed` | `0.0` | Speed adjustment (-1.0 to 1.0). | +| `left_handed` | `0` | Swap left and right buttons. | +| `middle_button_emulation` | `0` | Emulate middle button. | +| `swipe_min_threshold` | `1` | Minimum swipe threshold. | +| `send_events_mode` | `0` | `0` (Enabled), `1` (Disabled), `2` (Disabled on external mouse). | +| `button_map` | `0` | `0` (Left/right/middle), `1` (Left/middle/right). | + +--- + +--- + +## Keyboard Layout Switching + +To bind multiple layouts and toggle between them, define the layouts in `xkb_rules_layout` and use `xkb_rules_options` to set a toggle key combination. Then bind `switch_keyboard_layout` to trigger a switch. + +```ini +# Define two layouts: US QWERTY and US Dvorak +xkb_rules_layout=us,us +xkb_rules_variant=,dvorak +xkb_rules_options=grp:lalt_lshift_toggle +``` + +Or bind it manually to a key: + +```ini +# Bind Alt+Shift_L to cycle keyboard layout +bind=alt,shift_l,switch_keyboard_layout +``` + +Use `mmsg -g -k` to query the current keyboard layout at any time. + +--- + +## Input Method Editor (IME) + +To use Fcitx5 or IBus, set these environment variables in your config file. + +> **Info:** These settings require a restart of the window manager to take effect. + +**For Fcitx5:** + +```ini +env=GTK_IM_MODULE,fcitx +env=QT_IM_MODULE,fcitx +env=SDL_IM_MODULE,fcitx +env=XMODIFIERS,@im=fcitx +env=GLFW_IM_MODULE,ibus +``` + +**For IBus:** + +```ini +env=GTK_IM_MODULE,ibus +env=QT_IM_MODULE,ibus +env=XMODIFIERS,@im=ibus +``` diff --git a/docs/configuration/meta.json b/docs/configuration/meta.json new file mode 100644 index 0000000..bc209b4 --- /dev/null +++ b/docs/configuration/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Configuration", + "pages": ["basics", "monitors", "input", "xdg-portals", "miscellaneous"] +} diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md new file mode 100644 index 0000000..9e06781 --- /dev/null +++ b/docs/configuration/miscellaneous.md @@ -0,0 +1,51 @@ +--- +title: Miscellaneous +description: Advanced settings for XWayland, focus behavior, and system integration. +--- + +## System & Hardware + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `xwayland_persistence` | `1` | Keep XWayland running even when no X11 apps are open (reduces startup lag). | +| `syncobj_enable` | `0` | Enable `drm_syncobj` timeline support (helps with gaming stutter/lag). **Requires restart.** | +| `allow_lock_transparent` | `0` | Allow the lock screen to be transparent. | +| `allow_shortcuts_inhibit` | `1` | Allow shortcuts to be inhibited by clients. | +| `vrr` | - | Set via [monitor rule](/docs/configuration/monitors#monitor-rules). | + +## Focus & Input + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `focus_on_activate` | `1` | Automatically focus windows when they request activation. | +| `sloppyfocus` | `1` | Focus follows the mouse cursor. | +| `warpcursor` | `1` | Warp the cursor to the center of the window when focus changes via keyboard. | +| `cursor_hide_timeout` | `0` | Hide the cursor after `N` seconds of inactivity (`0` to disable). | +| `drag_tile_to_tile` | `0` | Allow dragging a tiled window onto another to swap their positions. | +| `drag_corner` | `3` | Corner for drag-to-tile detection (0: none, 1–3: corners, 4: auto-detect). | +| `drag_warp_cursor` | `1` | Warp cursor when dragging windows to tile. | +| `axis_bind_apply_timeout` | `100` | Timeout (ms) for detecting consecutive scroll events for axis bindings. | +| `axis_scroll_factor` | `1.0` | Scroll factor for axis scroll speed (0.1–10.0). | + +## Multi-Monitor & Tags + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `focus_cross_monitor` | `0` | Allow directional focus to cross monitor boundaries. | +| `exchange_cross_monitor` | `0` | Allow exchanging clients across monitor boundaries. | +| `focus_cross_tag` | `0` | Allow directional focus to cross into other tags. | +| `view_current_to_back` | `0` | Toggling the current tag switches back to the previously viewed tag. | +| `scratchpad_cross_monitor` | `0` | Share the scratchpad pool across all monitors. | +| `single_scratchpad` | `1` | Only allow one scratchpad (named or standard) to be visible at a time. | +| `circle_layout` | - | A comma-separated list of layouts `switch_layout` cycles through. | + +## Window Behavior + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `enable_floating_snap` | `0` | Snap floating windows to edges or other windows. | +| `snap_distance` | `30` | Max distance (pixels) to trigger floating snap. | +| `no_border_when_single` | `0` | Remove window borders when only one window is visible on the tag. | +| `idleinhibit_ignore_visible` | `0` | Allow invisible clients (e.g., background audio players) to inhibit idle. | +| `drag_tile_refresh_interval` | `8.0` | Interval (1.0–16.0) to refresh tiled window resize during drag. Too small may cause application lag. | +| `drag_floating_refresh_interval` | `8.0` | Interval (1.0–16.0) to refresh floating window resize during drag. Too small may cause application lag. | \ No newline at end of file diff --git a/docs/configuration/monitors.md b/docs/configuration/monitors.md new file mode 100644 index 0000000..92c2082 --- /dev/null +++ b/docs/configuration/monitors.md @@ -0,0 +1,274 @@ +--- +title: Monitors +description: Manage display outputs, resolution, scaling, and tearing. +--- + +## Monitor Rules + +You can configure each display output individually using the `monitorrule` keyword. + +**Syntax:** + +```ini +monitorrule=name:Values,Parameter:Values,Parameter:Values +``` + +> **Info:** If any of the matching fields (`name`, `make`, `model`, `serial`) are set, **all** of the set ones must match to be considered a match. Use `wlr-randr` to get your monitor's name, make, model, and serial. + +### Parameters + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `name` | string | Any | Match by monitor name (supports regex) | +| `make` | string | Any | Match by monitor manufacturer | +| `model` | string | Any | Match by monitor model | +| `serial` | string | Any | Match by monitor serial number | +| `width` | integer | 0-9999 | Monitor width | +| `height` | integer | 0-9999 | Monitor height | +| `refresh` | float | 0.001-9999.0 | Monitor refresh rate | +| `x` | integer | 0-99999 | X position | +| `y` | integer | 0-99999 | Y position | +| `scale` | float | 0.01-100.0 | Monitor scale | +| `vrr` | integer | 0, 1 | Enable variable refresh rate | +| `rr` | integer | 0-7 | Monitor transform | +| `custom` | integer | 0, 1 | Enable custom mode (not supported on all displays — may cause black screen) | + +### Transform Values + +| Value | Rotation | +| :--- | :--- | +| `0` | No transform | +| `1` | 90° counter-clockwise | +| `2` | 180° counter-clockwise | +| `3` | 270° counter-clockwise | +| `4` | 180° vertical flip | +| `5` | Flip + 90° counter-clockwise | +| `6` | Flip + 180° counter-clockwise | +| `7` | Flip + 270° counter-clockwise | + +> **Critical:** If you use XWayland applications, **never use negative coordinates** for your monitor positions. This is a known XWayland bug that causes click events to malfunction. Always arrange your monitors starting from `0,0` and extend into positive coordinates. + +### Examples + +```ini +# Laptop display: 1080p, 60Hz, positioned at origin +monitorrule=name:eDP-1,width:1920,height:1080,refresh:60,x:0,y:10 + +# Match by make and model instead of name +monitorrule=make:Chimei Innolux Corporation,model:0x15F5,width:1920,height:1080,refresh:60,x:0,y:0 + +# Virtual monitor with pattern matching +monitorrule=name:HEADLESS-.*,width:1920,height:1080,refresh:60,x:1926,y:0,scale:1,rr:0,vrr:0 +``` + +--- + +## Monitor Spec Format + +Several commands (`focusmon`, `tagmon`, `disable_monitor`, `enable_monitor`, `toggle_monitor`, `viewcrossmon`, `tagcrossmon`) accept a **monitor_spec** string to identify a monitor. + +**Format:** + +```text +name:xxx&&make:xxx&&model:xxx&&serial:xxx +``` + +- Any field can be omitted and there is no order requirement. +- If all fields are omitted, the string is treated as the monitor name directly (e.g., `eDP-1`). +- Use `wlr-randr` to find your monitor's name, make, model, and serial. + +**Examples:** + +```bash +# By name (shorthand) +mmsg -d toggle_monitor,eDP-1 + +# By make and model +mmsg -d toggle_monitor,make:Chimei Innolux Corporation&&model:0x15F5 + +# By serial +mmsg -d toggle_monitor,serial:12345678 +``` + +--- + +## Tearing (Game Mode) + +Tearing allows games to bypass the compositor's VSync for lower latency. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `allow_tearing` | `0` | Global tearing control: `0` (Disable), `1` (Enable), `2` (Fullscreen only). | + +### Configuration + +**Enable Globally:** + +```ini +allow_tearing=1 +``` + +**Enable per Window:** + +Use a window rule to force tearing for specific games. + +```ini +windowrule=force_tearing:1,title:vkcube +``` + +### Tearing Behavior Matrix + +| `force_tearing` \ `allow_tearing` | DISABLED (0) | ENABLED (1) | FULLSCREEN_ONLY (2) | +| :--- | :--- | :--- | :--- | +| **UNSPECIFIED** (0) | Not Allowed | Follows tearing_hint | Only fullscreen follows tearing_hint | +| **ENABLED** (1) | Not Allowed | Allowed | Only fullscreen allowed | +| **DISABLED** (2) | Not Allowed | Not Allowed | Not Allowed | + +### Graphics Card Compatibility + +> **Warning:** Some graphics cards require setting the `WLR_DRM_NO_ATOMIC` environment variable before mango starts to successfully enable tearing. + +Add this to `/etc/environment` and reboot: + +```bash +WLR_DRM_NO_ATOMIC=1 +``` + +Or run mango with the environment variable: + +```bash +WLR_DRM_NO_ATOMIC=1 mango +``` + +--- + +## GPU Compatibility + +If mango cannot display correctly or shows a black screen, try selecting a specific GPU: + +```bash +# Use a single GPU +WLR_DRM_DEVICES=/dev/dri/card1 mango + +# Use multiple GPUs +WLR_DRM_DEVICES=/dev/dri/card0:/dev/dri/card1 mango +``` + +Some GPUs have compatibility issues with `syncobj_enable=1` — it may crash apps like `kitty` that use syncobj. Set `WLR_DRM_NO_ATOMIC=1` in `/etc/environment` and reboot to resolve this. + +--- + +## Power Management + +You can control monitor power using the `mmsg` IPC tool. + +```bash +# Turn off +mmsg -d disable_monitor,eDP-1 + +# Turn on +mmsg -d enable_monitor,eDP-1 + +# Toggle +mmsg -d toggle_monitor,eDP-1 +``` + +You can also use `wlr-randr` for monitor management: + +```bash +# Turn off monitor +wlr-randr --output eDP-1 --off + +# Turn on monitor +wlr-randr --output eDP-1 --on + +# Show all monitors +wlr-randr +``` + +--- + +## Screen Scale + +### Without Global Scale (Recommended) + +- If you do not use XWayland apps, you can use monitor rules or `wlr-randr` to set a global monitor scale. +- If you are using XWayland apps, it is not recommended to set a global monitor scale. + +You can set scale like this, for example with a 1.4 factor. + +**Dependencies:** + +```bash +yay -S xorg-xrdb +yay -S xwayland-satellite +``` + +**In config file:** + +```ini +env=QT_AUTO_SCREEN_SCALE_FACTOR,1 +env=QT_WAYLAND_FORCE_DPI,140 +``` + +**In autostart:** + +```bash +echo "Xft.dpi: 140" | xrdb -merge +gsettings set org.gnome.desktop.interface text-scaling-factor 1.4 +``` + +**Edit autostart for XWayland:** + +```bash +# Start xwayland +/usr/sbin/xwayland-satellite :11 & +# Apply scale 1.4 for xwayland +sleep 0.5s && echo "Xft.dpi: 140" | xrdb -merge +``` + +### Using xwayland-satellite to Prevent Blurry XWayland Apps + +If you use fractional scaling, you can use `xwayland-satellite` to automatically scale XWayland apps to prevent blurriness, for example with a scale of 1.4. + +**Dependencies:** + +```bash +yay -S xwayland-satellite +``` + +**In config file:** + +```ini +env=DISPLAY,:2 +exec=xwayland-satellite :2 +monitorrule=name:eDP-1,width:1920,height:1080,refresh:60,x:0,y:0,scale:1.4,vrr:0,rr:0 +``` + +> **Warning:** Use a `DISPLAY` value other than `:1` to avoid conflicting with mangowm. + +--- + +## Virtual Monitors + +You can create and manage virtual displays through IPC commands: + +```bash +# Create virtual output +mmsg -d create_virtual_output + +# Destroy all virtual outputs +mmsg -d destroy_all_virtual_output +``` + +You can configure virtual monitors using `wlr-randr`: + +```bash +# Show all monitors +wlr-randr + +# Configure virtual monitor +wlr-randr --output HEADLESS-1 --pos 1921,0 --scale 1 --custom-mode 1920x1080@60Hz +``` + +Virtual monitors can be used for screen sharing with tools like [Sunshine](https://github.com/LizardByte/Sunshine) and [Moonlight](https://github.com/moonlight-stream/moonlight-android), allowing other devices to act as extended monitors. \ No newline at end of file diff --git a/docs/configuration/xdg-portals.md b/docs/configuration/xdg-portals.md new file mode 100644 index 0000000..27819ad --- /dev/null +++ b/docs/configuration/xdg-portals.md @@ -0,0 +1,76 @@ +--- +title: XDG Portals +description: Set up screen sharing, clipboard, keyring, and file pickers using XDG portals. +--- + +## Portal Configuration + +You can customize portal settings via the following paths: + +- **User Configuration (Priority):** `~/.config/xdg-desktop-portal/mango-portals.conf` +- **System Fallback:** `/usr/share/xdg-desktop-portal/mango-portals.conf` + +> **Warning:** If you previously added `dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=wlroots` to your config, remove it. Mango now handles this automatically. + +## Screen Sharing + +To enable screen sharing (OBS, Discord, WebRTC), you need `xdg-desktop-portal-wlr`. + +1. **Install Dependencies** + + `pipewire`, `pipewire-pulse`, `xdg-desktop-portal-wlr` + +2. **Optional: Add to autostart** + + In some situations the portal may not start automatically. You can add this to your autostart script to ensure it launches: + + ```bash + /usr/lib/xdg-desktop-portal-wlr & + ``` + +3. **Restart your computer** to apply changes. + +### Known Issues + +- **Window screen sharing:** Some applications may have issues sharing individual windows. See [#184](https://github.com/mangowm/mango/pull/184) for workarounds. + +- **Screen recording lag:** If you experience stuttering during screen recording, see [xdg-desktop-portal-wlr#351](https://github.com/emersion/xdg-desktop-portal-wlr/issues/351). + +## Clipboard Manager + +Use `cliphist` to manage clipboard history. + +**Dependencies:** `wl-clipboard`, `cliphist`, `wl-clip-persist` + +**Autostart Config:** + +```bash +# Keep clipboard content after app closes +wl-clip-persist --clipboard regular --reconnect-tries 0 & + +# Watch clipboard and store history +wl-paste --type text --watch cliphist store & +``` + +## GNOME Keyring + +If you need to store passwords or secrets (e.g., for VS Code or Minecraft launchers), install `gnome-keyring`. + +**Configuration:** + +Add the following to `~/.config/xdg-desktop-portal/mango-portals.conf`: + +```ini +[preferred] +default=gtk +org.freedesktop.impl.portal.ScreenCast=wlr +org.freedesktop.impl.portal.Screenshot=wlr +org.freedesktop.impl.portal.Secret=gnome-keyring +org.freedesktop.impl.portal.Inhibit=none +``` + +## File Picker (File Selector) + +**Dependencies:** `xdg-desktop-portal`, `xdg-desktop-portal-gtk` + +Reboot your computer once to apply. \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..13c6391 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,101 @@ +--- +title: FAQ +description: Frequently asked questions and troubleshooting. +--- + +### How do I arrange tiled windows with my mouse? + +You can enable the `drag_tile_to_tile` option in your config. This allows you to drag a tiled window onto another to swap them. + +```ini +drag_tile_to_tile=1 +``` + +--- + +### Why is my background blurry or why does blur look wrong? + +Blur applies to the transparent areas of windows. To disable it entirely, set `blur=0`. + +If you are experiencing **performance issues with blur**, make sure `blur_optimized=1` (the default). This caches the wallpaper as the blur background, which is much cheaper on the GPU: + +```ini +blur_optimized=1 +``` + +--- + +### Blur shows my wallpaper instead of the real background content + +This is expected behavior when `blur_optimized=1` (the default). The optimizer caches the wallpaper to reduce GPU load — windows will blur against the wallpaper rather than the actual content stacked beneath them. + +If you want blur to composite against the true background (i.e., show whatever is actually behind the window), set: + +```ini +blur_optimized=0 +``` + +> **Warning:** Disabling `blur_optimized` significantly increases GPU consumption and may cause rendering lag, especially on lower-end hardware. + +--- + +### My games are lagging or stuttering + +Try enabling **SyncObj** timeline support and **Adaptive Sync** (VRR) if your monitor supports it. + +```ini +syncobj_enable=1 +adaptive_sync=1 +``` + +--- + +### My games have high input latency + +You can enable **Tearing** (similar to VSync off). + +First, enable it globally: + +```ini +allow_tearing=1 +``` + +Then force it for your specific game: + +```ini +windowrule=force_tearing:1,title:Counter-Strike 2 +``` + +> **Warning:** Some graphics cards require setting `WLR_DRM_NO_ATOMIC=1` before mango starts for tearing to work. Add it to `/etc/environment` and reboot, or launch mango with `WLR_DRM_NO_ATOMIC=1 mango`. See [Monitors — Tearing](/docs/configuration/monitors#tearing-game-mode) for details. + +--- + +### How do I use pipes `|` in spawn commands? + +The standard `spawn` command does not support shell pipes directly. You must use `spawn_shell` instead. + +```ini +bind=SUPER,P,spawn_shell,echo "hello" | rofi -dmenu +``` + +--- + +### Certain key combinations do not work on my keyboard layout. + +`bind` automatically converts keysym to keycode, which is compatible with most layouts but can sometimes be imprecise. If a key combination is not triggering, use the **keycode** directly instead of the key name. + +Run `wev` and press the key to find its keycode, then use it in your bind: + +```ini +# Instead of: +bind=ALT,q,killclient + +# Use the keycode (e.g., code:24 = q on most layouts): +bind=ALT,code:24,killclient +``` + +You can also use `binds` (the `s` flag) to match by keysym instead of keycode: + +```ini +binds=ALT,q,killclient +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f4848cf --- /dev/null +++ b/docs/index.md @@ -0,0 +1,42 @@ +--- +title: Introduction +description: A lightweight and feature-rich Wayland compositor based on dwl. +--- + + +**mango** is a Wayland compositor based on [dwl](https://codeberg.org/dwl/dwl/). It aims to be as lightweight as `dwl` and can be built completely within a few seconds, without compromising on functionality. + +> **Philosophy:** **Lightweight & Fast**: mango is designed to be minimal yet functional. It compiles in seconds and offers a robust set of features out of the box. + +## Feature Highlights + +Beyond basic window management, mangowm provides a rich set of features designed for a modern Wayland experience. + +- **[Animations](/docs/visuals/animations)** — Smooth, customizable animations for opening, moving, closing windows and tag switching. +- **[Layouts](/docs/window-management/layouts)** — Supports Scroller, Master-Stack, Monocle, Grid, Deck, and more, with per-tag layouts. +- **[Visual Effects](/docs/visuals/effects)** — Built-in blur, shadows, corner radius, and opacity effects powered by scenefx. +- **[IPC & Scripting](/docs/ipc)** — Control the compositor externally with robust IPC support for custom scripts and widgets. + +## Additional Features + +- **XWayland Support** — Excellent compatibility for legacy X11 applications. +- **Tag System** — Uses tags instead of workspaces, allowing separate window layouts for each tag. +- **Input Methods** — Great support for text input v2/v3 (Fcitx5, IBus). +- **Window States** — Rich states including swallow, minimize, maximize, fullscreen, and overlay. +- **Hot-Reload Config** — Simple external configuration that supports hot-reloading without restarting. +- **Scratchpads** — Support for both Sway-like and named scratchpads. + +## Community + +- **[Join the mangowm Discord](https://discord.gg/CPjbDxesh5)** — Chat with the community, get support, share your setup, and stay updated with the latest mangowm news. +- **[Join the GitHub Discussions](https://github.com/mangowm/mango/discussions)** — Ask questions, request features, report issues, or share ideas directly with contributors and other users. + +## Acknowledgements + +This project is built upon the hard work of several open-source projects: + +- **[wlroots](https://gitlab.freedesktop.org/wlroots/wlroots)** — Implementation of the Wayland protocol. +- **[owl](https://github.com/dqrk0jeste/owl)** — Basal window animation reference. +- **[dwl](https://codeberg.org/dwl/dwl)** — Basal dwl features. +- **[sway](https://github.com/swaywm/sway)** — Sample implementation of the Wayland protocol. +- **[scenefx](https://github.com/wlrfx/scenefx)** — Library to simplify adding window effects. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..1297eaf --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,231 @@ +--- +title: Installation +description: Install mangowm on Arch, Fedora, Gentoo, Guix System, NixOS, PikaOS, or build from source. +--- + +## Package Installation + +mangowm is available as a pre-built package on several distributions. Choose your distribution below. + +--- + +### Arch Linux + +mangowm is available in the **Arch User Repository (AUR)**. + +You can install it using an AUR helper like `yay` or `paru`: + +```bash +yay -S mangowm-git +``` + +> **Tip:** This package pulls the latest git version, ensuring you have the newest features and fixes. + +--- + +### Fedora + +The package is in the third-party **Terra repository**. First, add the Terra Repository. + +> **Warning:** Both commands require root privileges. Use `sudo` if needed. + +```bash +dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release +``` + +Then, install the package: + +```bash +dnf install mangowm +``` + +--- + +### Gentoo + +The package is hosted in the community-maintained **GURU** repository. + +1. **Add the GURU repository** + ```bash + emerge --ask --verbose eselect-repository + eselect repository enable guru + emerge --sync guru + ``` + +2. **Unmask packages** + Add the required packages to your `package.accept_keywords` file: + - `gui-libs/scenefx` + - `gui-wm/mangowm` + +3. **Install mango** + ```bash + emerge --ask --verbose gui-wm/mangowm + ``` + +--- + +### Guix System + +The package definition is described in the source repository. + +1. **Add mango channel** + Add to `$HOME/.config/guix/channels.scm`: + ```scheme + (cons (channel + (name 'mangowm) + (url "https://github.com/mangowm/mango.git") + (branch "main")) + %default-channels) + ``` + +2. **Install** + After running `guix pull`, you can install mangowm: + ```bash + guix install mangowm + ``` + + Or add it to your system configuration using the mangowm module: + ```scheme + (use-modules (mangowm)) + + (packages (cons* + mangowm-git + ... ;; Other packages + %base-packages)) + ``` + +> **Tip:** For more information, see the [Guix System documentation](https://guix.gnu.org/manual/devel/en/html_node/Channels.html). + +--- + +### NixOS + +The repository provides a Flake with a NixOS module. + +1. **Add flake input** + ```nix + # flake.nix + { + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + mangowm = { + url = "github:mangowm/mango"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + # other inputs ... + }; + } + ``` + +2. **Import the NixOS module** + + **Option A — Import in `configuration.nix`:** + ```nix + # configuration.nix (or any other file that you import) + {inputs, ...}: { + imports = [ + inputs.mangowm.nixosModules.mango + # .. other imports ... + ]; + + # ... + } + ``` + + **Option B — Import directly in flake:** + ```nix + # flake.nix + { + # ... + + outputs = { self, nixpkgs, mangowm, ...}@inputs: let + inherit (nixpkgs) lib; + # ... + in { + nixosConfigurations.YourHostName = lib.nixosSystem { + modules = [ + mangowm.nixosModules.mango # or inputs.mangowm.nixosModules.mango + # other imports ... + ]; + }; + } + } + ``` + +3. **Enable the module** + ```nix + # configuration.nix (or any other file that you import) + { + programs.mango.enable = true; + } + ``` + +4. **Extra options** + - `programs.mango.package` — the mango package to use, allows usage of custom mango drvs + - `programs.mango.addLoginEntry` (default: `true`) — adds login entry to the display manager + +--- + +### PikaOS + +mangowm is available in the **PikaOS package repository**. + +You can install it using the `pikman` package manager: + +```bash +pikman install mangowc +``` + +--- + +## Building from Source + +If your distribution isn't listed above, or you want the latest unreleased changes, you can build mangowm from source. + +> **Info:** Ensure the following dependencies are installed before proceeding: +> - `glibc` +> - `wayland` +> - `wayland-protocols` +> - `libinput` +> - `libdrm` +> - `libxkbcommon` +> - `pixman` +> - `git` +> - `meson` +> - `ninja` +> - `libdisplay-info` +> - `libliftoff` +> - `hwdata` +> - `seatd` +> - `pcre2` +> - `xorg-xwayland` +> - `libxcb` + +You will need to build `wlroots` and `scenefx` manually as well. + +1. **Build wlroots** + Clone and install the specific version required (check README for latest version). + ```bash + git clone -b 0.19.2 https://gitlab.freedesktop.org/wlroots/wlroots.git + cd wlroots + meson build -Dprefix=/usr + sudo ninja -C build install + ``` + +2. **Build scenefx** + This library handles the visual effects. + ```bash + git clone -b 0.4.1 https://github.com/wlrfx/scenefx.git + cd scenefx + meson build -Dprefix=/usr + sudo ninja -C build install + ``` + +3. **Build mangowm** + Finally, compile the compositor itself. + ```bash + git clone https://github.com/mangowm/mango.git + cd mango + meson build -Dprefix=/usr + sudo ninja -C build install + ``` diff --git a/docs/ipc.md b/docs/ipc.md new file mode 100644 index 0000000..72beefb --- /dev/null +++ b/docs/ipc.md @@ -0,0 +1,154 @@ +--- +title: IPC +description: Control mangowm programmatically using mmsg. +--- + +## Introduction + +mangowm includes a powerful IPC (Inter-Process Communication) tool called `mmsg`. This allows you to query the window manager's state, watch for events, and execute commands from external scripts. + +## Basic Usage + +The general syntax for `mmsg` is: + +```bash +mmsg [-OTLq] +mmsg [-o ] -s [-t ] [-l ] [-c ] [-d ,,,,,] +mmsg [-o ] (-g | -w) [-OotlcvmfxekbA] +``` + +### Options + +| Flag | Description | +| :--- | :--- | +| `-q` | Quit mangowm. | +| `-g` | **Get** values (tags, layout, focused client). | +| `-s` | **Set** values (switch tags, layouts). | +| `-w` | **Watch** mode (streams events). | +| `-O` | Get all output (monitor) information. | +| `-T` | Get number of tags. | +| `-L` | Get all available layouts. | +| `-o` | Select output (monitor). | +| `-t` | Get/set selected tags (set with `[+-^.]`). | +| `-l` | Get/set current layout. | +| `-c` | Get title and appid of focused client. | +| `-v` | Get visibility of statusbar. | +| `-m` | Get fullscreen status. | +| `-f` | Get floating status. | +| `-d` | **Dispatch** an internal command. | +| `-x` | Get focused client geometry. | +| `-e` | Get the name of the last focused layer. | +| `-k` | Get current keyboard layout. | +| `-b` | Get current keybind mode. | +| `-A` | Get scale factor of monitor. | + +## Examples + +### Tag Management + +You can perform arithmetic on tags using the `-t` flag with `-s` (set). + +```bash +# Switch to Tag 1 +mmsg -t 1 + +# Add Tag 2 to current view (Multiview) +mmsg -s -t 2+ + +# Remove Tag 2 from current view +mmsg -s -t 2- + +# Toggle Tag 2 +mmsg -s -t 2^ +``` + +### Layouts + +Switch layouts programmatically. Layout codes: `S` (Scroller), `T` (Tile), `G` (Grid), `M` (Monocle), `K` (Deck), `CT` (Center Tile), `RT` (Right Tile), `VS` (Vertical Scroller), `VT` (Vertical Tile), `VG` (Vertical Grid), `VK` (Vertical Deck), `TG` (TGMix). + +```bash +# Switch to Scroller +mmsg -l "S" + +# Switch to Tile +mmsg -l "T" +``` + +### Dispatching Commands + +Any command available in `config.conf` keybindings can be run via IPC. + +```bash +# Close the focused window +mmsg -d killclient + +# Resize window by +10 width +mmsg -d resizewin,+10,0 + +# Toggle fullscreen +mmsg -d togglefullscreen + +# Disable a monitor power +mmsg -d disable_monitor,eDP-1 +``` + +### Monitoring & Status + +Use `-g` or `-w` to build custom status bars or automation scripts. + +```bash +# Watch for all message changes +mmsg -w + +# Get all messages without watch +mmsg -g + +# Watch focused client appid and title +mmsg -w -c + +# Get all available outputs +mmsg -O + +# Get all tags message +mmsg -g -t + +# Get current focused client message +mmsg -g -c + +# Get current keyboard layout +mmsg -g -k + +# Get current keybind mode +mmsg -g -b + +# Get scale factor of current monitor +mmsg -g -A +``` + +#### Tag Message Format + +- State: 0 → none, 1 → active, 2 → urgent + +Example output: + +| Monitor | Tag Number | Tag State | Clients in Tag | Focused Client | +|---------|------------|-----------|----------------|----------------| +| eDP-1 | tag 2 | 0 | 1 | 0 | + +| Monitor | occupied tags mask | active tags mask | urgent tags mask | +|---------|--------------------|------------------|------------------| +| eDP-1 | 14 | 6 | 0 | + +## Virtual Monitors + +You can create headless outputs for screen mirroring or remote desktop access (e.g., Sunshine/Moonlight). + +```bash +# Create a virtual output +mmsg -d create_virtual_output + +# Configure it (set resolution) +wlr-randr --output HEADLESS-1 --pos 1920,0 --mode 1920x1080@60Hz + +# Destroy all virtual outputs +mmsg -d destroy_all_virtual_output \ No newline at end of file diff --git a/docs/meta.json b/docs/meta.json new file mode 100644 index 0000000..f8aac0c --- /dev/null +++ b/docs/meta.json @@ -0,0 +1,14 @@ +{ + "title": "mangowm", + "pages": [ + "index", + "installation", + "quick-start", + "configuration", + "visuals", + "window-management", + "bindings", + "ipc", + "faq" + ] +} diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..85f67cc --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,88 @@ +--- +title: Quick Start +description: Basic configuration and first steps with mangowm. +--- + +Now that you have mangowm installed, let's get your environment set up. + +## Initial Setup + +1. **Create Configuration Directory** + + mangowm looks for configuration files in `~/.config/mango/`. + + ```bash + mkdir -p ~/.config/mango + ``` + +2. **Copy Default Config** + + A default configuration file is provided at `/etc/mango/config.conf`. Copy it to your local directory to start customizing. + + ```bash + cp /etc/mango/config.conf ~/.config/mango/config.conf + ``` + +3. **Launch mangowm** + + You can now start the compositor from your TTY. + + ```bash + mango + ``` + + Optional: To specify a custom config file path: + + ```bash + mango -c /path/to/your/config.conf + ``` + +## Essential Keybindings + +mangowm uses the following keybinds by default: + +| Key Combination | Action | +| :--- | :--- | +| `Alt` + `Return` | Open Terminal (defaults to `foot`) | +| `Alt` + `Space` | Open Launcher (defaults to `rofi`) | +| `Alt` + `Q` | Close (Kill) the active window | +| `Super` + `M` | Quit mangowm | +| `Super` + `F` | Toggle Fullscreen | +| `Alt` + `Arrow Keys` | Move focus (Left, Right, Up, Down) | +| `Ctrl` + `1-9` | Switch to Tag 1-9 | +| `Alt` + `1-9` | Move window to Tag 1-9 | + +> **Warning:** Some default bindings rely on specific tools like `foot` (terminal) and `rofi` (launcher). Ensure you have them installed or update your `config.conf` to use your preferred alternatives. + +## Recommended Tools + +To get a fully functional desktop experience, we recommend installing the following components: + +| Category | Recommended Tools | +| :--- | :--- | +| Application Launcher | rofi, bemenu, wmenu, fuzzel | +| Terminal Emulator | foot, wezterm, alacritty, kitty, ghostty | +| Status Bar | waybar, eww, quickshell, ags | +| Desktop Shell | Noctalia, DankMaterialShell | +| Wallpaper Setup | swww, swaybg | +| Notification Daemon | swaync, dunst, mako | +| Desktop Portal | xdg-desktop-portal, xdg-desktop-portal-wlr, xdg-desktop-portal-gtk | +| Clipboard | wl-clipboard, wl-clip-persist, cliphist | +| Gamma Control / Night Light | wlsunset, gammastep | +| Miscellaneous | xfce-polkit, wlogout | + +## Example Configuration + +Check out the [example configuration](https://github.com/DreamMaoMao/mango-config) by the creator of mangowm, including complete setups for mangowm, Waybar, Rofi, and more. + +```bash +git clone https://github.com/DreamMaoMao/mango-config.git ~/.config/mango +``` + +## Next Steps + +Now that you are up and running, dive deeper into customizing mangowm: + +- [Configure Monitors](/docs/configuration/monitors) — Set up resolution, scaling, and multi-monitor layouts. +- [Window Rules](/docs/window-management/rules#window-rules) — Define how specific applications should behave. +- [Appearance](/docs/visuals/theming) — Customize colors, borders, gaps, and effects. diff --git a/docs/visuals/animations.md b/docs/visuals/animations.md new file mode 100644 index 0000000..b4b8881 --- /dev/null +++ b/docs/visuals/animations.md @@ -0,0 +1,108 @@ +--- +title: Animations +description: Configure smooth transitions for windows and layers. +--- + +## Enabling Animations + +mangowm supports animations for both standard windows and layer shell surfaces (like bars and notifications). + +```ini +animations=1 +layer_animations=1 +``` + +## Animation Types + +You can define different animation styles for opening and closing windows and layer surfaces. + +Available types: `slide`, `zoom`, `fade`, `none`. + +```ini +animation_type_open=zoom +animation_type_close=slide +layer_animation_type_open=slide +layer_animation_type_close=slide +``` + +## Fade Settings + +Control the fade-in and fade-out effects for animations. + +```ini +animation_fade_in=1 +animation_fade_out=1 +fadein_begin_opacity=0.5 +fadeout_begin_opacity=0.5 +``` + +- `animation_fade_in` — Enable fade-in effect (0: disable, 1: enable) +- `animation_fade_out` — Enable fade-out effect (0: disable, 1: enable) +- `fadein_begin_opacity` — Starting opacity for fade-in animations (0.0–1.0) +- `fadeout_begin_opacity` — Starting opacity for fade-out animations (0.0–1.0) + +## Zoom Settings + +Adjust the zoom ratios for zoom animations. + +```ini +zoom_initial_ratio=0.3 +zoom_end_ratio=0.8 +``` + +- `zoom_initial_ratio` — Initial zoom ratio +- `zoom_end_ratio` — End zoom ratio + +## Durations + +Control the speed of animations (in milliseconds). + +| Setting | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `animation_duration_move` | integer | `500` | Move animation duration (ms) | +| `animation_duration_open` | integer | `400` | Open animation duration (ms) | +| `animation_duration_tag` | integer | `300` | Tag animation duration (ms) | +| `animation_duration_close` | integer | `300` | Close animation duration (ms) | +| `animation_duration_focus` | integer | `0` | Focus change (opacity transition) animation duration (ms) | + +```ini +animation_duration_move=500 +animation_duration_open=400 +animation_duration_tag=300 +animation_duration_close=300 +animation_duration_focus=0 +``` + +## Custom Bezier Curves + +Bezier curves determine the "feel" of an animation (e.g., linear vs. bouncy). The format is `x1,y1,x2,y2`. + +You can visualize and generate curve values using online tools like [cssportal.com](https://www.cssportal.com/css-cubic-bezier-generator/) or [easings.net](https://easings.net). + +| Setting | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `animation_curve_open` | string | `0.46,1.0,0.29,0.99` | Open animation bezier curve | +| `animation_curve_move` | string | `0.46,1.0,0.29,0.99` | Move animation bezier curve | +| `animation_curve_tag` | string | `0.46,1.0,0.29,0.99` | Tag animation bezier curve | +| `animation_curve_close` | string | `0.46,1.0,0.29,0.99` | Close animation bezier curve | +| `animation_curve_focus` | string | `0.46,1.0,0.29,0.99` | Focus change (opacity transition) animation bezier curve | +| `animation_curve_opafadein` | string | `0.46,1.0,0.29,0.99` | Open opacity animation bezier curve | +| `animation_curve_opafadeout` | string | `0.5,0.5,0.5,0.5` | Close opacity animation bezier curve | + +```ini +animation_curve_open=0.46,1.0,0.29,0.99 +animation_curve_move=0.46,1.0,0.29,0.99 +animation_curve_tag=0.46,1.0,0.29,0.99 +animation_curve_close=0.46,1.0,0.29,0.99 +animation_curve_focus=0.46,1.0,0.29,0.99 +animation_curve_opafadein=0.46,1.0,0.29,0.99 +animation_curve_opafadeout=0.5,0.5,0.5,0.5 +``` + +## Tag Animation Direction + +Control the direction of tag switch animations. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `tag_animation_direction` | `1` | Tag animation direction (1: horizontal, 0: vertical) | \ No newline at end of file diff --git a/docs/visuals/effects.md b/docs/visuals/effects.md new file mode 100644 index 0000000..23c1f20 --- /dev/null +++ b/docs/visuals/effects.md @@ -0,0 +1,82 @@ +--- +title: Window Effects +description: Add visual polish with blur, shadows, and opacity. +--- + +## Blur + +Blur creates a frosted glass effect for transparent windows. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `blur` | `0` | Enable blur for windows. | +| `blur_layer` | `0` | Enable blur for layer surfaces (like bars/docks). | +| `blur_optimized` | `1` | Caches the wallpaper and blur background, significantly reducing GPU usage. Disabling it will significantly increase GPU consumption and may cause rendering lag. **Highly recommended.** | +| `blur_params_radius` | `5` | The strength (radius) of the blur. | +| `blur_params_num_passes` | `1` | Number of passes. Higher = smoother but more expensive. | +| `blur_params_noise` | `0.02` | Blur noise level. | +| `blur_params_brightness` | `0.9` | Blur brightness adjustment. | +| `blur_params_contrast` | `0.9` | Blur contrast adjustment. | +| `blur_params_saturation` | `1.2` | Blur saturation adjustment. | + +> **Warning:** Blur has a relatively high impact on performance. If your hardware is limited, it is not recommended to enable it. If you experience lag with blur on, ensure `blur_optimized=1` — disabling it will significantly increase GPU consumption and may cause rendering lag. To disable blur entirely, set `blur=0`. + +--- + +## Shadows + +Drop shadows help distinguish floating windows from the background. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `shadows` | `0` | Enable shadows. | +| `layer_shadows` | `0` | Enable shadows for layer surfaces. | +| `shadow_only_floating` | `1` | Only draw shadows for floating windows (saves performance). | +| `shadows_size` | `10` | Size of the shadow. | +| `shadows_blur` | `15` | Shadow blur amount. | +| `shadows_position_x` | `0` | Shadow X offset. | +| `shadows_position_y` | `0` | Shadow Y offset. | +| `shadowscolor` | `0x000000ff` | Color of the shadow. | + +```ini +# Example shadows configuration +shadows=1 +layer_shadows=1 +shadow_only_floating=1 +shadows_size=12 +shadows_blur=15 +shadows_position_x=0 +shadows_position_y=0 +shadowscolor=0x000000ff +``` + +--- + +## Opacity & Corner Radius + +Control the transparency and roundness of your windows. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `border_radius` | `0` | Window corner radius in pixels. | +| `border_radius_location_default` | `0` | Corner radius location: `0` (all), `1` (top-left), `2` (top-right), `3` (bottom-left), `4` (bottom-right), `5` (closest corner). | +| `no_radius_when_single` | `0` | Disable radius if only one window is visible. | +| `focused_opacity` | `1.0` | Opacity for the active window (0.0 - 1.0). | +| `unfocused_opacity` | `1.0` | Opacity for inactive windows (0.0 - 1.0). | + +```ini +# Window corner radius in pixels +border_radius=0 + +# Corner radius location (0=all, 1=top-left, 2=top-right, 3=bottom-left, 4=bottom-right) +border_radius_location_default=0 + +# Disable radius if only one window is visible +no_radius_when_single=0 + +# Opacity for the active window (0.0 - 1.0) +focused_opacity=1.0 + +# Opacity for inactive windows +unfocused_opacity=1.0 +``` diff --git a/docs/visuals/meta.json b/docs/visuals/meta.json new file mode 100644 index 0000000..58723c4 --- /dev/null +++ b/docs/visuals/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Visuals", + "pages": ["theming", "status-bar", "effects", "animations"] +} diff --git a/docs/visuals/status-bar.md b/docs/visuals/status-bar.md new file mode 100644 index 0000000..f2924e8 --- /dev/null +++ b/docs/visuals/status-bar.md @@ -0,0 +1,141 @@ +--- +title: Status Bar +description: Configure Waybar for mangowm. +--- + +## Module Configuration + +mangowm is compatible with Waybar's `ext/workspaces` module (Wayland standard) or the `dwl/tags` module. We recommend `ext/workspaces` for the best experience. + +> **Tip:** You can also use the `dwl/tags` module, but `ext/workspaces` provides better integration with mangowm's features. The `ext/workspaces` module requires **Waybar > 0.14.0**. + +### `config.jsonc` + +Add the following to your Waybar configuration: + +```jsonc +{ + "modules-left": [ + "ext/workspaces", + "dwl/window" + ], + "ext/workspaces": { + "format": "{icon}", + "ignore-hidden": true, + "on-click": "activate", + "on-click-right": "deactivate", + "sort-by-id": true + }, + "dwl/window": { + "format": "[{layout}] {title}" + } +} +``` + +## Styling + +You can style the tags using standard CSS in `style.css`. + +### `style.css` + +```css +#workspaces { + border-radius: 4px; + border-width: 2px; + border-style: solid; + border-color: #c9b890; + margin-left: 4px; + padding-left: 10px; + padding-right: 6px; + background: rgba(40, 40, 40, 0.76); +} + +#workspaces button { + border: none; + background: none; + box-shadow: inherit; + text-shadow: inherit; + color: #ddca9e; + padding: 1px; + padding-left: 1px; + padding-right: 1px; + margin-right: 2px; + margin-left: 2px; +} + +#workspaces button.hidden { + color: #9e906f; + background-color: transparent; +} + +#workspaces button.visible { + color: #ddca9e; +} + +#workspaces button:hover { + color: #d79921; +} + +#workspaces button.active { + background-color: #ddca9e; + color: #282828; + margin-top: 5px; + margin-bottom: 5px; + padding-top: 1px; + padding-bottom: 0px; + border-radius: 3px; +} + +#workspaces button.urgent { + background-color: #ef5e5e; + color: #282828; + margin-top: 5px; + margin-bottom: 5px; + padding-top: 1px; + padding-bottom: 0px; + border-radius: 3px; +} + +#tags { + background-color: transparent; +} + +#tags button { + background-color: #fff; + color: #a585cd; +} + +#tags button:not(.occupied):not(.focused) { + font-size: 0; + min-width: 0; + min-height: 0; + margin: -17px; + padding: 0; + color: transparent; + background-color: transparent; +} + +#tags button.occupied { + background-color: #fff; + color: #cdc885; +} + +#tags button.focused { + background-color: rgb(186, 142, 213); + color: #fff; +} + +#tags button.urgent { + background: rgb(171, 101, 101); + color: #fff; +} + +#window { + background-color: rgb(237, 196, 147); + color: rgb(63, 37, 5); +} +``` + +## Complete Configuration Example + +> **Tip:** You can find a complete Waybar configuration for mangowm at [waybar-config](https://github.com/DreamMaoMao/waybar-config). \ No newline at end of file diff --git a/docs/visuals/theming.md b/docs/visuals/theming.md new file mode 100644 index 0000000..789ce47 --- /dev/null +++ b/docs/visuals/theming.md @@ -0,0 +1,59 @@ +--- +title: Theming +description: Customize the visual appearance of borders, colors, and the cursor. +--- + +## Dimensions + +Control the sizing of window borders and gaps. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `borderpx` | `4` | Border width in pixels. | +| `gappih` | `5` | Horizontal inner gap (between windows). | +| `gappiv` | `5` | Vertical inner gap. | +| `gappoh` | `10` | Horizontal outer gap (between windows and screen edges). | +| `gappov` | `10` | Vertical outer gap. | + +## Colors + +Colors are defined in `0xRRGGBBAA` hex format. + +```ini +# Background color of the root window +rootcolor=0x323232ff + +# Inactive window border +bordercolor=0x444444ff + +# Active window border +focuscolor=0xc66b25ff + +# Urgent window border (alerts) +urgentcolor=0xad401fff +``` + +### State-Specific Colors + +You can also color-code windows based on their state: + +| State | Config Key | Default Color | +| :--- | :--- | :--- | +| Maximized | `maximizescreencolor` | `0x89aa61ff` | +| Scratchpad | `scratchpadcolor` | `0x516c93ff` | +| Global | `globalcolor` | `0xb153a7ff` | +| Overlay | `overlaycolor` | `0x14a57cff` | + +> **Tip:** For scratchpad window sizing, see [Scratchpad](/docs/window-management/scratchpad) configuration. + +## Cursor Theme + +Set the size and theme of your mouse cursor. + +```ini +cursor_size=24 +cursor_theme=Adwaita +``` + +> **Tip:** You may also want to set the `XCURSOR_SIZE` environment variable to match: +> `env=XCURSOR_SIZE,24` diff --git a/docs/window-management/layouts.md b/docs/window-management/layouts.md new file mode 100644 index 0000000..26c05fe --- /dev/null +++ b/docs/window-management/layouts.md @@ -0,0 +1,99 @@ +--- +title: Layouts +description: Configure and switch between different window layouts. +--- + +## Supported Layouts + +mangowm supports a variety of layouts that can be assigned per tag. + +- `tile` +- `scroller` +- `monocle` +- `grid` +- `deck` +- `center_tile` +- `vertical_tile` +- `right_tile` +- `vertical_scroller` +- `vertical_grid` +- `vertical_deck` +- `tgmix` + +--- + +## Scroller Layout + +The Scroller layout positions windows in a scrollable strip, similar to PaperWM. + +### Configuration + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `scroller_structs` | `20` | Width reserved on sides when window ratio is 1. | +| `scroller_default_proportion` | `0.9` | Default width proportion for new windows. | +| `scroller_focus_center` | `0` | Always center the focused window (1 = enable). | +| `scroller_prefer_center` | `0` | Center focused window only if it was outside the view. | +| `scroller_prefer_overspread` | `1` | Allow windows to overspread when there's extra space. | +| `edge_scroller_pointer_focus` | `1` | Focus windows even if partially off-screen. | +| `scroller_proportion_preset` | `0.5,0.8,1.0` | Presets for cycling window widths. | +| `scroller_ignore_proportion_single` | `1` | Ignore proportion adjustments for single windows. | +| `scroller_default_proportion_single` | `1.0` | Default proportion for single windows in scroller. **Requires `scroller_ignore_proportion_single=0` to take effect.** | + +> **Warning:** `scroller_prefer_overspread`, `scroller_focus_center`, and `scroller_prefer_center` interact with each other. Their priority order is: +> +> **scroller_prefer_overspread > scroller_focus_center > scroller_prefer_center** +> +> To ensure a lower-priority setting takes effect, you must set all higher-priority options to `0`. + +```ini +# Example scroller configuration +scroller_structs=20 +scroller_default_proportion=0.9 +scroller_focus_center=0 +scroller_prefer_center=0 +scroller_prefer_overspread=1 +edge_scroller_pointer_focus=1 +scroller_default_proportion_single=1.0 +scroller_proportion_preset=0.5,0.8,1.0 +``` + +--- + +## Master-Stack Layouts + +These settings apply to layouts like `tile` and `center_tile`. + +| Setting | Default | Description | +| :--- | :--- | :--- | +| `new_is_master` | `1` | New windows become the master window. | +| `default_mfact` | `0.55` | The split ratio between master and stack areas. | +| `default_nmaster` | `1` | Number of allowed master windows. | +| `smartgaps` | `0` | Disable gaps when only one window is present. | +| `center_master_overspread` | `0` | (Center Tile) Master spreads across screen if no stack exists. | +| `center_when_single_stack` | `1` | (Center Tile) Center master when only one stack window exists. | + +```ini +# Example master-stack configuration +new_is_master=1 +smartgaps=0 +default_mfact=0.55 +default_nmaster=1 +``` + +--- + +## Switching Layouts + +You can switch layouts dynamically or set a default for specific tags using [Tag Rules](/docs/window-management/rules#tag-rules). + +**Keybinding Examples:** + +```ini +# Cycle through layouts +bind=SUPER,n,switch_layout + +# Set specific layout +bind=SUPER,t,setlayout,tile +bind=SUPER,s,setlayout,scroller +``` diff --git a/docs/window-management/meta.json b/docs/window-management/meta.json new file mode 100644 index 0000000..e0937d1 --- /dev/null +++ b/docs/window-management/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Window Management", + "pages": ["layouts", "rules", "overview", "scratchpad"] +} diff --git a/docs/window-management/overview.md b/docs/window-management/overview.md new file mode 100644 index 0000000..290d613 --- /dev/null +++ b/docs/window-management/overview.md @@ -0,0 +1,36 @@ +--- +title: Overview +description: Configure the overview mode for window navigation. +--- + +## Overview Settings + +| Setting | Type | Default | Description | +| :--- | :--- | :--- | :--- | +| `hotarea_size` | integer | `10` | Hot area size in pixels. | +| `enable_hotarea` | integer | `1` | Enable hot areas (0: disable, 1: enable). | +| `hotarea_corner` | integer | `2` | Hot area corner (0: top-left, 1: top-right, 2: bottom-left, 3: bottom-right). | +| `ov_tab_mode` | integer | `0` | Overview tab mode (0: disable, 1: enable). | +| `overviewgappi` | integer | `5` | Inner gap in overview mode. | +| `overviewgappo` | integer | `30` | Outer gap in overview mode. | + +### Setting Descriptions + +- `enable_hotarea` — Toggles overview when the cursor enters the configured corner. +- `hotarea_size` — Size of the hot area trigger zone in pixels. +- `hotarea_corner` — Corner that triggers the hot area (0: top-left, 1: top-right, 2: bottom-left, 3: bottom-right). +- `ov_tab_mode` — Circles focus through windows in overview; releasing the mod key exits overview. + +### Mouse Interaction in Overview + +When in overview mode: + +- **Left mouse button** — Jump to (focus) a window. +- **Right mouse button** — Close a window. + +To enable this behavior, add the following mouse bindings to your config: + +```ini +mousebind=NONE,btn_left,toggleoverview,1 +mousebind=NONE,btn_right,killclient,0 +``` diff --git a/docs/window-management/rules.md b/docs/window-management/rules.md new file mode 100644 index 0000000..996c172 --- /dev/null +++ b/docs/window-management/rules.md @@ -0,0 +1,249 @@ +--- +title: Rules +description: Define behavior for specific windows, tags, and layers. +--- + +## Window Rules + +Window rules allow you to set specific properties (floating, opacity, size, animations, etc.) for applications based on their `appid` or `title`. You can set all parameters in one line, and if you both set appid and title, the window will only follow the rules when appid and title both match. + +**Format:** + +```ini +windowrule=Parameter:Values,title:Values +windowrule=Parameter:Values,Parameter:Values,appid:Values,title:Values +``` + +### State & Behavior Parameters + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `appid` | string | Any | Match by application ID, supports regex | +| `title` | string | Any | Match by window title, supports regex | +| `isfloating` | integer | `0` / `1` | Force floating state | +| `isfullscreen` | integer | `0` / `1` | Force fullscreen state | +| `isfakefullscreen` | integer | `0` / `1` | Force fake-fullscreen state (window stays constrained) | +| `isglobal` | integer | `0` / `1` | Open as global window (sticky across tags) | +| `isoverlay` | integer | `0` / `1` | Make it always in top layer | +| `isopensilent` | integer | `0` / `1` | Open without focus | +| `istagsilent` | integer | `0` / `1` | Don't focus if client is not in current view tag | +| `force_maximize` | integer | `0` / `1` (default 1) | The state of client default to maximized | +| `ignore_maximize` | integer | `0` / `1` (default 1) | Don't handle maximize request from client | +| `ignore_minimize` | integer | `0` / `1` (default 1) | Don't handle minimize request from client | +| `force_tiled_state` | integer | `0` / `1` | Deceive the window into thinking it is tiling, so it better adheres to assigned dimensions | +| `noopenmaximized` | integer | `0` / `1` | Window does not open as maximized mode | +| `single_scratchpad` | integer | `0` / `1` (default 1) | Only show one out of named scratchpads or the normal scratchpad | +| `allow_shortcuts_inhibit` | integer | `0` / `1` (default 1) | Allow shortcuts to be inhibited by clients | +| `indleinhibit_when_focus` | integer | `0` / `1` (default 0) | Automatically keep idle inhibit active when this window is focused | + +### Geometry & Position + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `width` | integer | 0-9999 | Window width when it becomes a floating window | +| `height` | integer | 0-9999 | Window height when it becomes a floating window | +| `offsetx` | integer | -999-999 | X offset from center (%), 100 is the edge of screen with outer gap | +| `offsety` | integer | -999-999 | Y offset from center (%), 100 is the edge of screen with outer gap | +| `monitor` | string | Any | Assign to monitor by [monitor spec](/docs/configuration/monitors#monitor-spec-format) (name, make, model, or serial) | +| `tags` | integer | 1-9 | Assign to specific tag | +| `no_force_center` | integer | `0` / `1` | Window does not force center | +| `isnosizehint` | integer | `0` / `1` | Don't use min size and max size for size hints | + +### Visuals & Decoration + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `noblur` | integer | `0` / `1` | Window does not have blur effect | +| `isnoborder` | integer | `0` / `1` | Remove window border | +| `isnoshadow` | integer | `0` / `1` | Not apply shadow | +| `isnoradius` | integer | `0` / `1` | Not apply corner radius | +| `isnoanimation` | integer | `0` / `1` | Not apply animation | +| `focused_opacity` | integer | `0` / `1` | Window focused opacity | +| `unfocused_opacity` | integer | `0` / `1` | Window unfocused opacity | +| `allow_csd` | integer | `0` / `1` | Allow client side decoration | + +> **Tip:** For detailed visual effects configuration, see the [Window Effects](/docs/visuals/effects) page for blur, shadows, and opacity settings. + +### Layout & Scroller + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `scroller_proportion` | float | 0.1-1.0 | Set scroller proportion | +| `scroller_proportion_single` | float | 0.1-1.0 | Set scroller auto adjust proportion when it is single window | + +> **Tip:** For comprehensive layout configuration, see the [Layouts](/docs/window-management/layouts) page for all layout options and detailed settings. + +### Animation + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `animation_type_open` | string | zoom, slide, fade, none | Set open animation | +| `animation_type_close` | string | zoom, slide, fade, none | Set close animation | +| `nofadein` | integer | `0` / `1` | Window ignores fade-in animation | +| `nofadeout` | integer | `0` / `1` | Window ignores fade-out animation | + +> **Tip:** For detailed animation configuration, see the [Animations](/docs/visuals/animations) page for available types and settings. + +### Terminal & Swallowing + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `isterm` | integer | `0` / `1` | A new GUI window will replace the isterm window when it is opened | +| `noswallow` | integer | `0` / `1` | The window will not replace the isterm window | + +### Global & Special Windows + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `globalkeybinding` | string | `[mod combination][-][key]` | Global keybinding (only works for Wayland apps) | +| `isunglobal` | integer | `0` / `1` | Open as unmanaged global window (for desktop pets or camera windows) | +| `isnamedscratchpad` | integer | `0` / `1` | 0: disable, 1: named scratchpad | + +> **Tip:** For scratchpad usage, see the [Scratchpad](/docs/window-management/scratchpad) page for detailed configuration examples. + +### Performance & Tearing + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `force_tearing` | integer | `0` / `1` | Set window to tearing state, refer to [Tearing](/docs/configuration/monitors#tearing-game-mode) | + +### Examples + +```ini +# Set specific window size and position +windowrule=width:1000,height:900,appid:yesplaymusic,title:Demons + +# Global keybindings for OBS Studio +windowrule=globalkeybinding:ctrl+alt-o,appid:com.obsproject.Studio +windowrule=globalkeybinding:ctrl+alt+n,appid:com.obsproject.Studio +windowrule=isopensilent:1,appid:com.obsproject.Studio + +# Force tearing for games +windowrule=force_tearing:1,title:vkcube +windowrule=force_tearing:1,title:Counter-Strike 2 + +# Named scratchpad for file manager +windowrule=isnamedscratchpad:1,width:1280,height:800,appid:st-yazi + +# Custom opacity for specific apps +windowrule=focused_opacity:0.8,appid:firefox +windowrule=unfocused_opacity:0.6,appid:foot + +# Disable blur for selection tools +windowrule=noblur:1,appid:slurp + +# Position windows relative to screen center +windowrule=offsetx:20,offsety:-30,width:800,height:600,appid:alacritty + +# Send to specific tag and monitor +windowrule=tags:9,monitor:HDMI-A-1,appid:discord + +# Terminal swallowing setup +windowrule=isterm:1,appid:st +windowrule=noswallow:1,appid:foot + +# Disable client-side decorations +windowrule=allow_csd:1,appid:firefox + +# Unmanaged global window (desktop pets, camera) +windowrule=isunglobal:1,appid:cheese + +# Named scratchpad toggle +bind=alt,h,toggle_named_scratchpad,st-yazi,none,st -c st-yazi -e yazi +``` + +--- + +## Tag Rules + +You can set all parameters in one line. If only `id` is set, the rule is followed when the id matches. If any of `monitor_name`, `monitor_make`, `monitor_model`, or `monitor_serial` are set, the rule is followed only if **all** of the set monitor fields match. + +> **Warning:** Layouts set in tag rules have a higher priority than monitor rule layouts. + +**Format:** + +```ini +tagrule=id:Values,Parameter:Values,Parameter:Values +tagrule=id:Values,monitor_name:eDP-1,Parameter:Values,Parameter:Values +tagrule=id:Values,monitor_make:xxx,monitor_model:xxx,Parameter:Values +``` + +> **Tip:** See [Layouts](/docs/window-management/layouts#supported-layouts) for detailed descriptions of each layout type. + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `id` | integer | 0-9 | Match by tag id, 0 means the ~0 tag | +| `monitor_name` | string | monitor name | Match by monitor name | +| `monitor_make` | string | monitor make | Match by monitor manufacturer | +| `monitor_model` | string | monitor model | Match by monitor model | +| `monitor_serial` | string | monitor serial | Match by monitor serial number | +| `layout_name` | string | layout name | Layout name to set | +| `no_render_border` | integer | `0` / `1` | Disable render border | +| `no_hide` | integer | `0` / `1` | Not hide even if the tag is empty | +| `nmaster` | integer | 0, 99 | Number of master windows | +| `mfact` | float | 0.1–0.9 | Master area factor | + +### Examples + +```ini +# Set layout for specific tags +tagrule=id:1,layout_name:scroller +tagrule=id:2,layout_name:scroller + +# Limit to specific monitor +tagrule=id:1,monitor_name:eDP-1,layout_name:scroller +tagrule=id:2,monitor_name:eDP-1,layout_name:scroller + +# Persistent tags (1-4) with layout assignment +tagrule=id:1,no_hide:1,layout_name:scroller +tagrule=id:2,no_hide:1,layout_name:scroller +tagrule=id:3,monitor_name:eDP-1,no_hide:1,layout_name:scroller +tagrule=id:4,monitor_name:eDP-1,no_hide:1,layout_name:scroller + +# Advanced tag configuration with master layout settings +tagrule=id:5,layout_name:tile,nmaster:2,mfact:0.6 +tagrule=id:6,monitor_name:HDMI-A-1,layout_name:monocle,no_render_border:1 +``` + +> **Tip:** For Waybar configuration with persistent tags, see [Status Bar](/docs/visuals/status-bar) documentation. + +--- + +## Layer Rules + +You can set all parameters in one line. Target "layer shell" surfaces like status bars (`waybar`), launchers (`rofi`), or notification daemons. + +**Format:** + +```ini +layerrule=layer_name:Values,Parameter:Values,Parameter:Values +``` + +> **Tip:** You can use `mmsg -e` to get the last open layer name for debugging. + +| Parameter | Type | Values | Description | +| :--- | :--- | :--- | :--- | +| `layer_name` | string | layer name | Match name of layer, supports regex | +| `animation_type_open` | string | slide, zoom, fade, none | Set open animation | +| `animation_type_close` | string | slide, zoom, fade, none | Set close animation | +| `noblur` | integer | `0` / `1` | Disable blur | +| `noanim` | integer | `0` / `1` | Disable layer animation | +| `noshadow` | integer | `0` / `1` | Disable layer shadow | + +> **Tip:** For animation types, see [Animations](/docs/visuals/animations#animation-types). For visual effects, see [Window Effects](/docs/visuals/effects). + +### Examples + +```ini +# No blur or animation for slurp selection layer (avoids occlusion and ghosting in screenshots) +layerrule=noanim:1,noblur:1,layer_name:selection + +# Zoom animation for Rofi with multiple parameters +layerrule=animation_type_open:zoom,noanim:0,layer_name:rofi + +# Disable animations and shadows for notification daemon +layerrule=noanim:1,noshadow:1,layer_name:swaync + +# Multiple effects for launcher +layerrule=animation_type_open:slide,animation_type_close:fade,noblur:1,layer_name:wofi +``` diff --git a/docs/window-management/scratchpad.md b/docs/window-management/scratchpad.md new file mode 100644 index 0000000..398182f --- /dev/null +++ b/docs/window-management/scratchpad.md @@ -0,0 +1,73 @@ +--- +title: Scratchpad +description: Manage hidden "scratchpad" windows for quick access. +--- + +mangowm supports two types of scratchpads: the standard pool (Sway-like) and named scratchpads. + +## Standard Scratchpad + +Any window can be sent to the "scratchpad" pile, which hides it. You can then cycle through them. + +**Keybindings:** + +```ini +# Send current window to scratchpad +bind=SUPER,i,minimized + +# Toggle (show/hide) the scratchpad +bind=ALT,z,toggle_scratchpad + +# Retrieve window from scratchpad (restore) +bind=SUPER+SHIFT,i,restore_minimized +``` + +--- + +## Named Scratchpad + +Named scratchpads are bound to specific keys and applications. When triggered, mangowm will either launch the app (if not running) or toggle its visibility. + +**1. Define the Window Rule** + +You must identify the app using a unique `appid` or `title` and mark it as a named scratchpad. The application must support setting a custom appid or title at launch. Common examples: + +- `st -c my-appid` — sets the appid +- `kitty -T my-title` — sets the window title +- `foot --app-id my-appid` — sets the appid + +Use `none` as a placeholder when you only want to match by one field. + +```ini +# Match by appid +windowrule=isnamedscratchpad:1,width:1280,height:800,appid:st-yazi + +# Match by title +windowrule=isnamedscratchpad:1,width:1000,height:700,title:kitty-scratch +``` + +**2. Bind the Toggle Key** + +Format: `bind=MOD,KEY,toggle_named_scratchpad,appid,title,command` + +Use `none` for whichever field you are not matching on. + +```ini +# Match by appid: launch 'st' with class 'st-yazi' running 'yazi' +bind=alt,h,toggle_named_scratchpad,st-yazi,none,st -c st-yazi -e yazi + +# Match by title: launch 'kitty' with window title 'kitty-scratch' +bind=alt,k,toggle_named_scratchpad,none,kitty-scratch,kitty -T kitty-scratch +``` + +--- + +## Appearance + +You can customize the size of scratchpad windows relative to the screen. + +```ini +scratchpad_width_ratio=0.8 +scratchpad_height_ratio=0.9 +scratchpadcolor=0x516c93ff +```