Package QFlow

def app(
    **kwargs
):
    """
    Initializes the App with application-specific settings.

    Args:
        title (str): The title to set for the application window.
        geometry (list): The window geometry as a list [x, y, width, height].
        icon (QIcon): Callable of the icon to set for the window.
        name (str, optional): The name of the application window. Defaults to "App".
        template (QWidget): Callable of custom QWidget as a template. It needs to have a QStackedWidgets named 'screens' in order to render the screens there.
        resizable (bool, optional): Determines whether the window can be resized. Defaults to True.
        maximizable (bool, optional): Determines whether the window can be maximized. Defaults to True.
        strictClosingWindows (bool, optional): Determines whether all windows should be closed when the main window is closed. Defaults to True.
        opacity (float, optional): The opacity of the window. Defaults to 1.0.
        frameless (bool, optional): It can delete the window frame.
    """
    config = asdict(WindowParams(**kwargs))

    def decorator(cls):
        originit = getattr(cls, '__init__', None)

        def newinit(self, *args, **kwargs):
            super(cls, self).__init__(
                **config
            )

            self.args = deepcopy(config)

            if originit:
                originit(self, *args, **kwargs)

        cls.__init__ = newinit
        return cls

    return decorator

def screen(**kwargs):
    """
    Initialize the Screen object.
        
    Args:
        name (str): The name to assign to the screen.
        autoreloadUI (bool): If True, ensures the class has a `UI` method and reloads it on show.
        autoUI (bool): Executes the UI function during the showEvent without having to call it.
        parentType: Expected parent type for validation.
        *args: Additional positional arguments.
        **kwargs: Additional keyword arguments.
    """
    config = asdict(ScreenParams(**kwargs))

    def decorator(cls):
        originit = getattr(cls, '__init__', None)

        def newinit(self, *args, **kwargs):
            super(cls, self).__init__(
                **config
            )

            self.args = deepcopy(config)

            if originit:
                originit(self, *args, **kwargs)

        cls.__init__ = newinit
        return cls

    return decorator

def window(
    **kwargs
):
    config = asdict(WindowParams(**kwargs))

    def decorator(cls):
        originit = getattr(cls, '__init__', None)

        def newinit(self, *args, **kwargs):
            super(cls, self).__init__(
                **config
            )

            self.args = deepcopy(config)

            if originit:
                originit(self, *args, **kwargs)

        cls.__init__ = newinit
        return cls

    return decorator

class App(Window):
    """
    An application class that extends Window functionality for main application windows.
    
    This class provides all the functionality of a Window plus additional application-level
    features like strict window management and enhanced screen handling.
    """
    
    def __init__(
        self,
        **kwargs
    ):
        """
        Initializes the App with application-specific settings.

        Args:
            title (str): The title to set for the application window.
            geometry (list): The window geometry as a list [x, y, width, height].
            icon (QIcon): Callable of the icon to set for the window.
            name (str, optional): The name of the application window. Defaults to "App".
            template (QWidget): Callable of custom QWidget as a template. It needs to have a QStackedWidgets named 'screens' in order to render the screens there.
            resizable (bool, optional): Determines whether the window can be resized. Defaults to True.
            maximizable (bool, optional): Determines whether the window can be maximized. Defaults to True.
            strictClosingWindows (bool, optional): Determines whether all windows should be closed when the main window is closed. Defaults to True.
            opacity (float, optional): The opacity of the window. Defaults to 1.0.
            frameless (bool, optional): It can delete the window frame.
        """
        # Initialize the parent Window class

        self.windowParams = WindowParams(**kwargs)

        super().__init__(
            **asdict(self.windowParams)
        )
        
        # Application-specific properties
        self.maximizable = self.windowParams.maximizable
        
        # Configure window properties
        self.configureWindowProperties(
            self.windowParams.resizable, 
            self.windowParams.maximizable, 
            self.windowParams.geometry
        )
        
        # Set up close event handler
        self.closeEvent = lambda event: self.onWindowClose(event, self.name)

    def configureWindowProperties(self, resizable: bool, maximizable: bool, geometry: list[int]) -> None:
        """
        Configures window properties based on the provided settings.
        
        Args:
            resizable (bool): Whether the window should be resizable.
            maximizable (bool): Whether the window should be maximizable.
            geometry (list[int]): The window geometry.
        """
        if not resizable:
            # The last two indices of the geometry are width and height
            width, height = geometry[-2:]
            self.setFixedSize(width, height)
            self.setWindowFlags(Qt.WindowType.WindowMinimizeButtonHint | Qt.WindowType.WindowCloseButtonHint)
        
        if not maximizable:
            currentFlags = self.windowFlags()
            # Remove maximize button while keeping other flags
            newFlags = currentFlags & ~Qt.WindowType.WindowMaximizeButtonHint
            self.setWindowFlags(newFlags | Qt.WindowType.WindowMinimizeButtonHint | Qt.WindowType.WindowCloseButtonHint)
    
    def run(self, QApp: QApplication):
        self.show()
        sys.exit(QApp.exec())

