pomera-ai-commander 0.1.0 → 1.2.1

package/core/widget_cache.py

@@ -1,498 +1,498 @@
-"""
-Widget Cache - Caches tool widgets to avoid recreation on tool switching.
-
-Instead of destroying and recreating widgets on every tool switch,
-this cache hides/shows widgets as needed, improving performance.
-
-Author: Pomera AI Commander Team
-"""
-
-import tkinter as tk
-from tkinter import ttk
-from typing import Dict, Optional, Callable, Any, Set, List
-import logging
-import weakref
-from dataclasses import dataclass, field
-from enum import Enum
-
-
-logger = logging.getLogger(__name__)
-
-
-class CacheStrategy(Enum):
-    """Widget caching strategies."""
-    ALWAYS = "always"        # Always cache (default)
-    ON_DEMAND = "on_demand"  # Cache only when explicitly requested
-    NEVER = "never"          # Never cache (always recreate)
-    LRU = "lru"              # Least Recently Used eviction
-
-
-@dataclass
-class CachedWidget:
-    """
-    Information about a cached widget.
-    
-    Attributes:
-        widget: The actual Tkinter widget
-        tool_name: Name of the tool this widget belongs to
-        created_at: Timestamp when widget was created
-        last_shown: Timestamp when widget was last shown
-        show_count: Number of times widget has been shown
-        needs_refresh: Whether widget needs to be refreshed on next show
-    """
-    widget: tk.Widget
-    tool_name: str
-    created_at: float = 0.0
-    last_shown: float = 0.0
-    show_count: int = 0
-    needs_refresh: bool = False
-    
-    def mark_shown(self) -> None:
-        """Mark widget as shown."""
-        import time
-        self.last_shown = time.time()
-        self.show_count += 1
-
-
-class WidgetCache:
-    """
-    Caches tool widgets to improve tool switching performance.
-    
-    Instead of destroying and recreating widgets on every tool switch,
-    this cache hides/shows widgets as needed. This significantly improves
-    the user experience when switching between tools frequently.
-    
-    Usage:
-        cache = WidgetCache(parent_frame)
-        
-        # Register widget factories
-        cache.register_factory("Case Tool", lambda: create_case_tool_widget())
-        cache.register_factory("AI Tools", lambda: create_ai_tools_widget())
-        
-        # Switch to a tool (creates widget if not cached, shows it)
-        cache.show("Case Tool")
-        
-        # Switch to another tool (hides Case Tool, shows AI Tools)
-        cache.show("AI Tools")
-        
-        # Force refresh a widget on next show
-        cache.invalidate("Case Tool")
-    """
-    
-    def __init__(self, 
-                 parent_frame: tk.Frame,
-                 strategy: CacheStrategy = CacheStrategy.ALWAYS,
-                 max_cached: int = 20,
-                 logger: Optional[logging.Logger] = None):
-        """
-        Initialize the widget cache.
-        
-        Args:
-            parent_frame: The frame where tool widgets are displayed
-            strategy: Caching strategy to use
-            max_cached: Maximum number of widgets to cache (for LRU)
-            logger: Logger instance
-        """
-        self.parent_frame = parent_frame
-        self.strategy = strategy
-        self.max_cached = max_cached
-        self.logger = logger or logging.getLogger(__name__)
-        
-        # Widget storage
-        self._cache: Dict[str, CachedWidget] = {}
-        self._factories: Dict[str, Callable[[], tk.Widget]] = {}
-        self._current_tool: Optional[str] = None
-        
-        # Tools that should never be cached
-        self._never_cache: Set[str] = set()
-        
-        # Callbacks
-        self._on_widget_created: Optional[Callable[[str, tk.Widget], None]] = None
-        self._on_widget_shown: Optional[Callable[[str, tk.Widget], None]] = None
-        self._on_widget_hidden: Optional[Callable[[str, tk.Widget], None]] = None
-        
-        # Statistics
-        self._stats = {
-            'cache_hits': 0,
-            'cache_misses': 0,
-            'widgets_created': 0,
-            'widgets_destroyed': 0
-        }
-    
-    def register_factory(self, 
-                        tool_name: str, 
-                        factory: Callable[[], tk.Widget],
-                        never_cache: bool = False) -> None:
-        """
-        Register a factory function for creating a tool's widget.
-        
-        Args:
-            tool_name: Name of the tool
-            factory: Function that creates and returns the widget
-            never_cache: If True, widget will always be recreated
-        """
-        self._factories[tool_name] = factory
-        if never_cache:
-            self._never_cache.add(tool_name)
-        self.logger.debug(f"Registered factory for: {tool_name}")
-    
-    def unregister_factory(self, tool_name: str) -> bool:
-        """
-        Unregister a factory function.
-        
-        Args:
-            tool_name: Name of the tool
-            
-        Returns:
-            True if factory was found and removed
-        """
-        if tool_name in self._factories:
-            del self._factories[tool_name]
-            self._never_cache.discard(tool_name)
-            return True
-        return False
-    
-    def get_or_create(self, tool_name: str) -> Optional[tk.Widget]:
-        """
-        Get a cached widget or create it if not cached.
-        
-        Args:
-            tool_name: Name of the tool
-            
-        Returns:
-            The tool's widget, or None if no factory registered
-        """
-        # Check if we should never cache this tool
-        should_cache = (
-            self.strategy != CacheStrategy.NEVER and
-            tool_name not in self._never_cache
-        )
-        
-        # Return cached widget if available and valid
-        if tool_name in self._cache and should_cache:
-            cached = self._cache[tool_name]
-            if not cached.needs_refresh:
-                self._stats['cache_hits'] += 1
-                self.logger.debug(f"Cache hit for: {tool_name}")
-                return cached.widget
-            else:
-                # Widget needs refresh, destroy and recreate
-                self._destroy_widget(tool_name)
-        
-        self._stats['cache_misses'] += 1
-        
-        # Check if we have a factory
-        if tool_name not in self._factories:
-            self.logger.warning(f"No factory registered for tool: {tool_name}")
-            return None
-        
-        # Enforce max cache size (LRU eviction)
-        if self.strategy == CacheStrategy.LRU and len(self._cache) >= self.max_cached:
-            self._evict_lru()
-        
-        # Create new widget
-        try:
-            widget = self._factories[tool_name]()
-            
-            if should_cache:
-                import time
-                self._cache[tool_name] = CachedWidget(
-                    widget=widget,
-                    tool_name=tool_name,
-                    created_at=time.time()
-                )
-            
-            self._stats['widgets_created'] += 1
-            self.logger.debug(f"Created widget for: {tool_name}")
-            
-            # Callback
-            if self._on_widget_created:
-                self._on_widget_created(tool_name, widget)
-            
-            return widget
-            
-        except Exception as e:
-            self.logger.error(f"Failed to create widget for {tool_name}: {e}")
-            return None
-    
-    def show(self, tool_name: str) -> bool:
-        """
-        Show the widget for the specified tool, hiding others.
-        
-        Args:
-            tool_name: Name of the tool to show
-            
-        Returns:
-            True if successful, False otherwise
-        """
-        # Hide current widget
-        if self._current_tool and self._current_tool != tool_name:
-            self._hide_current()
-        
-        # Get or create the new widget
-        widget = self.get_or_create(tool_name)
-        if widget is None:
-            return False
-        
-        # Show the new widget
-        try:
-            widget.pack(fill=tk.BOTH, expand=True)
-            self._current_tool = tool_name
-            
-            # Update cached widget stats
-            if tool_name in self._cache:
-                self._cache[tool_name].mark_shown()
-            
-            # Callback
-            if self._on_widget_shown:
-                self._on_widget_shown(tool_name, widget)
-            
-            self.logger.debug(f"Showing widget: {tool_name}")
-            return True
-            
-        except tk.TclError as e:
-            self.logger.error(f"Failed to show widget {tool_name}: {e}")
-            # Widget might be destroyed, remove from cache
-            self._cache.pop(tool_name, None)
-            return False
-    
-    def hide(self, tool_name: str) -> bool:
-        """
-        Hide a specific tool's widget.
-        
-        Args:
-            tool_name: Name of the tool to hide
-            
-        Returns:
-            True if widget was hidden
-        """
-        if tool_name not in self._cache:
-            return False
-        
-        try:
-            self._cache[tool_name].widget.pack_forget()
-            
-            if self._current_tool == tool_name:
-                self._current_tool = None
-            
-            # Callback
-            if self._on_widget_hidden:
-                self._on_widget_hidden(tool_name, self._cache[tool_name].widget)
-            
-            return True
-            
-        except tk.TclError:
-            # Widget might be destroyed
-            self._cache.pop(tool_name, None)
-            return False
-    
-    def _hide_current(self) -> None:
-        """Hide the currently shown widget."""
-        if self._current_tool and self._current_tool in self._cache:
-            try:
-                self._cache[self._current_tool].widget.pack_forget()
-                
-                if self._on_widget_hidden:
-                    self._on_widget_hidden(
-                        self._current_tool, 
-                        self._cache[self._current_tool].widget
-                    )
-            except tk.TclError:
-                # Widget might be destroyed
-                self._cache.pop(self._current_tool, None)
-    
-    def invalidate(self, tool_name: str) -> None:
-        """
-        Mark a widget for refresh (will be recreated on next show).
-        
-        Args:
-            tool_name: Name of the tool to invalidate
-        """
-        if tool_name in self._cache:
-            self._cache[tool_name].needs_refresh = True
-            self.logger.debug(f"Invalidated cache for: {tool_name}")
-    
-    def destroy(self, tool_name: str) -> bool:
-        """
-        Destroy a cached widget immediately.
-        
-        Args:
-            tool_name: Name of the tool
-            
-        Returns:
-            True if widget was found and destroyed
-        """
-        return self._destroy_widget(tool_name)
-    
-    def _destroy_widget(self, tool_name: str) -> bool:
-        """Internal method to destroy a widget."""
-        if tool_name not in self._cache:
-            return False
-        
-        try:
-            self._cache[tool_name].widget.destroy()
-        except tk.TclError:
-            pass  # Already destroyed
-        
-        del self._cache[tool_name]
-        self._stats['widgets_destroyed'] += 1
-        
-        if self._current_tool == tool_name:
-            self._current_tool = None
-        
-        self.logger.debug(f"Destroyed widget: {tool_name}")
-        return True
-    
-    def _evict_lru(self) -> None:
-        """Evict the least recently used widget."""
-        if not self._cache:
-            return
-        
-        # Don't evict current widget
-        candidates = [
-            (name, cached) for name, cached in self._cache.items()
-            if name != self._current_tool
-        ]
-        
-        if not candidates:
-            return
-        
-        # Find LRU
-        lru_name, _ = min(candidates, key=lambda x: x[1].last_shown)
-        self._destroy_widget(lru_name)
-        self.logger.debug(f"Evicted LRU widget: {lru_name}")
-    
-    def clear(self) -> None:
-        """Clear all cached widgets."""
-        for tool_name in list(self._cache.keys()):
-            self._destroy_widget(tool_name)
-        self._current_tool = None
-        self.logger.debug("Cleared all cached widgets")
-    
-    def refresh_all(self) -> None:
-        """Mark all widgets for refresh."""
-        for cached in self._cache.values():
-            cached.needs_refresh = True
-        self.logger.debug("Marked all widgets for refresh")
-    
-    def is_cached(self, tool_name: str) -> bool:
-        """Check if a tool's widget is cached."""
-        return tool_name in self._cache
-    
-    def get_widget(self, tool_name: str) -> Optional[tk.Widget]:
-        """
-        Get a cached widget without creating it.
-        
-        Args:
-            tool_name: Name of the tool
-            
-        Returns:
-            The widget if cached, None otherwise
-        """
-        if tool_name in self._cache:
-            return self._cache[tool_name].widget
-        return None
-    
-    @property
-    def cached_tools(self) -> List[str]:
-        """Get list of currently cached tool names."""
-        return list(self._cache.keys())
-    
-    @property
-    def current_tool(self) -> Optional[str]:
-        """Get the currently displayed tool name."""
-        return self._current_tool
-    
-    @property
-    def factory_count(self) -> int:
-        """Get number of registered factories."""
-        return len(self._factories)
-    
-    def get_stats(self) -> Dict[str, Any]:
-        """Get cache statistics."""
-        total_requests = self._stats['cache_hits'] + self._stats['cache_misses']
-        hit_rate = (
-            self._stats['cache_hits'] / total_requests * 100
-            if total_requests > 0 else 0
-        )
-        
-        return {
-            **self._stats,
-            'cached_widgets': len(self._cache),
-            'registered_factories': len(self._factories),
-            'current_tool': self._current_tool,
-            'hit_rate_percent': round(hit_rate, 2),
-            'strategy': self.strategy.value
-        }
-    
-    def get_cache_info(self, tool_name: str) -> Optional[Dict[str, Any]]:
-        """
-        Get information about a cached widget.
-        
-        Args:
-            tool_name: Name of the tool
-            
-        Returns:
-            Dictionary with cache info, or None if not cached
-        """
-        if tool_name not in self._cache:
-            return None
-        
-        cached = self._cache[tool_name]
-        return {
-            'tool_name': cached.tool_name,
-            'created_at': cached.created_at,
-            'last_shown': cached.last_shown,
-            'show_count': cached.show_count,
-            'needs_refresh': cached.needs_refresh
-        }
-    
-    # Callback setters
-    def set_on_widget_created(self, callback: Callable[[str, tk.Widget], None]) -> None:
-        """Set callback for when a widget is created."""
-        self._on_widget_created = callback
-    
-    def set_on_widget_shown(self, callback: Callable[[str, tk.Widget], None]) -> None:
-        """Set callback for when a widget is shown."""
-        self._on_widget_shown = callback
-    
-    def set_on_widget_hidden(self, callback: Callable[[str, tk.Widget], None]) -> None:
-        """Set callback for when a widget is hidden."""
-        self._on_widget_hidden = callback
-
-
-# Global instance
-_widget_cache: Optional[WidgetCache] = None
-
-
-def get_widget_cache() -> Optional[WidgetCache]:
-    """Get the global widget cache instance."""
-    return _widget_cache
-
-
-def init_widget_cache(parent_frame: tk.Frame,
-                      strategy: CacheStrategy = CacheStrategy.ALWAYS,
-                      max_cached: int = 20) -> WidgetCache:
-    """
-    Initialize the global widget cache.
-    
-    Args:
-        parent_frame: Parent frame for widgets
-        strategy: Caching strategy
-        max_cached: Maximum cached widgets (for LRU)
-        
-    Returns:
-        Initialized WidgetCache
-    """
-    global _widget_cache
-    _widget_cache = WidgetCache(parent_frame, strategy, max_cached)
-    return _widget_cache
-
-
-def shutdown_widget_cache() -> None:
-    """Shutdown the global widget cache."""
-    global _widget_cache
-    if _widget_cache is not None:
-        _widget_cache.clear()
-        _widget_cache = None
-
+"""
+Widget Cache - Caches tool widgets to avoid recreation on tool switching.
+
+Instead of destroying and recreating widgets on every tool switch,
+this cache hides/shows widgets as needed, improving performance.
+
+Author: Pomera AI Commander Team
+"""
+
+import tkinter as tk
+from tkinter import ttk
+from typing import Dict, Optional, Callable, Any, Set, List
+import logging
+import weakref
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+logger = logging.getLogger(__name__)
+
+
+class CacheStrategy(Enum):
+    """Widget caching strategies."""
+    ALWAYS = "always"        # Always cache (default)
+    ON_DEMAND = "on_demand"  # Cache only when explicitly requested
+    NEVER = "never"          # Never cache (always recreate)
+    LRU = "lru"              # Least Recently Used eviction
+
+
+@dataclass
+class CachedWidget:
+    """
+    Information about a cached widget.
+    
+    Attributes:
+        widget: The actual Tkinter widget
+        tool_name: Name of the tool this widget belongs to
+        created_at: Timestamp when widget was created
+        last_shown: Timestamp when widget was last shown
+        show_count: Number of times widget has been shown
+        needs_refresh: Whether widget needs to be refreshed on next show
+    """
+    widget: tk.Widget
+    tool_name: str
+    created_at: float = 0.0
+    last_shown: float = 0.0
+    show_count: int = 0
+    needs_refresh: bool = False
+    
+    def mark_shown(self) -> None:
+        """Mark widget as shown."""
+        import time
+        self.last_shown = time.time()
+        self.show_count += 1
+
+
+class WidgetCache:
+    """
+    Caches tool widgets to improve tool switching performance.
+    
+    Instead of destroying and recreating widgets on every tool switch,
+    this cache hides/shows widgets as needed. This significantly improves
+    the user experience when switching between tools frequently.
+    
+    Usage:
+        cache = WidgetCache(parent_frame)
+        
+        # Register widget factories
+        cache.register_factory("Case Tool", lambda: create_case_tool_widget())
+        cache.register_factory("AI Tools", lambda: create_ai_tools_widget())
+        
+        # Switch to a tool (creates widget if not cached, shows it)
+        cache.show("Case Tool")
+        
+        # Switch to another tool (hides Case Tool, shows AI Tools)
+        cache.show("AI Tools")
+        
+        # Force refresh a widget on next show
+        cache.invalidate("Case Tool")
+    """
+    
+    def __init__(self, 
+                 parent_frame: tk.Frame,
+                 strategy: CacheStrategy = CacheStrategy.ALWAYS,
+                 max_cached: int = 20,
+                 logger: Optional[logging.Logger] = None):
+        """
+        Initialize the widget cache.
+        
+        Args:
+            parent_frame: The frame where tool widgets are displayed
+            strategy: Caching strategy to use
+            max_cached: Maximum number of widgets to cache (for LRU)
+            logger: Logger instance
+        """
+        self.parent_frame = parent_frame
+        self.strategy = strategy
+        self.max_cached = max_cached
+        self.logger = logger or logging.getLogger(__name__)
+        
+        # Widget storage
+        self._cache: Dict[str, CachedWidget] = {}
+        self._factories: Dict[str, Callable[[], tk.Widget]] = {}
+        self._current_tool: Optional[str] = None
+        
+        # Tools that should never be cached
+        self._never_cache: Set[str] = set()
+        
+        # Callbacks
+        self._on_widget_created: Optional[Callable[[str, tk.Widget], None]] = None
+        self._on_widget_shown: Optional[Callable[[str, tk.Widget], None]] = None
+        self._on_widget_hidden: Optional[Callable[[str, tk.Widget], None]] = None
+        
+        # Statistics
+        self._stats = {
+            'cache_hits': 0,
+            'cache_misses': 0,
+            'widgets_created': 0,
+            'widgets_destroyed': 0
+        }
+    
+    def register_factory(self, 
+                        tool_name: str, 
+                        factory: Callable[[], tk.Widget],
+                        never_cache: bool = False) -> None:
+        """
+        Register a factory function for creating a tool's widget.
+        
+        Args:
+            tool_name: Name of the tool
+            factory: Function that creates and returns the widget
+            never_cache: If True, widget will always be recreated
+        """
+        self._factories[tool_name] = factory
+        if never_cache:
+            self._never_cache.add(tool_name)
+        self.logger.debug(f"Registered factory for: {tool_name}")
+    
+    def unregister_factory(self, tool_name: str) -> bool:
+        """
+        Unregister a factory function.
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            True if factory was found and removed
+        """
+        if tool_name in self._factories:
+            del self._factories[tool_name]
+            self._never_cache.discard(tool_name)
+            return True
+        return False
+    
+    def get_or_create(self, tool_name: str) -> Optional[tk.Widget]:
+        """
+        Get a cached widget or create it if not cached.
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            The tool's widget, or None if no factory registered
+        """
+        # Check if we should never cache this tool
+        should_cache = (
+            self.strategy != CacheStrategy.NEVER and
+            tool_name not in self._never_cache
+        )
+        
+        # Return cached widget if available and valid
+        if tool_name in self._cache and should_cache:
+            cached = self._cache[tool_name]
+            if not cached.needs_refresh:
+                self._stats['cache_hits'] += 1
+                self.logger.debug(f"Cache hit for: {tool_name}")
+                return cached.widget
+            else:
+                # Widget needs refresh, destroy and recreate
+                self._destroy_widget(tool_name)
+        
+        self._stats['cache_misses'] += 1
+        
+        # Check if we have a factory
+        if tool_name not in self._factories:
+            self.logger.warning(f"No factory registered for tool: {tool_name}")
+            return None
+        
+        # Enforce max cache size (LRU eviction)
+        if self.strategy == CacheStrategy.LRU and len(self._cache) >= self.max_cached:
+            self._evict_lru()
+        
+        # Create new widget
+        try:
+            widget = self._factories[tool_name]()
+            
+            if should_cache:
+                import time
+                self._cache[tool_name] = CachedWidget(
+                    widget=widget,
+                    tool_name=tool_name,
+                    created_at=time.time()
+                )
+            
+            self._stats['widgets_created'] += 1
+            self.logger.debug(f"Created widget for: {tool_name}")
+            
+            # Callback
+            if self._on_widget_created:
+                self._on_widget_created(tool_name, widget)
+            
+            return widget
+            
+        except Exception as e:
+            self.logger.error(f"Failed to create widget for {tool_name}: {e}")
+            return None
+    
+    def show(self, tool_name: str) -> bool:
+        """
+        Show the widget for the specified tool, hiding others.
+        
+        Args:
+            tool_name: Name of the tool to show
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        # Hide current widget
+        if self._current_tool and self._current_tool != tool_name:
+            self._hide_current()
+        
+        # Get or create the new widget
+        widget = self.get_or_create(tool_name)
+        if widget is None:
+            return False
+        
+        # Show the new widget
+        try:
+            widget.pack(fill=tk.BOTH, expand=True)
+            self._current_tool = tool_name
+            
+            # Update cached widget stats
+            if tool_name in self._cache:
+                self._cache[tool_name].mark_shown()
+            
+            # Callback
+            if self._on_widget_shown:
+                self._on_widget_shown(tool_name, widget)
+            
+            self.logger.debug(f"Showing widget: {tool_name}")
+            return True
+            
+        except tk.TclError as e:
+            self.logger.error(f"Failed to show widget {tool_name}: {e}")
+            # Widget might be destroyed, remove from cache
+            self._cache.pop(tool_name, None)
+            return False
+    
+    def hide(self, tool_name: str) -> bool:
+        """
+        Hide a specific tool's widget.
+        
+        Args:
+            tool_name: Name of the tool to hide
+            
+        Returns:
+            True if widget was hidden
+        """
+        if tool_name not in self._cache:
+            return False
+        
+        try:
+            self._cache[tool_name].widget.pack_forget()
+            
+            if self._current_tool == tool_name:
+                self._current_tool = None
+            
+            # Callback
+            if self._on_widget_hidden:
+                self._on_widget_hidden(tool_name, self._cache[tool_name].widget)
+            
+            return True
+            
+        except tk.TclError:
+            # Widget might be destroyed
+            self._cache.pop(tool_name, None)
+            return False
+    
+    def _hide_current(self) -> None:
+        """Hide the currently shown widget."""
+        if self._current_tool and self._current_tool in self._cache:
+            try:
+                self._cache[self._current_tool].widget.pack_forget()
+                
+                if self._on_widget_hidden:
+                    self._on_widget_hidden(
+                        self._current_tool, 
+                        self._cache[self._current_tool].widget
+                    )
+            except tk.TclError:
+                # Widget might be destroyed
+                self._cache.pop(self._current_tool, None)
+    
+    def invalidate(self, tool_name: str) -> None:
+        """
+        Mark a widget for refresh (will be recreated on next show).
+        
+        Args:
+            tool_name: Name of the tool to invalidate
+        """
+        if tool_name in self._cache:
+            self._cache[tool_name].needs_refresh = True
+            self.logger.debug(f"Invalidated cache for: {tool_name}")
+    
+    def destroy(self, tool_name: str) -> bool:
+        """
+        Destroy a cached widget immediately.
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            True if widget was found and destroyed
+        """
+        return self._destroy_widget(tool_name)
+    
+    def _destroy_widget(self, tool_name: str) -> bool:
+        """Internal method to destroy a widget."""
+        if tool_name not in self._cache:
+            return False
+        
+        try:
+            self._cache[tool_name].widget.destroy()
+        except tk.TclError:
+            pass  # Already destroyed
+        
+        del self._cache[tool_name]
+        self._stats['widgets_destroyed'] += 1
+        
+        if self._current_tool == tool_name:
+            self._current_tool = None
+        
+        self.logger.debug(f"Destroyed widget: {tool_name}")
+        return True
+    
+    def _evict_lru(self) -> None:
+        """Evict the least recently used widget."""
+        if not self._cache:
+            return
+        
+        # Don't evict current widget
+        candidates = [
+            (name, cached) for name, cached in self._cache.items()
+            if name != self._current_tool
+        ]
+        
+        if not candidates:
+            return
+        
+        # Find LRU
+        lru_name, _ = min(candidates, key=lambda x: x[1].last_shown)
+        self._destroy_widget(lru_name)
+        self.logger.debug(f"Evicted LRU widget: {lru_name}")
+    
+    def clear(self) -> None:
+        """Clear all cached widgets."""
+        for tool_name in list(self._cache.keys()):
+            self._destroy_widget(tool_name)
+        self._current_tool = None
+        self.logger.debug("Cleared all cached widgets")
+    
+    def refresh_all(self) -> None:
+        """Mark all widgets for refresh."""
+        for cached in self._cache.values():
+            cached.needs_refresh = True
+        self.logger.debug("Marked all widgets for refresh")
+    
+    def is_cached(self, tool_name: str) -> bool:
+        """Check if a tool's widget is cached."""
+        return tool_name in self._cache
+    
+    def get_widget(self, tool_name: str) -> Optional[tk.Widget]:
+        """
+        Get a cached widget without creating it.
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            The widget if cached, None otherwise
+        """
+        if tool_name in self._cache:
+            return self._cache[tool_name].widget
+        return None
+    
+    @property
+    def cached_tools(self) -> List[str]:
+        """Get list of currently cached tool names."""
+        return list(self._cache.keys())
+    
+    @property
+    def current_tool(self) -> Optional[str]:
+        """Get the currently displayed tool name."""
+        return self._current_tool
+    
+    @property
+    def factory_count(self) -> int:
+        """Get number of registered factories."""
+        return len(self._factories)
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        total_requests = self._stats['cache_hits'] + self._stats['cache_misses']
+        hit_rate = (
+            self._stats['cache_hits'] / total_requests * 100
+            if total_requests > 0 else 0
+        )
+        
+        return {
+            **self._stats,
+            'cached_widgets': len(self._cache),
+            'registered_factories': len(self._factories),
+            'current_tool': self._current_tool,
+            'hit_rate_percent': round(hit_rate, 2),
+            'strategy': self.strategy.value
+        }
+    
+    def get_cache_info(self, tool_name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get information about a cached widget.
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            Dictionary with cache info, or None if not cached
+        """
+        if tool_name not in self._cache:
+            return None
+        
+        cached = self._cache[tool_name]
+        return {
+            'tool_name': cached.tool_name,
+            'created_at': cached.created_at,
+            'last_shown': cached.last_shown,
+            'show_count': cached.show_count,
+            'needs_refresh': cached.needs_refresh
+        }
+    
+    # Callback setters
+    def set_on_widget_created(self, callback: Callable[[str, tk.Widget], None]) -> None:
+        """Set callback for when a widget is created."""
+        self._on_widget_created = callback
+    
+    def set_on_widget_shown(self, callback: Callable[[str, tk.Widget], None]) -> None:
+        """Set callback for when a widget is shown."""
+        self._on_widget_shown = callback
+    
+    def set_on_widget_hidden(self, callback: Callable[[str, tk.Widget], None]) -> None:
+        """Set callback for when a widget is hidden."""
+        self._on_widget_hidden = callback
+
+
+# Global instance
+_widget_cache: Optional[WidgetCache] = None
+
+
+def get_widget_cache() -> Optional[WidgetCache]:
+    """Get the global widget cache instance."""
+    return _widget_cache
+
+
+def init_widget_cache(parent_frame: tk.Frame,
+                      strategy: CacheStrategy = CacheStrategy.ALWAYS,
+                      max_cached: int = 20) -> WidgetCache:
+    """
+    Initialize the global widget cache.
+    
+    Args:
+        parent_frame: Parent frame for widgets
+        strategy: Caching strategy
+        max_cached: Maximum cached widgets (for LRU)
+        
+    Returns:
+        Initialized WidgetCache
+    """
+    global _widget_cache
+    _widget_cache = WidgetCache(parent_frame, strategy, max_cached)
+    return _widget_cache
+
+
+def shutdown_widget_cache() -> None:
+    """Shutdown the global widget cache."""
+    global _widget_cache
+    if _widget_cache is not None:
+        _widget_cache.clear()
+        _widget_cache = None
+