Architecture Overview
How the five modules connect to form the PySideAbdhUI framework
+---------------------------------------------------------------------+
| PySideAbdhUI Framework |
| |
| +----------------+ +------------------+ |
| | Window.py |---------| Widgets.py | |
| | (AbdhWindow) | uses | (StackedWidget, | |
| | | | Separator, | |
| | Top-level app | | Label, | |
| | shell with | | RingProgress, | |
| | frameless | | SearchBox) | |
| | animated | +------------------+ |
| | panels | |
| +-------+--------+ |
| | |
| | uses |
| v |
| +----------------+ +------------------+ |
| | utils.py | | StyleManagers.py | |
| | (get_icon, | uses | (QtStyleSheet- | |
| | get_resource, |---------| Manager) | |
| | ThemeManager, | | | |
| | color utils) | | QSS load / edit / | |
| +-------+--------+ | save / validate | |
| | +------------------+ |
| | provides icons for |
| v |
| +----------------+ |
| | CardGridView.py| |
| | (CardWidget, | |
| | CardGridView) | |
| | | |
| | Scrollable grid| |
| | with CRUD + | |
| | infinite scroll| |
| +----------------+ |
| |
| +-------------------------+ |
| | document_editor.py | |
| | (RichTextEditor, | |
| | DebugPage) | |
| | | |
| | Chromium WYSIWYG | |
| | editor with KaTeX, | |
| | PDF/DOCX import/export | |
| +------------+------------+ |
| | |
| | imports |
| v |
| +----------------+ |
| | utils.py | |
| +----------------+ |
+---------------------------------------------------------------------+
Data Flow:
Window.py ──imports──► Widgets.py (StackedWidget for page hosting)
Window.py ──imports──► utils.py (get_icon for titlebar icons)
document_editor.py ──imports──► utils.py (get_resource_path for KaTeX/PDF resources)
CardGridView.py ──standalone── (no internal imports, pure Qt)
StyleManagers.py ──standalone── (no Qt widget deps, string-based QSS)
utils.py ──standalone── (resource resolution + ThemeManager)
Module Documentation
Click any card to open the full technical documentation for that module
Window.py
→
Frameless animated main window with collapsible side panels and 8-direction edge resize
Key Components
- AbdhWindow
- Size Lock System
- QGridLayout 2x3
- Panel Toggling
- Edge Resize
- QPropertyAnimation
- Event Filter
Widgets.py
→
Reusable widget library: animated stacked widget, separator, styled label, ring progress, and search box
Key Components
- StackedWidget
- Separator
- Label
- RingProgress
- SearchBox
- Page Navigation
- QPropertyAnimation
CardGridView.py
→
Scrollable card grid with CRUD operations, dynamic column reconfiguration, and infinite scroll
Key Components
- CardWidget
- CardGridView
- Infinite Scroll
- Dynamic Columns
- Selection State
- card_clicked Signal
utils.py
→
Resource resolution, icon loading, QSS template engine, ThemeManager with JSON persistence, and WCAG contrast colors
Key Components
- get_resource_path
- get_icon
- get_styles_template
- ThemeManager
- random_contrasting_hex
- WCAG 2.0 Contrast
StyleManagers.py
→
Regex-based QSS stylesheet manager with accent color placeholders, property editing, and syntax validation
Key Components
- QtStyleSheetManager
- add_property_to_widget
- remove_stylesheet_by_name
- replace_placeholder
- validate_stylesheet
- Accent Color System
document_editor.py
→
Chromium-based WYSIWYG rich text editor with KaTeX math rendering, multi-page layout, PDF/DOCX import/export, and image capture
Key Components
- RichTextEditor
- DebugPage
- KaTeX Rendering
- PDF Import/Export
- DOCX via Pandoc
- Multi-Page Engine
- Image Capture
- Table Editing
Internal Dependency Map
How modules import from each other within the framework
| Source Module | Imports From | Components Used | Purpose |
|---|---|---|---|
Window.py |
.Widgets |
StackedWidget |
Main content area with page navigation (back/forward) for the window shell. |
Window.py |
.utils |
get_icon |
Loading SVG icons for the titlebar buttons (minimize, maximize, close, etc.). |
CardGridView.py |
none | — | Standalone module with no internal framework dependencies; uses only PySide6. |
StyleManagers.py |
none | — | Standalone string-based QSS manager; no Qt widget dependencies. |
utils.py |
none | — | Standalone utilities; ThemeManager does import QApplication and QColor at method level. |
document_editor.py |
.utils |
get_resource_path |
Resolving paths to packaged KaTeX, pdf.js, and pdf-lib resources for the Chromium editor surface. |
Known Issues Across Modules
Notable bugs and caveats discovered during documentation analysis
| Module | Issue | Severity |
|---|---|---|
Widgets.py |
allow_same_tyoes typo in StackedWidget (should be allow_same_types) |
Medium |
Widgets.py |
Nested loop bug in add_page() — inner loop variable shadows outer loop variable |
High |
CardGridView.py |
clear() does not clear the cards dictionary, only removes widgets from layout |
Medium |
CardGridView.py |
Commented-out button connection in card widget (self.button.clicked.connect) |
Low |
utils.py |
Unreachable fallback code in ThemeManager.load() after early return |
Low |
utils.py |
Regex-based edit_widget_property may break on nested braces in QSS |
Medium |
utils.py |
get_icon defaults to ext='svg'; non-SVG icons require explicit extension |
Low |
StyleManagers.py |
Regex pattern may match partial widget names (e.g., QPushButton matches QPushButton#id) |
Medium |
StyleManagers.py |
validate_stylesheet does not check for missing closing comments */ |
Low |
document_editor.py |
Hardcoded Pandoc path (C:\Program Files\Abdh\pandoc\pandoc.exe) only works on Windows |
Medium |
document_editor.py |
load_file typo in docstring: “soecified” should be “specified” |
Low |
document_editor.py |
Async runJavaScript callbacks make error handling difficult; QEventLoop blocking can freeze UI |
Medium |