Source code for radioviz.models.menu_spec

#  Copyright 2025–2026 European Union
#  Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
#  SPDX-License-Identifier: EUPL-1.2
"""
Module for defining menu specifications used in the application's UI.

This module provides data structures for representing menu actions,
separators, and submenus that can be contributed by different tools
within the application. These specifications are UI-agnostic and can
be used to build various user interfaces.
"""

from dataclasses import dataclass
from typing import Callable, List, Optional, Protocol, Union




class ToolSeparatorSpec:
    """
    A separator used to group menu items in a menu.

    This class serves as a marker for a visual separator in menus.
    It does not contain any functional logic but is used to organize
    menu entries visually.

    No additional attributes or methods are required for this class.
    """





class SignalLike(Protocol):
    """
    Protocol describing signal-like objects with a connect method.

    This keeps menu specifications UI-agnostic while allowing Qt signals
    (or compatible signal implementations) to be referenced.
    """



    def connect(self, slot: Callable[..., object]) -> object:
        """
        Connect a slot to the signal.

        :param slot: Callable invoked when the signal is emitted.
        :type slot: Callable[..., object]
        :return: Implementation-specific connection result.
        :rtype: object
        """






@dataclass
class ToolActionSpec:
    """
    UI-agnostic description of a menu action.

    This data class represents a single menu action that can be
    triggered by the user. It contains all necessary information
    about the action including its text label, trigger function,
    and optional properties like shortcuts and checkability.

    :param text: The text label displayed for this menu action
    :type text: str
    :param triggered: Function to be called when the action is triggered
    :type triggered: Callable[[], None]
    :param enabled_changed_signal: Optional signal for when the action's enabled state changes
    :type enabled_changed_signal: Optional[SignalLike]
    :param toggled: Optional function called when a checkable action toggles
    :type toggled: Optional[Callable[[bool], None]]
    :param checked_changed_signal: Optional signal for check state changes
    :type checked_changed_signal: Optional[SignalLike]
    :param shortcut: Optional keyboard shortcut for this action
    :type shortcut: Optional[str]
    :param checkable: Whether the action supports checkable state (e.g., checkboxes)
    :type checkable: bool
    :param action_group: Optional action group name for exclusivity
    :type action_group: Optional[str]
    :param order: Optional explicit ordering key; lower values appear first
    :type order: Optional[int]
    """

    text: str
    triggered: Callable[[], None]
    enabled_changed_signal: Optional[SignalLike] = None
    toggled: Optional[Callable[[bool], None]] = None
    checked_changed_signal: Optional[SignalLike] = None
    shortcut: Optional[str] = None
    checkable: bool = False
    action_group: Optional[str] = None
    order: Optional[int] = None



MenuEntry = Union['ToolMenuSpec', ToolActionSpec, ToolSeparatorSpec]




@dataclass
class ToolMenuSpec:
    """
    A submenu contributed by a tool.

    This data class represents a submenu that can be added to the
    application's menu system. It contains a title and a list of
    entries (actions, submenus, or separators).

    :param title: The title of the submenu
    :type title: str
    :param entries: List of menu entries (actions, submenus, or separators)
    :type entries: List[MenuEntry]
    :param order: Optional explicit ordering key; lower values appear first
    :type order: Optional[int]
    """

    title: str
    entries: List[MenuEntry]
    order: Optional[int] = None