The FreeCAD interface

In the following exercise, we will first create a panel with Qt Creator that asks for length, width and height values, then we will create a Python class around it, that will read the values entered by the user from the panel, and create a box with the given dimensions. This Python class will then be used by FreeCAD to display and control the task panel:

Let's start by creating the widget. Start Qt Creator, then menu File -> New File or Project -> Files and Classes -> Qt -> Qt Designer Form -> Dialog without buttons. Click Next, give it a filename to save, click Next, leave all project fields to their default value (""), and Create. FreeCAD's Task system will automatically add OK/Cancel buttons, that's why we chose here a dialog without buttons.

Find the Label in the list in the left panel, and drag it onto the canvas of our widget. Double-click the recent placed Label, and change its text to Length.

Right-click the widget canvas, and choose Lay out-> Lay out in a Grid. This will turn our widget into a grid with currently only one cell, occupied by ourfirst label. We can now add the next items at the left, right, top or bottom of our first label, and the grid wil lexpand automatically.

Add two more labels below the first one, and change their text to Width and Height:

Now place 3 Double Spin Box widgets next to our Length, Width and Height labels. For each of them, in the lower left panel, which shows all the available settings for the selected widget, locate Suffix and set their suffix to mm. FreeCAD has a more advanced widget, that can handle different units, but that is not available in Qt Creator by default (but can be compiled), so for now we will use a standard Double Spin Box, and we add the "mm" suffix to make sure the user knows in which units they work:

Now our widget is done, we just need to make sure of one last thing. Since FreeCAD will need to access that widget and read the Length, Width and Height values, we need to give proper names to those widgets, so we can easily retrive them from within FreeCAD. Click each of the Double Spin Boxes, and in the upper right window, double-click their Object Name, and change them to something easy to remember, for example: BoxLength, BoxWidth and BoxHeight:

Save the file, you can now close Qt Creator, the rest will be done in Python.

Open FreeCAD and create a new macro from menu Macro -> Macros -> Create

Paste the following code. Make sure you change the file path to match where you saved the .ui file created in QtCreator:

import FreeCAD,FreeCADGui,Part # CHANGE THE LINE BELOW path_to_ui = "C:UsersyorikDocumentsdialog.ui" class BoxTaskPanel: def __init__(self): # this will create a Qt widget from our ui file self.form = FreeCADGui.PySideUic.loadUi(path_to_ui) def accept(self): length = self.form.BoxLength.value() width = self.form.BoxWidth.value() height = self.form.BoxHeight.value() if (length == 0) or (width == 0) or (height == 0): print("Error! None of the values can be 0!") # we bail out without doing anything return box = Part.makeBox(length,width,height) Part.show(box) FreeCADGui.Control.closeDialog() panel = BoxTaskPanel() FreeCADGui.Control.showDialog(panel)

In the code above, we used a convenience function (PySideUic.loadUi) from the FreeCADGui module. That function loads a .ui file, creates a Qt Widget from it, and maps names, so we can easily access the subwidget by their names (ex: self.form.BoxLength).

The "accept" function is also a convenience offered by Qt. When there is a "OK" button in a dialog (which is the case by default when using the FreeCAD Tasks panel), any funcion named "accept" will automatically be executed when the "OK" button is pressed. Similarily, you can also add a "reject" function which gets executed when the "Cancel" button is pressed. In our case, we ommitted that function, so pressing "Cancel" will do the default behaviour (do nothing and close the dialog).

If we implement any of the accept or reject functions, their default behaviour (do nothing and close) will not occur anymore. So we need to close the Task panel ourselves. This is done with:

FreeCADGui.Control.closeDialog()

Once we have our BoxTaskPanel that has 1) a widget called "self.form" and 2) if needed, accept and reject functions, we can open the task panel with it, which is done with these two last lines:

panel = BoxTaskPanel() FreeCADGui.Control.showDialog(panel)

Note that the widget created by PySideUic.loadUi is not specific to FreeCAD, it is a standard Qt widget which can be used with other Qt tools. For example, we could have shown a separate dialog box with it. Try this in the Python Console of FreeCAD (using the correct path to your .ui file of course):

from PySide import QtGui w = FreeCADGui.PySideUic.loadUi("C:UsersyorikDocumentsdialog.ui") w.show()

Of course we didn't add any "OK" or "Cancel" button to our dialog, since it was made to be used from the FreeCAD Task panel, which already provides such buttons. So there is no way to close the dialog (other than pressing its Window Close button). But the function show() creates a non-modal dialog, which means it doesn't block the rest of the interface. So, while our dialog is still open, we can read the values of the fields:

w.BoxHeight.value()

This is very useful for testing.

Finally, don't forget there is much more documentation about using Qt widgets on the FreeCAD Wiki, in the Python Scripting section, which contains a dialog creation tutorial, a special 3-part PySide tutorial that covers the subject extensively.

Read more

Qt Creator: https://en.wikipedia.org/wiki/Qt_Creator

