PowerToys/doc/specs/PowerToys-fancyzones.md

# FancyZones

## FancyZones
FancyZones is the base class that runs the show. It uses hooks to monitor for windows entering and exiting the move/size loop and to listen for key presses for hotkey interception. For every connected display, it creates a ZoneWindow which is used to display the active ZoneSet per monitor for use when editing the layout or displaying the drop targets. A ZoneSet is composed of one or more Zones which are the locations where windows can be easily positioned.

### SetWinEventHook
The main driving force behind FancyZones is the accessibility hook used to know when a window enters the move/size loop. It listens for EVENT_SYSTEM_MOVESIZESTART, EVENT_SYSTEM_MOVESIZEEND, and EVENT_OBJECT_LOCATIONCHANGE. For each of these three events, it forwards on to the ZoneWindow associated with the monitor that the window being dragged is currently on.

### Keyboard Hook
A low-level keyboard hook is installed in order to, optionally, intercept Window+Arrow hotkeys. Traditionally, Win+Left/Right arrow will move a window between Windows Snap regions. This hook allows FancyZones to use Win+Left/Right arrow to move windows between Zones.
The hook also allows using 0-9 to change the active ZoneSet during a drag operation. 

### Display Changes
During initial standup, FancyZones creates a ZoneWindow for each connected monitor. When it receives a WM_DISPLAYCHANGE, it updates the available ZoneWindows to reflect the state of the system (eg add a new ZoneWindow for newly connected monitor, delete ZoneWindow for disconnected monitor, etc)

### Interface
```
interface IFancyZones : public IUnknown
{
    // Returns the main application window
    IFACEMETHOD_(HWND, GetWindow)() = 0;

    // Returns the global HINSTANCE for the process
    IFACEMETHOD_(HINSTANCE, GetHInstance)() = 0;

    // Returns the global Settings object used to look up individual settings throughout the product
    IFACEMETHOD_(Settings, GetSettings)() = 0;

    // Used in WinMain to initialize FancyZones and enter the message loop
    IFACEMETHOD_(void, Run)() = 0;

    // Toggles the visibility of all ZoneWindows
    IFACEMETHOD_(void, ToggleZoneViewers)() = 0;

    // Shows a single ZoneWindow in editor mode on the provided monitor
    IFACEMETHOD_(void, ShowZoneEditorForMonitor)(_In_ HMONITOR monitor) = 0;

    // Returns true if we are currently detecting a movesize loop
    IFACEMETHOD_(bool, InMoveSize)() = 0;

    // Called by the event hook in response to EVENT_SYSTEM_MOVESIZESTART
    IFACEMETHOD(MoveSizeEnter)(_In_ HWND window, _In_ HMONITOR monitor, POINT ptScreen) = 0;

    // Called by the event hook in response to EVENT_SYSTEM_MOVESIZEEND
    IFACEMETHOD(MoveSizeExit)(_In_ HWND window, POINT ptScreen) = 0;

    // Called by the event hook in response to EVENT_OBJECT_LOCATIONCHANGE
    IFACEMETHOD(MoveSizeUpdate)(_In_ HMONITOR monitor, POINT ptScreen) = 0;

    // Called during startup or on WM_DISPLAYCHANGE to add a ZoneWindow to the collection
    // There will be one ZoneWindow per connected monitor
    IFACEMETHOD(AddZoneWindow)(_In_ IZoneWindow* zoneWindow, _In_ HMONITOR monitor) = 0;

    // Called in response to WM_DISPLAYCHANGE from the main application window
    IFACEMETHOD_(void, OnDisplayChange)(DisplayChangeType changeType) = 0;

    // Used to move the specified HWND into Zone
    // The ZoneSet used is found by looking up the monitor that window is currently on
    // This gets called to keep windows in their current zones after a WM_DISPLAYCHANGE
    IFACEMETHOD_(void, MoveWindowIntoZoneByIndex)(_In_ HWND window, int index) = 0;

    // Used to filter out windows that the hook should not be processing
    // Currently checks if the window's GWL_STYLE has WS_MAXIMIZEBOX
    IFACEMETHOD_(bool, IsInterestingWindow)(_In_ HWND window) = 0;

    // Called byt the event hook in response to EVENT_OBJECT_NAMECHANGE on the Desktop window
    // The accessible name of the desktop window changes when the current virtual desktop changes
    IFACEMETHOD_(void, VirtualDesktopChanged)() = 0;

    // Returns the GUID of the current active virtual desktop
    IFACEMETHOD_(GUID, GetCurrentVirtualDesktopId)() = 0;

    // Called by the LL keyboard hook
    // Used to override snap hotkeys and to change the active ZoneSet during a drag
    IFACEMETHOD_(bool, OnKeyDown)(LPARAM lparam) = 0;

    // Keep windows positioned inside their zones when the active ZoneSet changes
    IFACEMETHOD_(void, MoveWindowsOnActiveZoneSetChange)() = 0;
};
```

## ZoneWindow
ZoneWindow is used to display the Zones a user can drop a window in during a drag operation, flash the Zones when the ZoneSet changes, and draw the Zone Editor UI when in edit mode. Basically, when a ZoneSet needs to be visualized, ZoneWindow does it.

