# 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).