Installing Qt Creator: https://www.qt.io/ide/

Python scripting documentation: http://www.freecadweb.org/wiki/index.php?title=Power_users_hub

Dialog creation tutorial: http://www.freecadweb.org/wiki/index.php?title=Dialog_creation

PySide tutorials: http://www.freecadweb.org/wiki/index.php?title=PySide

PySide documentation: http://srinikom.github.io/pyside-docs/index.html

The Community

No manual dealing with free and open-source software would be complete without a chapter about the community. As the vast majority of free and open-source software projects, FreeCAD is made by a community, and maintained by that community. Instead of the opaque, unknown, impersonal and inaccessable firm that is more than often found behind commercial software, free and open-source software communities are open spaces, where you as a user are welcome, and where you can get answers very fast, and even have your say in the development of the software itself. You are also more than welcome to help, there are tasks for everybody.

The community is a growing, eclectic group of all kinds of people united by their passion for FreeCAD. All work on FreeCAD voluntarily, during their free time (although sometimes firms or individuals gather to pay a couple of programming hours to a developer to implement a specific function). Some are professional programmers, some are long-time FreeCAD users (some of them are true FreeCAD gurus, who know almost everything, and many of them end up knowing a lot about FreeCAD programming too), and many are new users of FreeCAD. There is nothing specific to do to be part of the community. Just use FreeCAD!

The main place where the community meets and discusses is the FreeCAD forum. All you need to do to participate to the discussions is to register an account on the forum (Your first post will need to be approved by a moderator before you can post more, to prevent spamming). The forum is a great place to ask questions when you are new to FreeCAD. Provided you made a good question (be sure to read the forum rules as they contain useful information to turn your question into a good question), you will usually get several replies within the same hour. If you think someone might have asked your question already, be sure to search, your answer might already be there.

The forum is also a great place to show what you achieved with FreeCAD, to help newcomers when you are more experienced, and to follow and give your opinions in more technical discussions about development. All the FreeCAD development is discussed on the forum, and anybody is free to read or participate.

There are also FreeCAD communities forming outside of the FreeCAD forum, for example on Facebook or Google+.

If you are becoming as enthusiastic about FreeCAD as we are, you might want to help the project. This can be done in many different ways, and there are tasks for everybody, programmers and non-programmers, for example:

Help to spread the word: Many people would get huge benefit from using a free, open-source 3D modeler like FreeCAD, but simply don't know its existence. Publishing the work you do with FreeCAD, talking about it on social networks, etc... helps these people to discover FreeCAD.

Help newcomers: The vast majority of discussions on the forum are questions asked by new users. You might know good anwers to give them.

Help reporting bugs: The stablility of FreeCAD comes in large part from the fixing of bugs. Since it is not possible for the FreeCAD developers to test all possible use cases, it is important that users report problems when they detect them. Be sure to read the guidelines if you think you found a bug, and then write a report on the bug tracker.

Help to write documentation: The FreeCAD documentation wiki is also written by community members. Some sections of it are still incomplete, or their information incorrect or obsolete. You might be able to help to fix that. To be able to work on the wiki, you will need to familiarize yourself with wiki editing, and ask permission to edit the FreeCAD wiki on the forum.

Help to translate FreeCAD: The translation of FreeCAD is done online by community members, on crowdin. If you don't see your language there, ask one of the administrators to have it added.

Help to translate the wiki documentation: Every page of the wiki is translatable, and requires very little knowledge of the wiki syntax. Helping with translation is also a great way to learn FreeCAD.

Write scripts and macros: FreeCAD has a growing list of Macros. If you wrote some interesting functionality, consider sharing it there.

Programming: For this, you need to know how to program in Python or C++, and have a good knowledge of FreeCAD itself.

The source code of FreeCAD is located on the Github account of the FreeCAD project. Anybody can download, use and modify the code. You can publish your modifications (on Github or any other Git hosting service). If you made interesting modifications, that you wish to see included in the FreeCAD source code, you must ask the community to have them included. This can be done using Github's pull requests mechanism, but the very best way is to discuss what you intend to do first on the forum, and then post an official request in the Pull requests section of the forum when your code is ready. This avoids that you work on something that someone else is already working on too, and ensures that others agree with the way you are doing it, so there is no risk of having your work refused for some reason you didn't foresee.

Hopefully, we managed to give you a good taste of FreeCAD in this manual, and you are already our newest community member. Welcome!

Read more

The FreeCAD forum: http://forum.freecadweb.org

The source code of FreeCAD: https://github.com/FreeCAD/FreeCAD

The Facebook FreeCAD community: https://www.facebook.com/FreeCAD

The Google+ FreeCAD community: https://plus.google.com/u/0/communities/103183769032333474646

The FreeCAD documentation wiki: http://www.freecadweb.org/wiki

Translating FreeCAD on crowdin: https://crowdin.com/project/freecad

The FreeCAD bug tracker: http://www.freecadweb.org/tracker