Debugging Tools for FreeCAD UI Development

FreeCAD provides a robust suite of built-in features and integration points designed to help developers build, test, and troubleshoot user interfaces directly inside the application environment. By combining an interactive Python runtime with native Qt introspection and real-time logging facilities, developers can inspect active widgets, debug PySide signals and slots, and tweak visual layouts without needing to recompile the application or restart their sessions.

The Interactive Python Console

The primary environment for real-time UI debugging in FreeCAD is the built-in Python Console. Because FreeCAD’s graphical interface is built on Qt using PySide, the entire running UI hierarchy is accessible to the embedded Python interpreter.

Developers can obtain a reference to the main application window using the FreeCADGui module:

import FreeCADGui
main_win = FreeCADGui.getMainWindow()

From this handle, developers can use native Qt methods such as findChildren() to query active widgets, inspect object names, simulate user interactions, and modify widget states live. Calling Qt's built-in dumpObjectTree() on any container widget prints the current hierarchy to standard output, making it straightforward to diagnose layout bugs and orphaned components.

The Report View and Logging Engine

The Report View acts as FreeCAD’s internal console for capturing standard output, standard error, and internal framework messaging. For UI developers, this view provides immediate visual feedback on broken layout constraints, missing PySide imports, and runtime execution errors.

FreeCAD routes UI and core messages through its logging engine, accessible in Python via the FreeCAD.Console module. Developers can emit graded log entries using dedicated functions:

  • FreeCAD.Console.PrintMessage(): General debugging output.
  • FreeCAD.Console.PrintWarning(): Non-fatal UI or configuration issues.
  • FreeCAD.Console.PrintError(): Exceptions, invalid signal connections, or missing UI resources.
  • FreeCAD.Console.PrintLog(): Detailed execution logs intended for verbose diagnostics.

Log output behavior can be tuned directly within FreeCAD’s preferences under Edit → Preferences → General → Output window, where developers can enable message redirection to capture Python exceptions alongside Qt warning messages.

Dynamic Qt Stylesheet (QSS) Testing

UI developers troubleshooting styling or theming inconsistencies can alter the visual appearance of widgets on the fly. Rather than packaging and reloading full workbenches to test minor visual adjustments, styles can be injected globally or applied to specific child widgets through the console:

main_win.setStyleSheet("QPushButton { background-color: #ff0000; }")

This live modification helps isolate conflicting CSS rules and determines whether display issues stem from the platform’s native desktop theme or FreeCAD's internal stylesheets.

Native UI File Loaders

FreeCAD includes built-in loaders for Qt Designer files (.ui), primarily through FreeCADGui.PySideUic. This integration allows developers to test task panels, dialog boxes, and custom widgets without pre-compiling UI files into Python code. By loading XML-based UI definitions directly into running workbenches via PySideUic.loadUi(), developers can instantly observe how custom forms behave inside FreeCAD’s dockable panels and task view framework.

Command-Line Diagnostic Flags

When troubleshooting severe UI freezes or rendering crashes, developers can utilize FreeCAD’s built-in command-line debugging parameters:

  • --write-log: Writes all internal logging and console messaging directly to a text file.
  • --log-file <target>: Specifies the exact path for recording runtime diagnostics, bypassing the UI completely if the graphical shell fails to initialize.
  • --console: Starts FreeCAD without loading the graphical interface, allowing headless validation of UI scripts and underlying modules.