Module developer’s guide to FreeCAD source code for FreeCAD version 0.17-dev 1 Module developer’s guide to FreeCAD source code by Qingfeng Xia http://www.iesensor.com • 2015-09-18 version 0.1 for FreeCAD version 0.16-dev • 2016-09-18 version 0.2 for FreeCAD version 0.17-dev License of this book This ebook is licensed the same as FreeCAD document license CC-BY 3.0 http://creativecommons.org/licenses/by/3.0/ Acknowledge to developers of FreeCAD Original/lead developers: • Jürgen Riegel • Werner Mayer • yorik van havre Add all contributors see http://www.freecadweb.org/wiki/index.php?title= Contributors Target audiances: new module developers Make sure you are familiar with FreeCAD workbench GUI and API as a user: • Foundamental document on official wiki for FreeCAD • FreeCAD python API document • single file PDF user manual for quick start Doxygen documents links Doxygen generated online documentation of source for 0.16dev Why I want to write this book • Learn the software architecture of FreeCAD: a large open source project • Learn to use git to contribute to open source projects like FreeCAD • Save time for new developers to explore the source codde of FreeCAD • Record personal note and lesson during writing/contributing code to FreeCAD • Some chapters of this ebook is seeking to be merged into official wiki after reviewed as usable 1 Organisation of this book • Chapters are written in markdown and PDF is generated by pandoc • Python scripts to link Introduction to header files: *_folder_desc.py • Python script merge.py merges chapters into single md file then PDF How to contribute to this ebook • git clone https://github.com/qingfengxia/FreeCAD_Mod_Dev_Guide.git 2 Contents 1 FreeCAD overview and architecture 7 1.1 Introduction to FreeCAD...............................................7 1.2 Key features.......................................................7 1.3 Software architecture..................................................7 1.3.1 Key software libaries..............................................7 1.3.2 Mixed python and c++............................................7 1.3.3 GPL code will not be included into installler................................8 1.4 How 3D model are renderred.............................................8 1.4.1 Selection of 3D visualization libarary.....................................8 1.4.2 Discussion of 3D rendering library selection on FreeCAD Forum.....................8 1.5 Roadmap........................................................9 1.5.1 Keep updated with main components:....................................9 1.5.2 Pyside 2 project for Qt 5.x..........................................9 2 Organisation of FreeCAD source code 11 2.1 Build system for FreeCAD............................................... 11 2.1.1 Analysis of src/cMake/SMesh.cMake ..................................... 11 2.2 List of files and folders in FreeCAD source folder.................................. 12 2.3 List of modules in FreeCAD Mod folder....................................... 13 2.4 Learning path...................................................... 14 2.5 Learning OpenInventor/Coin3D............................................ 14 2.5.1 OpenInventor in FreeCAD’s ViewProvider.................................. 14 2.5.2 important classes in OpenInventor...................................... 14 2.5.3 Window System integration.......................................... 18 2.5.4 Pivy: Coin3D ’s python wrapping...................................... 19 3 Base and App module (Standalone App without GUI) and Main module 21 3.1 List of header files in Base folder........................................... 21 3.1.1 Frequently included headers files....................................... 23 3.1.2 Correct way of using Sequencer in try-catch block............................. 23 3.1.3 String enconding utf8 and conversion into QString............................. 24 3.2 Type, BaseClass, PyObjectBase............................................ 24 3.2.1 Type system.................................................. 24 3.2.2 Base::BaseClass................................................. 25 3.2.3 PyObjectBase.................................................. 28 3.2.4 src/Base/Persistence.h............................................. 28 3.2.5 GeoFeature: Base class of all geometric document objects......................... 28 3.3 Unit scheme for physial quantity........................................... 28 3.3.1 src/Base/Unit.h................................................ 29 3.3.2 src/Base/Quantity.h.............................................. 29 3.4 List of header files in App folder........................................... 29 3.5 Property framewrok.................................................. 31 3.5.1 src/App/Property.h.............................................. 31 3.5.2 src/App/PropertyStandard.h......................................... 31 3.5.3 Geometry related property.......................................... 32 3.5.4 File related property.............................................. 32 3.5.5 Links related property............................................. 32 3.5.6 Units for physical Quantities......................................... 32 1 2 CONTENTS 3.5.7 src/App/PropertyContainer.h......................................... 32 3.5.8 Macro functions for Property......................................... 33 3.5.9 Naming of property.............................................. 34 3.5.10 PropertyMap.................................................. 34 3.6 Document-View-Observer Pattern.......................................... 34 3.6.1 src/App/Document.h............................................. 34 3.6.2 src/App/DocumentObject.h.......................................... 34 3.6.3 Observer and Subject pattern for documentObject............................. 35 3.6.4 App::DocumentObjectExecReturn...................................... 35 3.6.5 FeaturePython................................................. 36 3.6.6 FeaturePythonPy template class....................................... 36 3.7 Startup process of FreeCADCmd........................................... 38 3.7.1 skeleton of main() function in src/Main/MainCmd.cpp........................... 38 3.7.2 src/Main/MainPy.py.............................................. 38 3.7.3 App::Application class............................................. 38 3.7.4 How Python interpreter is integrated..................................... 39 3.8 FreeCADGui start up process............................................. 40 3.8.1 main() in src/Main/MainGui.cpp....................................... 40 3.8.2 runApplication() in src/Gui/Application.cpp............................... 41 3.8.3 src/Main/FreeCADGuiPy.cpp......................................... 42 4 Overview of Gui module 43 4.1 List of header files in Gui folder............................................ 43 4.2 Important classes in Gui namespace......................................... 46 4.2.1 Gui::Application................................................ 46 4.2.2 Gui::Document................................................. 46 4.2.3 GUI components................................................ 46 4.2.4 Gui Services API................................................ 46 4.3 ViewProvider framework and 3D rederring...................................... 48 4.3.1 Gui::ViewProvider .............................................. 48 4.3.2 Gui::DocumentObjectViewProvider ..................................... 49 4.3.3 Gui::ViewProviderGeometryObject ..................................... 50 4.3.4 Fem::ViewProviderFemConstraint ..................................... 50 4.3.5 3D CAD Part rendering............................................ 50 4.3.6 View3DInventor class............................................. 51 4.3.7 ViewProivder and 3DViewer......................................... 52 4.3.8 2D drawing rendering using Qt native QGraphicsView........................... 53 4.3.9 further reading on ViewProvider....................................... 53 4.4 selection framework.................................................. 53 4.4.1 src/Gui/Selection.h.............................................. 53 4.4.2 src/Gui/SelectionObject.h thin wrapper of DocumentObject pointer................... 53 4.4.3 src/Gui/SelectionView.h show present selection in QListWidget of DockWindow............ 54 4.4.4 src/Gui/SelectionFilter.h expression based filtering............................. 54 4.4.5 src/Gui/MouseSelection.h........................................... 54 4.4.6 Example of getSelection............................................ 54 4.5 Command framework................................................. 54 4.5.1 Overview of command framework....................................... 55 4.5.2 Drawbacks of QAction............................................. 55 4.5.3 Way out..................................................... 55 4.5.4 Boost::signal is used.............................................. 56 4.6 TaskView Framework: UI for interactive design................................... 56 4.6.1 Important classed related to TaskView.................................... 56 4.6.2 Controller of TaskView and TaskDialog................................... 56 4.7 Internationalization with FreeCAD.......................................... 58 4.7.1 Overview of FreeCAD i18n.......................................... 58 4.7.2 integrate a new language into FreeCAD................................... 58 4.7.3 Update of FreeCAD translation.......................................