Python Workbench Template with a demo feature

Author: chbergmann

Feature1.py

@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+
+__title__ = "Feature1"
+__author__ = "Christian Bergmann"
+__license__ = "LGPL 2.1"
+__doc__ = "An example for a workbench feature"
+
+import PythonWorkbenchTemplate
+import os
+import FreeCADGui
+import FreeCAD
+from FreeCAD import Vector
+import Part
+
+    
+class Feature1Worker:
+    def __init__(self, 
+                 fp,    # an instance of Part::FeaturePython
+                 base = None,
+                 green = False):
+        fp.addProperty("App::PropertyLink", "Base",  "Feature1",  "This object will be modified by this feature").Base = base
+        fp.addProperty("App::PropertyBool", "Green", "Feature1",  "Colorize the feature green").Green = green
+        
+        fp.Proxy = self
+    
+    def execute(self, fp):
+        '''Do something when doing a recomputation, this method is mandatory'''
+        redrawFeature1(fp)
+        
+    def onChanged(self, fp, prop):
+        '''Do something when a property has changed'''
+        if prop == "Base":
+            redrawFeature1(fp)
+            
+        if prop == "Green":
+            changeFeature1Color(fp)
+
+
+class Feature1ViewProvider:
+    def __init__(self, vobj):
+        '''Set this object to the proxy object of the actual view provider'''
+        vobj.Proxy = self
+        self.Object = vobj.Object
+            
+    def getIcon(self):
+        '''Return the icon which will appear in the tree view. This method is optional and if not defined a default icon is shown.'''
+        return (os.path.join(PythonWorkbenchTemplate.get_module_path(), "Resources", "icons", "feature1.svg"))
+
+    def attach(self, vobj):
+        '''Setup the scene sub-graph of the view provider, this method is mandatory'''
+        self.Object = vobj.Object
+        self.onChanged(vobj, "Base")
+ 
+    def updateData(self, fp, prop):
+        '''If a property of the handled feature has changed we have the chance to handle this here'''
+        pass
+    
+    def claimChildren(self):
+        '''Return a list of objects that will be modified by this feature'''
+        return [self.Object.Base]
+        
+    def onDelete(self, feature, subelements):
+        '''Here we can do something when the feature will be deleted'''
+        return True
+    
+    def onChanged(self, fp, prop):
+        '''Here we can do something when a single property got changed'''
+        pass
+        
+    def __getstate__(self):
+        '''When saving the document this object gets stored using Python's json module.\
+                Since we have some un-serializable parts here -- the Coin stuff -- we must define this method\
+                to return a tuple of all serializable objects or None.'''
+        return None
+ 
+    def __setstate__(self,state):
+        '''When restoring the serialized object from document we have the chance to set some internals here.\
+                Since no data were serialized nothing needs to be done here.'''
+        return None
+        
+
+def redrawFeature1(fp):
+    # check plausibility of all parameters
+    if not fp.Base:
+        return
+    
+    # fp.Shape contains the newly created object
+    fp.Shape = fp.Base.Shape.copy()
+    changeFeature1Color(fp)
+    
+       
+def changeFeature1Color(fp):       
+    if fp.Green:
+        fp.ViewObject.ShapeColor = (0.00, 1.00, 0.00)
+    else:
+        fp.ViewObject.ShapeColor = (1.00, 0.00, 0.00) 
+    
+        
+class Feature1():
+    '''This class will be loaded when the workbench is activated in FreeCAD. You must restart FreeCAD to apply changes in this class'''  
+      
+    def Activated(self):
+        '''Will be called when the feature is executed.'''
+        # Generate commands in the FreeCAD python console to create Feature1
+        FreeCADGui.doCommand("import PythonWorkbenchTemplate")
+        
+        selection = FreeCADGui.Selection.getSelectionEx()
+        if len(selection) > 0:
+            FreeCADGui.doCommand("base = FreeCAD.ActiveDocument.getObject('%s')"%(selection[0].ObjectName))
+            FreeCADGui.doCommand("PythonWorkbenchTemplate.makeFeature1(base)")
+        else:            
+            FreeCADGui.doCommand("PythonWorkbenchTemplate.makeFeature1()")
+                  
+
+    def IsActive(self):
+        """Here you can define if the command must be active or not (greyed) if certain conditions
+        are met or not. This function is optional."""
+        if FreeCAD.ActiveDocument:
+            return(True)
+        else:
+            return(False)
+        
+    def GetResources(self):
+        '''Return the icon which will appear in the tree view. This method is optional and if not defined a default icon is shown.'''
+        return {'Pixmap'  : os.path.join(PythonWorkbenchTemplate.get_module_path(), "Resources", "icons", "feature1.svg"),
+                'Accel' : "", # a default shortcut (optional)
+                'MenuText': "Feature1",
+                'ToolTip' : "A template for a workbench feature" }
+
+FreeCADGui.addCommand('Feature1', Feature1())

Init.py

@@ -0,0 +1,2 @@
+# FreeCAD init script of the PythonWorkbenchTemplate module
+# (c) 2020 Christian Bergmann LGPL

