GUI package

GUI Dialogs Module

Dialog windows for user input and configuration.

author:: Dipl.-Ing. (FH) Jonas Pfeiffer

class districtheatingsim.gui.dialogs.TemperatureDataDialog(parent=None)[source]

Bases: QDialog

Dialog for selecting TRY (Test Reference Year) weather data files.

Note

Simple file selection dialog for weather data input with default path.

__init__(parent=None)[source]

Initialize temperature data dialog.

Parameters:: parent (QWidget, optional) – Parent widget, defaults to None

initUI()[source]: Initialize the user interface components with file selection controls.

Note

Creates description label with DWD link, file input field with default TRY path, and OK/Cancel buttons.

selectFilename(lineEdit)[source]

Open file dialog and set selected path to line edit.

Parameters:: lineEdit (QLineEdit) – Target line edit widget

getValues()[source]

Get dialog values.

Returns:: Dictionary with TRY filename
Return type:: dict

class districtheatingsim.gui.dialogs.HeatPumpDataDialog(parent=None)[source]

Bases: QDialog

Dialog for selecting heat pump COP data files.

Note

Simple file selection dialog for heat pump performance data.

__init__(parent=None)[source]

Initialize heat pump data dialog.

Parameters:: parent (QWidget, optional) – Parent widget, defaults to None

initUI()[source]: Initialize the user interface components with COP file selection.

Note

Creates file input field with default COP data path and OK/Cancel buttons.

selectFilename(lineEdit)[source]

Open file dialog and set selected path to line edit.

Parameters:: lineEdit (QLineEdit) – Target line edit widget

getValues()[source]

Get dialog values.

Returns:: Dictionary with COP filename
Return type:: dict

GUI Utilities Module

Custom GUI widgets and utility functions for DistrictHeatingSim application.

author:: Dipl.-Ing. (FH) Jonas Pfeiffer

class districtheatingsim.gui.utilities.CheckableComboBox(parent=None)[source]

Bases: QComboBox

Custom combo box widget with checkable items for multiple selection.

Signal checkedStateChanged:: Emitted when any item’s checked state changes

Note

Extends QComboBox to provide checkbox functionality for each item.

