1. Getting Started

Qt is a cross-platform development framework used primarily for creating graphical user interfaces. It is written in C++, which is also its main development language; however, bindings exist for several other programming languages, including Python.

Qt provides two separate GUI toolkits: the traditional, desktop-oriented Qt Widgets, and the modern, declarative Qt Quick for building customized and fluid user interfaces. Qt applications run on Windows, Linux, macOS, iOS, Android, or embedded systems. It also supports deployment to the web via WebAssembly.

This book covers PySide6, Qt’s official Python binding. It focuses on beginner-level Qt Widgets while tackling a few intermediate-to-advanced topics, including multithreading and model-view programming. Each chapter presents a series of self-contained PySide6 examples that showcase a single key concept or idea using step-by-step code walkthroughs.

You can easily start writing small PySide6 applications by

1. Creating a Python virtual environment from the terminal:

2. Activating the pyside6-env virtual environment:

on Windows, or

on Linux or MacOS,

3. Installing the PySide6 Python package

Now, with the pyside6-env virtual environment active, you can run a PySide6 application from the terminal:

To improve your workflow, consider using an IDE or text editor to edit and run the examples in this book. Several of them, such as PyCharm, VS Code, or Qt Creator, let you create a virtual environment from their user interface.

Qt Widgets is the original, imperative Qt GUI toolkit, designed for building traditional desktop applications with native-looking windows, buttons, menus, tables, and dialogs. It relies on a hierarchy of objects that you compose programmatically or visually with Qt Designer, using layouts to manage their position and size, and signals & slots for event handling.

Qt Widgets fall into five main groups:

1. Display widgets. These widgets present information to the user - text, images, or visual indicators - without allowing direct editing,

2. Input widgets. Widgets that allow user interaction and data entry, covering data types including binary (on/off), numeric, textual, list-based, tabular, and hierarchical (tree) formats,

3. Containers. Visual organizers for grouping and managing child widgets,

4. Layout managers. Non-visual arrangement tools used to manage widget geometry (size and position),

5. Complex widgets. Self-contained, specialized interaction components composing display, input, and validation components, like dialogs and date/time widgets.

In the rest of this chapter we work through two “Hello, World” applications that you can use to test your PySide6 setup and get familiar with the basic structure of a PySide6 application.

The first example provides a reusable starting point for a PySide6 application, displaying nothing but an empty window while still showing the necessary PySide6 application boilerplate code.

To to that:

1. Create a Python class that is a subclass of QWidget. QWidget is the base class of all Qt widget classes, often used as a top-level widget. For more involved applications that need toolbars, menu bars, etc., you can use QMainWindow, which provides them out of the box. In your class __init__() method, you must call __init__() on the superclass (i.e., QWidget) or you’ll get a runtime error¹.

In the main script code

2. Create a QApplication instance. This should be the first thing you do in your application. For non-Qt-Widgets GUI applications, use QGuiApplication; for terminal/console applications, there is QCoreApplication. QApplication is a singleton, and if you try to create it more than once, you’ll get

   RuntimeError: Please destroy the QApplication singleton before creating a new QApplication instance.

   As all the examples in this book are quite simple, we won’t be checking if the QApplication instance already exists - but it’s good to be aware of this pattern for more complex applications.

3. Create an object of your class. We create a Window object and use the QWidget.show() method to show it on the screen.

4. Use QApplication.exec() to start the application event loop. With this, your application’s main window starts processing events. When you exit the application, for instance by pressing the window’s close button, the app.exec() method returns, and your application exits.

After you execute the code, you should see an empty Qt Widgets window like this:

To do that:

1. Create a class that inherits from QWidget. This class is used as the application’s main window. In the class’ __init__() method

2. Create a QVBoxLayout instance and set it as the window layout. QVBoxLayout lays out its child widgets vertically. There are also QHBoxLayout, QFormLayout, QGridLayout, and QStackedLayout to choose from. You don’t have to use layouts - you can position widgets manually, but layouts are more flexible and are typically used in Qt/PySide6 applications.

3. Create an instance of the QLabel class and add it to the layout. QLabel is a widget that is used to display read-only text or images.

The rest of the code is the same as in the script that shows an empty window, except that we use qApp - a variable available after importing PySide6 - which is equivalent to QApplication.instance().

The result should look like this:

In the next several chapters we’ll provide an overview of a number of commonly used Qt widgets, but not before we introduce the Qt’s signals and slots mechanism.