From ea50dd6d79fa9ff9bbc8b8137a34af456340ae2a Mon Sep 17 00:00:00 2001 From: Gleb Khmyznikov Date: Fri, 13 Jun 2025 16:23:31 +0200 Subject: [PATCH] update fancyzones doc --- doc/devdocs/modules/fancyzones-tools.md | 131 +++++++++++++++ doc/devdocs/modules/fancyzones.md | 150 +++++++++++++++++- doc/devdocs/modules/readme.md | 25 +++ doc/devdocs/readme.md | 1 + .../tools/fancyzones-draw-layout-test.md | 7 - doc/devdocs/tools/fancyzones-hit-test.md | 5 - .../tools/fancyzones-zonable-tester.md | 13 -- doc/devdocs/tools/readme.md | 3 - 8 files changed, 303 insertions(+), 32 deletions(-) create mode 100644 doc/devdocs/modules/fancyzones-tools.md create mode 100644 doc/devdocs/modules/readme.md delete mode 100644 doc/devdocs/tools/fancyzones-draw-layout-test.md delete mode 100644 doc/devdocs/tools/fancyzones-hit-test.md delete mode 100644 doc/devdocs/tools/fancyzones-zonable-tester.md diff --git a/doc/devdocs/modules/fancyzones-tools.md b/doc/devdocs/modules/fancyzones-tools.md new file mode 100644 index 0000000000..29ea00d9eb --- /dev/null +++ b/doc/devdocs/modules/fancyzones-tools.md @@ -0,0 +1,131 @@ +# FancyZones Debugging Tools + +## Overview + +FancyZones has several specialized debugging tools to help diagnose issues with window management, zone detection, and rendering. These tools are designed to isolate and test specific components of the FancyZones functionality. + +## Tools Summary + +| Tool | Purpose | Key Functionality | +|------|---------|-------------------| +| FancyZones_HitTest | Tests zone hit detection | Shows which zone is under cursor with detailed metrics | +| FancyZones_DrawLayoutTest | Tests layout drawing | Renders zone layouts to debug display issues | +| FancyZones_zonable_tester | Tests window zonability | Determines if windows can be placed in zones | +| StylesReportTool | Analyzes window properties | Generates window style reports for debugging | + +## FancyZones_HitTest + +![Image of the FancyZones hit test tool](/doc/images/tools/fancyzones-hit-test.png) + +### Purpose +Tests the FancyZones layout selection logic by displaying a window with zones and highlighting the zone under the mouse cursor. + +### Functionality +- Displays a window with 5 sample zones +- Highlights the zone under the mouse cursor +- Shows metrics used for zone detection in a sidebar +- Helps diagnose issues with zone positioning and hit testing + +### Usage +- Run the tool and move your mouse over the zones +- The currently detected zone will be highlighted +- The sidebar displays metrics used for determining the active zone +- Useful for debugging hit detection, positioning, and DPI issues + +## FancyZones_DrawLayoutTest + +### Purpose +Debug issues related to the drawing of zone layouts on screen. + +### Functionality +- Simulates zone layouts (currently only column layout supported) +- Tests rendering of zones with different configurations +- Helps diagnose display issues across monitor configurations + +### Usage +- Run the tool +- Press **W** key to toggle zone appearance on the primary screen +- Press **Q** key to exit the application +- The number of zones can be modified in the source code + +### Technical Notes +The application is DPI unaware, meaning it doesn't scale for DPI changes and always assumes a scale factor of 100% (96 DPI). Scaling is automatically performed by the system. + +## FancyZones_zonable_tester + +![Image of the FancyZones zonable tester](/doc/images/tools/fancyzones-zonable-tester.png) + +### Purpose +Tests if the window under the mouse cursor is "zonable" (can be placed in a FancyZones zone). + +### Functionality +- Analyzes the window under the cursor +- Provides detailed window information: + * HWND (window handle) + * Process ID + * HWND of foreground window + * Window style flags + * Extended style flags + * Window class + * Process path + +### Usage +- Run the command-line application +- Hover the mouse over a window to test +- Review the console output for detailed window information +- Check if the window is considered zonable by FancyZones + +### Limitations +Note that this tool may not be fully up-to-date with the latest zonable logic in the main FancyZones codebase. + +## StylesReportTool + +### Purpose +Generates detailed reports about window styles that affect zonability. + +### Functionality +- Creates comprehensive window style reports +- Focuses on style flags that determine if windows can be placed in zones +- Outputs report to "WindowStyles.txt" on the desktop + +### Usage +- Run the tool +- Focus the window you want to analyze +- Press **Ctrl+Alt+S** to generate a report +- Review WindowStyles.txt to understand why a window might not be zonable + +## Debugging Workflow + +For most effective debugging of FancyZones issues: + +1. Use **StylesReportTool** to analyze window properties of problematic windows +2. Use **FancyZones_zonable_tester** to check if specific windows can be zoned +3. Use **FancyZones_draw** for layout rendering issues on different monitors +4. Use **FancyZones_HitTest** for diagnosing zone detection problems + +## Testing Considerations + +When testing FancyZones with these tools, consider: + +- Testing on different Windows versions +- Testing with multiple monitors with different: + * Resolutions + * Scaling settings + * Physical arrangements +- Testing with various window types: + * Standard applications + * Legacy applications + * UWP/WinUI applications + * Administrative windows + * Special windows (like Task Manager) +- Testing various layouts: + * Grid layouts + * Custom layouts + * Overlapping zones + +## Initial Setup Issues + +If encountering JSON token errors on first run: +1. Launch FancyZones Editor through PowerToys Settings UI +2. This initializes required configuration files +3. Direct project execution won't initialize configs properly diff --git a/doc/devdocs/modules/fancyzones.md b/doc/devdocs/modules/fancyzones.md index 61a7ea58fa..47bbbadedf 100644 --- a/doc/devdocs/modules/fancyzones.md +++ b/doc/devdocs/modules/fancyzones.md @@ -1,13 +1,96 @@ -# FancyZones UI tests +# FancyZones + +## Overview + +FancyZones is a window manager utility that allows users to create custom layouts for organizing windows on their screen. + +## Architecture Overview + +FancyZones consists of several interconnected components: + +### Interface Layer: FancyZonesModuleInterface +- Exposes interface between FancyZones and the Runner +- Handles communication and configuration exchange +- Contains minimal code, most logic implemented in other modules + +### UI Layer: FancyZonesEditor and FancyZonesEditorCommon +- **FancyZonesEditor**: Main UI implementation with MainWindow.xaml as entry point +- **FancyZonesEditorCommon**: Provides data structures and I/O helpers for the Editor +- Acts as a visual config editor for layout configuration + +### Backend Implementation: FancyZones and FancyZonesLib +- **FancyZonesLib**: Core logic implementation + - All drag-and-drop behavior + - Layout UI during dragging (generated in C++ via WorkArea.cpp, NewZonesOverlayWindow function) + - Core data structures +- **FancyZones**: Wrapper around FancyZonesLib + +## Configuration Management + +### Configuration Files Location +- Path: `C:\Users\[username]\AppData\Local\Microsoft\PowerToys\FancyZones` +- Files: + - EditorParameters + - AppliedLayouts + - CustomLayouts + - DefaultLayouts + - LayoutHotkeys + - LayoutTemplates + - AppZoneHistory + +### Configuration Handling +- No central configuration handler +- Editor: Read/write handlers in FancyZonesEditorCommon project +- FancyZones: Read/write handlers in FancyZonesLib project +- Data synchronization: Editor sends update events, FancyZones refreshes memory data + +## Window Management + +### Monitor Detection and DPI Scaling +- Monitor detection handled in `FancyZones::MoveSizeUpdate` function +- DPI scaling: FancyZones retrieves window position without needing mouse DPI scaling info +- Window scaling uses system interface via `WindowMouseSnap::MoveSizeEnd()` function + +### Zone Tracking +- Window-to-zone tracking implemented in `FancyZones::MoveSizeUpdate` function +- Maintains history of which windows belong to which zones + +## Development History + +- FancyZones was originally developed as a proof of concept +- Many configuration options were added based on community feedback after initial development +- Some options were added to address specific issues: + - Options for child windows or pop-up windows + - Some options were removed later + - Community feedback led to more interactions being implemented + +## Admin Mode Considerations + +- FancyZones can't move admin windows unless running as admin +- By default, all utilities run as admin if PowerToys is running as admin + +## Troubleshooting + +### First Run JSON Error +**Error**: "The input does not contain any JSON tokens. Expected the input to start with a valid JSON token, when isFinalBlock is true. Path: $ | LineNumber: 0 | BytePositionInLine: 0." + +**Solution**: Launch the FancyZones Editor once through PowerToys Settings UI. Running the Editor directly within the project will not initialize the required configuration files. + +### Known Issues +- Potential undiscovered bugs related to data updates in the Editor +- Some automated tests pass in CI but fail on specific machines +- Complex testing requirements across different monitor configurations + +## FancyZones UI Testing UI tests are implemented using [Windows Application Driver](https://github.com/microsoft/WinAppDriver). -## Before running tests +### Before running tests - Install Windows Application Driver v1.2.1 from https://github.com/microsoft/WinAppDriver/releases/tag/v1.2.1. - Enable Developer Mode in Windows settings -## Running tests +### Running tests - Exit PowerToys if it's running - Run WinAppDriver.exe from the installation directory. Skip this step if installed in the default directory (`C:\Program Files (x86)\Windows Application Driver`); in this case, it'll be launched automatically during tests. @@ -16,8 +99,67 @@ UI tests are implemented using [Windows Application Driver](https://github.com/m >Note: notifications or other application windows, that are shown above the window under test, can disrupt the testing process. +### Test Framework Structure -## Extra tools and information +#### UI Test Requirements +All test cases require pre-configured user data and must reset this data before each test. + +**Required User Data Files**: +- EditorParameters +- AppliedLayouts +- CustomLayouts +- DefaultLayouts +- LayoutHotkeys +- LayoutTemplates +- AppZoneHistory + +#### Editor Test Suite + +**ApplyLayoutTest.cs** +- Verifies layout application and selection per monitor +- Tests file updates and behavior under display switching +- Validates virtual desktop changes + +**CopyLayoutTests.cs** +- Tests copying various layout types +- Validates UI and file correctness + +**CreateLayoutTests.cs** +- Tests layout creation and cancellation +- Focuses on file correctness validation + +**CustomLayoutsTests.cs** +- Tests user-created layout operations +- Covers renaming, highlight line changes, zone count changes + +**DefaultLayoutsTest.cs** +- Validates default and user layout files + +**DeleteLayoutTests.cs** +- Tests layout deletion across types +- Checks both UI and file updates + +**EditLayoutTests.cs** +- Tests zone operations: add/delete/move/reset/split/merge + +**FirstLaunchTest.cs** +- Verifies Editor launches correctly on first run + +**LayoutHotkeysTests.cs** +- Tests hotkey configuration file correctness +- Note: Actual hotkey behavior tested in FancyZones backend + +**TemplateLayoutsTests.cs** +- Tests operations on built-in layouts +- Covers renaming, highlight changes, zone count changes + +#### FancyZones Backend Tests + +**LayoutApplyHotKeyTests.cs** +- Focuses on hotkey-related functionality +- Tests actual hotkey behavior implementation + +### Extra tools and information **Test samples**: https://github.com/microsoft/WinAppDriver/tree/master/Samples diff --git a/doc/devdocs/modules/readme.md b/doc/devdocs/modules/readme.md new file mode 100644 index 0000000000..a84e53b517 --- /dev/null +++ b/doc/devdocs/modules/readme.md @@ -0,0 +1,25 @@ +# PowerToys Modules + +This section contains documentation for individual PowerToys modules, including their architecture, implementation details, and debugging tools. + +## Available Modules + +### FancyZones + +FancyZones is a window manager utility that allows users to create custom layouts for organizing windows on their screen. + +- [FancyZones Architecture and Implementation](fancyzones.md) - Details about the FancyZones architecture, components, and implementation +- [FancyZones Debugging Tools](fancyzones-tools.md) - Information about specialized tools for debugging FancyZones + +### Other Modules + +This section will be expanded with documentation for other PowerToys modules. + +## Adding New Module Documentation + +When adding documentation for a new module: + +1. Create a dedicated markdown file for the module (e.g., `modulename.md`) +2. If the module has specialized debugging tools, consider creating a separate tools document (e.g., `modulename-tools.md`) +3. Update this index with links to the new documentation +4. Follow the existing documentation structure for consistency diff --git a/doc/devdocs/readme.md b/doc/devdocs/readme.md index 554fef7bb3..af8c37c3a2 100644 --- a/doc/devdocs/readme.md +++ b/doc/devdocs/readme.md @@ -8,6 +8,7 @@ Welcome to the PowerToys developer documentation. This documentation provides in - [Runner](core/runner.md) - Details about the PowerToys Runner process - [Settings](core/settings.md) - Documentation on the settings system - [Installer](core/installer.md) - Information about the PowerToys installer +- [Modules](modules/readme.md) - Documentation for individual PowerToys modules ## Development Guidelines diff --git a/doc/devdocs/tools/fancyzones-draw-layout-test.md b/doc/devdocs/tools/fancyzones-draw-layout-test.md deleted file mode 100644 index 9f15a3a2ad..0000000000 --- a/doc/devdocs/tools/fancyzones-draw-layout-test.md +++ /dev/null @@ -1,7 +0,0 @@ -# [FancyZones_DrawLayoutTest](/tools/FancyZones_DrawLayoutTest/) - -This test tool is created in order to debug issues related to the drawing of zone layout on screen. - -Currently, only column layout is supported with modifiable number of zones. Pressing **w** key toggles zone appearance on primary screen (multi monitor support not yet in place). Pressing **q** key exits application. - -Application is DPI unaware which means that application does not scale for DPI changes and it always assumes to have a scale factor of 100% (96 DPI). Scaling will be automatically performed by the system. diff --git a/doc/devdocs/tools/fancyzones-hit-test.md b/doc/devdocs/tools/fancyzones-hit-test.md deleted file mode 100644 index 96856891f9..0000000000 --- a/doc/devdocs/tools/fancyzones-hit-test.md +++ /dev/null @@ -1,5 +0,0 @@ -# [FancyZone hit test tool](/tools/FancyZone_HitTest/) - -![Image of the FancyZones hit test tool](/doc/images/tools/fancyzones-hit-test.png) - -This tool tests the FancyZones layout selection logic. It displays a window with 5 zones. By hovering the mouse over the zones, the zone under the mouse cursor is highlighted. The sidebar shows different metrics that are used to determine which zone is under the mouse cursor. diff --git a/doc/devdocs/tools/fancyzones-zonable-tester.md b/doc/devdocs/tools/fancyzones-zonable-tester.md deleted file mode 100644 index 0b552f4636..0000000000 --- a/doc/devdocs/tools/fancyzones-zonable-tester.md +++ /dev/null @@ -1,13 +0,0 @@ -# [FancyZones_zonable_tester](/tools/FancyZones_zonable_tester/) - -![Image of the FancyZones zonable tester](/doc/images/tools/fancyzones-zonable-tester.png) - -This command line application tests if the window where the mouse cursor is located is zonable. It also adds additional information about the window to the console output: - -* The HWND (window handle) of the window -* The process ID of the window -* The HWND of the window in the foreground -* The style of the window -* The exStyle of the window -* The window class -* The path of the process that created the window diff --git a/doc/devdocs/tools/readme.md b/doc/devdocs/tools/readme.md index a2640bda7a..8050a3a6b7 100644 --- a/doc/devdocs/tools/readme.md +++ b/doc/devdocs/tools/readme.md @@ -11,9 +11,6 @@ Following tools are currently available: * [BugReportTool](bug-report-tool.md) - A tool to collect logs and system information for bug reports. * [Build tools](build-tools.md) - A set of scripts that help building PowerToys. * [Clean up tool](clean-up-tool.md) - A tool to clean up the PowerToys installation. -* [FancyZones hit test](fancyzones-hit-test.md) - A tool to test FancyZones layout selection logic. -* [FancyZones draw layout test](fancyzones-draw-layout-test.md) - A tool to test FancyZones layout drawing logic. -* [FancyZones zonable tester](fancyzones-zonable-tester.md) - A tool to test if a window is zonable. * [Monitor info report](monitor-info-report.md) - A small diagnostic tool which helps identifying WinAPI bugs related to the physical monitor detection. * [project template](/tools/project_template/README.md) - A Visual Studio project template for a new PowerToys project. * [StylesReportTool](styles-report-tool.md) - A tool to collect information about an open window.