radioviz.tools.base_controller

Base controller module for radioviz tools.

This module provides the foundational controller classes that manage the interaction between tools and their graphical interfaces. It defines the base controller abstraction that all tool controllers must implement, along with the necessary infrastructure for managing tool sessions, docks, and event handling.

The primary class in this module is ToolController, which serves as the base class for all tool controllers in the application. It handles the lifecycle of tool sessions, manages dock widgets, and provides mechanisms for communication between tools and their views.

Classes

ToolController(tool_ctx, tool)

Base controller class for radioviz tools.

class radioviz.tools.base_controller.ToolController(tool_ctx: ToolContext, tool: Tool[T_Tool_Controller])

Bases: QObject, Generic[T_SubWindowController, T_Session]

Base controller class for radioviz tools.

This abstract base class defines the interface and common behavior for all tool controllers in the radioviz application. It manages the tool’s session lifecycle, handles communication between the tool and its UI components, and provides infrastructure for dock widgets and event handling.

Variables:

• dock_event (Signal) – Signal emitted when a dock event occurs

• controller_event (Signal) – Signal emitted when a controller event occurs

• request_new_window (Signal) – Signal emitted when a new window is requested

• enable_for_window_type (SubWindowEnum) – Window types where this tool’s menus are available

Initialize the ToolController.

Parameters:

• tool_ctx (ToolContext) – The tool context containing application state

• tool (Tool) – The tool instance associated with this controller

_on_active_image_changed(new_window_controller: SubWindowController[Any] | None) → None

Handle active image change event.

This internal method is called when the active image window changes. If there’s an active session and it belongs to a different window, the session will be deactivated.

Parameters:

new_window_controller (SubWindowController[Any] | None) – The new active window controller

activate() → None

Activate the tool.

This method activates the tool by creating a new session for the currently active image window. If there’s no active image, the activation is skipped.

attach_view(view: QWidget) → None

Attach a view to this controller.

This method is called when the view becomes available to associate it with the controller.

Parameters:

view (object) – The view to attach

cleanup() → None

Clean up resources when the image window closes.

This method is called when the associated image window is closed. Subclasses can override this to perform final cleanup operations.

count_dependencies_for_image(window_controller: SubWindowController[Any]) → int

Count items managed by this tool that depend on a given image.

Subclasses can override this to expose in-place mutation impact.

Parameters:

window_controller (SubWindowController[Any]) – Image controller used as dependency root

Returns:

Number of dependent items

Return type:

int

create_dock(parent_window: QWidget) → 'ToolDockWidget[T_ToolControllerSelf]' | None

Create a dock widget for this tool.

Override this method in subclasses to provide custom dock widget creation functionality. By default, returns None indicating no dock widget is created.

Parameters:

parent_window (QWidget) – The parent window for the dock widget

Returns:

A new dock widget instance or None

Return type:

ToolDockWidget or None

abstract create_session(window_controller: T_SubWindowController) → T_Session

Create a new tool session for the given window controller.

This abstract method must be implemented by subclasses to create appropriate tool sessions for specific tools.

Parameters:

window_controller (SubWindowController[Any]) – The window controller to create session for

Returns:

A new tool session instance

Return type:

BaseToolSession

deactivate() → None

Deactivate the tool.

This method cancels the active session if one exists, effectively deactivating the tool. The session is properly cleaned up during this process.

emit_event(event: str, payload: Any | None = None) → None

Emit a controller event.

This method emits a controller event that can be listened to by other components in the application.

Parameters:

• event (str) – The event name

• payload (Any) – Optional event payload data

invalidate_dependencies_for_image(window_controller: SubWindowController[Any]) → int

Invalidate items managed by this tool that depend on a given image.

Subclasses can override this to safely remove stale dependent items when in-place image data changes make them invalid.

Parameters:

window_controller (SubWindowController[Any]) – Image controller used as dependency root

Returns:

Number of invalidated items

Return type:

int

menu_specs() → List[ToolMenuSpec]

Get menu specifications for this tool.

Returns a list of menu specifications that define how this tool should appear in menus. By default, returns an empty list.

Returns:

List of menu specifications

Return type:

List[ToolMenuSpec]

on_activate() → None

Called when the tool becomes active.

This method is invoked when the tool transitions to an active state. Subclasses can override this to perform initialization or setup tasks when the tool becomes active.

on_deactivate() → None

Called when the tool becomes inactive.

This method is invoked when the tool transitions to an inactive state. Subclasses can override this to perform cleanup or teardown tasks when the tool becomes inactive.

on_dock_event(event: ToolEvent) → None

Handle dock events.

This method processes events coming from the dock widget. Subclasses can override this to handle custom dock-related events.

Parameters:

event (ToolEvent) – The dock event to process

on_mouse_move(event: MouseEvent) → None

Handle mouse move events from the image view.

This method is called when a mouse move event occurs in the image view. Subclasses can override this to handle specific mouse interactions.

Parameters:

event (MouseEvent) – The mouse move event

on_mouse_press(event: MouseEvent) → None

Handle mouse press events from the image view.

This method is called when a mouse press event occurs in the image view. Subclasses can override this to handle specific mouse interactions.

Parameters:

event (MouseEvent) – The mouse press event

sync_menu_state() → None

Emit current action states for menu enablement.

This is useful when menus are built on demand (e.g., context menus) so actions start in the correct enabled/disabled state.

sync_menu_state_for(window_controller: SubWindowController[Any]) → None

Sync menu state for a specific window controller.

Subclasses can override this to emit additional state signals that depend on the active window (e.g., distance-calibration availability). By default this defers to sync_menu_state().

Parameters:

window_controller (SubWindowController[Any]) – Active window controller

toggle_dock_visibility(visible: bool) → None

Toggle the visibility of the dock widget.

Parameters:

visible (bool) – Whether to make the dock visible

property tool_id: str

Get the unique identifier for this tool.

Returns:

The tool identifier

Return type:

str