radioviz.controllers.sub_window_controller

Module for managing sub-windows and their controllers in the radioviz application.

This module provides the core functionality for handling different types of sub-windows such as image windows, profile windows, and region windows. It includes the base controller class for sub-windows and utilities for managing window states and flags.

The module defines the SubWindowEnum enumeration for identifying different sub-window types, and the SubWindowController base class that manages the lifecycle and behavior of sub-windows including view management, tool activation, and overlay handling.

It also provides utility functions for comparing sub-window flags and helper methods for managing data state, saving operations, and window lifecycle events.

Functions

compare_flags(current_flag, reference_flag)

Compare two sub-window flags to check if current flag is contained in reference flag.

Classes

`SubWindowController`(source[, storage, view])	Base controller class for managing sub-windows in the radioviz application.
`SubWindowEnum`(*values)	Enumeration representing different types of sub-windows in the application.

class radioviz.controllers.sub_window_controller.SubWindowController(source: DataSource, storage: DataStorage | None = None, view: T_SubWindow | None = None)[source]

Bases: QObject, Generic[T_SubWindow]

Base controller class for managing sub-windows in the radioviz application.

This controller handles the lifecycle and behavior of sub-windows including view management, tool activation, and overlay handling.

The controller maintains the data state through state and provides methods for marking data as modified or saved. It also manages the association between the controller and its view through set_view().

The controller implements methods for saving operations including checking if saving is possible (can_save()) and what save specifications are available (get_save_specs()). It also provides methods for determining if the window is dirty (is_dirty()) or saved (is_saved()).

Initialize the sub-window controller.

Parameters:

source (DataSource) – The data source for this controller
storage (Optional[DataStorage]) – Optional data storage for this controller
view (Optional[T_SubWindow]) – Optional view instance to associate with this controller

can_save() → bool[source]

Check if the current data can be saved.

A data can be saved if: 1. The storage path is set 2. The data is marked as modified 3. There are save specifications available

Returns:: True if the data can be saved, False otherwise
Return type:: bool

can_save_as() → bool[source]

Check if the current data can be saved with a new path.

A data can be saved as if there are save specifications available.

Returns:: True if the data can be saved as, False otherwise
Return type:: bool

close() → None[source]: Close the corresponding view

context_menu_specs() → list[ToolMenuSpec][source]

Return window-specific context menu specifications.

Subclasses can override this to provide built-in window menus that should appear in the context menu for the active window. Tool menus are filtered separately based on tool compatibility with the window type.

Returns:: List of menu specifications.
Return type:: list[ToolMenuSpec]

current_path() → Path | None[source]

Get the current storage path.

Returns:: The current storage path or None if not set
Return type:: Path | None

derive_kind() → DataKind[source]

Determine the kind of data based on the source parent.

If the source has no parent, it’s considered original data. Otherwise, it’s considered derived data.

Returns:: The data kind (ORIGINAL or DERIVED)
Return type:: DataKind

derive_state() → DataState[source]

Derive the current data state based on storage path.

If the storage path is set, the state is PERSISTENT. Otherwise, it’s MODIFIED.

Returns:: The current data state
Return type:: DataState

get_save_specs() → list[SaveSpec][source]

Get the list of available save specifications for this controller.

This method should be overridden by subclasses to provide actual save specs.

Returns:: List of save specifications
Return type:: list[SaveSpec]

is_dirty() → bool[source]

Check if the data has been modified but not yet saved.

Returns:: True if the data is dirty (modified), False otherwise
Return type:: bool

is_saved() → bool[source]

Check if the data has been saved to persistent storage.

Returns:: True if the data is saved, False otherwise
Return type:: bool

mark_modified() → None[source]

Mark the data as modified and emit state changed signal.

This method sets the MODIFIED flag in the controller’s state and emits the state_changed signal to notify observers of the change.

mark_saved(path: Path) → None[source]

Mark the data as saved with the given path.

Updates the storage path, removes the MODIFIED flag, adds the PERSISTENT flag, and updates the window name. Emits the state_changed signal.

Parameters:: path (Path) – The path where the data was saved

on_view_closed() → None[source]

Handle the event when the view is closed.

This method is called when the associated view is closed. Subclasses can override this method to implement custom cleanup logic.

on_view_created() → None[source]

Handle the event when the view is created.

This method is called when the associated view is created. Subclasses can override this method to implement custom initialization logic.

require_view() → T_SubWindow[source]

Return the associated view or raise if missing.

Returns:: The view instance associated with this controller
Return type:: T_SubWindow
Raises:: RuntimeError – If the controller has no view attached

set_view(view: T_SubWindow) → None[source]

Set the view associated with this controller.

Connects the view’s context menu signal to the controller’s signal.

Parameters:: view (T_SubWindow) – The view to associate with this controller

set_window_state(state: WindowState) → None[source]

Set the window state for the associated view.

If no view is associated, this method does nothing.

Parameters:: state (WindowState) – The window state to set

sync_context_menu_state() → None[source]

Sync context menu state for window-specific menus.

Subclasses can override this to emit signals that update checkable action states before the context menu is shown.

window_state() → WindowState[source]

Get the current window state from the associated view.

If no view is associated, returns WindowState.Normal.

Returns:: The current window state
Return type:: WindowState

class radioviz.controllers.sub_window_controller.SubWindowEnum(*values)[source]

Bases: Flag

Enumeration representing different types of sub-windows in the application.

This enum is used to identify and manage different sub-window types such as image windows, profile windows, and region windows. It supports bitwise operations to combine multiple window types.

The ALL attribute contains a combination of all non-NONE members.

This enum is used for UI enablement and categorization only; window instantiation is handled separately by the WindowFactory via string window type identifiers.

static _generate_next_value_(name, start, count, last_values)

Generate the next value when not given.

name: the name of the member start: the initial start value or None count: the number of existing members last_values: the last value assigned or None

radioviz.controllers.sub_window_controller.compare_flags(current_flag: SubWindowEnum, reference_flag: SubWindowEnum) → bool[source]

Compare two sub-window flags to check if current flag is contained in reference flag.

This utility function checks whether a specific sub-window type is included within a combination of sub-window types.

Parameters:

current_flag (SubWindowEnum) – The flag to check
reference_flag (SubWindowEnum) – The reference flag to check against

Returns:

True if current_flag is contained in reference_flag, False otherwise

Return type:

bool