FreeCAD provides the possibility to have one or more workbenches for a module. More...
FreeCAD provides the possibility to have one or more workbenches for a module.
A workbench changes the appearance of the main window in that way that it defines toolbars, items in the toolbox, menus or the context menu and dockable windows that are shown to the user. The idea behind this concept is that the user should see only the functions that are required for the task that he is doing at this moment and not to show dozens of unneeded functions which the user never uses.
Here follows a short description of how an own workbench can be added to a module.
First you have to subclass either Workbench or StdWorkbench and reimplement the methods setupMenuBar(), setupToolBars(), setupCommandBars() and setupDockWindows().
The difference between both classes is that these methods of Workbench are pure virtual while StdWorkbench defines already the standard menus and toolbars, such as the 'File', 'Edit', ..., 'Help' menus with their common functions.
If your class derives from Workbench then you have to define your menus, toolbars and toolbox items from scratch while deriving from StdWorkbench you have the possibility to add your preferred functions or even remove some unneeded functions.
class MyWorkbench : public StdWorkbench { ... protected: MenuItem* setupMenuBar() const { MenuItem* root = StdWorkbench::setupMenuBar(); // your changes return root; } ToolBarItem* setupToolBars() const { ToolBarItem* root = StdWorkbench::setupToolBars(); // your changes return root; } ToolBarItem* setupCommandBars() const { ToolBarItem* root = StdWorkbench::setupCommandBars(); // your changes return root; } };
or
class MyWorkbench : public Workbench { ... protected: MenuItem* setupMenuBar() const { MenuItem* root = new MenuItem; // setup from scratch return root; } ToolBarItem* setupToolBars() const { ToolBarItem* root = new ToolBarItem; // setup from scratch return root; } ToolBarItem* setupCommandBars() const { ToolBarItem* root = new ToolBarItem; // setup from scratch return root; } };
If you want to customize your workbench by adding or removing items you can use the ToolBarItem class for customizing toolbars and the MenuItem class for menus. Both classes behave basically the same. To add a new menu item you can do it as follows
MenuItem* setupMenuBar() const { MenuItem* root = StdWorkbench::setupMenuBar(); // create a sub menu MenuItem* mySub = new MenuItem; // note: no parent is given mySub->setCommand( "My &Submenu" ); *mySub << "Std_Undo" << "Std_Redo"; // My menu MenuItem* myMenu = new MenuItem( root ); myMenu->setCommand( "&My Menu" ); // fill up the menu with some command items *myMenu << mySub << "Separator" << "Std_Cut" << "Std_Copy" << "Std_Paste" << "Separator" << "Std_Undo" << "Std_Redo"; }
Toolbars can be customized the same way unless that you shouldn't create subitems (there are no subtoolbars).
Once you have implemented your workbench class you have to register it to make it known to the FreeCAD core system. You must make sure that the step of registration is performed only once. A good place to do it is e.g. in the global function initMODULEGui in AppMODULEGui.cpp where MODULE stands for the name of your module. Just add the line
MODULEGui::MyWorkbench::init();
somewhere there.
Though your workbench has been registered now, at this stage you still cannot invoke it yet. Therefore you must create an item in the list of all visible workbenches. To perform this step you must open your InitGui.py (a Python file) and do some adjustments. The file contains already a Python class MODULEWorkbench that implements the Activate() method (it imports the needed library). You can also implement the GetIcon() method to set your own icon for your workbench, if not, the default FreeCAD icon is taken, and finally the most important method GetClassName(). that represents the link between Python and C++. This method must return the name of the associated C++ including namespace. In this case it must the string "ModuleGui::MyWorkbench". At the end you can change the line from
Gui.addWorkbench("MODULE design",MODULEWorkbench())
to
Gui.addWorkbench("My workbench",MODULEWorkbench())
or whatever you want.
One of the key concepts of the workbench framework is to load a module at runtime when the user needs some function that it provides. So, if the user doesn't need a module it never gets loaded into RAM. This speeds up the startup procedure of FreeCAD and saves memory. At startup FreeCAD scans all module directories and invokes InitGui.py. So an item for a workbench gets created. If the user clicks on such an item the matching module gets loaded, the C++ workbench gets registered and activated.
The user is able to modify a workbench (Edit|Customize). E.g. he can add new toolbars or items for the toolbox and add his preferred functions to them. But he has only full control over "his" toolbars, the default workbench items cannot be modified or even removed.
FreeCAD provides also the possibility to define pure Python workbenches. Such workbenches are temporarily only and are lost after exiting the FreeCAD session. But if you want to keep your Python workbench you can write a macro and attach it with a user defined button or just perform the macro during the next FreeCAD session. Here follows a short example of how to create and embed a workbench in Python
w=Workbench() # creates a standard workbench (the same as StdWorkbench in C++) w.MenuText = "My Workbench" # the text that will appear in the combo box dir(w) # lists all available function of the object FreeCADGui.addWorkbench(w) # Creates an item for our workbenmch now # Note: We must first add the workbench to run some initialization code # Then we are ready to customize the workbench list = ["Std_Test1", "Std_Test2", "Std_Test3"] # creates a list of new functions w.appendMenu("Test functions", list) # creates a new menu with these functions w.appendToolbar("Test", list) # ... and also a new toolbar
1.6.1