From 318300ef79bfab458ad09e6781cec3ddf0041934 Mon Sep 17 00:00:00 2001 From: Steve Cliff Date: Thu, 20 Aug 2026 08:50:40 +0100 Subject: [PATCH] first commit --- README.md | 305 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b4d1057 --- /dev/null +++ b/README.md @@ -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).