class Screen(QWidget):
    """
    A class that provides screen properties and screen management capabilities.
    Can be used as a base class or through composition.
    """
    
    def __init__(self, **kwargs):
        """
        Initialize the Screen object.
        
        Args:
            name (str): The name to assign to the screen.
            autoreloadUI (bool): If True, ensures the class has a `UI` method and reloads it on show.
            autoUI (bool): Executes the UI function during __init__ without having to call it.
            parentType: Expected parent type for validation.
            *args: Additional positional arguments.
            **kwargs: Additional keyword arguments.
        """
        self.kwargs = ScreenParams(**kwargs)

        super().__init__(self.kwargs.parent)
        
        self.name = self.kwargs.name

        self.args = {}
        """
        Dictionary with the arguments passed from the screen decorator.
        """
        
        self.screenName = self.name
        self.parentType = self.kwargs.parentType
        self.autoreloadUI = self.kwargs.autoreloadUI
        self.autoUI = self.kwargs.autoUI
        self.loaded = False
        
        if self.kwargs.autoreloadUI:
            # Check if the class has a UI method
            if not hasattr(self, 'UI') or not callable(getattr(self, 'UI')):
                raise TypeError(f"The class '{self.__class__.__name__}' must have a UI() method.")
        
        # Store original parent method if it exists
        if hasattr(super(), 'parent'):
            originalParent = super().parent
            # Get the real parent, not the QStackedWidget
            parent = originalParent()
            self.parent = lambda: parent
        
        # Validate parent type if specified
        if self.kwargs.parentType is not None and hasattr(self, 'parent'):
            parent = self.parent()
            if parent and hasattr(parent, '__class__') and hasattr(parent.__class__, '__bases__'):
                if parent.__class__.__bases__[0] != self.kwargs.parentType:
                    raise TypeError(
                        f"Screen '{self.kwargs.name}' only accepts the parentType '{self.kwargs.parentType}' not '{parent.__class__.__bases__[0]}'."
                    )
                       
    def parent(self) -> Window: ...
    
    @staticmethod
    def removeAllLayouts(widget: QWidget):
        """
        Recursively removes all layouts and widgets from a given QWidget.

        Args:
            widget (QWidget): The widget from which all layouts and child widgets will be removed.
        """
        layout = widget.layout()
        
        if layout is not None:
            while layout.count():
                item = layout.takeAt(0)
                if item.widget():
                    item.widget().setParent(None)
                if item.layout():
                    Screen.removeAllLayouts(item.layout())

            layout.deleteLater()
    
    def reloadUI(self):
        """
        Reloads the interface.
        """
        if not hasattr(self, 'UI') or not callable(getattr(self, 'UI')):
            raise TypeError(f"The class '{self.__class__.__name__}' must have a UI() method")
        
        Screen.removeAllLayouts(self)
        QTimer.singleShot(0, lambda: self.UI())
    
    def setScreenName(self, name: str) -> None:
        """
        Changes the name of the screen.
        
        Args:
            name (str): The new name for the screen.
            
        Raises:
            ValueError: If name is empty or not a string.
        """
        if not name:
            raise ValueError("Screen name must be a non-empty string.")
        
        self.name = name
        self.screenName = name
    
    def showEvent(self, event):
        """
        Override showEvent to handle UI reloading and effects.
        
        Args:
            event: The show event.
        """
        if self.autoreloadUI:
            # Reload the UI after a short delay. Note: This line cost me 5 hours of debugging.
            QTimer.singleShot(0, lambda: self.reloadUI())

        if not self.autoreloadUI and self.autoUI and not self.loaded:
            # Execute the UI if autoUI
            QTimer.singleShot(0, lambda: self.UI())
            # Specifies that the screen has already been loaded
            self.loaded = True

        if hasattr(self, 'effect'):
            self.effect()

        # Call parent's showEvent if it exists
        if hasattr(super(), 'showEvent'):
            super().showEvent(event)

