Adding new modules and workbenches in FreeCAD is very easy. We call module any extension of FreeCAD, while a workbench is a special GUI configuration that groups some toolbars and menus. Usually you create a new module which contains its own workbench.

Modules can be programmed in C++ or in python, or in a mixture of both, but the module init files must be in python. Setting up a new module with those init files is easy, and can be done either manually or with the FreeCAD build tool.

Using the FreeCAD Build tool

Creating a new application module in FreeCAD is rather simple. In the FreeCAD development tree exists the FreeCAD Build Tool (fcbt) that does the most important things for you. It is a Python script located under

 trunk/src/Tools/fcbt.py

When your python interpreter is correctly installed you can execute the script from a command line with

 python fcbt.py

It will display the following menu:

 FreeCAD Build Tool
 Usage:
    fcbt <command name> [command parameter] 
 possible commands are:
  - DistSrc         (DS)   Build a source Distr. of the current source tree
  - DistBin         (DB)   Build a binary Distr. of the current source tree
  - DistSetup       (DI)   Build a Setup Distr. of the current source tree
  - DistSetup       (DUI)  Build a User Setup Distr. of the current source tree
  - DistAll         (DA)   Run all three above modules
  - NextBuildNumber (NBN)  Increase the Build Number of this Version
  - CreateModule    (CM)   Insert a new FreeCAD Module in the module directory
  - CreatePyModule  (CP)   Insert a new FreeCAD Python Module in the module directory

 For help on the modules type:
   fcbt <command name> ?

At the command prompt enter CM to start the creation of a module:

 Insert command: ''CM''

You are now asked to specify a name for your new module. Lets call it TestMod for example:

 Please enter a name for your application: ''TestMod''

After pressing enter fcbt starts copying all necessary files for your module in a new folder at

 trunk/src/Mod/TestMod/

Then all files are modified with your new module name. The only thing you need to do now is to add the two new projects "appTestMod" and "appTestModGui" to your workspace (on Windows) or to your makefile targets (unix). Thats it!

Setting up a new module manually

You need two things to create a new module:

  • A new folder in the FreeCAD Mod folder (either in InstalledPath/FreeCAD/Mod or in UserPath/.FreeCAD/Mod). You can name it as you like.
  • Inside that folder, an InitGui.py file. That file will be executed automatically on FreeCAD start (for ex, put a print("hello world") inside)

Additionally, you can also put an Init.py file. The difference is, the InitGui.py file is loaded only when FreeCAD runs in GUI mode, the Init.py file is loaded always. But if we are going to make a workbench, we'll put it in InitGui.py, because workbenches are used only in GUI mode, of course.

Creating a new workbench

Inside the InitGui.py file, one of the first thing you will want to do is to define a workbench. Here is a minimal code that you can use:

 class MyWorkbench ( Workbench ):
 	"My workbench object"
 	Icon = """
 			/* XPM */
 			static const char *test_icon[]={
 			"16 16 2 1",
 			"a c #000000",
 			". c None",
 			"................",
 			"................",
 			"..############..",
 			"..############..",
 			"..############..",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"................",
 			"................"};
 			"""
 	MenuText = "My Workbench"
 	ToolTip = "This is my extraordinary workbench"
 
         def GetClassName(self):
                return "Gui::PythonWorkbench"
 	
 	def Initialize(self):
 		import myModule1, myModule2
 		self.appendToolbar("My Tools", ["MyCommand1","MyCommand2"])
 		self.appendMenu("My Tools", ["MyCommand1","MyCommand2"])
 		Log ("Loading MyModule... done\n")
 
 	def Activated(self):
                # do something here if needed...
 		Msg ("MyWorkbench.Activated()\n")
 
 	def Deactivated(self):
                # do something here if needed...
 		Msg ("MyWorkbench.Deactivated()\n")
 
 FreeCADGui.addWorkbench(MyWorkbench)

The workbench must have all these attributes defined:

  • The Icon attribute is an XPM image (Most software such as GIMP can convert an image into xpm format, which is a text file. You can then paste the contents here)
  • MenuText is the workbench name as it appears in the workbenches list
  • Tooltip appears when you hover on it with the mouse
  • Initialize() is executed on FreeCAD load, and must create all menus and toolbars that the workbench will use. If you are going to make your module in C++, you can also define your menus and toolbars inside the C++ module, not in this InitGui.py file. The important is that they are created now, and not when the module is activated.
  • Activated() is executed when the user switches to your workbench
  • Deactivated() is executed when the user switches from yours to another workbench or leaves FreeCAD

Creating FreeCAD commands in Python

Usually you define all your tools (called Commands in FreeCAD) in another module, then import that module before creating the toolbars and menus. This is a minimal code that you can use to define a command:

 import FreeCAD,FreeCADGui
 
 class MyTool:
 	"My tool object"
 
        def GetResources(self):
                return {"MenuText": "My Command",
                        "Accel": "Ctrl+M",
                        "ToolTip": "My extraordinary command",
                        "Pixmap"  : """
 			/* XPM */
 			static const char *test_icon[]={
 			"16 16 2 1",
 			"a c #000000",
 			". c None",
 			"................",
 			"................",
 			"..############..",
 			"..############..",
 			"..############..",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"......####......",
 			"................",
 			"................"};
 			"""}
 
        def IsActive(self):
                if FreeCAD.ActiveDocument == None:
                        return False
                else:
                        return True
 
 	def Activated(self):
                # do something here...
 
 FreeCADGui.addCommand('MyCommand1',MyTool())
  • The GetResources() method must return a dictionnary with visual attributes of your tool. Accel defines a shortcut key but is not mandatory.
  • The IsActive() method defines if the command is active or greyed out in menus and toolbars.
  • The Activated() method is executed when the Command is called through a toolbar button or menu or even by script.

Creating FreeCAD Commands in C++

To Be Documented

Links

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎italiano • ‎polski • ‎română • ‎русский • ‎svenska • ‎Türkçe