Interface creation with UI files

From FreeCAD Documentation
Jump to navigation Jump to search
This page contains changes which are not marked for translation.
This page is a work in progress. Please do not edit or translate until this message is removed.


In this page we will show how to build a simple graphical interface with Qt Designer, Qt's official tool for designing interfaces, then using it inside FreeCAD. We'll assume that the user knows how to edit and run Python generally.

The Interface creation completely in Python page is similar to this page, but in that article the interface file is converted to Python. This is not necessary, as the .ui file can be used directly in the code.

FreeCAD creating interfaces.svg

Two general methods to create interfaces, by including the interface in the Python file, or by using .ui files.

Designing the dialog

In CAD applications, designing a good user interface (UI) is very important, as the user will interact directly with it: reading dialog boxes, pressing buttons, choosing between icons, etc. So it is very important to think carefully to what you want to do, how you want the user to behave, and how will be the workflow of your action.

There are a couple of concepts to know when designing interface:

  • Modal/non-modal dialogs: a modal dialog appears in front of your screen, stopping the action of the main window, forcing the user to respond to the dialog, while a non-modal dialog doesn't stop you from working on the main window. In some case the first is better, in other cases not.
  • Identifying what is required and what is optional: make sure the user knows what he must do. Label everything with proper description, use tooltips, etc.
  • Separating commands from parameters: this is usually done with buttons and text input fields. The user knows that clicking a button will produce an action while changing a value inside a text field will change a parameter somewhere.

We'll design a very simple dialog, like this:


We will then use this dialog in to produce a nice rectangular plane. You might find it not very useful to produce nice rectangular planes, but it will be easy to change it later to do more complex things. When you open it, Qt Designer looks like this:


Creating the dialog

Qt Designer is very simple to use. On the left bar you have elements that can be dragged on your widget. On the right side you have properties panels displaying all kinds of editable properties of selected elements. So, begin with creating a new widget.

  1. Select "Dialog without buttons", since we don't want the default OK/Cancel buttons.
  2. We need 'Labels. Labels are simple text strings that appear on your widget to inform the end user. If you select a label, notice that on the right side there will appear several properties that you can modify such as: font style, height, etc... So lets drag 3 separate labels on to our widget:
    • One label for the title
    • Another label for writing "Height"
    • Another label for writing "Width"
  3. We now need LineEdits (2 of them actually). Drag two of them on to the widget. LineEdits are text fields that the end user can fill in. So we need one LineEdit for the Height and one for the Width. Here too, we can edit properties. For example, why not set a default value say for example: 1.00 for each. This way, when the user will see the dialog, both values will be filled already. If the end user is satisfied, they can directly press the button, saving precious time.
  4. Next lets add a PushButton. This is the button the end user will need to press after they've filled both fields.

Note: that we chose very simple controls here. Qt has many more options, for example one could use Spinboxes instead of LineEdits, etc.

That's about all we need to do in Qt Designer. One last thing, though, let's rename all our elements with simpler names, so it will be easier to identify them in our scripts.


Using the dialog in Python

The .ui file needs to be loaded into our class under the self.form attribute.

import FreeCADGui as Gui

class SomeTool:
    def __init__(self):
        self.ui_path = "Mod/MyWorkbench/file.ui"
        self.form = Gui.PySideUic.loadUi(self.ui_path)

Once the class is ready we can launch it in the task panel.