"""Advanced window grid management and positioning algorithms.
This module implements sophisticated grid layout calculations for systematic window
organization across multi-monitor setups with intelligent spacing, padding, and
aspect ratio preservation.
Security: Coordinate bounds validation and overflow protection
Performance: Efficient grid calculations with position caching
Type Safety: Complete branded type system with mathematical validation
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from src.core.contracts import ensure, require
from src.core.displays import (
DisplayInfo,
WindowGridPattern,
)
from src.core.either import Either
from src.core.errors import WindowError
@dataclass(frozen=True)
class WindowPosition:
"""Precise window position specification with validation."""
x: int
y: int
width: int
height: int
@require(lambda self: self.width > 0 and self.height > 0)
@require(
lambda self: self.width <= 8192 and self.height <= 8192,
) # Reasonable limits
def __post_init__(self):
"""Contract validation for window position."""
def to_tuple(self) -> tuple[int, int, int, int]:
"""Convert to (x, y, width, height) tuple."""
return (self.x, self.y, self.width, self.height)
def center(self) -> tuple[int, int]:
"""Get center coordinates of window."""
return (self.x + self.width // 2, self.y + self.height // 2)
def area(self) -> int:
"""Get window area in pixels."""
return self.width * self.height
class GridCalculator:
"""Advanced grid layout calculations with mathematical precision."""
@staticmethod
# FIXME: Contract disabled - @require(lambda display: display.resolution[0] > 0 and display.resolution[1] > 0)
# FIXME: Contract disabled - @require( lambda pattern: pattern in GRID_PATTERN_SPECS or pattern == WindowGridPattern.CUSTOM, )
# FIXME: Contract disabled - @require(lambda window_count: window_count > 0)
# FIXME: Contract disabled - @require(lambda padding: padding >= 0)
@ensure(
lambda result: result.is_right() or result.get_left().is_calculation_error(),
)
def calculate_grid_positions(
display: DisplayInfo,
pattern: WindowGridPattern,
window_count: int,
padding: int = 10,
) -> Either[WindowError, list[WindowPosition]]:
"""Calculate precise window positions for grid layout.
Architecture: Mathematical grid system with aspect ratio preservation
Security: Bounds validation and coordinate overflow protection
Performance: Efficient position calculation with minimal allocation
"""
try:
if window_count <= 0:
return Either.left(WindowError("Window count must be positive"))
if padding < 0:
return Either.left(WindowError("Padding cannot be negative"))
# Get display bounds
dx, dy, dw, dh = display.bounds()
# Calculate usable area (minus padding)
usable_width = dw - (2 * padding)
usable_height = dh - (2 * padding)
if usable_width <= 0 or usable_height <= 0:
return Either.left(WindowError("Display too small for padding"))
# Calculate grid positions based on pattern
if pattern == WindowGridPattern.GRID_2X2:
positions = GridCalculator._calculate_standard_grid(
dx + padding,
dy + padding,
usable_width,
usable_height,
2,
2,
window_count,
padding,
)
elif pattern == WindowGridPattern.GRID_3X3:
positions = GridCalculator._calculate_standard_grid(
dx + padding,
dy + padding,
usable_width,
usable_height,
3,
3,
window_count,
padding,
)
elif pattern == WindowGridPattern.GRID_4X2:
positions = GridCalculator._calculate_standard_grid(
dx + padding,
dy + padding,
usable_width,
usable_height,
2,
4,
window_count,
padding,
)
elif pattern == WindowGridPattern.GRID_2X3:
positions = GridCalculator._calculate_standard_grid(
dx + padding,
dy + padding,
usable_width,
usable_height,
3,
2,
window_count,
padding,
)
elif pattern == WindowGridPattern.SIDEBAR_MAIN:
positions = GridCalculator._calculate_sidebar_layout(
dx + padding,
dy + padding,
usable_width,
usable_height,
window_count,
padding,
sidebar_left=True,
)
elif pattern == WindowGridPattern.MAIN_SIDEBAR:
positions = GridCalculator._calculate_sidebar_layout(
dx + padding,
dy + padding,
usable_width,
usable_height,
window_count,
padding,
sidebar_left=False,
)
elif pattern == WindowGridPattern.THIRDS_HORIZONTAL:
positions = GridCalculator._calculate_standard_grid(
dx + padding,
dy + padding,
usable_width,
usable_height,
1,
3,
window_count,
padding,
)
elif pattern == WindowGridPattern.THIRDS_VERTICAL:
positions = GridCalculator._calculate_standard_grid(
dx + padding,
dy + padding,
usable_width,
usable_height,
3,
1,
window_count,
padding,
)
elif pattern == WindowGridPattern.QUARTERS:
positions = GridCalculator._calculate_standard_grid(
dx + padding,
dy + padding,
usable_width,
usable_height,
2,
2,
window_count,
padding,
)
else:
return Either.left(
WindowError(f"Unsupported grid pattern: {pattern.value}"),
)
# Validate all positions are within display bounds
for pos in positions:
if not GridCalculator._validate_position_bounds(pos, display):
return Either.left(
WindowError("Calculated position outside display bounds"),
)
return Either.right(positions)
except Exception as e:
return Either.left(WindowError(f"Grid calculation failed: {e!s}"))
@staticmethod
def _calculate_standard_grid(
start_x: int,
start_y: int,
total_width: int,
total_height: int,
rows: int,
columns: int,
window_count: int,
cell_padding: int,
) -> list[WindowPosition]:
"""Calculate positions for standard rectangular grid."""
positions = []
# Calculate cell dimensions with padding
cell_width = (total_width - (columns - 1) * cell_padding) // columns
cell_height = (total_height - (rows - 1) * cell_padding) // rows
# Ensure minimum window size
cell_width = max(cell_width, 200)
cell_height = max(cell_height, 150)
count = 0
for row in range(rows):
for col in range(columns):
if count >= window_count:
break
x = start_x + col * (cell_width + cell_padding)
y = start_y + row * (cell_height + cell_padding)
positions.append(WindowPosition(x, y, cell_width, cell_height))
count += 1
if count >= window_count:
break
return positions
@staticmethod
def _calculate_sidebar_layout(
start_x: int,
start_y: int,
total_width: int,
total_height: int,
window_count: int,
padding: int,
sidebar_left: bool = True,
) -> list[WindowPosition]:
"""Calculate positions for sidebar + main area layout."""
positions = []
if window_count <= 0:
return positions
# Calculate sidebar and main area dimensions
sidebar_width = total_width // 3
main_width = total_width - sidebar_width - padding
if sidebar_left:
# Sidebar on left
if window_count >= 1:
positions.append(
WindowPosition(start_x, start_y, sidebar_width, total_height),
)
if window_count >= 2:
main_x = start_x + sidebar_width + padding
positions.append(
WindowPosition(main_x, start_y, main_width, total_height),
)
else:
# Sidebar on right
if window_count >= 1:
positions.append(
WindowPosition(start_x, start_y, main_width, total_height),
)
if window_count >= 2:
sidebar_x = start_x + main_width + padding
positions.append(
WindowPosition(sidebar_x, start_y, sidebar_width, total_height),
)
return positions
@staticmethod
def _validate_position_bounds(
position: WindowPosition,
display: DisplayInfo,
) -> bool:
"""Validate position is within display bounds."""
dx, dy, dw, dh = display.bounds()
# Check if window fits within display
return (
position.x >= dx
and position.y >= dy
and position.x + position.width <= dx + dw
and position.y + position.height <= dy + dh
)
class AdvancedGridManager:
"""Advanced grid management with layout persistence and optimization."""
def __init__(self):
self._layout_cache: dict[str, list[WindowPosition]] = {}
self._grid_calculator = GridCalculator()
@require(lambda __self, window_ids: len(window_ids) > 0)
@require(
lambda _self, display: display.resolution[0] > 0 and display.resolution[1] > 0,
)
async def arrange_windows_in_grid(
self,
window_identifiers: list[str],
display: DisplayInfo,
pattern: WindowGridPattern = WindowGridPattern.GRID_2X2,
padding: int = 10,
preserve_aspect_ratios: bool = False,
cache_layout: bool = True,
) -> Either[WindowError, list[dict[str, Any]]]:
"""Arrange windows in sophisticated grid layout with caching.
Architecture: Grid-based positioning with intelligent caching
Security: Window identifier validation and bounds checking
Performance: Position caching and efficient calculation algorithms
"""
try:
window_count = len(window_identifiers)
# Generate cache key
cache_key = f"{display.display_id}_{pattern.value}_{window_count}_{padding}"
# Check cache first
if cache_layout and cache_key in self._layout_cache:
positions = self._layout_cache[cache_key]
else:
# Calculate new positions
positions_result = GridCalculator.calculate_grid_positions(
display,
pattern,
window_count,
padding,
preserve_aspect_ratios,
)
if positions_result.is_left():
return Either.left(positions_result.get_left())
positions = positions_result.get_right()
# Cache positions
if cache_layout:
self._layout_cache[cache_key] = positions
# Create results with window assignments
results = []
for i, (window_id, position) in enumerate(
zip(window_identifiers, positions, strict=False),
):
result = {
"window_identifier": window_id,
"position": position.to_tuple(),
"grid_cell": i,
"display_id": display.display_id,
"success": True,
}
results.append(result)
return Either.right(results)
except Exception as e:
return Either.left(WindowError(f"Grid arrangement failed: {e!s}"))
async def calculate_optimal_pattern(
self,
window_count: int,
display: DisplayInfo,
preference: str | None = None,
) -> Either[WindowError, WindowGridPattern]:
"""Calculate optimal grid pattern for window count and display."""
try:
if window_count <= 0:
return Either.left(WindowError("Invalid window count"))
# Preference-based selection
if preference:
try:
return Either.right(WindowGridPattern(preference))
except ValueError:
pass # Fall through to automatic selection
# Automatic pattern selection based on window count and display aspect ratio
display_ratio = display.resolution[0] / display.resolution[1]
if window_count == 1:
return Either.right(WindowGridPattern.CUSTOM)
if window_count == 2:
if display_ratio > 1.5: # Wide display
return Either.right(WindowGridPattern.GRID_1X2)
return Either.right(WindowGridPattern.GRID_2X1)
if window_count == 3:
if display_ratio > 1.5:
return Either.right(WindowGridPattern.THIRDS_HORIZONTAL)
return Either.right(WindowGridPattern.THIRDS_VERTICAL)
if window_count == 4:
return Either.right(WindowGridPattern.GRID_2X2)
if window_count <= 6:
if display_ratio > 1.5:
return Either.right(WindowGridPattern.GRID_2X3)
return Either.right(WindowGridPattern.GRID_3X2)
if window_count <= 8:
return Either.right(WindowGridPattern.GRID_4X2)
if window_count <= 9:
return Either.right(WindowGridPattern.GRID_3X3)
return Either.right(
WindowGridPattern.GRID_3X3,
) # Default for many windows
except Exception as e:
return Either.left(WindowError(f"Pattern calculation failed: {e!s}"))
def clear_cache(self) -> None:
"""Clear layout position cache."""
self._layout_cache.clear()
def get_supported_patterns(self) -> list[WindowGridPattern]:
"""Get list of supported grid patterns."""
return [
WindowGridPattern.GRID_2X2,
WindowGridPattern.GRID_3X3,
WindowGridPattern.GRID_4X2,
WindowGridPattern.GRID_2X3,
WindowGridPattern.GRID_1X2,
WindowGridPattern.GRID_2X1,
WindowGridPattern.SIDEBAR_MAIN,
WindowGridPattern.MAIN_SIDEBAR,
WindowGridPattern.THIRDS_HORIZONTAL,
WindowGridPattern.THIRDS_VERTICAL,
WindowGridPattern.QUARTERS,
]
# Grid pattern metadata for UI and documentation
GRID_PATTERN_METADATA = {
WindowGridPattern.GRID_2X2: {
"name": "2x2 Grid",
"description": "Four equal quadrants",
"max_windows": 4,
"best_for": "Balanced layout for productivity apps",
},
WindowGridPattern.GRID_3X3: {
"name": "3x3 Grid",
"description": "Nine equal cells",
"max_windows": 9,
"best_for": "Many small windows or detailed organization",
},
WindowGridPattern.SIDEBAR_MAIN: {
"name": "Sidebar + Main",
"description": "Left sidebar with main content area",
"max_windows": 2,
"best_for": "Reference + work or navigation + content",
},
WindowGridPattern.THIRDS_HORIZONTAL: {
"name": "Horizontal Thirds",
"description": "Three equal horizontal columns",
"max_windows": 3,
"best_for": "Wide displays and workflow stages",
},
WindowGridPattern.QUARTERS: {
"name": "Quarters",
"description": "Four equal corner positions",
"max_windows": 4,
"best_for": "Standard productivity layout",
},
}
