widget_utilities.py

"""
Widget utilities base class for PySide6 widgets.

Provides standard initialization patterns and debug utilities.
"""

from PySide6 import QtWidgets, QtCore, QtGui
from contextlib import contextmanager
import sys
import base64
from io import BytesIO
from PIL import Image
import matplotlib.pyplot as plt
from loguru import logger


# For demo purposes, we'll redefine the class here in this notebook. In practical usage, you'd import:
# from pyside_refrances.widget_utilities import WidgetUtilities


# Helper functions:
def close_qt_windows():
    """
    Close all visible top-level Qt windows.
    
    Iterates through all top-level widgets in the application and closes
    any that are currently visible. Useful for cleaning up during
    interactive development in notebooks.
    
    Returns:
        int: Number of windows closed
    """
    closed_count = 0
    
    for widget in QtWidgets.QApplication.topLevelWidgets():
        if widget.isVisible():
            logger.debug(f"Closing widget: {widget.objectName() or widget.__class__.__name__}")
            widget.close()
            closed_count += 1
    
    if closed_count:
        logger.info(f"Closed {closed_count} Qt window(s)")
    else:
        logger.debug("No visible Qt windows to close")
        
    return closed_count



# For demo purposes, we'll redefine the class here in this notebook. In practical usage, you'd import:
# from pyside_refrances.widget_utilities import WidgetUtilities



