250 lines
14 KiB
HTML
250 lines
14 KiB
HTML
<html><head><title>Workbench creation</title><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><link type='text/css' href='wiki.css' rel='stylesheet'></head><body><h1>Workbench creation</h1></div>
|
|
|
|
<div id="mw-content-text" lang="en" dir="ltr" class="mw-content-ltr"><div class="mw-parser-output"><p>This page will show you how to add a new workbench to the FreeCAD interface. <a href="Workbenches.html" title="Workbenches">Workbenches</a> are containers for FreeCAD commands. They can be coded in python, in C++, or in a mix of both, which has the advantage to ally the speed of C++ to the flexibility of python. In all cases, though, your workbench will be launched by a set of two python files.
|
|
</p>
|
|
<div id="toc" class="toc"><div class="toctitle"><h2>Contents</h2></div>
|
|
<ul>
|
|
<li class="toclevel-1 tocsection-1"><a href="#The_workbench_structure"><span class="tocnumber">1</span> <span class="toctext">The workbench structure</span></a>
|
|
<ul>
|
|
<li class="toclevel-2 tocsection-2"><a href="#C.2B.2B_workbench_structure"><span class="tocnumber">1.1</span> <span class="toctext">C++ workbench structure</span></a></li>
|
|
<li class="toclevel-2 tocsection-3"><a href="#The_Init.py_file"><span class="tocnumber">1.2</span> <span class="toctext">The Init.py file</span></a></li>
|
|
<li class="toclevel-2 tocsection-4"><a href="#Python_workbenches"><span class="tocnumber">1.3</span> <span class="toctext">Python workbenches</span></a></li>
|
|
<li class="toclevel-2 tocsection-5"><a href="#C.2B.2B_workbenches"><span class="tocnumber">1.4</span> <span class="toctext">C++ workbenches</span></a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toclevel-1 tocsection-6"><a href="#FreeCAD_commands"><span class="tocnumber">2</span> <span class="toctext">FreeCAD commands</span></a>
|
|
<ul>
|
|
<li class="toclevel-2 tocsection-7"><a href="#Python_command_definition"><span class="tocnumber">2.1</span> <span class="toctext">Python command definition</span></a></li>
|
|
<li class="toclevel-2 tocsection-8"><a href="#C.2B.2B_command_definition"><span class="tocnumber">2.2</span> <span class="toctext">C++ command definition</span></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<h2><span class="mw-headline" id="The_workbench_structure">The workbench structure</span></h2>
|
|
<p>Basically it is simple: You need a folder, with any name you like, placed in the Mod directory, with an <b>Init.py</b> file, and, optionally an <b>InitGui.py</b> file. The Init file is executed when FreeCAD starts, always, and the InitGui.py file is executed immediately after, but only when FreeCAD starts in GUI mode, not in console mode. That's all it needs for FreeCAD to find your workbench at startup and add it to its interface.
|
|
</p><p>Inside those files you can do whatever you want. Usually they are used like this:
|
|
</p>
|
|
<ul><li> In the Init.py file you just add a couple of things used even when FreeCAD works in console mode, for example the file importers and exporters</li></ul>
|
|
<ul><li> In the InitGui.py file you usually define a workbench, which contains a name, an icon, and a series of FreeCAD commands (see below). That workbench also defines functions that are executed when FreeCAD loads (you try to do as little as possible there, so you don't slow down the startup), another that gets executed when the workbench is activated (that's where you'll do most of the work), and a third one when the workbench is deactivated (so you can remove things if needed).</li></ul>
|
|
<h3><span class="mw-headline" id="C.2B.2B_workbench_structure">C++ workbench structure</span></h3>
|
|
<p>If you are going to code your workbench in python, you don't need to take special care, and can simply place your other python files together with your Init.py and InitGui.py files. When working with C++, however, you should take greater care, and start with respecting one fundamental rule of FreeCAD: The separation of your workbench between an App part (that can run in console mode, without any GUI element), and a Gui part, which will only be loaded when FreeCAD runs with its full GUI environment. So when doing a C++ workbench, you will actually most likely be doing two modules, an App and a Gui. These two modules must of course be callable from python. Any FreeCAD module (App or Gui) consists, at the very least, of a module init file. This is a typical AppMyModuleGui.cpp file:
|
|
</p>
|
|
<pre>extern "C" {
|
|
void MyModuleGuiExport initMyModuleGui()
|
|
{
|
|
if (!Gui::Application::Instance) {
|
|
PyErr_SetString(PyExc_ImportError, "Cannot load Gui module in console application.");
|
|
return;
|
|
}
|
|
try {
|
|
// import other modules this one depends on
|
|
Base::Interpreter().runString("import PartGui");
|
|
// run some python code in the console
|
|
Base::Interpreter().runString("print('welcome to my module!')");
|
|
}
|
|
catch(const Base::Exception& e) {
|
|
PyErr_SetString(PyExc_ImportError, e.what());
|
|
return;
|
|
}
|
|
(void) Py_InitModule("MyModuleGui", MyModuleGui_Import_methods); /* mod name, table ptr */
|
|
Base::Console().Log("Loading GUI of MyModule... done\n");
|
|
|
|
// initializes the FreeCAD commands (in another cpp file)
|
|
CreateMyModuleCommands();
|
|
|
|
// initializes workbench and object definitions
|
|
MyModuleGui::Workbench::init();
|
|
MyModuleGui::ViewProviderSomeCustomObject::init();
|
|
|
|
// add resources and reloads the translators
|
|
loadMyModuleResource();
|
|
}
|
|
} </pre>
|
|
<h3><span class="mw-headline" id="The_Init.py_file">The Init.py file</span></h3>
|
|
<pre># FreeCAD init script of XXX module
|
|
|
|
#***************************************************************************
|
|
#* (c) John Doe john@doe.com 2015 *
|
|
#* *
|
|
#* This file is part of the FreeCAD CAx development system. *
|
|
#* *
|
|
#* This program is free software; you can redistribute it and/or modify *
|
|
#* it under the terms of the GNU Lesser General Public License (LGPL) *
|
|
#* as published by the Free Software Foundation; either version 2 of *
|
|
#* the License, or (at your option) any later version. *
|
|
#* for detail see the LICENCE text file. *
|
|
#* *
|
|
#* FreeCAD is distributed in the hope that it will be useful, *
|
|
#* but WITHOUT ANY WARRANTY; without even the implied warranty of *
|
|
#* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
|
|
#* GNU Lesser General Public License for more details. *
|
|
#* *
|
|
#* You should have received a copy of the GNU Library General Public *
|
|
#* License along with FreeCAD; if not, write to the Free Software *
|
|
#* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
|
|
#* USA *
|
|
#* *
|
|
#***************************************************************************/
|
|
|
|
FreeCAD.addImportType("My own format (*.own)","importOwn")
|
|
FreeCAD.addExportType("My own format (*.own)","importOwn")
|
|
print "I am executing some stuff here when FreeCAD starts!" </pre>
|
|
<p>You can choose any license you like for your workbench, but be aware that if you wish
|
|
to see your workbench integrated into and distributed with the FreeCAD source code at
|
|
some point, it needs to be LGPL2+ like the example above.
|
|
The FreeCAD.addImportType() and addEXportType() functions allow you to give the name
|
|
and extension of a file type, and a python module responsible for its import. In the
|
|
example above, an "importOwn.py" module will handle .own files. See <a href="Code_snippets.html" title="Code snippets">Code snippets</a>
|
|
for more examples.
|
|
</p>
|
|
<h3><span class="mw-headline" id="Python_workbenches">Python workbenches</span></h3>
|
|
<div class="mw-highlight mw-content-ltr" dir="ltr"><pre>class MyWorkbench (Workbench):
|
|
|
|
MenuText = "My Workbench"
|
|
ToolTip = "A description of my workbench"
|
|
Icon = """paste here the contents of a 16x16 xpm icon"""
|
|
|
|
def Initialize(self):
|
|
"This function is executed when FreeCAD starts"
|
|
import MyModuleA, MyModuleB # import here all the needed files that create your FreeCAD commands
|
|
self.list = ["MyCommand1, MyCommand2"] # A list of command names created in the line above
|
|
self.appendToolbar("My Commands",self.list) # creates a new toolbar with your commands
|
|
self.appendMenu("My New Menu",self.list) # creates a new menu
|
|
self.appendMenu(["An existing Menu","My submenu"],self.list) # appends a submenu to an existing 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("My commands",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(MyWorkbench())</pre></div>
|
|
<p>Other than that, you can do anything you want: You could put your whole workbench code
|
|
inside the InitGui.py if you want, but it is usually more convenient to place the different
|
|
functions of your workbench in separate files. So those files are smaller and easier to
|
|
read. Then you import those files into your InitGui.py file. You can organize those files
|
|
the way you want, a good example is one for each FreeCAD command you add.
|
|
</p>
|
|
<h3><span class="mw-headline" id="C.2B.2B_workbenches">C++ workbenches</span></h3>
|
|
<p>If you are going to code your workbench in C++, you will probably want to code the
|
|
workbench definition itself in C++ too (although it is not necessary: You could also
|
|
code only the tools in C++, and leave the workbench definition in python). In that case,
|
|
the InitGui.py file becomes very simple: It might contain just one line:
|
|
</p>
|
|
<pre>import MyModuleGui </pre>
|
|
<p>where MyModule is your complete C++ workbench, including the commands and workbench
|
|
definition.
|
|
</p><p>Coding C++ workbenches works in a pretty similar way. This is a typical Workbench.cpp
|
|
file to include in the Gui part of your module:
|
|
</p>
|
|
<pre>namespace MyModuleGui {
|
|
class MyModuleGuiExport Workbench : public Gui::StdWorkbench
|
|
{
|
|
TYPESYSTEM_HEADER();
|
|
|
|
public:
|
|
Workbench();
|
|
virtual ~Workbench();
|
|
|
|
virtual void activated();
|
|
virtual void deactivated();
|
|
|
|
protected:
|
|
Gui::ToolBarItem* setupToolBars() const;
|
|
Gui::MenuItem* setupMenuBar() const;
|
|
};
|
|
} </pre>
|
|
<h2><span class="mw-headline" id="FreeCAD_commands">FreeCAD commands</span></h2>
|
|
<p>FreeCAD commands are the basic building block of the FreeCAD interface. They can appear
|
|
as a button on toolbars, and as a menu entry in menus. But it is the same command. A
|
|
command is a simple python class, that must contain a couple of predefined attributes
|
|
and functions, that define the name of the command, its icon, and what to do when the
|
|
command is activated.
|
|
</p>
|
|
<h3><span class="mw-headline" id="Python_command_definition">Python command definition</span></h3>
|
|
<pre>class My_Command_Class():
|
|
"""My new command"""
|
|
|
|
def GetResources(self):
|
|
return {'Pixmap'  : 'My_Command_Icon', # the name of a svg file available in the resources
|
|
'Accel' : "Shift+S", # a default shortcut (optional)
|
|
'MenuText': "My New Command"
|
|
'ToolTip' : "What my new command does"}
|
|
|
|
def Activated(self):
|
|
"Do something here"
|
|
return
|
|
|
|
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."""
|
|
return True
|
|
|
|
FreeCADGui.addCommand('My_Command',My_Command_Class()) </pre>
|
|
<h3><span class="mw-headline" id="C.2B.2B_command_definition">C++ command definition</span></h3>
|
|
<p>Similarly, you can code your commands in C++, typically have a Commands.cpp file in your Gui module. This is a typical Commands.cpp file:
|
|
</p>
|
|
<pre>DEF_STD_CMD_A(CmdMyCommand);
|
|
|
|
CmdMyCommand::CmdMyCommand()
|
|
 :Command("My_Command")
|
|
{
|
|
sAppModule = "MyModule";
|
|
sGroup = QT_TR_NOOP("MyModule");
|
|
sMenuText = QT_TR_NOOP("Runs my command...");
|
|
sToolTipText = QT_TR_NOOP("Describes what my command does");
|
|
sWhatsThis = QT_TR_NOOP("Describes what my command does");
|
|
sStatusTip = QT_TR_NOOP("Describes what my command does");
|
|
sPixmap = "some_svg_icon_from_my_resource";
|
|
}
|
|
|
|
void CmdMyCommand::activated(int iMsg)
|
|
{
|
|
openCommand("My Command");
|
|
doCommand(Doc,"print('Hello, world!')");
|
|
commitCommand();
|
|
updateActive();
|
|
}
|
|
|
|
bool CmdMyCommand::isActive(void)
|
|
{
|
|
if( getActiveGuiDocument() )
|
|
return true;
|
|
else
|
|
return false;
|
|
}
|
|
|
|
void CreateMyModuleCommands(void)
|
|
{
|
|
Gui::CommandManager &rcCmdMgr = Gui::Application::Instance->commandManager();
|
|
rcCmdMgr.addCommand(new CmdMyCommand());
|
|
} </pre>
|
|
<p><br />
|
|
</p>
|
|
</div>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
</div><div class="printfooter">
|
|
Online version: "<a dir="ltr" href="https://www.freecadweb.org/wiki/index.php?title=Workbench_creation&oldid=189364">http://www.freecadweb.org/wiki/index.php?title=Workbench_creation&oldid=189364</a>"</div>
|
|
<div id="catlinks" class="catlinks" data-mw="interface"></div><div class="visualClear"></div>
|
|
</div>
|
|
</div>
|
|
<div id="mw-navigation">
|
|
<h2>Navigation menu</h2>
|
|
|
|
</body></html> |