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

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

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:

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

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 }

Changing active_layout to equal-thirds 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:

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:

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:

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

.\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:

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