class WidgetUtilities:
    """
    Abstract base class providing common widget utilities and initialization structure.
    
    Provides debug tools for widget inspection and a standard initialization sequence
    for GUI widgets. Subclasses must implement the abstract initialization methods.
    """

    # ==================================
    # === GUI Setup Abstract Methods ===
    # ==================================

    def _widget_startup_init_calls(self):
        """Call all GUI initialization methods in the proper sequence."""
        self.gui_layout_init()
        self.gui_sizing_init()
        self.gui_styling_init()
        self.gui_wiring_init()

    def gui_layout_init(self):
        """Initialize and arrange all GUI elements."""
        raise NotImplementedError("Subclass must implement gui_layout_init")

    def gui_sizing_init(self):
        """Set widget size constraints and properties."""
        raise NotImplementedError("Subclass must implement gui_sizing_init")

    def gui_styling_init(self):
        """Apply widget styling and appearance settings."""
        raise NotImplementedError("Subclass must implement gui_styling_init")

    def gui_wiring_init(self):
        """Connect widget signals to their slots."""
        raise NotImplementedError("Subclass must implement gui_wiring_init")


    # ========================
    # === Usage Utilities ===
    # ========================
    
    @contextmanager
    def temp_block_widgets_signals(self, *widgets):
        """
        Context manager to temporarily block signals for multiple widgets.
        
        Blocks all signals from the specified widgets for the duration of the
        context, then restores their previous signal state. Useful for preventing
        circular signal emission when programmatically updating widget values.
        
        Args:
            *widgets: Variable number of QWidget instances to block
            
        Example:
            with self.temp_block_widgets_signals(self.lineEdit, self.comboBox):
                self.lineEdit.setText("new value")
                self.comboBox.setCurrentIndex(2)
                # No signals emitted from these widgets during this block
                
        Note:
            If a widget was already blocking signals before entering the context,
            it will remain blocked after exiting.
        """
        # Store original signal blocking states
        original_states = []
        
        for widget in widgets:
            if isinstance(widget, QtCore.QObject):  # Check it's a Qt object
                original_states.append((widget, widget.blockSignals(True)))
            else:
                logger.warning(f"Skipping non-QObject: {widget}")
                original_states.append((widget, None))
        
        try:
            yield
        finally:
            # Restore original signal blocking states
            for widget, original_state in original_states:
                if original_state is not None:  # Was a valid QObject
                    widget.blockSignals(original_state)
    
    
    # ===================
    # === Debug Tools ===
    # ===================
    
    def set_debug_tooltips(self):
        """
        Set debug tooltips on all widgets showing their variable names.
        
        If a widget already has a tooltip, appends debug info to it.
        Otherwise, sets the debug tooltip directly.
        """
        for attr_name in dir(self):
            attr = getattr(self, attr_name, None)
            if isinstance(attr, QtWidgets.QWidget):
                debug_info = f"Widget: {attr_name}\nType: {type(attr).__name__}"
                
                existing_tooltip = attr.toolTip()
                if existing_tooltip:
                    # Append debug info to existing tooltip
                    attr.setToolTip(f"{existing_tooltip}\n\n--- Debug Info ---\n{debug_info}")
                else:
                    # No existing tooltip, just set debug info
                    attr.setToolTip(debug_info)
        
        if isinstance(self, QtWidgets.QWidget):
            debug_info = f"Widget: {self.__class__.__name__}"
            existing_tooltip = self.toolTip()
            
            if existing_tooltip:
                self.setToolTip(f"{existing_tooltip}\n\n--- Debug Info ---\n{debug_info}")
            else:
                self.setToolTip(debug_info)
    
    def capture_widget_info(self):
        """
        Capture widget images and locations for automation.
        
        Iterates through all visible QWidget attributes and captures their
        screen position, size, and appearance. Intended for future use with
        pyautogui or similar automation tools.
        
        Returns:
            dict: Widget information indexed by attribute name. Each entry contains:
                {
                    'location': tuple[int, int],  # (x, y) global screen coordinates of the top-left corner
                    'size': tuple[int, int],      # (width, height) in pixels
                    'image_base64': str,          # Base64 encoded PNG image
                    'type': str                   # Widget class name (e.g., 'QPushButton')
                }
                
        Example:
            >>> info = widget.capture_widget_info()
            >>> info['self']['type']  # The parent widget itself
            'FileFolderSelectorQWidget'
            >>> info['submit_QPushButton']['location']
            (100, 200)
        """
        widget_info = {}
        
        # First, capture the parent widget itself if it's a QWidget
        if isinstance(self, QtWidgets.QWidget) and self.isVisible():
            # Get screen position of widget's top-left corner
            global_pos = self.mapToGlobal(QtCore.QPoint(0, 0))
            location = (global_pos.x(), global_pos.y())
            size = (self.width(), self.height())
            
            # Create a pixmap (off-screen image) of the widget's size
            pixmap = QtGui.QPixmap(self.size())
            # Render the widget's visual appearance into the pixmap
            self.render(pixmap)
            
            # Convert pixmap to base64 string for storage/transmission
            byte_array = QtCore.QByteArray()
            buffer = QtCore.QBuffer(byte_array)
            buffer.open(QtCore.QIODevice.WriteOnly)
            pixmap.save(buffer, "PNG")  # Save pixmap as PNG into buffer
            base64_str = base64.b64encode(byte_array.data()).decode()
            
            widget_info['self'] = {
                'location': location,
                'size': size,
                'image_base64': base64_str,
                'type': type(self).__name__
            }
        
        # Then capture all child widgets
        for attr_name in dir(self):
            attr = getattr(self, attr_name, None)
            if isinstance(attr, QtWidgets.QWidget) and attr.isVisible():
                # Get widget's position in global screen coordinates
                global_pos = attr.mapToGlobal(QtCore.QPoint(0, 0))
                location = (global_pos.x(), global_pos.y())
                size = (attr.width(), attr.height())
                
                # Create pixmap and render widget appearance
                pixmap = QtGui.QPixmap(attr.size())
                attr.render(pixmap)
                
                # Convert to base64 for easy storage/transmission
                byte_array = QtCore.QByteArray()
                buffer = QtCore.QBuffer(byte_array)
                buffer.open(QtCore.QIODevice.WriteOnly)
                pixmap.save(buffer, "PNG")
                base64_str = base64.b64encode(byte_array.data()).decode()
                
                widget_info[attr_name] = {
                    'location': location,
                    'size': size,
                    'image_base64': base64_str,
                    'type': type(attr).__name__
                }
        
        return widget_info

    @staticmethod
    def show_widget_image(widget_info, widget_name):
        """
        Display captured widget image with formatted metadata.
        
        Args:
            widget_info: Dictionary from capture_widget_info()
            widget_name: Name of widget to display
        """
        img_data = base64.b64decode(widget_info[widget_name]['image_base64'])
        img = Image.open(BytesIO(img_data))
        
        # Create figure with better spacing
        fig, ax = plt.subplots(figsize=(8, 5))
        
        # Display image
        ax.imshow(img)
        ax.axis('off')
        
        # Add border around image
        ax.add_patch(plt.Rectangle((0, 0), img.width-1, img.height-1, 
                                  fill=False, edgecolor='gray', linewidth=2))
        
        # Format widget info
        info = widget_info[widget_name]
        
        # Main title - widget name and type
        ax.set_title(f"{widget_name} ({info['type']})", 
                    fontsize=14, fontweight='bold', pad=10)
        
        # Subtitle with location and size info
        location_text = f"Widget Top-Left corner location in screen space: {info['location']} • Size: {info['size'][0]}×{info['size'][1]}px"
        fig.text(0.5, 0.92, location_text, 
                ha='center', fontsize=10, color='gray')
        
        # Tighten layout
        plt.tight_layout()
        plt.subplots_adjust(top=0.85)
        
        plt.show()