radioviz.services.menu_builder

Module for building Qt menus from specification objects.

This module provides functionality to construct Qt menu structures from specification objects. It handles the creation of menus, submenus, actions, and separators based on the provided specifications.

Functions

build_context_menu(parent, menu_specs)

Build a context menu from menu specifications.

build_tool_menus(parent, menu_specs)

Build a list of Qt menus from tool menu specifications.
radioviz.services.menu_builder._build_menu(parent: QWidget, spec: ToolMenuSpec, group_map: Dict[str, QActionGroup] | None = None, root_menu: QMenu | None = None, close_on_trigger: bool = False) → QMenu[source]

Recursively build a Qt menu from a tool menu specification.

Creates a Qt menu object and populates it with actions, submenus, and separators based on the specification entries. Actions that declare an action_group are assigned to a shared QActionGroup (one group per name), enforcing exclusive radio-like behavior.

Parameters:

  • parent (QWidget) – The parent widget for the menu

  • spec (radioviz.models.menu_spec.ToolMenuSpec) – Tool menu specification

  • group_map (Dict[str, QActionGroup] | None) – Optional mapping of action group names to QActionGroups

Returns:

Created Qt menu object

Return type:

PySide6.QtWidgets.QMenu

radioviz.services.menu_builder._entry_alpha_key(entry: ToolMenuSpec | ToolActionSpec | ToolSeparatorSpec) → str[source]

Produce a case‑folded string key for alphabetical sorting of menu entries.

For menu specifications the key is the title; for action specifications it is the displayed text. Non‑sortable entries return a placeholder that sorts after normal strings.

Parameters:

entry (radioviz.models.menu_spec.MenuEntry) – The menu entry to generate a key for.

Returns:

A lower‑cased string used as a sorting key.

Return type:

str

radioviz.services.menu_builder._entry_order(entry: ToolMenuSpec | ToolActionSpec | ToolSeparatorSpec) → int | None[source]

Retrieve the order attribute of a menu entry, if applicable.

Both ToolMenuSpec and ToolActionSpec may define an order. For other entry types None is returned.

Parameters:

entry (radioviz.models.menu_spec.MenuEntry) – The menu entry to inspect.

Returns:

The order value or None if not defined.

Return type:

int | None

radioviz.services.menu_builder._merge_entries(entries: List[ToolMenuSpec | ToolActionSpec | ToolSeparatorSpec]) → List[ToolMenuSpec | ToolActionSpec | ToolSeparatorSpec][source]

Recursively merge a list of MenuEntry objects.

Menu entries that are themselves ToolMenuSpec and share the same title are combined: their order is reconciled and their child entries are merged. Non‑menu entries are passed through unchanged.

Parameters:

entries (List[radioviz.models.menu_spec.MenuEntry]) – List of menu entries to merge.

Returns:

List of merged menu entries.

Return type:

List[radioviz.models.menu_spec.MenuEntry]

radioviz.services.menu_builder._merge_menu_specs(specs: Sequence[ToolMenuSpec]) → List[ToolMenuSpec][source]

Merge a sequence of ToolMenuSpec objects.

Duplicate menus (identified by their title) are merged into a single specification, preserving the order and entries of each. The function returns a list containing only the top‑level menu specifications.

Parameters:

specs (Sequence[radioviz.models.menu_spec.ToolMenuSpec]) – Sequence of menu specifications to merge.

Returns:

List of merged top‑level menu specifications.

Return type:

List[radioviz.models.menu_spec.ToolMenuSpec]

radioviz.services.menu_builder._normalize_separators(entries: Sequence[ToolMenuSpec | ToolActionSpec | ToolSeparatorSpec]) → List[ToolMenuSpec | ToolActionSpec | ToolSeparatorSpec][source]

Remove redundant and trailing separators from a sequence of menu entries.

Consecutive ToolSeparatorSpec objects are collapsed into a single separator, and any separator at the end of the list is discarded. The function returns a new list preserving the original order of non‑separator entries.

Parameters:

entries (Sequence[radioviz.models.menu_spec.MenuEntry]) – Sequence of menu entries possibly containing separators.

Returns:

List of entries with normalized separators.

Return type:

List[radioviz.models.menu_spec.MenuEntry]

radioviz.services.menu_builder._sorted_entries(entries: Sequence[ToolMenuSpec | ToolActionSpec | ToolSeparatorSpec]) → List[ToolMenuSpec | ToolActionSpec | ToolSeparatorSpec][source]

Return menu entries sorted by explicit order, then alphabetically.

If any entry defines an order attribute, entries are sorted first by the presence of an order (unordered entries come last), then by the numeric order, followed by a case‑insensitive alphabetical key, and finally by their original position to preserve stability. When no entry defines an order, the original sequence is returned unchanged.

Parameters:

entries (Sequence[radioviz.models.menu_spec.MenuEntry]) – Sequence of menu entries to sort.

Returns:

List of sorted menu entries.

Return type:

List[radioviz.models.menu_spec.MenuEntry]

radioviz.services.menu_builder.build_context_menu(parent: QWidget, menu_specs: List[ToolMenuSpec]) → QMenu[source]

Build a context menu from menu specifications.

Creates a root QMenu that contains the merged top-level menu specifications as submenus. This allows combining tool menus with window-specific menus. The resulting menu is designed for context use and closes automatically after actions are triggered.

Parameters:
Returns:

Root context menu

Return type:

PySide6.QtWidgets.QMenu

radioviz.services.menu_builder.build_tool_menus(parent: QWidget, menu_specs: List[ToolMenuSpec]) → List[QMenu][source]

Build a list of Qt menus from tool menu specifications.

Creates Qt menu objects from the provided menu specifications and associates them with the given parent widget.

Parameters:
Returns:

List of created Qt menu objects

Return type:

List[PySide6.QtWidgets.QMenu]