The Hypothetical FreeCAD Workbench SDK

A Conceptual Mapping Based on the LibreOffice SDK Architecture

⚠️ DISCLAIMER FOR TESTING AND VALIDATION ⚠️ This document represents a conceptual hypothesis. FreeCAD does not distribute a formal, standalone "Software Development Kit" archive like LibreOffice or Android. Instead, the FreeCAD application itself, combined with its embedded Python console and Qt framework, acts as the SDK. The directory structures and concepts described below under "The SDK Structure" are a comparative analogy designed to bridge the mental model from LibreOffice UNO/IDL to FreeCAD's Python/Qt architecture. If you plan to test or validate these concepts, you must use the live Sample Projects linked in Section 3, as downloading a "FreeCAD-SDK.zip" is not structurally possible.

1. The Structure Up Front: Mapping the SDK

If FreeCAD were to package its development tools into a traditional SDK folder structure (mimicking the LibreOffice model), it would conceptually look like this:

`📁 bin/` (Build & Design Tools)

In LibreOffice, this contains IDL compilers and registry merge tools. In FreeCAD, interface compilation is handled by standard Python and Qt tools:

Qt Designer: The visual layout editor. You do not write GUI coordinate code by hand; you drag-and-drop elements to generate .ui XML files. [^1]
pyside2-uic / pyside6-uic: The compiler that translates your .ui XML files into executable Python classes for your workbench.
FreeCAD Addon Manager: Acts as the dependency manager and distribution compiler, similar to a package manager.

`📁 interfaces/` (The API Definitions)

LibreOffice uses abstract UNO IDL files. FreeCAD uses core Base Classes that you must inherit from:

Gui.Command: The absolute base interface for any clickable button or tool in FreeCAD. It requires you to implement Activated(), GetResources(), and IsActive(). [^2]
Workbench / StdWorkbench: The interface defining how your tools are grouped into menus and toolbars.
App.Property: The definitions (e.g., App::PropertyLength, App::PropertyBool) that tell FreeCAD how to expose your internal variables to the user-facing Property Editor.

`📁 include/` (Headers & Bridges)

LibreOffice uses C++ headers to bridge Java/C++ and UNO. FreeCAD bridges the OpenCASCADE C++ kernel to Python:

FreeCAD (App): The headless bridge module. Handles document topology, object creation, and mathematical logic.
FreeCADGui (Gui): The visual bridge module. Handles 3D view manipulation, colors, and Qt window spawning.
pivy (Coin3D): The bridge to the 3D scenegraph, allowing you to draw custom manipulators (like drag-arrows) directly in the 3D viewport. [^3]

2. UI Paradigm Clarifications (from the Video)

https://www.youtube.com/watch?v=_tFZRfQNGt

Based on the provided video (FreeCAD Python Programming: QT Gui Reusable Custom Widgets), FreeCAD's UI development drastically differs from standard LibreOffice VCL dialogs.

The "Widget-Window" Duality: FreeCAD leverages Qt's modularity. You do not code a "Pop-up Window" differently than a "Docked Panel". You create a subclass of QWidget.
- If you call myWidget.show(), it behaves as a floating dialog.
- If you pass it to FreeCADGui.Control.showDialog(myWidget), it seamlessly embeds itself into FreeCAD's native "Task Panel" (the left-hand sidebar).
Complex List Items (QListWidgetItem): Workbenches often require parametric managers (e.g., a list of materials where each row has its own "Edit" button). The video clarifies that you can inject entire custom widgets into single list rows using setItemWidget(), rather than relying on standard text-only arrays.
Inheritance over Interface: Unlike LibreOffice's strict "implement this UNO interface" rule, FreeCAD UI relies on Qt inheritance. You subclass native Qt widgets and override their specific event handlers (like mousePressEvent) to interact with the FreeCAD 3D view.

3. Sample Projects for Forking & Testing

To begin experimentation, you must fork a community-standard template. These repositories contain the boilerplate Init.py and InitGui.py files required by FreeCAD's initialization engine.

Option A: The Official Starter Kit (Best for modern setups)

Repository: FreeCAD/freecad.workbench_starterkit [^4]
Description: The official template maintained by the FreeCAD core team. It includes standard CI/CD workflows, licensing boilerplate, and the exact folder structure expected by the Addon Manager.
How to test: 1. Clone the repo. 2. Symlink the folder into your local FreeCAD Mod directory: * Linux: ln -s /path/to/repo ~/.local/share/FreeCAD/Mod/ * Windows: Create a shortcut in %APPDATA%\FreeCAD\Mod\ 3. Restart FreeCAD; the new dummy workbench will appear in the dropdown.

Option B: The Minimal Python Template (Best for absolute beginners)

Repository: chbergmann/PythonWorkbenchTemplate [^5]
Description: A highly simplified, bare-bones template. It provides a single dummy command (coloring an object red or green) and demonstrates how to hook up a basic .ui file designed in Qt Designer to the FreeCAD Task Panel.

4. Extensive Sources & Footnotes

[^1]: FreeCAD Developers Handbook - Design Guide: Official guidelines on User Experience, Interaction, and Qt Interface development in FreeCAD. Read here. [^2]: FreeCAD Wiki: Workbench Creation: The definitive guide on the Init.py / InitGui.py initialization sequence and the Gui.Command class structure. Read here. [^3]: FreeCAD Wiki: Power Users Hub (Coin3D): Documentation detailing how the GUI uses the Coin3D scenegraph via the pivy library for viewport rendering. Read here. [^4]: GitHub: FreeCAD/freecad.workbench_starterkit: The official template for workbench add-ons. Note: The cookiecutter aspect was recently deprecated in favor of standard templating, but the repository remains the structural gold standard. View Repository. [^5]: GitHub: chbergmann/PythonWorkbenchTemplate: A community-provided template demonstrating a fully functional, minimal Python workbench with an integrated Task Panel UI. View Repository. [^6]: FreeCAD GitHub Discussions (#18254): Developer consensus on the recommended approaches for generating workbenches from templates (comparing the Starterkit vs. the internal fcbt FreeCAD Build Tool). View Discussion.