fancyzones-tools.md
1 # FancyZones Debugging Tools 2 3 ## Overview 4 5 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. 6 7 ## Tools Summary 8 9 | Tool | Purpose | Key Functionality | 10 |------|---------|-------------------| 11 | FancyZones_HitTest | Tests zone hit detection | Shows which zone is under cursor with detailed metrics | 12 | FancyZones_DrawLayoutTest | Tests layout drawing | Renders zone layouts to debug display issues | 13 | FancyZones_zonable_tester | Tests window zonability | Determines if windows can be placed in zones | 14 | StylesReportTool | Analyzes window properties | Generates window style reports for debugging | 15 16 ## FancyZones_HitTest 17 18  19 20 ### Purpose 21 Tests the FancyZones layout selection logic by displaying a window with zones and highlighting the zone under the mouse cursor. 22 23 ### Functionality 24 - Displays a window with 5 sample zones 25 - Highlights the zone under the mouse cursor 26 - Shows metrics used for zone detection in a sidebar 27 - Helps diagnose issues with zone positioning and hit testing 28 29 ### Usage 30 - Run the tool and move your mouse over the zones 31 - The currently detected zone will be highlighted 32 - The sidebar displays metrics used for determining the active zone 33 - Useful for debugging hit detection, positioning, and DPI issues 34 35 ## FancyZones_DrawLayoutTest 36 37 ### Purpose 38 Debug issues related to the drawing of zone layouts on screen. 39 40 ### Functionality 41 - Simulates zone layouts (currently only column layout supported) 42 - Tests rendering of zones with different configurations 43 - Helps diagnose display issues across monitor configurations 44 45 ### Usage 46 - Run the tool 47 - Press **W** key to toggle zone appearance on the primary screen 48 - Press **Q** key to exit the application 49 - The number of zones can be modified in the source code 50 51 ### Technical Notes 52 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. 53 54 ## FancyZones_zonable_tester 55 56  57 58 ### Purpose 59 Tests if the window under the mouse cursor is "zonable" (can be placed in a FancyZones zone). 60 61 ### Functionality 62 - Analyzes the window under the cursor 63 - Provides detailed window information: 64 * HWND (window handle) 65 * Process ID 66 * HWND of foreground window 67 * Window style flags 68 * Extended style flags 69 * Window class 70 * Process path 71 72 ### Usage 73 - Run the command-line application 74 - Hover the mouse over a window to test 75 - Review the console output for detailed window information 76 - Check if the window is considered zonable by FancyZones 77 78 ### Limitations 79 Note that this tool may not be fully up-to-date with the latest zonable logic in the main FancyZones codebase. 80 81 ## StylesReportTool 82 83 ### Purpose 84 Generates detailed reports about window styles that affect zonability. 85 86 ### Functionality 87 - Creates comprehensive window style reports 88 - Focuses on style flags that determine if windows can be placed in zones 89 - Outputs report to "WindowStyles.txt" on the desktop 90 91 ### Usage 92 - Run the tool 93 - Focus the window you want to analyze 94 - Press **Ctrl+Alt+S** to generate a report 95 - Review WindowStyles.txt to understand why a window might not be zonable 96 97 ## Debugging Workflow 98 99 For most effective debugging of FancyZones issues: 100 101 1. Use **StylesReportTool** to analyze window properties of problematic windows 102 2. Use **FancyZones_zonable_tester** to check if specific windows can be zoned 103 3. Use **FancyZones_draw** for layout rendering issues on different monitors 104 4. Use **FancyZones_HitTest** for diagnosing zone detection problems 105 106 ## Testing Considerations 107 108 When testing FancyZones with these tools, consider: 109 110 - Testing on different Windows versions 111 - Testing with multiple monitors with different: 112 * Resolutions 113 * Scaling settings 114 * Physical arrangements 115 - Testing with various window types: 116 * Standard applications 117 * Legacy applications 118 * UWP/WinUI applications 119 * Administrative windows 120 * Special windows (like Task Manager) 121 - Testing various layouts: 122 * Grid layouts 123 * Custom layouts 124 * Overlapping zones 125 126 ## Initial Setup Issues 127 128 If encountering JSON token errors on first run: 129 1. Launch FancyZones Editor through PowerToys Settings UI 130 2. This initializes required configuration files 131 3. Direct project execution won't initialize configs properly