steve/fancywin
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 2 Wiki Activity

first commit

Browse Source
This commit is contained in:
Steve Cliff
2026-08-20 08:50:40 +01:00
commit 318300ef79
1 changed files with 305 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+305
View File
@@ -0,0 +1,305 @@
# 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.
- 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 window-moving backend rather than a complete PowerToys
replacement. It does not display a zone overlay or include a visual layout
editor. It also 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
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. |
| `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 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.
## 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).