Custom Widgets

Reusable custom Qt widgets for the application UI.

Package Overview

Package	Purpose
feedback/	User feedback widgets (loading bars, progress indicators)
widget_handlers/	Widget manipulation utilities (replacement, caching, splitters)
calendar/	Calendar and date-related widgets
dialogs/	Custom dialog widgets

Quick Start

Loading Bar

from src.custom_widgets.feedback.custom_loading_bar import LoadingBar

loading_bar = LoadingBar(parent)
layout.addWidget(loading_bar)

# Start loading
loading_bar.start_loading("Uploading...", "Upload complete!")

# When done
loading_bar.stop_loading(success=True)

Widget Replacement

from src.custom_widgets.widget_handlers.set_custom_widget import replace_with_custom_widget

# Replace Qt Designer placeholder with custom widget
custom_calendar = MilestoneCalendar()
replace_with_custom_widget(self.ui.calendar_placeholder, custom_calendar)

View Caching

from src.custom_widgets.widget_handlers.stacked_widget.view_cache_manager import (
    cache_and_show_widget,
    restore_cached_widget,
)

# Navigate to new view while caching current
cached, index = cache_and_show_widget(stacked_widget, new_view)

# Navigate back
restore_cached_widget(stacked_widget, cached, index)

Splitter Widgets

from src.custom_widgets.widget_handlers.splitter_widgets.api import (
    SplitterWidgetManager,
)

manager = SplitterWidgetManager(main_splitter, detach_enabled=True)

Architecture Principles

1. Theme-Aware: Widgets register with StylesheetManager for automatic theme updates
2. Object Names: All widgets use setObjectName() for QSS targeting
3. No Hardcoded Styles: Styling handled through external QSS files

What Belongs Here

Put in custom_widgets: - Reusable UI components used across multiple views - Widget utilities (replacement, caching, layout helpers) - Custom implementations of standard Qt widgets

Do NOT put here: - Module-specific widgets (stay in module's view/) - One-off dialog implementations - Business logic