### Interface
```
interface IZoneWindow : public IUnknown
{
    // Shows the ZoneWindow
    // If activate is true, set foreground to the window otherwise just show
    IFACEMETHOD(ShowZoneWindow)(bool activate) = 0;

    // Hide the ZoneWindow
    IFACEMETHOD(HideZoneWindow)() = 0;
    
    // Called when the drag enters the monitor this ZoneWindow is assigned to
    IFACEMETHOD(MoveSizeEnter)(_In_ HWND window, POINT ptScreen, DragMode dragMode) = 0;

    // Called when the drag exits the monitor
    IFACEMETHOD(MoveSizeExit)(_In_ HWND window, POINT ptScreen) = 0;

    // Called when the drag updates position on this monitor
    IFACEMETHOD(MoveSizeUpdate)(POINT ptScreen, DragMode dragMode) = 0;

    // Called when a drag ends and the window is not dropped in a Zone
    IFACEMETHOD(MoveSizeCancel)() = 0;

    // Returns the DragMode of the current drag operation
    // DragMode allows for overriding drag behavior via settings or via hotkey
    IFACEMETHOD_(DragMode, GetDragMode)() = 0;

    // Part of the chain to move a window into a specific Zone
    IFACEMETHOD_(void, MoveWindowIntoZoneByIndex)(_In_ HWND window, int index) = 0;
    
    // Used to cycle a window between zones via the hijacked snap hotkeys
    IFACEMETHOD_(void, MoveWindowIntoZoneByDirection)(_In_ HWND window, DWORD vkCode) = 0;

    // Called in response to WM_DISPLAYCHANGE
    // Allows cleanup, if necessary, since ZoneWindow will be destroyed shortly thereafter
    IFACEMETHOD_(void, OnDisplayChange)(DisplayChangeType type) = 0;

    // Allows changing the active ZoneSet via key press either during a drag or while the ZoneWindow is in foreground
    IFACEMETHOD_(void, CycleActiveZoneSet)(DWORD vkCode) = 0;
};
```

## ZoneSet
Collection of one or more Zones. Only one ZoneSet is active at a time per monitor.

### Interface
```
interface IZoneSet : public IUnknown
{
    // Gets the unique ID used to identify this ZoneSet
    IFACEMETHOD_(GUID, GetId)() = 0;

    // Adds a Zone to the collection
    IFACEMETHOD(AddZone)(_In_ Microsoft::WRL::ComPtr<IZone> zone, bool front) = 0;

    // Removes a Zone from the collection
    IFACEMETHOD(RemoveZone)(_In_ Microsoft::WRL::ComPtr<IZone> zone) = 0;

    // Returns the topmost Zone at the given point
    IFACEMETHOD_(Microsoft::WRL::ComPtr<IZone>, ZoneFromPoint)(POINT pt) = 0;

    // Returns a Zone that the window is in
    // Will return nullptr if the window is not in a Zone
    IFACEMETHOD_(Microsoft::WRL::ComPtr<IZone>, ZoneFromWindow)(_In_ HWND window) = 0;

    // Gets all the Zones
    IFACEMETHOD_(std::vector<Microsoft::WRL::ComPtr<IZone>>, GetZones)() = 0;
    
    // ZoneSetLayout
    // * Grid - Pregenerated layout (2x2, 3x3, etc)
    // * Row - Pregenerated layout in a single row
    // * Focus - Pregenerated layout with a central focus Zone and fanned peripheral Zones
    // * Custom - User generated Zone
    IFACEMETHOD_(ZoneSetLayout, GetLayout)() = 0;

    // The amount of default padding between Zones in a generated layout
    IFACEMETHOD_(int, GetInnerPadding)() = 0;

    // Makes a copy of the IZoneSet and marks it as ZoneSetLayout::Custom
    IFACEMETHOD_(Microsoft::WRL::ComPtr<IZoneSet>, MakeCustomClone)() = 0;

    // Persists ZoneSet data to the registry
    IFACEMETHOD_(void, Save)() = 0;

    // Moves a Zone to the front of the collection
    IFACEMETHOD_(void, MoveZoneToFront)(_In_ Microsoft::WRL::ComPtr<IZone> zone) = 0;

    // Moves a Zone to the back of the collection
    IFACEMETHOD_(void, MoveZoneToBack)(_In_ Microsoft::WRL::ComPtr<IZone> zone) = 0;
    
    // Part of the chain to move a window into a specific Zone
    IFACEMETHOD_(void, MoveWindowIntoZoneByIndex)(_In_ HWND window, _In_ HWND zoneWindow, int index) = 0;

    // Part of the chain to move a window into a specific Zone
    IFACEMETHOD_(void, MoveWindowIntoZoneByDirection)(_In_ HWND window, _In_ HWND zoneWindow, DWORD vkCode) = 0;

    // Called when a drag ends or leaves the monitor this ZoneWindow is on
    // This will remove the window from its currently assigned Zone and assign it
    // to a different Zone based on the current cursor position
    IFACEMETHOD_(void, MoveSizeExit)(_In_ HWND window, _In_ HWND zoneWindow, _In_ POINT ptClient) = 0;
};
```

## Zone
Basically a RECT and a map of HWND->RECT to keep track of where windows can be placed and which windows are currently in the Zone.

### Interface
```
interface IZone : public IUnknown
{
    // Returns the RECT that this Zone represents
    IFACEMETHOD_(RECT, GetZoneRect)() = 0;

    // Returns true if the specified window is in this Zone's collection
    IFACEMETHOD_(bool, ContainsWindow)(_In_ HWND window) = 0;

    // Adds the window the collection
    IFACEMETHOD_(void, AddWindowToZone)(_In_ HWND window, _In_ HWND zoneWindow, bool stampZone) = 0;

    // Removes the window from the collection
    IFACEMETHOD_(void, RemoveWindowFromZone)(_In_ HWND window, bool restoreSize) = 0;

    // Sets an id for this Zone
    // The id will be unique per ZoneSet
    IFACEMETHOD_(void, SetId)(size_t id) = 0;

    // Returns the id given to this Zone
    IFACEMETHOD_(size_t, GetId)() = 0;
};
```