fancywin/README.md

# 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. A console window remains open while
FancyWin is running and shows its status, detected monitors, configuration
reloads, and any errors. Closing that console stops FancyWin.

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

overlay:
  enabled: true
  color: "#00AEEF"
  opacity: 90
  border_width: 3

layouts:
  - monitor: "*"
    zones:
      - name: left
        x: 0
        y: 0
        width: 50
        height: 100
      - name: right
        x: 50
        y: 0
        width: 50
        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 error is printed and the previous valid configuration stays in
use.

### 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. |
| `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: 3
```

- `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.

### Monitor-specific layouts

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:
  - monitor: "*"
    zones:
      - { name: left,  x: 0,  y: 0, width: 50, height: 100 }
      - { name: right, x: 50, y: 0, width: 50, height: 100 }

  - monitor: '\\.\DISPLAY2'
    zones:
      - { name: main, x: 0,  y: 0, width: 70, height: 100 }
      - { name: side, x: 70, y: 0, width: 30, height: 100 }
```

Only one layout may be declared for each monitor name.

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

# Print detailed window-move and snapping 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 closes immediately

Open PowerShell in the FancyWin directory and run:

```powershell
.\fancywin.exe
```

The console will remain visible so you can read the error. Common causes are a
missing `fancywin.yaml`, invalid YAML, a shortcut conflict, or another running
copy of FancyWin.

For detailed diagnostics, stop FancyWin and restart it with:

```powershell
.\fancywin.exe -debug
```

The debug output 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 and check the console. FancyWin keeps using the last
valid configuration when a new edit cannot be parsed or validated.

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