From 0ec7d4dc6920e359455f9a3c81c3fd7db70f5de2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Drago=C8=99-Andrei=20Bobu?= Date: Wed, 5 Aug 2026 23:54:10 +0300 Subject: [PATCH 1/2] docs: add editor workflow graphic --- docs/editor-workflow.svg | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/editor-workflow.svg diff --git a/docs/editor-workflow.svg b/docs/editor-workflow.svg new file mode 100644 index 0000000..f6beba8 --- /dev/null +++ b/docs/editor-workflow.svg @@ -0,0 +1,40 @@ + + Circuit Diagram Builder workflow + Users choose a component from a menu, rotate and place it, connect component terminals with routed lines, and arrange a circuit diagram. The project visualizes circuits but does not simulate electricity. + + + + + + + Circuit Diagram Builder + A WinBGIm-based schematic editor for placing, rotating and connecting electronic symbols + + + + + + + Choose + Battery, resistor, + capacitor, diode, + transistor and more + Orient + Right-click rotates + the selected symbol + through four states + Place + Left-click positions + the symbol on the + full-screen canvas + Connect + Select two terminals + to draw an orthogonal + wire between them + + + + + Visual editor only + No voltage, current, logic or electrical-behaviour simulation is implemented + From 02dd7c6917de4a9d2447a3facdd24265c3bc97ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Drago=C8=99-Andrei=20Bobu?= Date: Wed, 5 Aug 2026 23:55:05 +0300 Subject: [PATCH 2/2] docs: expand Circuit Diagram Builder technical guide --- README.md | 330 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 308 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 1d9673d..9632dd7 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,318 @@ -# πŸ› οΈ Circuit Diagram Builder -Welcome to Circuit Diagram Builder, a project developed in C++ as part of my Introduction to Programming Course during my Bachelor's studies. +# Circuit Diagram Builder -## πŸ“ Description -This project allows you to create and visualize electronic circuits using a graphical user interface. You can add different components such as resistors, capacitors, and LEDs, and connect them using wires to create a functioning circuit. +**A C++/WinBGIm desktop prototype for arranging and connecting electronic schematic symbols on a graphical canvas.** -Please note that this project is still in development and does not yet have a simulation feature. +

+ Circuit Diagram Builder workflow +

-## πŸš€ Getting Started -To use this project, you will need to have Code::Blocks installed with the [WinBGIm](https://home.cs.colorado.edu/~main/bgi/dev-c++/) library. +

+ Language + Graphics + IDE + Platform + Status +