class Template(QWidget):
    """
    A class that represents a custom template for screens; its main characteristic is having a parent Window.
    """
    def __init__(self, parent):
        super().__init__(parent)

        self.parent: Callable[[], Window] = lambda: parent

class Window(QMainWindow):
    """
    A window class that provides window properties and screen management capabilities.

    This class allows you to configure the title, geometry, and icon of a window,
    while also providing built-in screen management functionality.
    """
    
    def __init__(
        self,
        **kwargs
    ):
        """
        Initializes the Window with specified properties and screen management.

        Args:
            name (str): The name of the window.
            title (str): The title of the window.
            geometry (list): The geometry of the window (ax: int, ay: int, aw: int, ah: int).
            maximizable (bool, optional): Determines whether the window can be maximized. Defaults to True.
            icon (QIcon): Callable of the icon to set for the window.
            template (QWidget): Callable of custom QWidget as a template. It needs to have a QStackedWidgets named 'screens' in order to render the screens there.
            parent: Parent widget.
            parentType: Expected parent type for validation.
            resizable (bool, optional): The ability to resize the window. Defaults to True.
            strictClosingWindows (bool, optional): Determines whether all windows should be closed when the window is closed. Defaults to True.
            opacity (float, optional): The opacity of the window.
            frameless (bool, optional): It can delete the window frame.
        """
        self.kwargs = WindowParams(**kwargs)

        super().__init__(self.kwargs.parent)
        
        # Initialize window properties
        self.name = self.kwargs.name
        self.title = self.kwargs.title
        self.windowGeometry = self.kwargs.geometry
        self.icon = self.kwargs.icon
        self.frameless = self.kwargs.frameless
        self.template = self.kwargs.template

        self.args = {}
        """
        Dictionary with the arguments passed from the window decorator.
        """
        
        # Initialize screen management
        self.screenHistory = []
        self.screens = {}
        self.windows = {}
        self.strictClosingWindows = self.kwargs.strictClosingWindows
        
        # Configure window
        self.setWindowTitle(self.title)
        self.setGeometry(*self.windowGeometry)

        if not self.kwargs.resizable:
            # The last two indices of the geometry are width and height
            width, height = self.kwargs.geometry[-2:]
            self.setFixedSize(width, height)
            self.setWindowFlags(Qt.WindowType.WindowMinimizeButtonHint | Qt.WindowType.WindowCloseButtonHint)

        if not self.kwargs.maximizable:
            currentFlags = self.windowFlags()
            # Remove maximize button while keeping other flags
            newFlags = currentFlags & ~Qt.WindowType.WindowMaximizeButtonHint
            self.setWindowFlags(newFlags | Qt.WindowType.WindowMinimizeButtonHint | Qt.WindowType.WindowCloseButtonHint)

        # Do that frameless
        if self.frameless:
            self.setWindowFlags(Qt.FramelessWindowHint)

        if self.kwargs.icon is not None:
            self.setWindowIcon(self.kwargs.icon())

        # Find and set the QStackedWidget in the custom template
        if self.template is not None:
            # Initialize template
            self.template: QWidget = self.kwargs.template(self)

            self.stackedScreens = self.template.findChild(QWidget, 'screens')

            # Raise
            if self.stackedScreens is None:
                raise Exception("Undefined 'screens' in your template.")

            self.setCentralWidget(self.template)
        else:
            self.stackedScreens = QStackedWidget()
            # Set normal
            self.setCentralWidget(self.stackedScreens)

        if self.kwargs.opacity != 1.0:
            self.setWindowOpacity(self.kwargs.opacity)

        self.opacity = self.kwargs.opacity

        # Validate parent type if specified
        if self.kwargs.parentType is not None and self.kwargs.parent is not None:
            if type(self.kwargs.parent) != self.kwargs.parentType:
                raise TypeError(
                    f"Window '{self.kwargs.name}' only accepts the parentType '{self.kwargs.parentType}' not '{type(self.kwargs.parent)}'."
                )

    def addScreen(self, screen: QWidget) -> None:
        """
        Adds a screen widget to the window's stacked widget.

        This method checks that the screen has a valid 'screenName' attribute and adds it 
        to the stacked widget for navigation.

        Args:
            screen (QWidget): The screen widget to add to the stacked widget.

        Raises:
            Exception: If the screen does not have a 'screenName' attribute.
        """
        if not hasattr(screen, 'screenName'):
            raise Exception(f"'{screen}' does not have screenName attribute.")
        
        name = screen.screenName
        self.screens[name] = screen
        self.stackedScreens.addWidget(screen)

    def setScreen(self, name: str, args: dict = None) -> None:
        """
        Sets the current screen to display based on the screen name.

        This method accepts a string name that must match the 'screenName' attribute
        of a previously added screen.

        Args:
            name (str): The name of the screen to display.
            args (dict): Arguments for the screen.

        Raises:
            Exception: If the specified screen does not exist.
        """
        if name in self.screens:
            currentScreen = self.stackedScreens.currentWidget()
            if currentScreen:
                self.screenHistory.append(currentScreen)

            screen = self.screens[name]
            if not hasattr(screen, 'screenName'):
                raise Exception(f"The screen '{screen}' does not have screenName attribute.")
            
            if args:
                INSTANCEARGS.setArgs(instance=screen, args=args)
            
            self.stackedScreens.setCurrentWidget(screen)      
        else:
            raise Exception(f"The screen '{name}' does not exist.")
            
    def goBack(self) -> None:
        """
        Navigates back to the previous screen in the screen history.
        """
        if self.screenHistory:
            previousScreen = self.screenHistory.pop()
            self.stackedScreens.setCurrentWidget(previousScreen)
    
    def setWindowName(self, name: str) -> None:
        """
        Changes the name of the window.
        
        Args:
            name (str): The new name for the window.
            
        Raises:
            ValueError: If name is empty or not a string.
        """
        if not name:
            raise ValueError("Window name must be a non-empty string.")
        
        self.name = name

    def showEvent(self, event):
        """   
        Args:
            event: The show event.
        """

        if hasattr(self, 'effect'):
            self.effect()

            # QMainWindow always has showEvent
            super().showEvent(event)

    def existScreen(self, name: str) -> bool:
        """
        Checks if a screen exists in the window.

        Args:
            name (str): The name of the screen.
        Returns:
            bool: True if the screen exists, False if it does not exist.
        """
        return name in self.screens

    def reloadScreens(self) -> None:
        """
        Reloads all window screens.
        """
        for name, screen in self.screens.items():
            if self.existScreen(name):
                screen.reloadUI()
    
    def reloadScreen(self, name: str) -> None:
        """
        Reloads a screen of the window.

        Args:
            name (str): The name of the screen to reload.
        """
        if self.existScreen(name):
            screen = self.screens[name]
            screen.reloadUI()

    def createWindow(self, window: "Window", args: dict = None) -> None:
        """
        Creates a new window and adds it to the windows dictionary for management.

        The window is created using the attributes 'windowGeometry', 'title', and 'name' 
        of the specified Window instance.

        Args:
            window (Window): The window to create.
            args (dict): Arguments for the window.

        Raises:
            Exception: If the window is missing any of the required attributes.
        """
        geometry = getattr(window, 'windowGeometry', None)
        title = getattr(window, 'title', None)
        name = getattr(window, 'name', None)

        if not geometry:
            raise Exception(f"The window '{window}' does not have a valid <windowGeometry>.")
        if not title:
            raise Exception(f"The window '{window}' does not have a valid <title>.")
        if not name:
            raise Exception(f"The window '{window}' does not have a valid <name>.")

        if not hasattr(self, 'windows'):
            self.windows = {}
        
        if not self.windows.get(name):
            window.closeEvent = lambda event: self.onWindowClose(event, name)
            self.windows[name] = window
            window.setGeometry(*geometry)
            window.setWindowTitle(title)

            if args:
                INSTANCEARGS.setArgs(instance=window, args=args)

            window.show()
        else:                
            print(f"The window '{name}' already exists.")

    def onWindowClose(self, event, name: str) -> None:
        """
        Handles the window close event and removes the window from the windows list.

        Args:
            event: The close event.
            name (str): The name of the window being closed.
        """
        if self.strictClosingWindows:
            # Close all child windows when any window is closed
            localWindow: Window = self.windows.get(name, None)

            if localWindow is not None:
                for windowName, windowInstance in list(localWindow.windows.items()):
                    windowInstance: Window
                    if windowName != name:  # Don't close the window that's already closing
                        windowInstance.close()
            else:
                for windowName, windowInstance in list(self.windows.items()):
                    windowInstance: Window
                    if windowName != name:  # Don't close the window that's already closing
                        windowInstance.close()      

        QTimer.singleShot(0, lambda: self.removeWindow(name))
        event.accept()

    def removeWindow(self, name: str) -> None:
        """
        Removes a window from the windows list.

        Args:
            name (str): The name of the window to remove.
        """
        if name in self.windows:
            del self.windows[name]

    def setWindow(self, name: str, args: dict = None) -> None:
        """
        Brings a specified window to the front and activates it.

        Args:
            name (str): The name of the window to bring to the front.
            args (dict): Arguments for the window.

        Raises:
            Exception: If the specified window does not exist.
        """
        if name in self.windows:
            self.windows[name].raise_()
            self.windows[name].activateWindow()

            if args:
                INSTANCEARGS.setArgs(instance=self.windows[name], args=args)

        else:
            raise Exception(f"The window '{name}' does not exist.")
            
    def closeWindow(self, name: str) -> None:
        """
        Closes a specified window.

        Args:
            name (str): The name of the window to close.

        Raises:
            Exception: If the specified window does not exist.
        """
        if name in self.windows:
            self.windows[name].close()
            del self.windows[name]
        else:
            raise Exception(f"The window '{name}' does not exist.")
    
    def removeScreen(self, name: str) -> None:
        """
        Removes a screen from the screens list.

        Args:
            name (str): The name of the screen to remove.
            
        Raises:
            Exception: If the screen does not exist.
        """
        if name not in self.screens:
            raise Exception(f"The screen '{name}' does not exist.")
        
        if hasattr(self, 'stackedScreens'):
            self.stackedScreens.removeWidget(self.screens[name])
        
        self.screens.pop(name)

    def existWindow(self, name: str) -> bool:
        """
        Checks if a window exists in the main window.

        Args:
            name (str): The name of the window.
        Returns:
            bool: True if the window exists, False if it does not exist.
        """
        return name in self.windows

    def reloadWindowScreens(self, window: str) -> None:
        """
        Reloads the screens of a window.

        Args:
            window (str): The name of the window to reload.
        """
        targetWindow: Window = self.windows.get(window)
        if targetWindow:
            targetWindow.reloadScreens()
    
    def reloadWindowScreen(self, window: str, screen: str) -> None:
        """
        Reloads a screen of a window.

        Args:
            window (str): The name of the window to reload.
            screen (str): The name of the screen to reload.
        """
        targetWindow: Window = self.windows.get(window)
        if targetWindow:
            targetWindow.reloadScreen(screen)
        
    def getScreenHistory(self) -> list:
        """
        Returns the current screen navigation history.
        
        Returns:
            list: List of screens in navigation history.
        """
        return self.screenHistory.copy()

    def clearScreenHistory(self) -> None:
        """
        Clears the screen navigation history.
        """
        self.screenHistory.clear()

    def getCurrentScreen(self) -> QWidget:
        """
        Gets the currently active screen.
        
        Returns:
            QWidget: The currently active screen widget.
        """
        return self.stackedScreens.currentWidget()

    def getAllScreens(self) -> Dict[str, QWidget]:
        """
        Gets all registered screens.
        
        Returns:
            Dict[str, QWidget]: Dictionary of all registered screens.
        """
        return self.screens.copy()

    def getAllWindows(self) -> Dict[str, "Window"]:
        """
        Gets all managed windows.
        
        Returns:
            Dict[str, Window]: Dictionary of all managed windows.
        """
        return self.windows.copy()