First Steps With Qt Designer and PySide2

So far we have been creating apps using Python code. This works great in many cases, but as your applications get larger or interfaces more complicated, it can get a bit cumbersome to define all widgets programmatically. The good news is that Qt comes with a graphical editor — Qt Designer — which contains a drag-and-drop UI editor. Using Qt Designer you can define your UIs visually and then simply hook up the application logic later.

In this tutorial we'll cover the basics of creating PySide2 UIs with Qt Designer. The principles, layouts and widgets are identical, so you can apply everything you've already learnt. You'll also need your knowledge of the PySide2 Python API to hook up your application logic later.

This tutorial requires Qt Creator to be installed. You can download it from the Qt website. Go to the download page and get the appropriate Qt package for your platform. During the installation, you can opt to install only Qt Creator.

Open up Qt Designer/Qt Creator and you will be presented with the main window.

Using Qt Designer in Qt Creator

If you're using Qt Designer standalone you can skip ahead.

In Qt Creator access to Designer is via the tab on the left hand side. However, to activate this you first need to start creating a .ui file.

The Qt Creator interface, with the Design section shown on the left.

To create a .ui file go to File -> New File or Project... In the window that appears select Qt under Files and Classes on the left, then select Qt Designer Form on the right. You'll notice the icon has "ui" on it, showing the type of file you're creating.

Create a new Qt .ui file in Qt Creator.

In the next step you'll be asked what type of widget you want to create. If you are starting an application then Main Window is the right choice. However, you can also create .ui files for dialog boxes, forms and custom compound widgets.

Select the type of widget to create, for most applications this will be Main Window.

Next choose a filename and save folder for your file. Save your .ui file with the same name as the class you'll be creating, just to make subsequent commands simpler.

Choose save name and folder for your .ui file.

Finally, you can choose to add the file to your version control system if you're using one. Feel free to skip this step — it doesn't affect your UI.

Optionally add the file to your version control, e.g. Git.

Laying Out Your Main Window in Qt Designer

You'll be presented with your newly created main window in the UI designer. There isn't much to see to begin with, just a grey working area representing the window, together with the beginnings of a window menu bar.

The initial view of the created main window in Qt Designer.

You can resize the window by clicking the window and dragging the blue handles on each corner.

Resizing the main window using drag handles.

The first step in building an application is to add some widgets to your window. In our first applications we learnt that to set the central widget for a QMainWindow we need to use .setCentralWidget(). We also saw that to add multiple widgets with a layout, we need an intermediary QWidget to apply the layout to, rather than adding the layout to the window directly.

Qt Creator takes care of this for you automatically, although it's not particularly obvious about it.

To add multiple widgets to the main window with a layout, first drag your widgets onto the QMainWindow. Here we're dragging 3 labels. It doesn't matter where you drop them.

Main window with labels and a button added via drag and drop.

We've created 2 widgets by dragging them onto the window, making them children of that window. We can now apply a layout.

Find the QMainWindow in the right hand panel (it should be right at the top). Underneath you see centralwidget representing the window's central widget. The icon for the central widget shows the current layout applied. Initially it has a red circle-cross through it, showing that there is no layout active.

Right click on the QMainWindow object, and find 'Layout' in the resulting dropdown.

Right click on the main window, and choose layout.

Next you'll see a list of layouts which you can apply to the window. Select Lay Out Horizontally and the layout will be applied to the widget.

Select a layout to apply to the main window.

The selected layout is applied to the centralwidget of the QMainWindow and the widgets are added to the layout, being arranged depending on the selected layout type. Note that in Qt Creator you can actually drag and re-order the widgets within the layout, or select a different layout, as you like. This makes it especially nice for prototyping and trying out different arrangements.

Vertical layout applied to widgets on the main window in Qt Designer.

Using Your Generated .ui File in PySide2

We've created a very simple UI in Qt Designer. The next step is to get this into Python and use it to construct a working PySide2 application.

First save your .ui file — by default it will save at the location you chose while creating it, although you can choose another location if you like.

The .ui file is in XML format. To use our UI from Python we have two alternative methods available —

1. Load it into a class using the QUiLoader
2. Convert it to Python using the pyside2-uic tool

These two approaches are covered below. Personally I prefer to convert the UI to a Python file to keep things similar from a programming & packaging point of view.

Loading the .ui File Directly with QUiLoader

To load .ui files in PySide2 we first create a QUiLoader instance and then call the loader.load() method to load the UI file.

import sys
from PySide2 import QtCore, QtGui, QtWidgets
from PySide2.QtUiTools import QUiLoader

loader = QUiLoader()
app = QtWidgets.QApplication(sys.argv)
window = loader.load("mainwindow.ui", None)
window.show()
app.exec_()

The second parameter to the loader.load() method is for the parent of the widget you're creating.

A simple PySide2 UI designed in Qt Designer

The PySide2 QUiLoader does not allow you to apply a UI layout to an existing widget. This prevents you from adding custom code for the initialization of the widget in a class __init__ block. However, you can work around this with a separate init function.

import sys
from PySide2 import QtWidgets
from PySide2.QtUiTools import QUiLoader

loader = QUiLoader()

def mainwindow_setup(w):
    w.setWindowTitle("MainWindow Title")

app = QtWidgets.QApplication(sys.argv)

window = loader.load("mainwindow.ui", None)
mainwindow_setup(window)
window.show()
app.exec_()

You can create a standalone class which handles loading of the UI files, the creation and customization of the windows, and contains any business logic for your application.

Converting Your .ui File to Python with pyside2-uic

Instead of importing your .ui files into your application directly, you can convert them into Python code and then import them like any other module. To generate a Python output file run pyside2-uic from the command line, passing the .ui file and the target file for output, with a -o parameter. The following will generate a Python file named MainWindow.py which contains our created UI.

pyside2-uic mainwindow.ui -o MainWindow.py

You can open the resulting MainWindow.py file in an editor to take a look, although you should not edit this file. The power of using Qt Designer is being able to edit, tweak and update your application while you develop. Any changes made to this file will be lost when you update it. However, you can override and tweak anything you like by importing and subclassing the class in your own code.

Importing the resulting Python file works as for any other. You can import your class as follows. The pyside2-uic converter tool appends Ui_ to the name of the object defined in Qt Designer, and it is this object you want to import.

from MainWindow import Ui_MainWindow

To create the main window in your application, create a class as normal but subclassing from both QMainWindow and your imported Ui_MainWindow class. Finally, call self.setupUi(self) from within the __init__ to trigger the setup of the interface.

import sys
from PySide2 import QtWidgets

from MainWindow import Ui_MainWindow


class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
    def __init__(self):
        super().__init__()
        self.setupUi(self)


app = QtWidgets.QApplication(sys.argv)

window = MainWindow()
window.show()
app.exec_()

This produces exactly the same result as before.

A simple PySide2 UI designed in Qt Designer and loaded in Python

That's it. Your window is now fully set up. Since the use of a .ui file abstracts out the UI-specific code, you can use this same pattern to load any interface you design.

Adding Application Logic to Your PySide2 GUI

You can interact with widgets created through Qt Designer just as you would those created with code. To make things simpler pyside2-uic adds all child widgets to the window object by their id name as specified in Qt Designer. We'll cover how to work with these in the next part.