pySimBlocks.gui.project_controller

class pySimBlocks.gui.project_controller.ProjectController(project_state: ProjectState, view: DiagramView, resolve_block_meta: Callable[[str, str], BlockMeta], undo_manager: UndoManager)

Bases: QObject

Controller coordinating all mutations to the project model and diagram view.

Acts as the single point of truth for block and connection lifecycle operations, dirty-state tracking, plot management, and simulation parameter updates.

project_state

Shared mutable state of the open project.

view

The diagram canvas widget.

resolve_block_meta

Callable returning BlockMeta for a given category and block type.

is_dirty

True if there are unsaved changes.

dirty_changed: Signal

Signal emitted with the new dirty flag value whenever the unsaved-changes state changes.

add_block(category: str, block_type: str, block_layout: dict | None = None) → BlockInstance

Create and add a new block of the given type to the project.

Parameters:

• category – Category name of the block.

• block_type – Type name of the block within the category.

• block_layout – Optional dict with position/size hints for the view.

Returns:

The newly created BlockInstance.

add_copy_block(block_instance: BlockInstance) → BlockInstance

Add a copy of an existing block to the project.

Parameters:

block_instance – The block to copy.

Returns:

The newly created copy as a BlockInstance.

rename_block(block_instance: BlockInstance, new_name: str) → None

Rename a block and update all references in logging and plot signals.

Parameters:

• block_instance – The block to rename.

• new_name – Desired new name. A unique suffix is appended if the name is already taken.

update_block_param(block_instance: BlockInstance, params: dict[str, Any]) → None

Apply new parameter values to a block, refreshing ports and connections as needed.

Parameters:

• block_instance – The block to update.

• params – New parameter dict. If a 'name' key is present the block is also renamed.

remove_block(block_instance: BlockInstance) → None

Remove a block, its connections, and its signals from the project.

Parameters:

block_instance – The block to remove.

make_unique_name(base_name: str) → str

Return base_name or a suffixed variant that is unique across all blocks.

Parameters:

base_name – Desired block name.

Returns:

base_name if available, otherwise base_name_N for the smallest N that is not already taken.

is_name_available(name: str, current=None) → bool

Return True if name is not already used by another block.

Parameters:

• name – Name to check for availability.

• current – Block instance to exclude from the check (e.g. the block being renamed).

Returns:

True if the name is free, False if it is taken by another block.

add_connection(port1: PortInstance, port2: PortInstance, points: list[QPointF] | None = None) → None

Create a connection between two ports if compatible.

The method silently returns without creating a connection if the ports are not compatible or if the destination port cannot accept another connection.

Parameters:

• port1 – First port (output or input).

• port2 – Second port (input or output).

• points – Optional list of intermediate waypoints for the wire.

remove_connection(connection: ConnectionInstance) → None

Remove a connection from both the model and the view.

Parameters:

connection – The ConnectionInstance to remove.

execute_move_resize_block(block_instance: BlockInstance, old_pos: QPointF, old_rect: QRectF, new_pos: QPointF, new_rect: QRectF) → None

execute_toggle_orientation(block_instance: BlockInstance) → None

begin_macro(text: str) → None

end_macro() → None

make_dirty() → None

Mark the project as having unsaved changes and emit dirty_changed.

clear_dirty() → None

Clear the unsaved-changes flag and emit dirty_changed.

clear() → None

Reset the project state and diagram view to an empty state.

update_project_param(new_path: Path, ext: str) → None

Update the project directory path and external module reference.

Parameters:

• new_path – New project directory path.

• ext – New external module path string, or '' to clear it.

load_project(loader: ProjectLoader) → None

Delegate project loading to the given loader service.

Parameters:

loader – A ProjectLoader implementation that reads the project files and populates this controller.

create_plot(title: str, signals: list[str], mode: str = 'auto') → None

Append a new plot to the project configuration.

Parameters:

• title – Title of the plot figure.

• signals – List of signal names to display in the plot. Any signal not already logged is automatically added to the logging list.

• mode – Plot display mode (auto, overlay, split_signals, or split_components).

update_plot(index: int, title: str, signals: list[str], mode: str = 'auto', series_styles: dict[str, dict[str, str]] | None = None) → None

Update the title and signals of an existing plot.

Parameters:

• index – Index of the plot in ProjectState.plots.

• title – New title for the plot.

• signals – New list of signal names. Any signal not yet logged is automatically added.

• mode – Plot display mode (auto, overlay, split_signals, or split_components).

• series_styles – Optional per-component style map for YAML storage.

delete_plot(index: int) → None

Remove a plot by index.

Parameters:

index – Index of the plot in ProjectState.plots.

add_manual_layout_preset(plot: dict) → int

Append a manual multi-panel layout preset to the project.

Parameters:

plot – Plot descriptor with layout: manual and panels.

Returns:

Index of the new preset in ProjectState.plots.

update_manual_layout_preset(index: int, plot: dict) → None

Replace an existing manual layout preset at index.

Parameters:

• index – Index in ProjectState.plots.

• plot – Plot descriptor with layout: manual and panels.

update_simulation_params(params: dict[str, float | str]) → None

Apply new simulation parameters to the project state.

Parameters:

params – Dict of simulation parameters (e.g. dt, T).

set_logged_signals(signals: list[str]) → None

Replace the logging list with signals, preserving insertion order.

Parameters:

signals – New list of signal names to log. Duplicates are removed while preserving the first occurrence.

staticMetaObject = PySide6.QtCore.QMetaObject("ProjectController" inherits "QObject": Methods:   #4 type=Signal, signature=dirty_changed(bool), parameters=bool )