InitGui.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+
+__title__ = "FreeCAD Default Workbench - Init file"
+__author__ = "Christian Bergmann"
+__url__ = ["http://www.freecadweb.org"]
+__version__ = "0.0.1"
+
+
+class PythonWorkbenchTemplate (Workbench):
+    def __init__(self):
+        import os
+        import PythonWorkbenchTemplate
+        self.__class__.MenuText = "PythonWorkbenchTemplate"
+        self.__class__.ToolTip = "A template for a new workbench"
+        self.__class__.Icon = os.path.join(PythonWorkbenchTemplate.get_module_path(), "Resources", "icons", "freecad.svg")
+
+    def Initialize(self):
+        "This function is executed when FreeCAD starts"
+        # import here all the needed files that create your FreeCAD commands
+        import Feature1
+        
+        self.list = ["Feature1"] # A list of command names created in the line above
+        self.appendToolbar("Curved Shapes", self.list) # creates a new toolbar with your commands
+        self.appendMenu("Curved Shapes", self.list) # creates a new menu
+
+    def Activated(self):
+        "This function is executed when the workbench is activated"
+        return
+
+    def Deactivated(self):
+        "This function is executed when the workbench is deactivated"
+        return
+
+    def ContextMenu(self, recipient):
+        "This is executed whenever the user right-clicks on screen"
+        # "recipient" will be either "view" or "tree"
+        self.appendContextMenu("Curved Shapes", self.list) # add commands to the context menu
+
+    def GetClassName(self): 
+        # this function is mandatory if this is a full python workbench
+        return "Gui::PythonWorkbench"
+       
+Gui.addWorkbench(PythonWorkbenchTemplate())

PythonWorkbenchTemplate.py

@@ -0,0 +1,23 @@
+import os
+import FreeCAD
+from importlib import reload
+
+def get_module_path():
+    """ Returns the current module path.
+    Determines where this file is running from, so works regardless of whether
+    the module is installed in the app's module directory or the user's app data folder.
+    (The second overrides the first.)
+    """
+    return os.path.dirname(__file__)
+
+
+def makeFeature1(base = None, green = False):
+    '''Python command to create a Feature1'''
+    import Feature1      
+    reload(Feature1)     # causes FreeCAD to reload Feature1.py every time a new Feature1 is created.       
+    fp = FreeCAD.ActiveDocument.addObject("Part::FeaturePython", "Feature1")
+    Feature1.Feature1Worker(fp, base, green)
+    Feature1.Feature1ViewProvider(fp.ViewObject)
+    FreeCAD.ActiveDocument.recompute()
+    return fp
+    

README.md

@@ -0,0 +1,44 @@
+# Python Workbench Template
+   
+A template for creating a new FreeCAD workbench in Python.  
+FreeCAD offers great opportunities to create scripted objects. This should be a starting point to create your own workbench.
+  
+## Installation
+
+### Automatic Installation
+**Note: This is the recommended way to install this workbench.**  
+The Python Workbench Template will be available soon through the builtin FreeCAD [Addon Manager](https://github.com/FreeCAD/FreeCAD-addons#1-builtin-addon-manager).
+Once installed all that is needed is to restart FreeCAD and the workbench will be available in the [workbench dropdown list](https://freecadweb.org/wiki/Std_Workbench) menu.
+
+### Manual Installation
+
+```bash
+cd ~/FreeCAD/Mod/ 
+git clone https://github.com/chbergmann/PythonWorkbenchTemplate.git
+```
+When you restart FreeCAD, "Python Workbench Template" workbench should now show up in the [workbench dropdown list](https://freecadweb.org/wiki/Std_Workbench).
+  
+## Getting started with a new FreeCAD workbench
+- Create a new git repository and copy the contents of this project to your new project
+- Rename PythonWorkbenchTemplate.py to YourWorkbenchsName.py. Search all files for PythonWorkbenchTemplate and replace with the name of your workbench
+- Rename Feature1.py with YourNewFeature.py 
+- Edit InitGui.py. Delete Feature1 and add your new feature instead. Edit the \__title\__, \__author\__, \__url\__ and \__version\__ tags.
+- Write your new feature and test it well.
+- Write a documentation in README.md. Explain the purpose of your workbench. Explain your features. Screenshots are great.
+- Announce your workbench in the [FreeCAD forum](https://forum.freecadweb.org/index.php). Add the link of your new thread in README.md
+- Add your workbench to the [Addon manager](https://github.com/FreeCAD/FreeCAD-addons)
+
+## Tools
+### ![Feature1Icon](./Resources/icons/feature1.svg) Feature1
+Colorizes a selected object red or green. For demonstration how to write a workbench feature.
+
+#### Parameters
+- Base: The object to colorize
+- Green: if True, the linked object will be colored green, otherwise red.
+
+
+## Discussion
+Please offer feedback or connect with the developer via the [dedicated FreeCAD forum thread](LINK).
+
+## License
+GNU Lesser General Public License v3.0