-### Building From Source (using Code::Blocks) -To get started with this project, follow these steps: +## Overview -1. Clone this repository to your local machine. -2. Open the [Electron.cbp](https://github.com/BobuDragos/Circuit-Diagram-Builder/blob/main/Electron/Electron.cbp) file with Code::Blocks. -3. Build and run the project. +Circuit Diagram Builderβ€”internally titled **Electron**β€”is an educational desktop application for constructing schematic diagrams. Users select electronic symbols from a menu, rotate and position them, then connect their terminals with routed lines. -### Windows Executable -If you just want to execute the software, you can find [this Windows executable](https://github.com/BobuDragos/Circuit-Diagram-Builder/blob/main/Electron/bin/Debug/Electron%20prof.exe) under `Bin/Debug`. +The project focuses on graphical editing and interaction. It does **not** simulate current, voltage, logic states or electrical behaviour. -### Linux Building from Source -You'll have to build the [c++ Source Code](https://github.com/BobuDragos/Circuit-Diagram-Builder/blob/main/Electron/unitedCode.cpp) using `gcc` +## What the application supports -If you encounter any issues, feel free to open an issue in the repository. -## πŸ“ License -This project is released under the GNU General Public License v3.0. +- Full-screen WinBGIm graphical interface. +- Menu of reusable electronic symbols. +- Data-driven symbol descriptions loaded from `.PS` files. +- Placement of multiple instances on a drawing canvas. +- Four-way symbol rotation. +- Connection points attached to symbols. +- Orthogonal wire drawing between terminals. +- Automatic creation of an intermediate node when a connection ends away from an existing terminal. +- Moving already placed components. +- Zooming symbols in and out. +- Audible feedback for editing actions. +- Debug and release targets in a Code::Blocks project. -Enjoy exploring the world of circuit design with Circuit Diagram Builder! πŸš€ +## Included component types -## 🀝 Contact -If you have any questions about this repository or would like to get in touch with Dragos A. Bobu, feel free to reach out to his [email](mailto:bobudragos0@gmail.com?subject=[GitHub]CircuitDiagram%20Interest) or [website](https://bobudragos.github.io/). +The Code::Blocks project includes definition files for: + +| Definition file | Intended symbol | +|---|---| +| `AMPLOP.PS` | Operational amplifier | +| `BATERIE.PS` | Battery | +| `CONDENS.PS` | Capacitor | +| `DIODA.PS` | Diode | +| `NOD.PS` | Connection node | +| `POLARIZ.PS` | Polarised component/source | +| `REZIST.PS` | Resistor | +| `SERVOMOT.PS` | Servo motor | +| `SINU.PS` | Sinusoidal source | +| `STOP.PS` | Stop/indicator component | +| `TRANZNPN.PS` | NPN transistor | +| `TRANZPNP.PS` | PNP transistor | +| `ZENNER.PS` | Zener diode | + +The labels are inherited from the original Romanian implementation. + +## User workflow + +```mermaid +flowchart LR + Menu[Component menu] + Select[Select symbol] + Rotate[Right-click to rotate] + Place[Left-click to place] + Terminal[Select a terminal] + Destination[Select destination terminal] + Wire[Draw orthogonal wire] + Edit[Move or zoom components] + + Menu --> Select --> Rotate --> Place + Place --> Terminal --> Destination --> Wire + Wire --> Edit + Edit --> Select +``` + +### Place a component + +1. Open the create/editor view. +2. Left-click a component in the menu. +3. While positioning it, right-click to rotate it. +4. Left-click the canvas to place it. + +### Connect components + +1. Left-click near a connection point on a placed component. +2. Move the pointer; the application previews a routed line. +3. Left-click a connection point on another component. +4. The connection is stored and rendered. + +When the destination does not match an existing component terminal, the current implementation may add a node at the clicked position. + +### Move a component + +Right-click near an already placed component, then reposition it through the placement workflow. + +### Zoom + +- Double right-click: increase symbol zoom. +- Double left-click: decrease symbol zoom. + +The zoom operation redraws existing pieces at the new scale. + +## Architecture + +```mermaid +flowchart TD + Project[Electron.cbp] + App[unitedCode.cpp] + Definitions[*.PS symbol definitions] + Menu[Symbol menu] + PieceState[Placed-piece array] + Connections[Connection array] + WinBGIm[WinBGIm / graphics.h] + Canvas[Desktop canvas] + + Project --> App + Definitions --> App + App --> Menu + App --> PieceState + App --> Connections + App --> WinBGIm + WinBGIm --> Canvas +``` + +## Data model + +The single source file defines compact C-style structures: + +### `piesa` β€” component instance + +Stores: + +- numeric identifier; +- instance frequency/count; +- name and display content; +- canvas position; +- orientation; +- connection points; +- a drawing description. + +### `descriere` β€” drawing instructions + +Stores a command list and coordinate pairs. Symbol-definition files are loaded into this structure and rendered through primitives such as lines and rectangles. + +### `legatura` β€” connection + +Stores: + +- the two component/node identifiers; +- the selected terminal index on each endpoint; +- a connection type field reserved for future use. + +### Fixed-capacity storage + +The implementation uses fixed-size global arrays for menu entries, placed pieces, nodes and connections. This keeps the introductory-programming implementation straightforward but places hard limits on document size. + +## Repository structure + +```text +Circuit-Diagram-Builder/ +β”œβ”€β”€ Electron/ +β”‚ β”œβ”€β”€ Electron.cbp # Code::Blocks project +β”‚ β”œβ”€β”€ unitedCode.cpp # Application source +β”‚ β”œβ”€β”€ *.PS # Component drawing definitions +β”‚ β”œβ”€β”€ bin/ +β”‚ β”‚ β”œβ”€β”€ Debug/ +β”‚ β”‚ └── Release/ +β”‚ └── obj/ # Generated object files +β”œβ”€β”€ docs/ +β”‚ └── editor-workflow.svg +β”œβ”€β”€ LICENSE +└── README.md +``` + +## Recommended platform + +The application is strongly Windows-specific because it uses: + +- `winbgim.h`; +- `graphics.h`; +- Windows mouse event constants such as `WM_LBUTTONDOWN`; +- `GetSystemMetrics`; +- `Beep`; +- a Code::Blocks GNU compiler configuration. + +The most reliable path is Windows with Code::Blocks and a correctly configured WinBGIm toolchain. + +## Build with Code::Blocks + +### Prerequisites + +- Windows. +- Code::Blocks with a MinGW/GCC compiler. +- WinBGIm headers and libraries configured for that compiler. + +### Steps + +```bash +git clone https://github.com/Machine-Learning-Compatible-Game-Engine/Circuit-Diagram-Builder.git +``` + +Then: + +1. Open `Electron/Electron.cbp` in Code::Blocks. +2. Confirm that `winbgim.h` and `graphics.h` are visible to the compiler. +3. Confirm that the required BGI libraries are linked by the Code::Blocks toolchain configuration. +4. Select the `Debug` or `Release` target. +5. Build and run. + +The project declares: + +- Debug output: `Electron/bin/Debug/Electron prof.exe` +- Release output: `Electron/bin/Release/Electron prof.exe` + +The component `.PS` files must remain available in the working directory expected by the executable because the application opens them by relative filename. + +## Run the committed Windows executable + +A historical debug executable is stored at: + +```text +Electron/bin/Debug/Electron prof.exe +``` + +Run executables committed to source repositories only after reviewing their provenance. Building from source is preferable. + +## Why a direct Linux build is not currently portable + +The previous README suggested compiling the source with GCC on Linux. In practice, ordinary Linux GCC is insufficient because the program depends on Windows APIs and WinBGIm-specific event handling. + +A portable Linux version would require replacing or abstracting: + +- WinBGIm drawing and window management; +- Windows mouse constants; +- screen-size detection; +- sound feedback; +- executable and project configuration. + +Suitable replacement options could include SDL2, SFML, raylib or Qt. + +## Symbol-definition format + +Each component is loaded from a file named after its internal symbol name with a `.ps`/`.PS` extension. The current parser reads: + +1. symbol name; +2. number of connection points; +3. coordinates for each terminal; +4. display content; +5. number of drawing commands; +6. command letters and coordinate pairs. + +This allows symbols to be changed without recompiling the C++ source, but the format is positional and undocumented beyond the parser. + +A future schema should define: + +- formal command names; +- versioning; +- validation errors; +- coordinate units; +- supported primitives; +- arbitrary terminal counts; +- metadata such as category and electrical type. + +## Current rendering model + +The editor uses immediate drawing calls and redraws pieces manually. Rotations transform each stored point through repeated 90-degree coordinate changes. Connections are displayed as three orthogonal line segments: + +```text +endpoint A β†’ horizontal midpoint β†’ vertical segment β†’ endpoint B +``` + +This keeps wires visually structured without implementing a full routing algorithm. + +## Known limitations + +- No electrical simulation. +- No circuit-rule validation. +- No voltage/current/source model. +- No undo/redo system. +- Fixed-size arrays cap the number of pieces and connections. +- The entire application is concentrated in one large source file. +- Global mutable state is used throughout. +- File parsing lacks robust error handling and schema validation. +- The code assumes every definition file exists and is correctly formatted. +- Symbol rotation logic duplicates transformations for each drawing primitive. +- Wire routing is only midpoint-based and does not avoid obstacles. +- Connections do not automatically follow all component moves reliably without a more explicit graph/redraw model. +- The connection type field is unused. +- Windows-specific APIs prevent a straightforward Linux build. +- Generated object files and executables are committed. +- There is no automated test suite or CI build. +- Existing binaries may not run on every modern Windows environment. + +## Recommended next steps + +1. Separate model, rendering, input and persistence code into modules. +2. Introduce dynamic containers such as `std::vector`. +3. Define and validate a versioned component-description format. +4. Replace WinBGIm with a maintained cross-platform UI or graphics framework. +5. Add a scene graph where wires reference component terminal identifiers. +6. Recompute wire endpoints whenever a component moves or rotates. +7. Add selection, deletion, undo and redo. +8. Add save/load using a documented project format. +9. Add grid snapping and obstacle-aware wire routing. +10. Treat simulation as a separate subsystem after the editor model is reliable. +11. Remove generated binaries and build artefacts from version control. +12. Add screenshots from a freshly built version and automated Windows builds. + +## Project context + +The project originated in an introductory university programming course. Its main value is demonstrating how a graphical editor can be assembled from basic structures, file parsing, mouse events, geometry transformations and drawing primitives. + +## Licence + +The repository contains a GNU General Public License v3.0 licence. Redistribution and derivative work must comply with that licence.