# FancyWin user guide FancyWin is a portable window-zone manager for Windows 11. It lets you arrange windows into layouts defined in a YAML file, using either Shift-dragging or global keyboard shortcuts. There is no installer. FancyWin does not add a Windows service, driver, Start menu entry, or registry settings. ## What FancyWin does - Snaps a dragged window into the zone beneath the mouse pointer. - Shows a transparent, click-through guide with every zone's outline and name while Shift-dragging. - Moves the focused window between zones with keyboard shortcuts. - Supports different layouts for different monitors. - Uses percentages, so layouts adapt to resolution, orientation, display scaling, and the space occupied by the taskbar. - Reloads its configuration automatically after the YAML file changes. - Lets you exclude applications that should never be moved. FancyWin is a focused window manager rather than a complete PowerToys replacement. It does not include a visual layout editor and does not currently remember application positions, combine multiple zones, or assign layouts per virtual desktop. ## Getting started You need these two files in the same directory: - `fancywin.exe` - `fancywin.yaml` The supplied [example configuration](fancywin.example.yaml) can be copied or renamed to `fancywin.yaml`. Double-click `fancywin.exe` to start it. FancyWin runs quietly in the Windows notification area without leaving a console or taskbar window open. Hover over its tray icon to see the active layout. Right-click the icon to select any configured layout or choose `Exit` to stop FancyWin. The active layout is marked with a check. Run `fancywin.exe --debug` from PowerShell when you want a console showing status, detected monitors, drag diagnostics, configuration reloads, and errors. Only one copy of FancyWin can run at a time. ## Moving windows ### With the mouse 1. Drag a window by its title bar. 2. Move the pointer into the desired zone. 3. Keep Shift held while releasing the mouse button. The window is resized and moved into that zone. The gap configured for the zone does not create a dead area for the pointer. Mouse snapping can be disabled by setting `shift_drag: false`. ### With the keyboard Keyboard shortcuts operate on the currently focused window. The example configuration provides: | Shortcut | Result | | --- | --- | | `Win+Alt+Left` | Move to the previous zone | | `Win+Alt+Right` | Move to the next zone | | `Win+Alt+1` | Move directly to zone 1 | | `Win+Alt+2` | Move directly to zone 2 | | `Win+Alt+3` | Move directly to zone 3 | Shortcuts can be removed or changed in `fancywin.yaml`. If another application or Windows already owns a shortcut, FancyWin reports the conflict instead of silently ignoring it. ## Configuring layouts FancyWin reads `fancywin.yaml` from the directory containing the executable. Here is a complete two-column configuration: ```yaml version: 1 gap: 8 shift_drag: true active_layout: columns overlay: enabled: true color: "#00AEEF" opacity: 90 border_width: 10 layouts: - name: columns monitor: "*" zones: - name: left x: 0 y: 0 width: 50 height: 100 - name: right x: 50 y: 0 width: 50 height: 100 - name: fullscreen monitor: "*" zones: - name: full x: 0 y: 0 width: 100 height: 100 excluded_apps: - mstsc.exe hotkeys: - keys: "win+alt+left" action: previous_zone - keys: "win+alt+right" action: next_zone - keys: "win+alt+1" action: zone_1 - keys: "win+alt+2" action: zone_2 ``` FancyWin checks the file for unknown fields and invalid values. While it is running, a valid edit takes effect within about two seconds. If an edit is invalid, the previous valid configuration stays in use. Restart with `--debug` to investigate configuration errors. ### General settings | Setting | Meaning | | --- | --- | | `version` | Configuration format. This must currently be `1`. | | `gap` | Inward spacing, in pixels, applied to every edge of every zone. Valid range: `0`–`500`. | | `shift_drag` | Enables or disables mouse snapping when Shift is held at the end of a drag. | | `active_layout` | Name of the layout currently used for snapping and the overlay. | | `overlay` | Controls the transparent zone guide shown during Shift-dragging. | | `layouts` | One or more monitor layouts containing zones. | | `excluded_apps` | Applications FancyWin must not move. May be empty. | | `hotkeys` | Global keyboard shortcuts. May be empty. | ### Zone overlay The overlay appears after a window has begun moving and Shift is held. It shows all zones on the monitor beneath the pointer, using the same gap-adjusted rectangles that windows snap into. Each outline contains the zone's `name`, or `Zone N` when its name is empty. Releasing Shift or the mouse button immediately hides it. ```yaml overlay: enabled: true color: "#00AEEF" opacity: 90 border_width: 10 ``` - `enabled` turns the guide on or off. - `color` is an outline and label color in `#RRGGBB` format. - `opacity` is from `1` to `100` percent. - `border_width` is from `1` to `20` physical pixels. The guide is transparent between its outlines, does not receive mouse input, does not take keyboard focus, and does not appear in Alt+Tab. ### Zone coordinates Each zone is a rectangle described as percentages of the monitor's usable work area: - `x`: distance from the left edge - `y`: distance from the top edge - `width`: zone width - `height`: zone height - `name`: a descriptive label for people reading the file Coordinates begin at `0`, and the right and bottom edges may not exceed `100`. Width and height must be greater than zero. For example, the bottom-right quarter is: ```yaml - name: bottom-right x: 50 y: 50 width: 50 height: 50 ``` Zones may overlap. If the pointer is inside more than one zone, the first matching zone listed in the file is selected. ### Named layouts and monitor-specific variants Every entry under `layouts` has a `name`. Set `active_layout` to that name to choose which layout FancyWin uses: ```yaml active_layout: focus layouts: - name: focus monitor: "*" zones: - { name: left, x: 0, y: 0, width: 25, height: 100 } - { name: middle, x: 25, y: 0, width: 50, height: 100 } - { name: right, x: 75, y: 0, width: 25, height: 100 } - name: equal-thirds monitor: "*" zones: - { name: left, x: 0, y: 0, width: 33.333, height: 100 } - { name: middle, x: 33.333, y: 0, width: 33.334, height: 100 } - { name: right, x: 66.667, y: 0, width: 33.333, height: 100 } ``` Select a name from the tray menu to switch immediately. FancyWin also updates `active_layout` in the YAML so the choice survives a restart. Alternatively, changing `active_layout` by hand is applied automatically within about two seconds; FancyWin does not need to be restarted. Use `monitor: "*"` as the fallback layout for every display that does not have a specific entry. At startup, FancyWin prints detected device names such as `\\.\DISPLAY1` and `\\.\DISPLAY2`. A specific monitor layout can override the fallback: ```yaml layouts: - name: focus monitor: "*" zones: - { name: left, x: 0, y: 0, width: 50, height: 100 } - { name: right, x: 50, y: 0, width: 50, height: 100 } - name: focus monitor: '\\.\DISPLAY2' zones: - { name: main, x: 0, y: 0, width: 70, height: 100 } - { name: side, x: 70, y: 0, width: 30, height: 100 } ``` The monitor-specific entry must use the same layout name as its fallback. Only one entry may be declared for each combination of layout name and monitor name. Names and monitor matching are not case-sensitive. Older configurations containing no `active_layout` and no layout names are loaded as one backwards-compatible layout named `default`. ### Hotkeys Each hotkey has a `keys` combination and an `action`. Available modifiers are `win`, `alt`, `ctrl`, and `shift`. Combine one or more modifiers with exactly one of the following: - A letter from `a` to `z` - A digit from `0` to `9` - `left`, `right`, `up`, or `down` - `pageup` or `pagedown` (also accepted as `pgup` and `pgdn`) Available actions are: | Action | Result | | --- | --- | | `next_zone` | Move to the next zone, wrapping at the end. | | `previous_zone` | Move to the previous zone, wrapping at the beginning. | | `zone_N` | Move directly to zone number N; numbering starts at 1. | If `zone_N` refers to a zone that does not exist in the focused window's monitor layout, nothing is moved. ### Excluding applications Use `excluded_apps` for programs that should retain their own positioning: ```yaml excluded_apps: - mstsc.exe - games ``` An entry containing a filename extension, such as `mstsc.exe`, matches that executable name exactly and is not case-sensitive. An entry without an extension, such as `games`, matches any executable name containing that text. ## Command-line options Run these commands from PowerShell or Command Prompt in the FancyWin directory: ```powershell # Check fancywin.yaml without starting the window manager .\fancywin.exe -check # Use a configuration stored elsewhere .\fancywin.exe -config D:\Portable\Layouts\work.yaml # Print the built-in default configuration .\fancywin.exe -print-default # Print the FancyWin version .\fancywin.exe -version # Keep a console open and print detailed diagnostics .\fancywin.exe -debug ``` `-check` can be combined with `-config` to validate another file. ## Administrator permissions Run FancyWin normally for everyday use. It does not require administrator permissions to move ordinary desktop applications. Windows prevents a normal process from reliably controlling a window belonging to an administrator-mode process. If you need to move an elevated application, FancyWin must also be started as administrator. This lowers the security isolation between FancyWin and other elevated applications, so only do it when necessary. ## Troubleshooting ### FancyWin does not appear to start Open PowerShell in the FancyWin directory and run: ```powershell .\fancywin.exe --debug ``` The console remains attached so you can read errors. Common causes are a missing `fancywin.yaml`, invalid YAML, a shortcut conflict, or another running copy of FancyWin. Debug output also reports whether Windows emitted a move event, whether the window passed filtering, whether Shift was active during the drag, which monitor and zone were selected, and whether Windows accepted the final move request. ### A window does not snap when dragged - Confirm `shift_drag` is `true`. - Keep Shift held until after releasing the mouse button. - Check whether the application is listed under `excluded_apps`. - Confirm the pointer is inside a configured zone. - Some applications use custom window implementations and do not emit the standard Windows move/size events FancyWin relies on. - An administrator-mode application cannot be moved by a normal FancyWin process. ### A keyboard shortcut does nothing - Make sure the intended window is focused. - Check that its monitor has a matching or `*` fallback layout. - Confirm the action refers to a zone that exists on that monitor. - Read the console for shortcut-registration errors. ### A window is slightly larger or smaller than its zone Some applications enforce their own minimum sizes, aspect ratios, or custom window borders. FancyWin compensates for standard Windows 11 invisible resize borders, but it cannot override size rules imposed by the application itself. ### Configuration changes are not applied Wait at least two seconds. FancyWin keeps using the last valid configuration when a new edit cannot be parsed or validated. Restart with `--debug` and repeat the edit to see the exact error. ### The tray icon is missing - Check the notification-area overflow menu behind the upward arrow; Windows may place new icons there automatically. - Start FancyWin with `--debug` and check for a notification-area error. - Only one FancyWin instance may run at a time. - If Windows Explorer restarts, FancyWin automatically adds its icon again. ### A layout is missing from the tray menu - Confirm every layout entry has a non-empty `name`. - Monitor-specific variants sharing the same name intentionally appear as one menu choice. - Check the YAML with `fancywin.exe -check`. - Layouts added while FancyWin is running appear after the configuration reload. ### The zone overlay does not appear - Confirm `overlay.enabled` and `shift_drag` are both `true`. - Begin moving the window before expecting the guide; a stationary Shift-click is intentionally ignored. - Keep Shift held during the drag. - Check the console for `cannot show zone overlay` errors. ## Project relationship FancyWin is an independent implementation and does not contain Microsoft PowerToys source code. PowerToys and FancyZones are Microsoft trademarks. This project is not affiliated with or endorsed by Microsoft. Developer documentation is available in [BUILD.md](BUILD.md).