# polarix/simplegui architecture

> Architecture diagram of the GitHub repository polarix/simplegui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polarix/simplegui
- Repository: https://github.com/polarix/simplegui

## Overview

##### Project type and purpose
- SimpleGUI is a lightweight C-based GUI interface library for monochrome display screens, accompanied by:
- A core GUI rendering library (GUI/)
- An interaction engine (HMI/)
- A sample application (DemoProc/)
- A PC-side simulator (Simulator/)
- Hardware-specific BSP code for embedded targets (Transplant/MiniDevCore/)
- External dependencies (iconv under Library/)
- Its purpose is to render basic graphics and GUI components on resource-constrained monochrome displays, and to provide a simulator for development off-target.

##### File structure
- Top-level build: CMakeLists.txt orchestrates builds for embedded and simulator targets.
- Library/ contains iconv for character encoding.
- GUI/inc, GUI/src: core drawing and widget interfaces.
- HMI/inc, HMI/src: input/event engine that drives GUI widgets.
- DemoProc/inc, DemoProc/src: sample application showcasing GUI usage.
- Simulator/: C++/SDL2 project that links GUI & HMI for PC simulation.
- Transplant/MiniDevCore/BSP: hardware abstraction for timers, display, input on embedded boards.
- Documents/ and Images/ provide user guides and API docs (not part of runtime).

##### README for additional insights
- Core design goals: minimal resource usage, no layers/buffers, direct drawing APIs.
- Simulator originally used wxWidgets, now uses SDL2 via VirtualSDK abstraction.
- Emphasis on portability and low-overhead.

##### Main components and interactions
a. Components
1. Core GUI Library
2. HMI Interaction Engine
3. Sample App (DemoProc)
4. PC Simulator (SDL2)
5. Hardware Abstraction Layer (BSP)
6. External Iconv Library
7. Build System (CMake)
b. Relationships
- DemoProc and Simulator both link against the core GUI library and HMI engine.
- On PC, GUI/HMI use SDL2 via the Simulator_if layer to emulate display and input.
- Iconv provides text encoding support to the GUI text module.
- CMake drives configuration, selects build targets (embedded vs simulator), and locates external libraries.
c. Architectural patterns
– Layered architecture:
- Presentation layer (GUI library)
- Interaction layer (HMI engine)
- Platform abstraction layer (BSP or Simulator interface)
- Application layer (DemoProc)
– Separation of concerns: core drawing vs input vs platform code vs applications.
d. Technologies
- Language: C (GUI, HMI, BSP), C++ (Simulator)
- Build: CMake, optional Code::Blocks project for Simulator
- External libs: iconv, SDL2
- Documentation in Markdown/PDF

##### Detailed capture of essential elements
- Build branching in CMake: options for TARGET=EMBEDDED vs TARGET=SIMULATOR.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    CMAKE["CMakeLists.txt"]:::build

    %% External Dependencies
    ICONV["iconv (Library)"]:::external

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        GUI["GUI Library\n(GUI/)"]:::core
        HMI["HMI Engine\n(HMI/)"]:::core
    end

    %% Platform Adapters
    subgraph "Platform Adapters" 
        direction TB
        BSP["BSP HAL\n(Transplant/MiniDevCore/BSP/)"]:::platform
        USERINIT["User Init\n(Transplant/MiniDevCore/User/)"]:::platform
        SIM_IF["Simulator Interface\n(Simulator/)"]:::platform
    end

    %% Applications
    subgraph "Applications"
        direction TB
        DEMOPROC["DemoProc App\n(DemoProc/)"]:::app
        SIMULATOR["PC Simulator\n(Simulator/)"]:::app
    end

    %% Targets / Hardware
    subgraph "Targets"
        direction TB
        PHYS_DISPLAY["Physical Display\n/ Input / Timers"]:::hardware
        SDL2["SDL2 Window"]:::hardware
    end

    %% Build relationships
    CMAKE -->|configures build| GUI
    CMAKE -->|configures build| HMI
    CMAKE -->|configures build| DEMOPROC
    CMAKE -->|configures build| SIMULATOR
    CMAKE -->|selects target| BSP
    CMAKE -->|selects target| SIM_IF

    %% Dependency flows
    ICONV -->|text encoding| GUI
    DEMOPROC -->|uses| HMI
    DEMOPROC -->|uses| GUI
    SIMULATOR -->|links| HMI
    SIMULATOR -->|links| GUI

    HMI -->|calls| GUI
    GUI -->|draw / timer / input calls| BSP
    USERINIT -->|initializes hardware| BSP
    BSP -->|drives| PHYS_DISPLAY

    GUI -->|SDL2 draw / input| SIM_IF
    SIM_IF -->|uses| SDL2
    SIMULATOR -->|runs on| SDL2

    %% Click Events
    click GUI "https://github.com/polarix/simplegui/tree/Stable/GUI/"
    click HMI "https://github.com/polarix/simplegui/tree/Stable/HMI/"
    click DEMOPROC "https://github.com/polarix/simplegui/tree/Stable/DemoProc/"
    click SIMULATOR "https://github.com/polarix/simplegui/tree/Stable/Simulator/"
    click BSP "https://github.com/polarix/simplegui/tree/Stable/Transplant/MiniDevCore/BSP/"
    click USERINIT "https://github.com/polarix/simplegui/tree/Stable/Transplant/MiniDevCore/User/"
    click ICONV "https://github.com/polarix/simplegui/tree/Stable/Library/"
    click CMAKE "https://github.com/polarix/simplegui/blob/Stable/CMakeLists.txt"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef platform fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef app fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef build fill:#FFFFE0,stroke:#333,stroke-width:1px;
    classDef hardware fill:#FFC0CB,stroke:#333,stroke-width:1px;
```
