Source code for radioviz.tools.base_dock

#  Copyright 2025–2026 European Union
#  Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
#  SPDX-License-Identifier: EUPL-1.2
"""
Base dock widget for tool components.

This module provides the base class for creating dock widgets that can be used
to display tool-specific interfaces within the application's main window.
"""

from typing import TYPE_CHECKING, Any, Generic, Optional, TypeVar

from PySide6.QtCore import Qt, Signal
from PySide6.QtGui import QAction
from PySide6.QtWidgets import QDockWidget, QWidget

from radioviz.controllers.sub_window_controller import SubWindowEnum
from radioviz.tools.base_tool import ToolEvent

if TYPE_CHECKING:
    from radioviz.tools.base_controller import ToolController

T_ToolController = TypeVar('T_ToolController', bound='ToolController[Any, Any]')
T_ToolController.__doc__ = 'Tool controller type associated with this dock widget.'




class ToolDockWidget(QDockWidget, Generic[T_ToolController]):
    """
    Base class for tool dock widgets.

    This class provides the foundation for creating dockable widgets that
    can be associated with specific tools and controllers within the application.

    :ivar dock_position: Default position where the dock widget will be placed
    :vartype dock_position: Qt.DockWidgetArea
    :ivar initial_visibility: Whether the dock widget is initially visible
    :vartype initial_visibility: bool
    :ivar enable_for_window_type: SubWindowEnum value indicating which window types this dock is enabled for
    :vartype enable_for_window_type: SubWindowEnum
    :ivar event_emitted: Signal emitted when an event occurs within the dock widget
    :vartype event_emitted: Signal
    """

    dock_position = Qt.DockWidgetArea.RightDockWidgetArea
    initial_visibility = False
    enable_for_window_type = SubWindowEnum.NONE
    event_emitted = Signal(object)  # it is sending a ToolEvent

    def __init__(
        self, title: str, parent: Optional[QWidget] = None, controller: Optional[T_ToolController] = None
    ) -> None:
        """
        Initialize the ToolDockWidget.

        :param title: Title of the dock widget
        :type title: str
        :param parent: Parent widget
        :type parent: QWidget, optional
        :param controller: Controller associated with this dock widget
        :type controller: ToolController, optional
        """
        super().__init__(title, parent)
        self.setObjectName(title.lower().replace(' ', '_'))
        self.controller: Optional[T_ToolController] = controller



    def set_controller(self, controller: T_ToolController) -> None:
        """
        Set the controller for this dock widget.

        :param controller: Controller to associate with this dock widget
        :type controller: ToolController
        """
        self.controller = controller




    def emit_event(self, event: str, payload: Optional[Any] = None) -> None:
        """
        Emit an event signal.

        :param event: Name of the event to emit
        :type event: str
        :param payload: Optional payload data to send with the event
        :type payload: Any, optional
        """
        if self.controller is None:
            raise RuntimeError('Tool dock widget has no controller assigned.')
        self.event_emitted.emit(ToolEvent(self.controller.tool.tool_id, event, payload))




    def handle_event(self, event: ToolEvent) -> None:
        """
        Handle an incoming event.

        This method should be overridden by subclasses to implement specific
        event handling logic.

        :param event: The event to handle
        :type event: ToolEvent
        """
        raise NotImplementedError




    def generate_view_dock_action(self, parent: QWidget) -> QAction:
        """
        Generate a view action for the dock widget.

        This method should be overridden by subclasses to create a QAction
        that can be used to show/hide the dock widget.

        :param parent: Parent widget for the action
        :type parent: QWidget
        :return: A QAction for controlling the dock widget visibility
        :rtype: QAction
        """
        raise NotImplementedError