# githubuser0xffff/qt-advanced-docking-system architecture

> Architecture diagram of the GitHub repository githubuser0xffff/qt-advanced-docking-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/githubuser0xffff/qt-advanced-docking-system
- Repository: https://github.com/githubuser0xffff/qt-advanced-docking-system

## Overview

##### Project Type and Purpose
- This is an open‑source C++/Qt library (“Qt Advanced Docking System”) providing a rich docking framework (dock widgets, auto‑hide sidebars, floating containers, perspectives, etc.) with Python bindings (via SIP) and accompanying demo and example applications.

##### File Structure Analysis
- Top‐level build/config files: CMakeLists.txt, .pro/.pri (Qt qmake), CI configs (.travis.yml, appveyor), LICENSE, MANIFEST.in
- cmake/: custom CMake modules
- src/: core C++ library implementation (CDockManager, CDockWidget, DockComponentsFactory, various widget and controller classes, stylesheets, resources)
- sip/: SIP interface definitions to generate Python extension modules
- project.py & pyproject.toml: Python packaging entry points
- demo/: “AdvancedDockingSystemDemo” Qt‑based application (C++ & Python entrypoints), UI files, resources, CSS
- examples/: standalone Qt/C++ and Qt/Python sample apps illustrating specific features (auto‑hide, sidebar, central widget, etc.)
- doc/: user guide, manifest for Qt Marketplace, Markdown docs, images/gifs

##### README Insights
- Confirms core functionality (docking, auto‑hide, splitter modes, perspectives)
- Highlights dual C++/Python API surface, supported Qt versions, build instructions and dependencies

a. Main Components
- Core Library (C++/Qt)
- Python Binding Layer (SIP‑generated extensions)
- Demo Application (C++ Qt demo & optional Python launcher)
- Example Applications (C++ and Python sample UIs)
- Build System (CMake + qmake, SIP toolchain)
- External Dependencies (Qt5/Qt6, Python, SIP)
- Persistence (perspectives.ini)
b. Relationships & Data Flows
- Demo & examples → link to Core Library
- Python demos/examples → import SIP‑generated Python module → calls into C++ library
- Build System orchestrates: compiles src/ into shared library, runs SIP on sip/ to produce binding code, packages Python module, builds demo & examples
- Core Library ↔ Qt framework (widgets, signals/slots, QSplitter, QMainWindow)
- Core Library → reads/writes perspectives.ini (persist/)
c. Architectural Patterns & Principles
- Modular layering: UI logic separated from core docking logic
- Factory pattern: DockComponentsFactory abstracts creation of internal widget elements
- Plugin/Binding extensibility via SIP interfaces
- Single source of truth for state via DockManager and perspectives
d. Key Technologies & Frameworks
- C++17 (or C++11/14) with Qt Widgets (Qt5/6)
- CMake (primary) + Qt .pro/.pri for qmake compatibility
- SIP for Python bindings (PyQt5/6, PySide6)
- Python 3 packaging (pyproject.toml, project.py)
- CI: Travis, Appveyor, GitHub Actions

##### Essential Elements
- Core modules grouping (e.g., Manager, Widgets, Controllers, Factories)
- SIP folder → Python module generation path
- Demo & examples executables with UI artifacts (UI files, CSS)
- CMake & qmake invocations
- External Qt and Python environments

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Applications Layer
    subgraph "Applications" 
        direction TB
        Demo_CPP["AdvancedDockingSystemDemo (C++ Launcher)"]:::apps
        Demo_Py["AdvancedDockingSystemDemo (Python Launcher)"]:::apps
        Ex_CPP["Examples (C++ Samples)"]:::apps
        Ex_Py["Examples (Python Scripts)"]:::apps
    end

    %% SIP Binding Layer
    subgraph "Python Binding Layer" 
        direction TB
        SIP_Module["ads_python (SIP-generated Module)"]:::sip
    end

    %% Core Library Layer
    subgraph "Core C++ Library" 
        direction TB
        Core_Manager["ads::CDockManager"]:::core
        Core_Factory["DockComponentsFactory"]:::core
        Core_Widgets["CDockWidget & Controllers"]:::core
        Core_Resources["Stylesheets & Images"]:::core
    end

    %% Persistence
    Persist["persist/perspectives.ini"]:::persistence

    %% Build System Layer
    subgraph "Build System & Packaging"
        direction TB
        Root_CMake["CMakeLists.txt (root)"]:::build
        Qmake_Proj["ads.pro / ads.pri"]:::build
        CMake_Modules["cmake/modules/"]:::build
        CI_Config[".travis.yml / appveyor / workflows"]:::build
        Py_Pack["pyproject.toml / project.py"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Qt["Qt5 / Qt6"]:::external
        Python["Python 3 + SIP"]:::external
    end

    %% Runtime Relationships
    Demo_CPP -->|"uses API"| Core_Manager
    Ex_CPP -->|"uses API"| Core_Manager
    Demo_Py -->|"imports"| SIP_Module
    Ex_Py -->|"imports"| SIP_Module
    SIP_Module -->|"calls"| Core_Manager
    Core_Manager -->|"creates via"| Core_Factory
    Core_Manager -->|"manages"| Core_Widgets
    Core_Resources -->|"loaded by"| Core_Widgets
    Persist -->|"read/write"| Core_Manager
    Core_Manager -->|"relies on"| Qt
    SIP_Module -->|"relies on"| Python

    %% Build-time Relationships
    Root_CMake -.->|"compiles"| Core_Manager
    Root_CMake -.->|"processes"| SIP_Module
    Root_CMake -.->|"builds"| Demo_CPP
    Root_CMake -.->|"builds"| Ex_CPP
    Qmake_Proj -.->|"alternative build"| Core_Manager
    CMake_Modules -.-> Root_CMake
    CI_Config -.-> Root_CMake
    Py_Pack -.-> SIP_Module

    %% Click Events
    click Core_Manager "https://github.com/githubuser0xffff/qt-advanced-docking-system/tree/master/src/"
    click Core_Manager "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/src/CMakeLists.txt"
    click Core_Resources "https://github.com/githubuser0xffff/qt-advanced-docking-system/tree/master/src/stylesheets/"
    click Core_Resources "https://github.com/githubuser0xffff/qt-advanced-docking-system/tree/master/src/images/"
    click SIP_Module "https://github.com/githubuser0xffff/qt-advanced-docking-system/tree/master/sip/"
    click SIP_Module "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/sip/ads.sip"
    click Py_Pack "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/project.py"
    click Py_Pack "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/pyproject.toml"
    click Demo_CPP "https://github.com/githubuser0xffff/qt-advanced-docking-system/tree/master/demo/"
    click Demo_CPP "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/demo/CMakeLists.txt"
    click Ex_CPP "https://github.com/githubuser0xffff/qt-advanced-docking-system/tree/master/examples/"
    click Root_CMake "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/CMakeLists.txt"
    click Qmake_Proj "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/ads.pro"
    click Qmake_Proj "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/ads.pri"
    click CMake_Modules "https://github.com/githubuser0xffff/qt-advanced-docking-system/tree/master/cmake/modules/"
    click CI_Config "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/.travis.yml"
    click CI_Config "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/.appveyor.yml"
    click CI_Config "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/.github/workflows/linux-builds.yml"
    click Persist "https://github.com/githubuser0xffff/qt-advanced-docking-system/blob/master/persist/perspectives.ini"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#006064,color:#006064
    classDef sip fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef apps fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef build fill:#ECEFF1,stroke:#455A64,color:#37474F
    classDef external fill:#FFFDE7,stroke:#F9A825,color:#F57F17
    classDef persistence fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
```
