first commit
This commit is contained in:
Steve Cliff
@@ -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).
|
||||
Reference in New Issue
Block a user