checkedStateChanged

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:: pyqtSignal(*types, name
Type:: str = …, revision

__init__(parent=None)[source]

Initialize the checkable combo box.

Parameters:: parent (QWidget, optional) – Parent widget, defaults to None

handleItemPressed(index)[source]

Toggle item’s check state when pressed.

Parameters:: index (QModelIndex) – Index of the pressed item

itemChecked(index)[source]

Check if item at given index is checked.

Parameters:: index (int) – Item index to check
Returns:: True if item is checked
Return type:: bool

addItem(text, data=None)[source]

Add a checkable item to the combo box.

Parameters:

text (str) – Item text to display
data (any, optional) – Optional user data for the item, defaults to None

checkedItems()[source]

Get list of checked item texts.

Returns:: Text of all checked items
Return type:: list of str

districtheatingsim.gui.utilities.convert_to_serializable(obj)[source]

Convert various data types to JSON-serializable format.

Parameters:: obj (any) – Object to convert
Returns:: JSON-serializable representation of the object
Return type:: any

Note

Handles pandas objects, numpy arrays, and datetime objects for JSON serialization.

Welcome Screen Module

Initial welcome screen with project management, recent projects, and quick actions.

author:: Dipl.-Ing. (FH) Jonas Pfeiffer

class districtheatingsim.gui.welcome_screen.ThemeToggleSwitch(parent=None)[source]

Bases: QCheckBox

Modern toggle switch for theme switching with animated handle.

Note

Renders custom painted toggle with sun/moon icons for light/dark theme indication.

__init__(parent=None)[source]

Initialize toggle switch with custom styling and animation.

Parameters:: parent (QWidget, optional) – Parent widget, defaults to None

mousePressEvent(event)[source]

Handle mouse press events to toggle the checkbox state.

Parameters:: event (QMouseEvent) – Mouse event

paintEvent(event)[source]

Custom paint event for rendering the toggle switch with animated handle.

Parameters:: event (QPaintEvent) – Paint event

Note

Draws track background, circular handle, and sun/moon icons based on theme state.

class districtheatingsim.gui.welcome_screen.RecentProjectWidget(project_path: str, project_info: Dict)[source]

Bases: QFrame

Widget for displaying a single recent project with thumbnail and metadata.

Signal projectSelected:: Emitted when project is selected (str: project_path)

Note

Displays project name, path, and last modification date in clickable frame.

projectSelected

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:: pyqtSignal(*types, name
Type:: str = …, revision

__init__(project_path: str, project_info: Dict)[source]

Initialize recent project widget.

Parameters:

project_path (str) – Path to the project folder
project_info (Dict) – Dictionary with project metadata

setup_ui()[source]: Setup the UI for the recent project widget with name, path, and modification date.

Note

Creates clickable frame with project metadata display and hover cursor.

mousePressEvent(event)[source]

Handle mouse press to emit project selection signal.

Parameters:: event (QMouseEvent) – Mouse event

class districtheatingsim.gui.welcome_screen.WelcomeScreen(config_manager=None)[source]

Bases: QWidget

Welcome screen widget providing project management and quick actions.

Signal projectSelected:: Emitted when user selects a project (str: path)
Signal newProjectRequested:: Emitted when user wants to create new project
Signal themeChangeRequested:: Emitted when user changes theme (str: theme_key)

Note

Features recent projects display, quick action buttons, documentation links, and clean modern interface.

projectSelected

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:: pyqtSignal(*types, name
Type:: str = …, revision

newProjectRequested

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:: pyqtSignal(*types, name
Type:: str = …, revision

themeChangeRequested

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:: pyqtSignal(*types, name
Type:: str = …, revision

__init__(config_manager=None)[source]

Initialize welcome screen with config manager for recent projects.

Parameters:: config_manager (ConfigManager, optional) – Configuration manager instance, defaults to None

setup_ui()[source]: Setup the main welcome screen UI with header, content sections, and footer.

Note

Creates three-section layout: header with title/theme toggle, content with recent projects and quick actions, funding footer.

create_header(parent_layout)[source]

Create the welcome screen header with title, subtitle, and theme switcher.

Parameters:: parent_layout (QVBoxLayout) – Parent layout to add header to

Note

Includes main title, subtitle, introductory text, and theme toggle switch positioned top-right.

create_recent_projects_section(parent_layout)[source]

Create the recent projects section with scrollable project list.

Parameters:: parent_layout (QHBoxLayout) – Parent layout to add section to

Note

Creates scrollable area with project widgets and project count badge.

create_actions_section(parent_layout)[source]

Create the quick actions and getting started section in right panel.

Parameters:: parent_layout (QHBoxLayout) – Parent layout to add section to

Note

Combines quick action buttons and getting started resources.

create_quick_actions(parent_layout)[source]

Create the quick actions section with New Project and Open Project buttons.

Parameters:: parent_layout (QVBoxLayout) – Parent layout to add quick actions to

Note

Creates styled action button containers with callbacks.

create_action_button(title: str, style_class: str, callback)[source]

Create an action button with title and callback inside styled container.

Parameters:

title (str) – Button text
style_class (str) – CSS class for button styling
callback – Function to call on button click

Returns:

Framed button container

Return type:

QFrame

create_getting_started(parent_layout)[source]

Create the getting started section with documentation, examples, and support links.

Parameters:: parent_layout (QVBoxLayout) – Parent layout to add section to

Note

Provides quick access to documentation, example projects, and GitHub support.

create_funding_footer(parent_layout)[source]

Create the funding notice footer with logo and project information.

Parameters:: parent_layout (QVBoxLayout) – Parent layout to add footer to

Note

Displays Saxony funding logo, project title, and developer information.

load_recent_projects()[source]: Load and display recent projects from config manager with fallback to example project.

Note

Clears existing widgets, loads from config manager, adds Görlitz example if no projects found.

get_bundled_example_project() → tuple | None[source]

Get the bundled Görlitz example project path.

This method locates the Görlitz example project that is bundled with the application in the project_data directory. Works both in development and in frozen (PyInstaller) deployments.

Returns:: (project_path, project_info) if found, None otherwise
Return type:: Optional[tuple]

scan_for_projects() → List[tuple][source]

Scan common directories for existing project folders.

Returns:: List of tuples (project_path, project_info) sorted by modification time
Return type:: List[tuple]

Note

Scans Documents, current directory, and application directory for valid project structures.

is_project_folder(folder_path: str) → bool[source]

Check if a folder contains typical DistrictHeatingSim project structure.

Parameters:: folder_path (str) – Path to check
Returns:: True if appears to be a project folder
Return type:: bool

Note

Looks for indicator folders like ‘Eingangsdaten allgemein’, ‘Definition Quartier IST’, ‘Variante 1’.

get_project_info(project_path: str) → Dict[source]

Get metadata information about a project folder.

Parameters:: project_path (str) – Path to the project
Returns:: Dictionary with name, path, last_modified, last_modified_timestamp
Return type:: Dict

Note

Extracts folder name and modification timestamp for display and sorting.

new_project_clicked()[source]: Handle new project button click by emitting newProjectRequested signal.

Note

Main window handles complete workflow including folder selection and project creation.

open_project_clicked()[source]: Handle open project button click with file dialog for folder selection.

Note

Opens file dialog starting in default project directory, emits projectSelected signal.

get_default_project_directory()[source]

Get a sensible default directory for project dialogs.

Returns:: Path to default directory (most recent project parent or Documents folder)
Return type:: str

Note

Prefers parent directory of most recent project, falls back to ~/Documents.

project_selected(project_path: str)[source]

Handle project selection by emitting projectSelected signal.

Parameters:: project_path (str) – Path to selected project

open_documentation()[source]: Open the ReadTheDocs documentation website in default browser.

Note

Opens https://districtheatingsim.readthedocs.io/en/latest/

open_examples()[source]: Open example projects folder or GitHub examples page.

Note

Opens local examples folder if exists, otherwise opens GitHub examples page.

open_support()[source]: Open GitHub issues page for support and bug reporting.

Note

Opens https://github.com/JonasPfeiffer123/DistrictHeatingSim/issues

on_theme_toggle(checked)[source]

Handle theme toggle switch change to apply light or dark theme.

Parameters:: checked (bool) – True if dark theme, False if light theme

apply_light_theme()[source]: Request light theme application for entire application.

Note

Emits themeChangeRequested signal with ‘light_theme_style_path’.

apply_dark_theme()[source]: Request dark theme application for entire application.

Note

Emits themeChangeRequested signal with ‘dark_theme_style_path’.

set_current_theme(is_dark_theme: bool)[source]

Set the toggle switch state based on current theme without triggering signals.

Parameters:: is_dark_theme (bool) – True for dark theme, False for light theme

Note

Temporarily disconnects signal to avoid loops when updating toggle state.

refresh_recent_projects()[source]: Refresh the recent projects list by reloading from config manager.

Note

Calls load_recent_projects() to update the displayed project widgets.

districtheatingsim.gui.welcome_screen.main()[source]: Test the welcome screen standalone for development and debugging.

Note

Creates QApplication and displays WelcomeScreen widget.