GUI Architecture & Qt Integration
Relevant source files
The following files were used as context for generating this wiki page:
The GUI architecture of the project is built upon the Qt framework, utilizing a decoupled approach where user interface definitions are separated from the underlying logic. The system integrates C++ backend controllers with Qt Designer .ui files and Python-based workbench initializations to provide a responsive and modular modeling environment. This architecture supports specialized components such as Task Panels, Workbenches, and specialized widgets for 3D coordinate manipulation.
Sources: src/Mod/Draft/drafttaskpanels/README.md:1-10, src/Mod/TechDraw/Gui/TaskComplexSection.cpp:45-60
Workbench and Task Panel Structure
The project employs a structured approach to GUI components, emphasizing the separation of concerns. Workbenches serve as the primary containers for tools and GUI commands, while Task Panels provide the specific interface for active operations.
Task Panel Logic
Modern GUI commands utilize individual task panel modules and corresponding .ui files. This replaces "old style" commands that relied on monolithic modules (like DraftGui.py) which selectively hid or showed widgets. The current standard requires:
- UI Definitions: Stored in
.uifiles created with Qt Designer and located inResources/ui/directories. - Logic Classes: Backend C++ or Python classes that handle the state and data flow of the interface (e.g.,
TaskDlgComplexSection).
Sources: src/Mod/Draft/drafttaskpanels/README.md:10-25, src/Mod/TechDraw/Gui/TaskComplexSection.cpp:665-680
GUI Component Interaction
The following diagram illustrates the relationship between GUI commands, task panels, and the Qt resource system.
The diagram shows how the logic layer orchestrates the display of task panels by loading predefined UI resources.
Sources: src/Mod/Draft/drafttaskpanels/README.md:5-20, src/Mod/TechDraw/Gui/TaskComplexSection.cpp:670-685
Qt Integration and Build System
The integration of Qt components into the build process is handled via CMake, specifically through the qt_find_and_add_translation and qt_add_resources macros.
UI and Resource Compilation
The build system manages the conversion of .ui files and translation files (.ts to .qm) into executable code.
| Component Type | Description | File Patterns |
|---|---|---|
| User Interface | Qt Designer files defining widget layouts. | *.ui |
| Resources | Compiled icons, fonts, and metadata. | *.qrc |
| Translations | XML-based source strings for internationalization. | *.ts |
Sources: src/Mod/TechDraw/Gui/CMakeLists.txt:30-70, src/Mod/Help/Resources/translations/Help_en.ts:5-20
Translation Workflow
The system uses PySide and QtWebEngineWidgets for rendering documentation and help files. If these components are missing, the system defaults to the system web browser.
Sources: src/Mod/Help/Resources/translations/Help_en.ts:115-125, src/Mod/Help/Resources/translations/Help_ms.ts:170-185
Specialized GUI Components
TaskComplexSection Implementation
The TaskComplexSection class demonstrates complex integration of custom Qt widgets and 3D data. It uses:
- CompassWidget: For directional selection.
- VectorEditWidget: For coordinate input.
- WaitCursor: To provide visual feedback during long-running operations.
This sequence shows the interactive loop when a user modifies section parameters in a Task Panel.
Sources: src/Mod/TechDraw/Gui/TaskComplexSection.cpp:250-280, src/Mod/TechDraw/Gui/TaskComplexSection.cpp:530-550
Coding Conventions for GUI
Strict coding standards are maintained for GUI development to ensure consistency and minimize merge conflicts.
- GUI Guards: Imports of modules requiring a graphical interface (e.g.,
FreeCADGui) must be guarded by anif FreeCAD.GuiUp:test to ensure console-only functionality remains intact. - Separation of Logic: Console-only functions must be kept separate from GUI implementations.
- Naming: Command icons must use the command name precisely.
Sources: src/Mod/Draft/coding_conventions.md:45-55, src/Mod/Fem/coding_conventions.md:165-175
Summary
The GUI architecture focuses on modularity through the use of discrete Task Panels and Qt Designer files. By enforcing strict separation between logic and interface definitions, the system allows for independent tool development and robust internationalization. Integration with the 3D core is achieved through specialized widgets and a command-based synchronization mechanism that ensures the document state remains consistent with user interactions.