35. State Machines

",{"_546":547,"_43":44,"_47":48,"_45":46,"_65":66,"_548":549,"_678":544},"previewContent","

\n1. Getting Started\n
- \n1.1 Installation\n
- \n1.2 Qt Widgets\n
- \n1.3 Hello World\n
- \n1.4 Hello World Again\n
\n
\n2. Signals & Slots\n
- \n2.1 Basic Signals & Slots Mechanism\n
- \n2.2 Using Python Lambda Functions\n
\n
\n3. Qt Widgets Layouts\n
- \n3.1 Laying out Widgets Vertically - QVBoxLayout\n
- \n3.2 Horizontal Layout - QHBoxLayout\n
- \n3.3 Grid Layout - QGridLayout\n
- \n3.4 Form Layout - QFormLayout\n
\n
\n4. Display Widgets\n
- \n4.1 Displaying Text with QLabel\n
- \n4.2 Displaying Images with Qlabel\n
- \n4.3 Displaying LCD-like Numbers with QLCDNumber\n
\n
\n5. Qt Widgets Buttons\n
- \n5.1 QPushButton\n
- \n5.2 QCheckBox\n
- \n5.3 QRadioButton\n
\n
\n6. Numeric Widgets\n
- \n6.1 QSpinBox\n
- \n6.2 QDoubleSpinBox\n
- \n6.3 QSlider\n
- \n6.4 QDial\n
\n
\n7. Text Widgets\n
- \n7.1 QLineEdit\n
- \n7.2 QTextEdit\n
- \n7.3 QPlainTextEdit\n
\n
\n8. List Widgets\n
- \n8.1 QComboBox\n
- \n8.2 QListWidget\n
- \n8.3 QListView\n
\n
\n9. Table Widgets\n
- \n9.1 QTableWidget\n
- \n9.2 QTableView\n
\n
\n10. Tree Widgets\n
\n11. Containers\n
- \n11.1 QGroupBox\n
- \n11.2 QScrollArea\n
- \n11.3 QToolBox\n
- \n11.4 QTabWidget\n
- \n11.5 QSplitter\n
\n
\n12. Building Complex UIs with QMainWindow\n
- \n12.1 Setting Up the Central Widget\n
- \n12.2 Adding a Status Bar\n
- \n12.3 Creating Menus and Actions\n
- \n12.4 Adding Toolbars\n
- \n12.5 Using Dock Widgets\n
- \n12.6 Completing the Editor\n
\n
\n13. Dialogs\n
- \n13.1 Standard Message Dialogs with QMessageBox\n
- \n13.2 Input Dialogs with QInputDialog\n
- \n13.3 File Dialogs with QFileDialog\n
- \n13.4 Color Selection with QColorDialog\n
- \n13.5 Font Selection with QFontDialog\n
- \n13.6 Creating Custom Dialogs by Subclassing QDialog\n
\n
\n14. Complex Widgets\n
\n15. Further Topics\n
\n16. Further Topics\n
\n17. Object Trees and Ownership\n
- \n17.1 Parent-Child Relationships\n
- \n17.2 Reparenting Qt Objects\n
- \n17.3 Finding Qt Object Children\n
- \n17.4 Manual Ownership Transfer\n
\n
\n18. More Signals & Slots\n
- \n18.1 A Common Pitfall\n
- \n18.2 Custom Signals\n
- \n18.3 Signal Blocking\n
- \n18.4 Connection Objects\n
- \n18.5 Connecting Multiple Slots with a Signal\n
- \n18.6 Disconnecting\n
\n
\n19. Events\n
- \n19.1 Event Handlers\n
- \n19.2 Object Event Filters\n
- \n19.3 Application-Wide Event Filters\n
- \n19.4 Event Propagation\n
- \n19.5 Custom Events\n
\n
\n20. Timers\n
- \n20.1 Single-Shot\n
- \n20.2 Starting and Stopping a Timer\n
- \n20.3 Adjusting a Timer Interval\n
- \n20.4 Countdown Timer\n
- \n20.5 Stopwatch\n
\n
\n21. Properties\n
\n22. Model-View Programming with QAbstractListModel\n
- \n22.1 Read-only List Model\n
- \n22.2 Editable List Model\n
- \n22.3 Editable List Model with Data-Widget Mapping\n
- \n22.4 Resizable List Model\n
\n
\n23. Model-View Programming with QAbstractTableModel\n
- \n23.1 Basic Read-Only Table Model\n
- \n23.2 Making the Table Model Editable\n
- \n23.3 Using Data Widget Mapper with Table Models\n
- \n23.4 Resizable Table Model\n
\n
\n24. Model-View Programming with QAbstractItemModel\n
\n25. Model-View Programming - Delegates\n
\n26. Model-View Programming - Sorting, Filtering and Selection\n
\n27. Multithreading - moveToThread\n
- \n27.1 Blocking the Qt GUI: How Not to Do It\n
- \n27.2 A Minimal Working Example\n
- \n27.3 Walking the Filesystem\n
- \n27.4 Reusing the QThread object\n
- \n27.5 Walking the Filesystem reusing the QThread Object\n
- \n27.6 Signals and Slots Across Threads\n
\n
\n28. Using a QThread subclass\n
- \n28.1 A Minimal Example\n
- \n28.2 Walking the Filesystem\n
\n
\n29. Multithreading with QThreadPool and QRunnable\n
- \n29.1 A Minimal Example\n
- \n29.2 Walking the Filesystem\n
\n
\n30. Thread Synchronization\n
- \n30.1 Race Condition Demo\n
- \n30.2 Queued Signal-Slot Connection\n
- \n30.3 QMutex\n
- \n30.4 QMutexLocker\n
- \n30.5 QSemaphore\n
- \n30.6 QSemaphoreReleaser\n
- \n30.7 QWaitCondition\n
\n
\n31 More Timers\n
\n32. Signals & Slots Connection Types\n
- \n32.1 Direct Connection\n
- \n32.2 Queued Connection\n
- \n32.3 Blocking Queued Connection\n
\n
\n33. Databases\n
\n34. Processes\n
\n35. State Machines\n

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.\nQt 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.

1.1 Installation

You can easily start writing small PySide6 applications by

\nCreating a Python virtual environment from the terminal:\n

1 python -m venv pyside6-env\n

\n\n

\nActivating the pyside6-env virtual environment:\n

1 pyside6-env\\Scripts\\activate\n

\n\n

on Windows, or

1 source pyside6-env/bin/activate\n

\n\n

on Linux or MacOS,

\nInstalling the PySide6 Python package\n

1 pip install PySide6\n

\n\n

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

1 (pyside6-env) $ python helloworld.py\n

\n\n

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.

1.2 Qt Widgets

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:

\n
Display widgets. These widgets present information to the user - text, images, or visual indicators - without allowing direct editing,
\n
\n
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,
\n
\n
Containers. Visual organizers for grouping and managing child widgets,
\n
\n
Layout managers. Non-visual arrangement tools used to manage widget geometry (size and position),
\n
\n
Complex widgets. Self-contained, specialized interaction components composing display, input, and validation components, like dialogs and date/time widgets.
\n

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.

1.3 Hello World

\n\n\n

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.

\n\n\n\n

$\"An$

Your first task: show an empty Qt window on the screen.

To to that:

\nCreate 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¹.\n

In the main script code

\n
\n
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
\n
\n
\n
\n
\n
RuntimeError: Please destroy the QApplication singleton before creating a new QApplication instance.
\n
\n
\n
\n
\n
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.
\n
\n
\n
Create an object of your class. We create a Window object and use the QWidget.show() method to show it on the screen.
\n
\n
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.
\n

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

\n\n

1.4 Hello World Again

\n\n\n\n

$\"An$

Your task: using the first example as the template, add widgets to that window

\n\n\n

To do that:

\n
Create a class that inherits from QWidget. This class is used as the application’s main window. In the class’ __init__() method
\n
\n
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.
\n
\n
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.
\n

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:

\n\n

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.

\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎

2. Signals & Slots

The signals and slots mechanism is a core Qt feature used for inter-object communication. A signal is emitted when an event (e.g., a mouse click) occurs and a slot is a Python method or function that gets executed in response. To establish a connection, you must connect() a signal to a slot.

2.1 Basic Signals & Slots Mechanism

\n\n\n\n

$\"An$

Your task is to create a button that displays a message in the terminal when clicked.

Here’s how to do that:

\n\n\n

\n
Create a QPushButton instance and add it to the layout. QPushButton is a widget that emits a signal when you click on it. It also supports pressed(), released() and toggled() signals. The clicked() signal combines pressed() and released().
\n
\n
\n
Add a method to the Window class that will act as the slot when the button is clicked. We have decorated it with the Slot() decorator. This optional - omitting it still works, but the Qt documentation recommends it to avoid runtime overhead.
\n
\n
\n
Notice the on_button_clicked() method’s signature includes a checked parameter, which matches the signature of QPushButton.clicked() signal, which, in turn, maches the parameter passed to the @Slot() decorator. In this example, checked will always be false because the button’s checkable property defaults to False (and we haven’t changed it).You could simplify the slot declaration and use
\n
\n
```
1 def on_button_clicked(self)\n
```
\n
\n
\n
if you don’t need the button’s checked value - it would simply be ignored.¹ The slot just prints a message to the terminal, but you can add any code to it (e.g. to update other widgets or save data).
\n
\n
\n
\n
Connect the signal to the slot using
\n
\n
```
1 object.signal_name.connect(slot_name)\n
```
\n
\n
\n
Note that there are no parentheses after self.on_button_clicked - connect() expects a function object, not a function call.
\n
\n

Run the script and you’ll see a window with a button that prints a message when you click on it.

2.2 Using Python Lambda Functions

\n\n\n\n

$\"An$

Your task is to display a message in the terminal when a button is clicked. QPushButton.clicked() doesn’t support passing additional parameters so you decide to use a lambda function.

To do this:

\n\n\n

\n
Create the widget. It’s a QPushButton like in the previous example.
\n
\n
\n
Connect the QPushButton.clicked() signal to the slot. There are two things to note here:
\n
\n
\n
- \n
  You can connect a signal to a Python lambda function (ie. an anonymous function), instead of a named method,
  \n
- \n
  Lambdas let you pass extra arguments to your slot. In the lambda we call self.log() passing it an extra string argument (My log message).
  \n
\n
\n

When you run the code, clicking the button executes the lambda, which in turn invokes log() that prints two lines to the terminal:

1 Button clicked\n2 My log message\n

\n\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎

3. Qt Widgets Layouts

When you create a Qt widget like QPushButton you need a way to position it inside a window or a container widget. It is possible, but quite uncommon, to position Qt widgets by setting their x and y coordinates - Most Qt applications use layouts to automatically arrange widgets in rows, columns grids, forms, or stacks, to achieve the desired layout¹.

3.1 Laying out Widgets Vertically - `QVBoxLayout`\n

QVBoxLayout arranges widgets in a column. If you look up the QVBoxLyout parents in the Qt documentation, you’ll notice that QWidget is not a QVBoxLayout’s parent class. This means you cannot show a layout on the screen - it is not a visual element but a geometry manager.

\n\n\n\n

$\"An$

To add a vertical layout to a QWidget:

\n\n\n

\n
Create a QVBoxLayout instance and set it as your window layout with setLayout(). This also works for any QWidget subclass. You can nest layouts inside other layouts to achieve complex layouts.
\n
\n
Create widgets you want to lay out. Here we create three QPushButton instances.
\n
\n
Add them to the layout using addWidget(). For nested layouts you would use addLayout() instead.
\n

Run the script and resize the window: The buttons stack vertically and expand horizontally to fill the width, but their height stays fixed, creating gaps between them. There are two ways you can change this:

\nAdd stretchable space with addStretch() at the end of the layout - it pushes the widgets to the top while allowing empty space to grow.\n
\nSet a widget’s size Expanding for both directions, e.g. button_1.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Expanding). This lets it resize in both axes.\n

We’ve also connected all three buttons’ clicked signals to a single @Slot() method. Inside the slot, you can use QObject.sender() to identify the sender:\nsender = self.sender()

as we need a way to tell which button emitted the clicked signal. This lets us reuse a single slot to handle signals from different widgets - but keep in mind this warning from the Qt docs:

\n
\n
Warning: This function violates the object-oriented principle of modularity. However, getting access to the sender might be useful when many signals are connected to a single slot.
\n
\n

When executed, the script shows a window like this:

3.2 Horizontal Layout - `QHBoxLayout`\n

\n\n\n\n

$\"An$

QHBoxLayout arranges widgets horizontally. The setup is the same as for QVBoxLayout:

\n\n\n

\n
Create the layout and assign it to a QWidget with setLayout()
\n
\n
Create child widgets. Here, a QPushButton and QLabel. We set the label’s minimum width to fit its text.
\n
\n
Add them to the layout using addWidget() in the desired order.
\n

For interactivity, we’ve connected the button’s clicked signal to update the label with the current time using QTime.currentTime(). This shows an important point: Qt is more than a GUI toolkit and offers tools that overlap with Python’s - for instance the developer needs to decide whether to use time from the Python standard library or QTime from PySide6,QtCore.

After execution, you’ll see a window like this:

Both layout classes arrange widgets in the order you add them with addWidget(), QVBoxLayout top to bottom, and QHBoxLayout left to right. You can change this their setDirection() method with the QBoxLayout.BottomToTop or QBoxLayout.RightToLeft. You can achieve dynamic layouts by using removeWidget() to remove a widget from a layout or insertWidget() to insert a widget out of order.

If you create a widget without setting its parent, as we do in the above examples, adding them to a widget’s layout reparents them to that widget.

3.3 Grid Layout - `QGridLayout`\n

QGridLayout positions widgets in a grid. Unlike linear layouts, you specify each widget’s row and column when adding it.

\n\n\n\n

$\"An$

To use a grid layout:

\n\n\n

\n
Create a QGridLayout instance and set it as a QWidget layout.
\n
\n
Create widgets and add them with addWidget(widget, row, col).Leave cells empty for gaps. For spanning, use addWidget(widget, row, col, row_span, col_span) - e.g., addWidget(self.label, 4, 0, 1, 4) for a label spanning one row over four columns.
\n

Here, we populate a 4x4 grid with 16 QPushButtons using two nested loops. Using sender() in the slot lets us identify the clicked button.

After execution, the window looks like this:

Using the documentation

The PySide6 Documentation ² is, for the most part, auto-generated, as indicated by this warning:

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

The Qt documentation³ itself, on the other hand, is very good - each class is documented in detail (QObject, for instance ⁴), having details like:

\nParent and child classes\n
\nProperties\n
\nFunctions\n
\nSlots\n
\nSignals\n
\nDetailed description\n

Each function is documented with its C++ signature, description, and often with a short C++ code snipped demonstrating its use. Most of the time you can refer to it, consulting the PySide6 docs for Python-specific details.

3.4 Form Layout - `QFormLayout`\n

QFormLayout creates a two-column form layout: labels on the left, fields on the right, similar to HTML forms.

\n\n\n\n

$\"An$

To implement it:

\n\n\n

\n
Create a QFormLayout instance and set it as the QWidget layout.
\n
\n
Create child widgets. Since we need to access the widgets from the slot method, we make the them Windows instance members.
\n
\n
Add child widgets to the form using QFormLayout.addRow(label_text, widget). addRow() is a convenience method that automatically creates a QLabel instance for you, setting its text to label_text.
\n

In this example, three QlineEdit fields handle user input. Their editingFinished is emitted on pressing Enter/Return or when focus leaves the changed field. A single slot updates a summary QLabel with the values. (No sender() needed here since we reference widgets directly.)

\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎
https://doc.qt.io/qtforpython-6/↩︎
https://doc.qt.io/↩︎
https://doc.qt.io/qt-6/qobject.html↩︎

4. Display Widgets

Display widgets are read-only widgets used to provide information to the user. They include

\nQlabel for text, images, and animations,\n
\nQProgressBar for showing task progress,\n
\nQLCDNumber for displaying number in an LCD-style,\n
\nQTextBrowser for read-only rich text with hyperlink support.\n

4.1 Displaying Text with `QLabel`\n

QLabel supports three text formats: plain text, Markdown, and rich text (rendered using a subset of HTML). The format is controlled via setTextFormat(). Available constants are:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Value	Enum Constant	Description
0	`Qt::PlainText`	Plain text
1	`Qt::RichText`	Qt-supported HTML subset
2	`Qt::AutoText`	Format automatically detected (default)
3	`Qt::MarkdownText`	Markdown formatting

\n\n\n\n

$\"An$

To display text using QLabel:

\n\n\n

\n
\n
Create a QLabel object, setting its text. We create three labels:
\n
\n
\n
- \none with plain text (no formatting),\n
- \none with Markdown syntax,\n
- \none with HTML syntax.\n
\n
\n
\n
\n
Set the text format for the Markdown and rich-text labels using setTextFormat():
\n
\n
\n
- \nQt.TextFormat.MarkdownText for the Markdown text,\n
- \nQt.TextFormat.RichText for the rich-text label.\n
\n
\n
\n
Add the label(s) to the layout and display the window. When the window is shown, the Markdown and rich-text labels will display bold text.
\n

When you run the application you should see a window like this:

4.2 Displaying Images with `Qlabel`\n

QLabel can display static images, vector graphics, and animated GIFs using the following methods:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Method	Description
`setPixmap()`	Displays a static image from a QPixmap
`setPicture()`	Displays a vector graphic from a QPicture
`setMovie()`	Displays an animated GIF or movie from a QMovie

\n\n\n\n

$\"An$

To display an image in a label:

\n\n\n

\n
Create an image object. We create two pictures: a png image using QPixmap and an animated gif image using QMovie,
\n
\n
Create label objects that will display the images.
\n
\n
Set the labels’ contents to the png and the gif images.
\n

The running application should look like this:

4.3 Displaying LCD-like Numbers with `QLCDNumber`\n

As the documentation states, QLCDNumber is the very oldest part of Qt, tracing its roots back to a BASIC program on the Sinclair Spectrum.

\n\n\n\n

$\"An$

To use it in your application:

\n\n\n

\n
Create a QLCDNumber instance,
\n
\n
Set its digit count,
\n
\n
Set the number to display using QLCDNumber.display()
\n

When you start the application, you should see this:

You are not restricted to QLabel for images - any widget can draw images by reimplementing its paintEvent() method, giving you full control over rendering.

5. Qt Widgets Buttons

Non-interactive display widgets like QLabel show text or images to the user but cannot accept input. Buttons, on the other hand, can accept user input, which is typically binary (checked or unchecked, on or off). Not all buttons are checkable by default (e.g., QPushButton requires explicit configuration), while QCheckBox supports an optional tri-state mode with three states: checked, unchecked, and partially checked.

Qt provides several button classes, all inheriting from QAbstractButton:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Qt Button Class	Purpose
`QPushButton`	Lets the user send a command to the application. Supports text, icons, and optional toggling.
`QCheckBox`	Used for non-mutually exclusive options (e.g., preferences). Supports binary or tri-state.
`QRadioButton`	Mutually exclusive choices within a group. Automatically deselects other radio buttons in the group.
`QToolButton`	For use in toolbars (e.g., “Save” icon). Supports popups for sub-menus.
`QCommandLinkButton`	Mimics Windows Vista command link style.

All button classes share these signals:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Signal	Emitted
`clicked(bool checked=False)`	When the button is clicked.
`pressed()`	When the button is pressed down.
`released()`	When the button is released.
`toggled(bool checked)`	When a checkable button changes its check state.

toggled() is only emitted for buttons where setCheckable(True) has been called. clicked() is emitted for both checkable and non-checkable buttons.

You can optionally add text, an icon, a shortcut, and a tooltip to a button using these methods:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Method
`setText(text)`
`setIcon(icon)`
`setShortcut(shortcut)`
`setToolTip(text)`

5.1 `QPushButton`\n

QPushButton is a common GUI element that lets the user send a command to the application. toggled() is useful only if you set the QPushButton.checkable property to True, which effectively turns it into a toggle button: once pressed, it stays pressed until pressed again.

\n\n\n\n

$\"An$

You are given a task to show a random integer in a label when a button is clicked.

To do this:

\n\n\n

\n
Create a QPushButton object, setting the text to be displayed on the button.
\n
\n
Create the method to be used as the slot - this is the method that will be called when the button is clicked. In the example, the method is named on_button_clicked() and sets a label’s text to a random integer. Note that the label is added to Window as an instance variable so we can access it from the slot.
\n
\n
Connect the button’s clicked() signal with the slot.
\n

After running the application and clicking the button you should see a window like this:

\n\n

5.2 `QCheckBox`\n

QCheckBox is a widget that consists of a graphical check box and a label. it can be checked, unchecked and - if you set its tristate property to True - partially checked. Checkboxes are used to represent options that are not mutually exclusive - more than one checkbox in a group can be checked at the same time.

\n\n\n\n

$\"An$

Your task is to allow the user to select one or more operating systems.

To do this:

\n\n\n

\n
Create a QCheckBox object and set its display text. We create three checkboxes and add them to the window’s layout. We also set each checkbox objectName property. Setting objectName can be useful in debugging or when you need to find a widget using QObject.findChild().
\n
\n
\n
Create the slot to process checkboxes’ checkStateChanged signals. The documentation suggests that you mark it with the Slot() decorator but if you do you also need to import the Qt class from PySide6.QtCore. If you don’t, you get the following error:
\n
\n
\n
\n
\n
TypeError: Cannot call meta function “void on_state_changed(Qt::CheckState)” because parameter 0 of type “Qt::CheckState” cannot be converted.
\n
\n
\n
\n
\n
This is because the state argument is of type Qt.CheckState and Qt.CheckState, like many other Qt enums, resides in PySide6.QtCore.Qt so you’ll often need to import it. So, in this case, either import Qt or leave out the Slot() decorator.
\n
\n
\n
The slot sets the label’s text to the signal sender’s object name.
\n
\n
\n
Finally, connect each checkbox checkStateChanged signal to the created slot.
\n

5.3 `QRadioButton`\n

QRadioButton is a widget that presents the user with a set of mutually exclusive options. When you select (check) a radio button all other radio buttons that have the same parent widget are automatically unselected.

\n\n\n\n

$\"An$

You want to let the user select a label’s background color.

To do this:

\n\n\n

\n
Create the radio button objects and add them to the parent widget. In this example all three radio buttons have the same parent widget - the Window object which is also the top level widget.
\n
\n
Create the slot to handle the radio buttons toggled() signal. In this case the slot has an argument that toggled does not provide named color. color holds a string containing a color name and each radio button provides an appropriate color to the slot using a lambda. Qt offers its own version of CSS (cascading style sheets), called QSS² which you can apply to widgets using QWidget.setStyleSheet(). This is how we change the label’s background and foreground colors when a raio button is toggled.
\n
\n
Connect the signals and the slot. In this case lambdas are needed to pass the extra argument to the slot.
\n

Radio buttons form a group of mutually exclusive states based on their common parent widget but you can customize this behavior using QButtonGroup³.

\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎
https://doc.qt.io/qtforpython-6/↩︎
https://doc.qt.io/↩︎

6. Numeric Widgets

Qt offers several widgets designed for numeric input:

\nQSpinBox - integer values\n
\nQDoubleSpinBox - floating-point (decimal) values\n
\nQSlider - linear selection with a sliding handle\n
\nQDial - selection with a circular dial\n

These widgets form two distinct inheritance trees. QDoubleSpinBox and QSpinBox are inherited from QAbstractSpinBox

While QSlider and QDial are inherited from QAbstractSlider:

All of them are bounded (they have configurable minimum and maximum values) and emit the valueChanged() when the user modifies the value.

6.1 `QSpinBox`\n

A QSpinBox allows the user select an integer either by clicking the up/down arrows, pressing the keyboard arrows or typing directly.

\n\n\n\n

$\"An$

You want to enable the user to select the amount of RAM.

To do this:

\n\n\n

\n
Create the QSpinBox instance and configure it. The default spinbox range is 0-99, but in this example we restrict it to realistic RAM sizes (16-256 GB), set the step size 2 GB, the initial value to 32 GB, and append the unit with setSuffix(' GB').
\n
\n
Define a slot that receives the new value and decorate it with @Slot(int). The slot name is set_ram() and it sets a label’s text to the spinbox value.
\n
\n
Connect the valueChanged signal to the slot. The slot receives the spinbox value as its argument.
\n

The application looks like this:

6.2 `QDoubleSpinBox`\n

QDoubleSpinBox lets the user select a floating-point (float) value. In this example we use it to control the opacity of another widget (a green label).

\n\n\n\n

$\"An$

You need to let the user set a label’s opacity.

To do this:

\n\n\n

\n
Create the spinbox and configure its properties. We limit the range to 0.0-1.0, and choose a single step of 0.05.
\n
\n
Create a slot to react to the valueChanged() signal. The slot change_opacity() receives the new value as a float. We appl it to QGraphicsOpacityEffect attached to the target widget. The effect’s setOpacity() method accepts values between 0.0 (fully transparent) and 1.0 (fully opaque).
\n
\n
Connect the signal to the slot.
\n

6.3 `QSlider`\n

QSlider provides a vertical or horizontal slider that lets the user select an integer value by dragging a handle. Its main signals are:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Signal	Description
`valueChanged(int)`	Emitted when the slider value changes (by user or programmatically)
`sliderPressed()`	Emitted when the user starts dragging the handle
`sliderMoved(int)`	Emitted when the slider is dragged by the user (not on `setVBalue()`\n
`sliderReleased()`	Emitted when the user releases the handle

\n\n\n\n

$\"An$

You are given the task to let the user set a label’s opacity.

To do this:

\n\n\n

\n
Create and configure the slider. Set the range with setRange(min, max) In this example we use 0-255 because we want to control the alpha channel of a color in a stylesheet (rgba(0, 128, 0, alpha)). We start at 255 (fully opaque) and make the slider horizontal.
\n
\n
Create a slot to react to value changes. The slot receives an int. Here qe dynamically update a QLabels stylesheet, inserting the slider value as the alpha component of an rgba() color.
\n
\n
Connect the signal to the slot.
\n

6.4 `QDial`\n

The QDial class provides a rounded range control. Unlike the QSlider, which is linear, QDial lets the user “turn” a value by dragging around a circular widget.

\n\n\n\n

$\"An$

You need to create a sound volume control in your app.

To do this:

\n\n\n

\n
Create and configure the dial.
\n
\n
Create a slot to respond to the dial value changes.
\n
\n
Connect the signal to the slot.
\n

In the example, turning the QDial updates a QProgressBar in real time.

7. Text Widgets

While Qt buttons and the numeric widgets let the user enter binary and numerical data, text widgets support plain text and rich text input. Qt offers three text widgets:

\nQLineEdit - single-line plain-text editing,\n
\nQTextEdit - provides multi-line richtext with Markdown and HTML¹ support,\n
\nQPlainTextEdit - multi-line plain-text with optional support for syntax coloring.\n

7.1 `QLineEdit`\n

QLineEdit provides a single-line plain-text editor. It supports the usual edit operations (copy, cut, paste, undo, redo) via standard keyboard shortcuts and a built-in context menu. You can restrict input length with setMaxLength(), validate input using a QValidator or input mask, and turn the widget into a password field by setting echoMode to EchoMode.Password.

Here are the QLineEdit signals you are likely to use:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Signal	When Emitted
`textChanged(text)`	Any change to the text (user or programmatic)
`textEdited(text)`	Only when the user types, pastes, or deletes
`returnPressed()`	Enter/Return key is pressed
`editingFinished()`	Enter pressed or the line edit loses focus
`selectionChanged()`	Selected text changes
`inputRejected()`	A validator rejects the input

\n\n\n\n

$\"An$

Suppose you need a text field that accepts only letters and warns the user about invalid input.

Here’s how to do it:

\n\n\n

\n
Create a QLineEdit object, attach a regular expression validator that allows only letters, and add a Qlabel to display feedback.
\n
\n
Implement two slots: one to show the final text when editing finishes, and another to warn the user when an invalid character is rejected.
\n
\n
Connect the editingFinished() and inputRejected() signal to the corresponding slots.
\n

7.2 `QTextEdit`\n

QTextEdit is a widget for displaying and editing both plain text and rich text. It can handle large documents efficiently and can be used as an advanced WYSIWYG editor that support rich text formatting via HTML or Markdown. Internally, QtextEdit uses a QTextDocument object, which organizes content in a hierarchy of frames, blocks and fragments.

Commonly used QTextEdit signals:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Signal	Description
`textChanged()`	Emitted when document’s content changes
`cursorPositionChanged()`	Emitted when cursor position changes
`copyAvailable(yes)`	Emitted when the availability of copy changes
`redoAvailable(available)`	Emitted when redo becomes available/unavailable
`undoAvailable(available)`	Emitted when undo becomes available/unavailable
`selectionChanged()`	Emitted when current selection changes

Note: textChanged() is emitted for both user edits and programmatic changes (e.g., calling setPlainText(), setHtml(), or setMarkdown()).

\n\n\n\n

$\"An$

Let’s say you need to create a basic Markdown editor with side-by-side live preview.

To do it:

\n\n\n

\n
Create the source editor. Instantiate QTextEdit for editing. Use monospace font for better allignment.
\n
\n
Create the preview widget. Instantiate a second QTextEdit that will display the rendered Markdown. Make it read-only and give it a distinct appearance.
\n
\n
Implement the preview slot to and connect the signal. Get the source textedit contents as plain text and use setMarkdown() to render it as Markdown in the preview textedit. By default, setMarkdown() uses the GitHub-flavored Markdown dialect.
\n

Note that we perform the initial setPlainText() only after connecting the textChanged() signal. This ensures the slot runs immediately and the preview is rendered with the initial text.

7.3 `QPlainTextEdit`\n

QPlainTextEdit provides a widget optimized for editing and displaying plain text. Unlike QTextEdit, it does not support HTML or Markdown.

A QPlainTextEdit document is composed of characters and blocks (paragraphs) separated by newline characters. Each block contains a sequence of characters with optional formatting.

\n\n\n\n

$\"An$

You are tasked with creating a basic plain-text editor that uses a monospace font and shows the current cursor line and column, as well as the total text length. To do this:

\n\n\n

\n
Create a QPlainTextEdit object, use QFontDatabase to set its font to a generic monospace font, and disable line wrapping. Also add two labels to the window: one for showing character count, and the other for showing cursor position.
\n
\n
Implement the slots to display text stats. In update_char_count(), retrieve the character count directly from the editor’s underlying QTextDocument and display it in the label. In update_position(), use the editor’s QTextCursor to get the current block number and the current cursor position within the block, then use these to calculate the cursor’s current line (block number + 1) and column (position within the block + 1).
\n
\n
Connect the signals to the slots. Update the character count when textChanged() emits, update cursor position when cursorPositionChanged() emits.
\n

\n\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎
https://doc.qt.io/qtforpython-6/↩︎

8. List Widgets

Qt provides several widgets for displaying and managing lists of items, including:

\nQComboBox - for showing a compact dropdown list,\n
\nQTableWidget- for built-in list item management,\n
\nQTableView - for model-based list mnagement.\n

8.1 `QComboBox`\n

QComboBox combines a button and a line edit with a pop-up list, which makes it useful for displaying list in a constrained space. It can be populated using its insert methods:

\naddItem() - appends an item,\n
\naddItems() - appends a list of items,\n
\ninsertItem() - insert an item at the given index,\n
\ninsertItems() - inserts a list of items at the given index,\n
\nremoveItem() - removes the item at the given index.\n

Combobox items can have text, icons, and additional user data. As QCombobox is a part of the Qt’s model/view framework, you can provide data for it using one of the Qt model classes instead of managing items manually.

QComboBox provides several signals:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Signal	Description
`activated(index)`	User chooses an item from the list
`currentIndexChanged(index)`	Current index changes (user or programmatic)
`currentTextChanged(text)`	Current text changes
`editTextChanged(text)`	Text edited in editable combobox
`highlighted(index)`	Item in the popup list highlighted
`textActivated(text)`	User chooses an item
`textHighlighted(text)`	Item in the popup list highlighted

Combobox items are indexed, starting from zero. Its line edit widget can be accessed with QComboBox.lineEdit() and it can be made editable with setEditable().

\n\n\n\n

$\"An$

You need to enable the user to select an economic sector from the list and also add new sectors to the list. When a sector is selected, all other users need to be notified. To do this:

\n\n\n

\n
Create a QComboBox object and add items to it. Sort the combobox items and set the first item as the current item.
\n
\n
Enable the user to add items. QComboBoxes are read-only by default so set the editable() property to True. Set the added items to be inserted alphabetically.
\n
\n
Create a slot to notify users when an item is selected. Connect to the list widget’s activated() signal. When the user selects an item or adds a new one to the list, the slot is executed.
\n

8.2 `QListWidget`\n

The QlistWidget class is an item-based list widget. This means its items are instances of the QListWidgetItem class, and you add them to the list widget using methods such as:

\naddItem(item),\n
\naddItem(label) or\n
\naddItems(labels).\n

QListWidget also provides methods to insert items at specific positions, retrieve an item at a given row, and remove an item using the takeItem(row) method.

QListWidgetItem, the accompanying class, can hold several pieces of information, such as text, icons, or tooltips. It can also store custom user-defined data.

Common QListWidgets include:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Signal	Description
`currentItemChanged(current, previous)`	Emitted when the current item changes.
`currentRowChanged(currentRow)`	Emitted when the current row changes.
`currentTextChanged(currentText)`	Emitted when the text of the current item changes.
`itemActivated(item)`	Emitted when an item is activated (double-click or Enter/Space while selected).
`itemChanged(item)`	Emitted when an item’s data is modified by the user.
`itemClicked(item)`	Emitted on any mouse click on an item.
`itemDoubleClicked(item)`	Emitted specifically on double-click.
`itemSelectionChanged()`	Emitted when the selection changes.

\n\n\n\n

$\"An$

You need to create a list of common weather conditions. When the user selects one, you need provide additional information about it. To do this:

\n\n\n

\n
Create a QListWidget object and add items to it. After creating the list widget, create a Python list of tuples, where each tuple’s first element contains the weather condition name and the second element contains its description. Iterate over the list, and for each tuple, create a QListWidget object, setting the weather condition description as custom user data. Add each widget item to the list widget. Also create two labels for displaying the information.
\n
\n
Implement a slot to display the weather condition name and description when the current item is changed. You get the name of a weather condition using the DisplayRole item data role, and the description using the UserRole item data role.
\n
\n
Connect the signal to the slot. The currentItemChanged() signal is emitted whenever the current item changes. It provides both the current and the previous QListWidgetItem objects to the slot (though we need only the current item in this example).
\n

8.3 `QListView`\n

A QListView presents items stored in a model, either as a list or a collection of icons. It is part of Qt’s model/view framework, which separates data (models) from its visual representation (views). This allows one model to be shared across multiple views.

\n\n\n\n

$\"An$

Provide a read-only list view of the user’s home directory, decorating each item with an appropriate icon. When the user hovers over a file, display a tooltip showing its size in KB. To do this:

\n\n\n

\n
Create the view. Instantiate a QListView object and disable its edit triggers using NoEditTriggers - this prevents actions like double-click editing.
\n
\n
Create the model and populate it with data. Use a QStandardItemModel object to store filesystem data. For each filesystem entry in the user’s home directory create a QStandardItem object, initialize it with the entry name, and set its icon based on the type (file or directory). If the entry is a file, set its tooltip text to the file size in a human-readable format. Finally, append the item to the model.
\n
\n
Set the view’s model to the QStandardItemModel object.
\n

We use Python’s pathlib.Path to access filesystem data for the model. In the get_icon() method, we return the Qt’s standard icons for files and directories to avoid using external resources. When initializing a QStandardItem with a filesystem entry name, the name is assigned to the DisplayRole by default. To assign data to its tooltip, use the ToolTipRole when setting the data.

\n\n

\n\n

9. Table Widgets

Table widgets in Qt provide a structured way do display and interact with tabular data.

\n
QTableWidget is a self-contained widget that includes its own data storage, allowing developers to easily manipulate items directly within the widget.
\n
\n
QTableView is part of the Qt model-view framework, requiring an external model to supply data, promoting separation of concerns and reusability in larger applications.
\n

Both support sorting, resizing columns and rows, and selecting multiple cells. These widgets are commonly used in applications requiring grid-based input or visualization, such as data entry forms or result displays.

9.1 `QTableWidget`\n

[TODO: INHERITANCE TREE]

The QTableWidget class provides an item-based table view with a default model. Simply put, it’s a table. The items in a QTableWidget are provided by QTableWidgetItem objects.

\n\n\n\n

$\"An$

You need to enable your boss to create and edit a service comparison matrix for your company.

To use a table widget in your application:

\n\n\n

\n
Create a QTableWidget instance and set the table dimensions. The table in the example has five rows and four columns. We also add a label to the window and a push button for exporting the comparison matrix.
\n
\n
Fill the table cells with data. Each table cell is represented with a QTableWidgetItem instance so we use a nested loop to create the items. We set each item’s data from a two-dimensional list using QTableWidgetItem.setData(). After that, each QTableWidgetItem is assigned to a table cell using QTableWidget.setItem(row, column, item).
\n
\n
Create two slot methods: one connected to QTableWidget’s itemChanged() signal and the other connected to the push button’s clicked() signal. The first slot updates the label text when a table item is changed, and the second one ‘exports’ the matrix by printing it. The table is editable; if the user double-clicks a cell, changes its value, and presses Enter, the label’s text is updated accordingly.
\n

A key distinction between QTableWidget and QTableView is in their handling of data. QTableWidget is well-suited for semi-structured or heterogeneous data, where individual cells can vary in type or format without column consistency - for instance, allowing a user to enter ‘Maybe’ in a boolean-like field instead of strictly True or False. In contrast, QTableView, paired with a model, is suitable for use with structured data, as model typically enforce uniform data types and validation rules per column. This flexibility makes QTableWidget ideal for quick prototypes and ad-hoc tables, while QTableView supports more scalable, data-driven applications.

9.2 `QTableView`\n

[TODO: INHERITANCE TREE]

QTableView is the default model-view class for displaying tabular data, and just as QListWidget is a subclass of QListView, QTableWidget is a subclass of QTableView.

\n\n\n\n

$\"An$

You users need to edit a table of aggregate economic indicators and select which ones to include in the report.

To use QTableView in your application:

\n\n\n

\n
Create a QTableView instance. We also add a label to the window to notify users of changes.
\n
\n
Create a model instance. In the example, we use QStandardItemModel, populating it with data from the two- dimensional data list. Each item is represented with a QStandardItem object. We set the data using setData() for DisplayRole and adjust flags to make the first column read-only.
\n
\n
Set the view’s model using QTableView.setModel(). Connect the model’s itemChanged() signal to a slot to handle updates.
\n

This separates the data model from the view, allowing the same model to be used with multiple views, and allowing a view’s model to be changed dynamically.

10. Tree Widgets

11. Containers

Qt container widgets are visual elements that group other widgets together to form structured interfaces - they organize layout, provide borders, and create logical sections of the UI.

11.1 `QGroupBox`\n

QGroupBox is a widget that has a frame and a title on top and allows you to display other widgets inside itself but is commonly used to group checkboxes or radiobuttons. QGroupBox does not lay out its child widgets automatically - you need to do it yourself using one of the Qt layout classes. You can set a QGroupBox to be checkable, which lets the user enable or disable all its child widgets simultaneously.

\n\n\n\n

$\"An$

Your task is to create a group of mutually exclusive options. You also need to be able to enable or disable the whole group.

\n\n\n

\n
Create a QGroupBox object and add a layout to it as you can’t add widgets directly. In the example, we use a QVBoxLayout.
\n
\n
Create widgets and add them to the layout. In the example, we add three QRadioButtons. We also set one of the radio buttons to checked.
\n
\n
Create the slot method to handle QRadioButton.toggled() signals. The slot sets a label’s text to the text of the checked radiobutton and the last two radiobuttons also toggle the group box togglable property.
\n
\n
Connect QRadioButton.toggled signals with the slot.
\n

11.2 `QScrollArea`\n

If a QScrollArea’ child widget exceeds its size it provides scrollbars so that the whole child widget can be viewed.

\n\n\n\n

$\"An$

You need to create a simple text editor in a constrained space.

\n\n\n

\n
Create a QScrollArea object
\n
\n
Create the child widget. In the example we use a QPlainTextEdit object and set its wrap mode to WrapMode.NoWrap so that it expands when text is entered
\n
\n
Add the QPlainTextEdit to the scroll area using QScrollArea.addWidget(). We also set the QScrollArea.widgetResizable property to True so that the text box resizes along with the scroll area.
\n

Now if you enter a long line of text in the text box the scroll area shows the horizontal scrollbar and if you enter several lines the scroll area shows the vertical scrollbar.

11.3 `QToolBox`\n

QToolBox provides a column of tabbed widget items. This doesn’t really tell you much - it is a Qt container widget pretty similar to the ubiquitous accordion widget that lets you pack multiple widgets within a relatively small space and expand or collapse them as needed. QToolBox pages are called items in the documentation.

\n\n\n\n

$\"An$

You need to add a collapsible set of options within a small space.

\n\n\n

\n
Create a QToolBox object
\n
\n
Create the child widgets. In the example we simply create three push buttons each representing a popular operating system. You can also add multiple child widgets to a page by adding them to a layout as demonstrated on the `Linux’ page.
\n
\n
Add the widgets to the toolbox using QToolBox.addItem()
\n

In the example we also handle the child push buttons clicked signals for demonstration purposes, setting a label’s text to the text of the clicked button.

11.4 `QTabWidget`\n

QTabWidget is a tabbed container widget - when you click on a tab its associated page is shown.

\n\n\n\n

$\"An$

Your space is limited and you need to create options for your editor styles and margins.

\n\n\n

\n
Create a QTabWidget object.
\n
\n
Create its intended child widgets. Each page contains a single widget but that widget, in turn, can be a QWidget or a container class which allows you to pack multiple children into a QTabWidget page.
\n
\n
Use QTabWidget.addTab() to add the child widgets to the tab widget object. In the example we have two QWidgets and add each to the tab widget. The first QWidget has three check boxes as its children and the second QWidgets children are three radio buttons.
\n

The tab indexes start with zero so the first tab has the index of 0 and the second has the index of 1. Each tab has a label (Styles and Margins in the example). You can change the tab position (North, South, West and East) and shape (Rounded and Triangular).

11.5 `QSplitter`\n

The QSplitter class lets the user resize its child widgets using the mouse.

\n\n\n\n

$\"An$

Your task is to create an application with three resizable panes and you want the user to be able to toggle their orientation.

\n\n\n

\n
Create the QSplitter object. It lays its child widgets horizontally by default but you can change that using the QSplitter.setOrientation() method.
\n
\n
Create the child widgets. In the example we create three QGroupBox objects. We also add two radio buttons to the first group box - selecting the buttons changes the QSplitter orientation dynamically.
\n
\n
Add the child widgets to the splitter.
\n

12. Building Complex UIs with `QMainWindow`\n

QMainWindow is a QWidget subclass with built-in support for toolbars, dock widgets, menu bars, and status bars. It is useful as a starting point for building applications that have a central area and those elements.

[TODO: MAIN WINDOW LAYOUT IMAGE]

It handles layout and docking automatically, saving you from manual QWidget management.

\n\n

A central widget ca be any of the standard widgets, typically a QTextEdit, a QTableView, or a QGraphicsView. It is set with setCentralWidget().

\n\n\n\n

$\"An$

You are building a simple note-taking application. It needs to support rich text editing (bold, italic, different font sizes, etc.), and you anticipate more features in the future, such as menus, toolbars, and side panels. You decide to use QMainWindow as the main window and place a QTextEdit as its central widget.

To use QMainWindow in your application:

\n\n\n

\n
Create a class that inherits from QMainWindow and name it Editor.
\n
\n
Inside the Editor class’s __init__() method, instantiate a QTextEdit widget. This will serve as the primary area for viewing and editing notes.
\n
\n
Call self.setCentralWidget() on the QMainWindow instance, passing the QTextEdit object. This places the text editor in the window’s central area, automatically handling resizing and layout.
\n

When you run the application, you see a window filled with the editable text area. You can type, select, copy, and paste text. The context menu and both scrollbars are present but text formatting (bold, italic, font size) is not available.

12.2 Adding a Status Bar

The QStatusBar class is a horizontal bar at the bottom of a QMainWindow, used for displaying status information. It supports three types of messages:

\n
Temporary - briefly shown over normal messages but not permanent ones. Used for notifications, tool tip explanations, or menu help text.
\n
\n
Normal - displayed persistently on the left side. Used for dynamic information like cursor position, document length, or similar.
\n
\n
Permanent - always visible on the right side. Used for indicators such as Caps Lock status or character encoding.
\n

\n\n\n\n

$\"An$

Your note-taking application users have requested live feedback at the bottom of the window: the current cursor line and column, the total character count, and (when text is selected) a note showing how many characters are selected.

To add a status bar to the main window:

\n\n\n

\n
Create QLabel widgets for the information you want to display persistently. In our example, we use one label for cursor position and another for total character count.
\n
\n
Access the status bar with self.statusBar() and add the labels using addWidget() for normal messages and addPermanentWidget() for permanent ones.
\n
\n
\n
Connect QTextEdit signals to update the information:
\n
\n
\n
- \ntextChanged() to refresh cursor position and character count.\n
- \nselectionChanged() to show the selected character count temporarily.\n
\n
\n

In the example, the permanent label always shows the total character count, while the normal label shows the cursor position. When text is selected, we briefly display a temporary message showing the selection size (e.g., “42 characters selected”). The temporary message hides the normal label for a couple of seconds but leaves the permanent character count visible.

12.3 Creating Menus and Actions

Menus are constructed using QMenuBar as the top-level container, with QMenu objects for each dropdown group, and QAction objects for the individual commands or items. QActions can be reused across menus, toolbars, and keyboard shortcuts.

[TODO: MENUBAR DIAGRAM]

\n\n\n\n

$\"An$

Your application users expect standard application menus: a File menu with an Exit command and a Help menu with an About dialog that shows application information and version.

To add drop-down menus to your main window:

\n\n\n

\n
Access the main window’s menu bar with QMainWindow.menuBar(). Add individual menus using QMenuBar.addMenu() with a title (e.g., ‘&File’). Ampersands enable keyboard shortcuts.
\n
\n
For each menu item, create a QAction object. Set its text, a shortcut with setShortcut(), and connect its triggered() signal to a slot (e.g., for quitting or showing a dialog). Set the main window as the action parent to ensure it stays in scope for the application lifetime.
\n
\n
Add the action to the menu using QMenu.addAction().
\n

Menu-level keyboard accelerators are enabled by prefixing letters with an ampersand (&) in the menu title (e.g., “&File” allows Alt+F to open it). For action-level shortcuts (e.g., Ctrl+Q for Exit), use setShortcut().

When you run the application, the menu bar appears at the top. Selecting “Exit” closes the app, and “About” displays a simple dialog.

12.4 Adding Toolbars

QToolBar provides a panel for quick-access controls. Users can drag a toolbar to different dock areas, float them as separate windows, or customize their position. You can reuse the same QAction objects for both menus and toolbars.

\n\n\n\n

$\"An$

You are enhancing the note-taking application with a toolbar. You decide to place the Exit and About commands on it.

To use a toolbar in your application:

\n\n\n

\n
Create the toolbar using QMainWindow.addToolBar().
\n
\n
Add existing QAction objects (reused from menus), custom QWidgets, or separators as needed.
\n
\n
Optionally, add icons to the actions with setIcon(). Icons display in both menus and toolbars. Customize the toolbar’s appearance with setToolButtonStyle().
\n

When you run the application, the toolbar appears at the top. Hovering shows tooltips (inherited from action text), and clicking performs the same functions as the menu. Users can right-click the toolbar area to toggle visibility or drag it to reposition.

12.5 Using Dock Widgets

QDockWidget enables the creation of panels that can be docked within a QMainWindow or floated as independent windows. It is used for tools that users may want to rearrange or hide to customise their workflow.

Your text editor users want quick access to common formatting tools (bold, italic, and font size selection) without cluttering the main menu or toolbar. You provide these controls in a dockable widget that can be positioned on the left or right and floated if needed.

To use a dock widget in your application:

\n\n\n

\n
Instantiate a QDockWidget and configure its properties, such as title or allowed docking areas.
\n
\n
Create child widgets and arrange them in a layout within a container QWidget, then set this container as the dock’s content using setWidget().
\n
\n
Connect signals from the child widgets to slots that apply formatting via QTextCharFormat and mergeCurrentCharFormat(). To reflect the current text format in the dock (e.g., when moving the cursor), connect QTextEdit.cursorPositionChanged() to update the widgets’ states.
\n

12.6 Completing the Editor

13. Dialogs

A dialog is a small window that presents information to the users and prompts them for a response. A dialog can be modal, in which case the user cannot continue without closing it, or modeless, where the user can continue work while the dialog is still open.¹ Qt offers several standard dialogs while also letting developers create custom ones by subclassing the QDialog class.

Qt standard dialogs²:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Name	Description
QColorDialog	Dialog widget for choosing colors
QFileDialog	Dialog that allows users to select files or directories
QFontDialog	Dialog widget for selecting a font
QInputDialog	Convenience dialog to get a single value from the user
QMessageBox	Modal dialog for informing the user or for asking the user a question and receiving an answer
QProgressDialog	Feedback on the progress of a slow operation

[TODO: A NOTE ON PARENTS]

13.1 Standard Message Dialogs with `QMessageBox`\n

QMessageBox is a modal dialog for providing information to the user or asking a question and receiving an answer. A message box can display a text message, an icon and Qt’s standard buttons for accepting the user’s response³.

\n\n\n\n

$\"An$

You are building a simple note-taking application where users can save their notes. To confirm actions like discarding unsaved changes, you decide to use a standard message dialog to prompt the user before closing the window.

To use a message box in your application:

\n\n\n

\n
Create a QMessageBox object. In the example, we detect when the user attempts to close the application by overriding the main window’s closeEvent(). The document is stored in a text edit and we only show the message box if the document’s isModified() property is true.
\n
\n
Set the message box properties. We set the title, icon, text, and informative text to provide additional information to the user (for even more details, use detailedText()). We also add three standard buttons, Save, Discard and Cancel, and set Save as the default.
\n
\n
Display the message box using exec(), making it modal, and handle the user response. The message box’s return value is one of the standard button enumeration values: if the user presses Save, we simulate saving the document and set its modified() property to false; if the user presses Discard we continue without saving the document; and if the user presses Cancel we ignore the close event and the application remains open.
\n

13.2 Input Dialogs with `QInputDialog`\n

Whereas QMessageBox typically returns a QMessageBox.StandardButton value, QinputDialog can return single-line or multiline text, an integer, a double, or a string selected from a list.

\n\n\n\n

$\"An$

In your note-taking app, users need to give each note a title. You opt for a simple input dialog to enter text, and set the opened note title.

To use a QInputDialog in your application:

\n\n\n

\n
Provide a way for the user to invoke the dialog. We create a QAction and connect its triggered() signal to the set_note_title() slot.
\n

Show the dialog. When the user triggers the action, display the input dialog using one of the QInputDialog’s static methods:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Method	Description
`getDouble()`	Gets a floating point number from the user
`getInt()`	Gets an integer from the user
`getItem()`	Gets an item from a list
`getMultiLineText()`	Gets multi-line text input
`getText()`	Gets a single line of text

In the example, the user needs to enter a string so we use getText().

\n
\n
Check the return value and handle the user response. getText() returns a tuple:
\n
\n
```
1 (text, ok)\n
```
\n
\n
\n
text is the string the user entered. ok will be true if the user presses Ok and false if the user presses Cancel. If ok is true, set the note title and update the action’s icon indicating the note has a title.
\n
\n

13.3 File Dialogs with `QFileDialog`\n

QFileDialog lets users select files or directories. The easiest approach is using one of its static methods⁴:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Method	Description
`getExistingDirectory()`	Select a directory
`getExistingDirectoryUrl()`	Select a directory (URL)
`getOpenFileContent()`	Open file and read content
`getOpenFileName()`	Select a single file to open
`getOpenFileNames()`	Select multiple files to open
`getOpenFileUrl()`	Select a file to open (URL)
`getOpenFileUrls()`	Select multiple files (URLs)
`getSaveFileName()`	Select a file name to save
`getSaveFileUrl()`	Select a file to save (URL)
`saveFileContent()`	Save content to file

Behind the scenes, QFileDialog uses a platform-native file dialog if one is available, resulting in different appearence accross platforms.

\n\n\n\n

$\"An$

For a note-taking application, you need to let users open an existing file and save a new one. Implement a file dialog to handle file selection with options for filtering by file types.

To use a file dialog in your application:

\n\n

\n\n\n

\n
Give users a way to display the dialog. Create two QActions, one for saving and one for opening a file. For both actions, set text, a shortcut and an icon. Connect each action’s triggered() signal to a slot - save_note() for the save action and open_note() for the open action.
\n
\n
Display the dialog. In open_note() we use getOpenFileName(). In save_note(), the file dialog is shown only if the note has not been already saved. For both dialogs set the title, the starting directory and the file filter.
\n
\n
Use the return value to handle the user’s response. getSaveFileName() returns a tuple:
\n

1 (fileName, selectedFilter)\n

\n\n

If the user presses Cancel, fileName is an empty string so we don’t need to do anything. If the user presses the Save button, we save the contents of the text edit into fileName.

Likewise, we use fileName to read the file contents into the text edit only if getOpenFileName() does not return an empty string.

13.4 Color Selection with `QColorDialog`\n

QColorDialog allows users to select colors. You typically use its getColor() static method to show it as a modal dialog⁵.

\n\n\n\n

$\"An$

Users of your note-taking application want to be able to change their note text and background colors. You use a color dialog to allow selecting a color from a palette without building a custom color picker.

To use a color dialog in your application:

\n\n\n

\n
Provide a way for users to display the dialog. In the main window’s __init__(), create actions for selecting the foreground and background colors. Connect the actions to the slots and add the them to the the main window’s menu bar and toolbar.
\n
\n
Show the dialog. We want both dialogs to open with the current text colors. foreground() and background() are QBrush objects, so we extract their colors and use them as the dialogs’ initial colors.
\n
\n
If the dialog returns a valid color use it in your application. Unlike QInputDialog and QFileDialog, QColorDialog does not return a tuple - it always returns a QColor object, so we need to check if it isValid() to confirm that the user pressed Ok.
\n

13.5 Font Selection with `QFontDialog`\n

QFontDialog provides a dialog for selecting a font. It is created by invoking one of the static getFont() methods⁶:

\ngetFont(parent)\n
\ngetFont(initial, parent, title, options)\n

\n\n\n\n

$\"An$

AYou need to add font selection to your note-taking application’s formatting toolbar. You use a font dialog to let users choose family, style, size, and effects.

To use a font dialog in your application:

\n\n\n

\n
Create an action to trigger the dialog.
\n
\n
Show the dialog to the user. In set_font(), we get the current QFont from the text edit’s currentCharFormat() and pass it to getFont() so the dialog opens with that font selected.
\n
\n
If the user presses Ok, update the font. getFont() returns a tuple where the first element, ok, is true if the user pressed Ok and false otherwise. The second element is a QFont object representing the font the user selected.
\n

13.6 Creating Custom Dialogs by Subclassing `QDialog`\n

Standard dialogs are straightforward to use - you display them using static methods and handle the result based on which button the user pressed. They are designed to fiy most common use cases like showing messages, choosing colors, files and folders, fonts, and accepting user input. For more complex or custom dialogs, however, you can subclass the QDialog class and create your own.

QDialog is the base class of all the Qt standard dialogs, implementing the slots common to all of them:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Slot	Description
`accept()`	Closes dialog with Accepted result
`done(int r)`	Closes dialog with specified result code
`exec()`	Shows dialog modally, returns result code
`open()`	Shows dialog non-modally
`reject()`	Closes dialog with Rejected result

and their common methods:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Method	Description
`isSizeGripEnabled()`	Returns if resize grip is enabled
`result()`	Returns the dialog’s result code
`setModal(bool)`	Sets whether dialog is modal
`setResult(int)`	Sets the dialog’s result code
`setSizeGripEnabled(bool)`	Enables/disables resize grip

signals:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Signal	Description
`accepted()`	Emitted when dialog is accepted
`finished(int)`	Emitted when dialog closes with result code
`rejected()`	Emitted when dialog is rejected

and properties:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Property	Description
`modal`	Whether dialog blocks input to other windows
`sizeGripEnabled`	Whether dialog has a resize grip

Set result() to one of the QDialog.DialogCode values, Accepted or Rejected.

The QDialogButtonBox class, commonly used with QDialog, automatically arranges standard buttons in a layout appropriate for the user’s desktop environment. For instance, Windows places the OK button before Cancel, while Gnome reverses this order.

\n\n\n\n

$\"An$

For a user preferences panel in your application, you need a dialog with multiple input fields and buttons. Create a custom dialog subclass to organize these elements and handle acceptance/rejection.

To create a custom Qt dialog:

\n\n\n

\n
Create a QDialog subclass. We create a class named SettingsDialog, set its window title and set it to be modal.
\n
\n
\n
Add the child widgets to the dialog. In the example, we create three widgets:
\n
\n
\n
- \nA checkbox to set whether the application should auto-save the current note or not,\n
- \nA spinbox to set the auto-save interval,\n
- \nA checkbox to make the application reopen the last edited note.\nThe spinbox is enabled only if the auto-save checkbox is checked and lets the user select values between one and sixty minutes.\n
\n
\n
\n
Add QDialogButtonBox to the dialog. We want the application to have a native look on multiple platforms so we add a button box with the Ok and Cancel buttons. We also connect the button box accepted signal to accept() and the rejected signal to reject(). The current widget values are saved to a .ini file using QSettings.
\n

\n\n\n

\nUse the custom dialog in your application. In the main window, we create the settings action and, when it’s triggered, show our custom dialog so the user can edit the settings.\n

\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎
https://doc.qt.io/qtforpython-6/↩︎
https://doc.qt.io/↩︎
https://doc.qt.io/qt-6/qobject.html↩︎
https://doc.qt.io/qt-6/qcolordialog.html↩︎
https://doc.qt.io/qt-6/qfontdialog.html↩︎

14. Complex Widgets

15. Further Topics

16. Further Topics

17. Object Trees and Ownership

QObjects are organized in trees: when you create an object with another object as a parent, the child is added to the parent’s children() list and automatically deleted when the parent is¹. There are several ways to set an object’s parent:

\nCreating an object by passing the parent to its __init__() method.\n
\nUsing QObject.setParent(). This methods allows changing an object’s parent after creation.\n
\nAdding a widget to a layout. When adding a widget to a QLayout, the layout automatically reparents it to the layout’s owning widget\n
\nSetting a layout on a widget. Assigning a layout using setLayout() makes the widget the parent of any widgets in the layout.\n

Note that Python objects also form tree hierarchies, but a Python parent-child relationship doesn’t imply Qt a Qt one.

17.1 Parent-Child Relationships

\n\n\n\n

$\"An$

You are tasked with creating five Qt push buttons and displaying them in a window.

\n\n\n

You create five QPushButton instances in the window’s __init__() method:

\n
Create the first button and set the window as its parent. Omit adding it to the layout or as an instance member, leaving it as a local variable.
\n
\n
Create the second button without setting a parent. Add it to the layout (which reparents it to the window), but keep it as a local variable.
\n
\n
Create the third button, setting the window as its parent. Add it to the layout, but as local variable.
\n
\n
Create the fourth button as a local variable without setting a parent.
\n
\n
Create the fifth button as an instance member of the window class but without setting a Qt parent.
\n

The program output is:

1 Button 1 parent:  Main Window\n2 Button 2 parent:  Main Window\n3 Button 3 parent:  Main Window\n4 Button 4 parent:  None\n5 Button 5 parent:  None\n6 \n7 Window members:\n8 button5\n

\n\n

The first three buttons become the windows child widgets - directly or via the layout - and appear on the screen. The first button displays in the top-left corner since it is not in the layout. None of these three buttons are instance members of the Window Python object.

The fourth button is neither part of the Qt object hierarchy nor a Python object member, so it goes out of scope (and is garbage-collected) when __init__() returns, and is never shown.

The fifth button is an instance member of the window object (preventing garbage collection) but not part of the Qt object hierarchy, so it is not shown in the window.

17.2 Reparenting Qt Objects

\n\n\n\n

$\"An$

You need to create two top-level Qt windows and switch a child widget on demand.

To do this:

\n\n\n

\n
Create two top-level Qt Windows. On clicking the main window’s ‘Show widgets’ button show two QWidget objects. Don’t set their parents on creation - this makes them top-level windows (if you close the main window, they remain visible and active).
\n
\n
Create the child widget. Add a QLineEdit object to the layout of widget1.
\n
\n
On clicking the ‘Switch parent’ button reparent the line edit. Remove it from the current widget’s layout, use setParent() to assign the other widget as its parent, and add it to its layout for visibility. The line edit displays its current parent’s object name.
\n

17.3 Finding Qt Object Children

Qt lets you find an object’s children using these QObject methods:

\nfindChild(type[, name[, options]]): Finds a single matching child.\n
\nfindChildren(type, pattern[, options]): Finds multiple children by exact name.\n
\nfindChildren(type[, name[, options]]): Finds multiple children by regex pattern,\n

with these parameters:

\ntype: A PySide6 class such as QWidget, QLabel, or QCheckBox,\n
\nname: The child’s object name, set via setObjectName(). Defaults to an empty string so it must be set it explicitly for name-based searches (optional).\n
\npattern: A QRegularExpression instance for pattern matching.\n
\noptions: Either Qt.FindChildOptions.FindDirectChildrenOnly or Qt.FindChildOptions.FindDirectChildrenRecursively (optional).\n

\n\n\n\n

$\"An$

You have a set of checkboxes in a group box and need to check them programmatically based on user input.

To do that:

\n\n\n

\n
Create the checkboxes. Instantiate three QCheckBox objects in a QGroupBox and set an object name for each. Also, create a QLineEdit for user input and a button to start the search.
\n
\n
Find the checkboxes. When the button is pressed, use the QLineEdit text to create a QRegularExpression and pass it to findChildren().
\n
\n
Update the checkboxes. Iterate over the found checkboxes and set each one’s check state to Checked.
\n

17.4 Manual Ownership Transfer

Sometimes you want to dynamically reconfigure a UI by moving a widget from one container to another - complete with correct behavior in its new location.

\n\n\n\n

$\"An$

A “Clear” button lives inside a group box and clears its sibling QLineEdit. You want to move that button to another group box so it clears a different lineedit.

We have two groupboxes, each containing a QlineEdit. A single “Clear” button starts in Group 1 and clear its sibling lineedit. Clicking “Move the Button” transfers the button to the other groupbox, and you must set it to clear its new sibling.

\n\n\n

\n
\n
Update state and connections. Moving a widget does not affect existing signal-slot connections. Our button is still connected to the old lineedit’s clear() slot. We have to:
\n
\n
\n
- \nDisconnect the old connection\n
- \nConnect to the new lineedit\n
- \nUpdate state (enable/disable the appropriate lineedit)\n
\n
\n
\n
Transfer ownership. There is no need remove the button from its original layout or use setObject() to change its parent, as adding it to the new layout takes care of the both.
\n

Now if you move the Clear button from one groupbox to another, it will clear its sibling lineedit text correctly.

\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎

18. More Signals & Slots

18.1 A Common Pitfall

We have already seen that a Python lambda can be used to pass additional arguments to a slot, however, there is a pitfall that makes lambdas a bit tricky. The value of a variable used in a lambda is looked up at the time it is called¹. Let’s say you have five lambda functions and you want to pass them a loop index as the parameter:

1 functions = []\n2 \n3 for i in range(5):\n4     functions.append(lambda: print(i))\n5 \n6 print(\"Calling the functions after the loop:\")\n7 for func in functions:\n8     func()\n

\n\n

The output is:

1 Calling the functions after the loop:\n2 4\n3 4\n4 4\n5 4\n6 4\n

\n\n

When the functions are executed (in the second loop) the i variable value is 4 so all four print 4 instead of 0, 1, 2, 3 and 4 as one would expect. You can change this by assigning the current index to a lambda argument:

1 functions = []\n2 \n3 for i in range(5):\n4     functions.append(lambda x=i: print(x))\n5 \n6 print(\"Calling the fixed functions:\")\n7 for func in functions:\n8     func()\n

\n\n

Now, the output is:

1 Calling the fixed functions:\n2 0\n3 1\n4 2\n5 3\n6 4\n

\n\n\n\n\n

$\"An$

You want to log each QCheckBox checked state change into multiple log files.

\n\n\n

\n
Create the checkbox.
\n
\n
Use a loop to connect its checkStateChanged() signal to the slots. In each loop iteration, capture the index and checkbox checkState() current values
\n
\n
Log the checkbox state changes.
\n

Now, if you check the checkbox, the output is:

 1 Logging to file no: 0\n 2 State: CheckState.Checked\n 3 Logging to file no: 1\n 4 State: CheckState.Checked\n 5 Logging to file no: 2\n 6 State: CheckState.Checked\n 7 Logging to file no: 3\n 8 State: CheckState.Checked\n 9 Logging to file no: 4\n10 State: CheckState.Checked\n

\n\n

18.2 Custom Signals

Most of the Qt classes provide a set of predefined signals. However, when creating your own QObject inherited class, you may want to provide custom signals to accompany it.

\n\n\n\n

$\"An$

Suppose we want to create a custom button class that that keeps track of the number of times the user has clicked on it. We also want the class to be able to notify other classes when the counter changes.

PySide6 provides the means to do this in a pythonic way:

\n\n\n

\n
Import the Signal class from the PySide6.QtCore namespace. Signal provides the connect(), disconnect() and emit() methods.
\n
\n
Create a QObject inherited class and add a signal to it. We inherit the class from QPushButton and add a signal named counterChanged() to it. The signal is declared as a class-level variable of the class and takes a list of Python types as argument. counterChanged() takes a single int argument. Each time the button is clicked we increment the counter and emit the signal, passing it the self.counter variable.
\n
\n
In the main window use the custom signal the same way as the predefined Qt signals. We create an instance of the CounterButton, create a slot named on_counter_changed(), and connect the button’s counterChanged signal with it. Now, each time the button is clicked, the counter is incremented and the counterChanged() signal is emitted:
\n

1 Counter:  1\n2 Button clicked\n3 Counter:  2\n4 Button clicked\n5 Counter:  3\n6 Button clicked\n

\n\n

18.3 Signal Blocking

At times, you may want to prevent signal emission, for instance during class initialization, or when making programmatic changes to a widget’s values that would trigger a signal.

\n\n\n\n

$\"An$

Your task is to allow the user to temporarily block a button’s clicked() signals

To temporarily block a signal, use the QObject.blockSignals() passing it a boolean value. If the value is True all signals emitted by the object are blocked. If the value is False, signals are not blocked.

\n\n\n

In the example we have a button’s clicked() signal connected to a slot named on_button_clicked(). We use a QCheckBox() to block/unblock the button’s signals:

1 if state == Qt.CheckState.Checked:\n2     self.button.blockSignals(True)\n3     print('Signals blocked!')\n4 else:\n5     self.button.blockSignals(False)\n6     print('Signals unblocked!')\n

\n\n

When the checkbox is checked the button’s signals are blocked:

1 Button clicked, checked: False\n2 Signals blocked!\n3 Signals unblocked!\n4 Button clicked, checked: False\n

\n\n

18.4 Connection Objects

The Signal.connect() method has a return value of type QMetaObject.Connection. It is a handle to the signal-slot connection the Signal.connection() call established.

\n\n\n\n

$\"An$

You need to enable the user to connect or disconnect a button’s signals.

To use a connection object in your application:

\n\n\n

\n
Store a reference to the Connection object that Signal.connect() returned. We store the reference in the instance variable named conn.
\n
\n
Use the reference to disconnect the signal from the slot. Aside from connect() PuSide6 Signal object also have a method named disconnect() that we use to disconnect the signal from the slot.
\n

The output is:

1 <class 'PySide6.QtCore.QMetaObject.Connection'>\n2 Connection is valid\n3 <class 'PySide6.QtCore.QMetaObject.Connection'>\n4 Connection is invalid\n5 Already disconnected\n

\n\n

The first time we click the Disconnect button the connection is valid and succesfully disconnected. The second time we click it the connection is not valid so we don’t call disconnect()

If we didn’t check the connection validity we would have got a

1 RuntimeWarning: Failed to disconnect (<PySide6.QtCore.QMetaObject.Connection object at 0x7fee46154040>) from signal \"clicked()\".\n

\n\n

18.5 Connecting Multiple Slots with a Signal

You can connect a slot with more than one signals. In the example we create three slots and connect them with the button.clicked signal.

\n\n\n

The output is

1 Executed first\n2 Executed second\n3 Executed third\n

\n\n

Notice that the slots are executed in the order in which they were connected to the signal. This not necessarily true for signals and slots across different threads.

18.6 Disconnecting

In the Qt.UniqueConnection example we saw that you can break a signal-slot connection using the Signal.disconnect(receiver) method.

\n\n\n

1 self.button.clicked.disconnect(self.on_clicked)\n

\n\n

This breaks up the connection between button.clicked signal and the on_clicked() slot. However, QObject also has a disconnect() method with several overloads that give you more control over which signal-slot connections are removed.

\nstatic disconnect(connection) lets you pass a connection object to it. In the example we store all connection objects in the Window.connections list. On clicking the Disconnect 1 button all connections are disconnected in a loop:\n

1 def on_disconnect_1(self):\n2     for c in self.connections:\n3         QObject.disconnect(c)\n4     self.update_label()\n

\n\n

\n static disconnect(sender, signal, receiver, member) lets you specify both the sender and the receiverobjects as well as thesignaland thememberie the slot. On clicking theDisconnect 2button we setself.buttonas thesenderand the other three arguments toNone. Noneacts as a wildcard so this disconnects **all** signal-slot connections whereself.button` is the signal sender.\n

1 def on_disconnect_2(self):\n2     QObject.disconnect(self.button, None, None, None)\n3     self.update_label()\n

\n\n

\nOn clicking the Disconnect 3 button we set self.button as sender and clicked(bool) as signal. receiverandmemberare still set toNone`.\n

1 def on_disconnect_3(self):\n2     QObject.disconnect(self.button, SIGNAL('clicked(bool)'), None, None)\n3     self.update_label()\n

\n\n

This will disconnect only the slots with the signature clicked(bool) ie. Slot1 and Slot3. The connection between button.clicked and Slot2 remains.

\nOn clicking the Disconnect 4 button we set sender to button and reciver to self (ie to the Window instance). signal and member are set to None. This breaks up all connections since all the slots are Window members.\n

1 def on_disconnect_4(self):\n2     QObject.disconnect(self.button, None, self, None)\n3     self.update_label()\n

\n\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎

19. Events

In the Qt framework, events are objects derived from the QEvent class that represent occurences, such as user input or system notifications, that require handling. Events are especially relevant for Qt widgets, as they allow widgets to react to changes like mouse movements, keyboard presses, or window resizes. The event system relies on Qt’s event loop, which processes queued events and dispatches them to the appropriate QObject receivers. Developers can customize event handling by overriding virtual event methods in subclasses, providing fine-grained control over application behavior. Common event types include QMouseEvent for pointer interactions, QKeyEvent for keyboard actions, and QPaintEvent for rendering updates¹.

There are five ways events can be processed:

\nReimplementing event type-specific event handler methods like mousePressEvent().\n
\nReimplementing the QObject.event() method.\n
\nInstalling an event filter on the object.\n
\nInstalling an event filter on QCoreApplication instance.\n
\nReimplementing the QCoreApplication.notify() method².\n

19.1 Event Handlers

A Qt class main event handler is the event() method. When an event occurs, this method receives a QEvent object representing it. Typically, it does not handle the event itself but instead calls the specific event handler method for that event type. You can override the base class’s event handler completely, in which case you must implement all handling yourself, or handle only certain event types and call the base class method for others.

\n\n\n\n

$\"An$

Whenever your application’s main window becomes visible on the screen, add it to the list of visible windows. When it becomes hidden, remove it from the list. Your additional task is to record and suppress key press events when the user presses the letter ‘q’.

\n\n\n

\n
Extend the keyPressEvent() method. To suppress the ‘q’ key presses, check if event.text() equals ‘q’. If it does, record it in a label. Since QKeyEvent.isAccepted() is True by default, this suppresses the ‘q’ key presses. For all other key presses, call the base class keyPressEvent().
\n
\n
Extend the showEvent() method. Simulate adding the window to a visible windows list by recording the event in the label, then call the base class showEvent().
\n
\n
Extend the hideEvent() method. When the window is hidden, the label is also hidden, so simulate removing the window from the visible windows list by printing a message. Then call the base class hideEvent() for further processing.
\n

The event() method dispatches events to type-specific event handlers like showEvent() or keyPressEvent(). While you can use it to handle events directly, the documentation recommends using the event type-specific handlers instead. In the example, we intercept key press and show events in event() and print a message for each. Then we call the base class event() for further processing. You can also use event() to suppress events - if you uncomment the two return True statements, events never reach keyPressEvent() and showEvent().

19.2 Object Event Filters

In the previous section we saw how to intercept events by overriding a QObject’s event() method before the events reach the specific event handlers. Sometimes, however, you need to monitor or suppress events destined for other objects. This is achieved by installing an event filter.

\n\n\n\n

$\"An$

Your task is to log mouse press events for a group of buttons while completely suppressing clicks on one particular button.

To use an event filter in your application:

\n\n\n

\nCreate a class that inherits from QObject and implement its eventFilter() method. The signature is:\n

1 def eventFilter(self, watched: QObject, event: QEvent) -> bool\n

\n\n

The watched parameter refers to the object receiving the event. In this example, we check for MouseButtonPress events, log them to the console, and return True for button2 to consume the event (preventing further processing, including the clicked() signal). For all other cases, we return the result of the base class implementation.

\n
Instantiate the event filter object (in this case a MousePressFilter instance named event_filter.
\n
\n
Install the event filter on each target widget using installEventFilter().
\n

If you delete the watched object inside eventFilter(), you need to return True, otherwise the application might crash.

The output is:

1 Filter mouse press for:  button1\n2 Button clicked:  button1\n3 Filter mouse press for:  button2\n4 Filter mouse press for:  button3\n5 Button clicked:  button3\n

\n\n

Consuming an event means stopping it from being processed further. The clicked() signal requires Qt to process both a mouse press and a mouse release on the button. By consuming the mouseButtonPress event in the filter, the button never receives the press event, so it can’t recognize a complete click action.

Event filters can be chained, meaning you can install multiple filters on the same object. When event occurs, Qt calls the filters in reverse order of installation.

19.3 Application-Wide Event Filters

In the previous section, we installed an event filter on individual buttons. An event filter installed on the QApplication object, however, can intercept all events for all widgets in the application - including mouse events that would normally be ignored by disabled widgets.

\n\n\n\n

$\"An$

You want users to be able to “click” disabled buttons (i.e., trigger their clicked signal) without re-enabling them visually or functionally.

To implement a global event filter:

\n\n\n

\n
Create the event filter class. Override eventFilter() to detect MouseButtonPress events If the target widget (the watched parameter) is a disabled QPushButton, manually emit its clicked() signal and consume the event by returning True.
\n
\n
Instantiate the filter object, passing the QApplication instance as its parent.
\n
\n
Install the filter on the QApplication instance using QApplication.installEventFilter().
\n

Sample console output when clicking each button in order:

1 Filter mouse press for:  Main WindowWindow\n2 Filter mouse press for:  button1\n3 Button clicked:  button1\n4 Filter mouse press for:  Main WindowWindow\n5 Filter mouse press for:  button2\n6 Button clicked:  button2\n7 Filter mouse press for:  Main WindowWindow\n8 Filter mouse press for:  button3\n9 Button clicked:  button3\n

\n\n

Notice that filter receives each mouse press event twice. Qt delivers them first to the top-level window, then to the specific button under the mouse. Since the filter is installed at the application level, it intercepts the event at both stages.

This approach bypasses Qt’s normal disabled-state behavior. Disabled buttons will emit clicked() signals but won’t show visual press feedback. Application-wide filters see every event in your application, so keep the eventFilter() method efficient to avoid perdormance issues.

19.4 Event Propagation

The QCoreApplication.notify() method delivers all events to their receiver objects. Certain event types, such as mouse and key events, propagate up the parent widget chain if the receiver ignores them (i.e., does not accept the event).

\n\n\n\n

$\"An$

Your application requires users to create an account. To better understand how they interact with the “Create account” dialog - for usability testing or debugging - you want to log every mouse click and keyboard press, including which widget received the event and how events propagate when not handled.

To implement a global activity logger:

\n\n\n

\n
Create an EventFilter class inheriting from QObject. In its eventFilter() method, detect MouseButtonPress and KeyPress events and log them to the console.
\n
\n
In the main section, after creating the QApplication, instantiate the filter and install it globally using QApplication.installEventFilter().
\n
\n
Create the main window as a QWidget containing:
\n

\nA QLineEdit for entering the user name,\n
\nA Qlabel below it displaying the generated e-mail address. Make the text selectable so users can copy it.\n
\nA checkbox to enable email notifications.\n

The widgets are nested inside two QGroupBox containers to create a clear parent hierarchy.

Here is a sample output from typical interactions:

 1 Log: key pressed in  MainWindowWindow\n 2 Log: key pressed in  line_edit\n 3 Log: mouse pressed in  MainWindowWindow\n 4 Log: mouse pressed in  checkbox\n 5 Log: mouse pressed in  MainWindowWindow\n 6 Log: mouse pressed in  label\n 7 Log: key pressed in  MainWindowWindow\n 8 Log: key pressed in  label\n 9 Log: key pressed in  inner_groupbox\n10 Log: key pressed in  outer_groupbox\n11 Log: key pressed in  MainWindow\n

\n\n

Because the filter is installed at the application level, it sees events at every step of delivery and propagation.Interactive widgets like the line edit and checkbox accept most events they receive, stopping further propagation. The label behaves differently: it accepts mouse presses but ignores most key presses. As a result, key events on the label propagate up through the inner group box, outer group box, and finally the main window.

19.5 Custom Events

Qt allows you to define and post your own event types, extending the event system for application-specific needs. Custom events are processed in the event loop like built-in events and can be handled in the customEvent() handler, event() or via event filters.

To create a custom event:

\nRegister a unique type with QEvent.registerEventType().\n
\nSubclass QEvent and add data attributes.\n
\nPost instances to receivers using QApplication.postEvent(receiver, event).\n

\n\n\n\n

$\"An$

Your task is to create a custom Qt event whenever the current CPU usage percent exceeds a threshold. The event should hold the CPU usage percent as the data.

To create custom Qt events:

\n\n\n

\n
Define a custom event class CpuUsageEvent that inherits from QEvent and carries the used CPU percent value. Use QEvent.registerEventType() to assign a unique type to the class.
\n
\n
Use a QTimer with an interval of 1000 ms to periodically poll the CPU usage percent with psutil.cpu_percent.
\n
\n
If the CPU percent exceeds the threshold, create and post a new event object to each receiver.
\n

Note that custom events do not automatically propagate up the widget hierarchy like mouse or key events.

\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎
https://doc.qt.io/qtforpython-6/↩︎

20. Timers

In programming, timers are used to measure time intervals and trigger actions or events after a speecified delay (single-shot) or at regular intervals. They enable task scheduling, such as updating GUI elements, or polling resources, without blocking the main execution flow.¹

In Qt, timers are integrated with the application’s event loop. They allow non-blocking time-based operations, ensuring responsive applications, ensuring responsive GUI applications. Qt provides several timer facilites:

\n
QObject.startTimer(): A low-level method on any QObject to start a timer with a millisecond interval.
\n
\n
QBasicTimer: A lightweight wrapper around a timer Id from startTimer()
\n
\n
QTimer: A high-level QObject subclass with millisecond precision (up to 24 days range) which emits a timeout() signal.
\n
\n
QChronoTimer: A drop-in replacement for QTimer but with nanosecond precision and larger ranges (up to 292 years).
\n

The following two timer classes do not integrate with the Qt event loop:

\n
QElapsedTimer: A stopwatch for measuring elapsed time.
\n
\n
QDeadlineTimer: Represents a deadline for timeouts in blocking functions.
\n

The one you will be using the most of the time is QTimer - here are its most important methods:

Here’s a table of QTimer’s most important methods:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Method	Description
`start(int msec)`	Starts or restarts the timer with a timeout of msec milliseconds
`start()`	Starts or restarts the timer with the timeout specified in `setInterval()`\n
`stop()`	Stops the timer
`setInterval(int msec)`	Sets the timeout interval in milliseconds
`interval()`	Returns the current interval in milliseconds
`isActive()`	Returns true if the timer is running, false otherwise
`setSingleShot(bool)`	Sets whether the timer fires only once (true) or repeatedly (false)
`isSingleShot()`	Returns true if the timer is single-shot
`timerId()`	Returns the timer’s ID, or -1 if the timer is not running
`remainingTime()`	Returns the remaining time in milliseconds before the timer times out
`setTimerType(Qt::TimerType)`	Sets the timer’s precision (Precise, Coarse, or VeryCoarse)
`timerType()`	Returns the timer’s type
`timeout`	Signal emitted when the timer times out
`singleShot(int msec, receiver, slot)`	Static method that creates a single-shot timer that calls a slot after msec milliseconds

20.1 Single-Shot

Qt’s single-shot timer is a feature of the QTimer class that allows developers to schedule a one-time event to occur after a specified delay,without the need for repeated intervals. It can be useful for tasks like delaying UI updates, handling asynchronous operations, or implementing timeouts in applications.

\n\n\n\n

$\"An$

You need to updata a label’s text one second after a button is clicked.

To do this:

\n\n\n

\n
Create QPushButton and QLabel instances, add them to the window layout, and connect the button’s clicked signal to a slot.
\n
\n
In the slot, call QTimer.singleShot(), passing a 1000ms delay interval and the on_single_shot() method to execute after the delay.
\n
\n
In on_single_shot(), get the current time and display it in the label. This executes with a one-second delay while keeping the GUI responsive.
\n

As singleSHot() is a class (static) method, you don’t create an instance of the QTimer class.

20.2 Starting and Stopping a Timer

Calling a timer’s start() method begins firing timeout() signals at specified intervals. Stopping a timer with stop() halts its operation, preventing further timeouts until it is restarted.

\n\n\n\n

$\"An$

You are given the task of creating a simple application that counts elapsed seconds, allowing the user to start and stop the tracking as needed.

To do this:

\n\n\n

\n
Create a Start timer and a Stop timer QPushButtons along with a QLabel that displays the current number of elapsed seconds. Keep the count in an instance field named counter initialized to 0.
\n
\n
Create a QTimer object and set its interval to 1000 milliseconds.
\n
\n
\n
When the Start timer button is clicked:
\n
\n
\n
- \nDisable the Start button and enable the Stop button,\n
- \nStart the timer.\n
\n
\n
\n
When the Stop timer button is clicked:
\n
\n
\n
- \nEnable the Start button and disable the Stop button,\n
- \nStop the timer.\n
\n
\n
\n
Each time the timer’s timeout signal is emitted, increment counter by one and update the label to show the new value.
\n

20.3 Adjusting a Timer Interval

\n\n\n\n

$\"An$

You need a timer that remains active through your application’s runtime, while allowing the user to adjust its interval without restarting the countdown.

\n\n\n

\n
Create the spinbox and timer. In the main window’s __init__(), create a QSpinBox with an initial value of 1000ms, a range of 200-2000 ms, and a step of 100ms. COnnect its valueChanged() signal to a slot for handling value changes. Then, create a QTimer, connect its timeout() signal to a slot, and start it with the initial interval.
\n
\n
When the user changes the spinbox value, store that value in the pending_interval instance variable.
\n
\n
On the timer’s timeout() signal, check if pending_interval is set. If it is, adjust the timer interval and reset pending_interval to None. Also perform your application timer-related tasks (in this case, update a label).
\n

The intermediate pending_interval variable is necessary to avoid restarting the timer’s current countdown cycle when the spinbox value changes. Calling setInterval() directly on a running QTimer stops and restarts it, resetting the countdown to the new interval from that moment, which could delay or advance the next timeout() signal. By using pending_interval, we defer the change until the start of the on_timeout() slot - after the current interval has completed - ensuring the new interval only applies to future cycles without interrupting the ongoing one.

20.4 Countdown Timer

Countdown timers are designed to count down from a specified time interval to zero, signaling the end of a period or event. They operate by decrementing the time at regular intervals, often in seconds, and can trigger actions like notifications or program executions upon reaching zero.

\n\n\n\n

$\"An$

You need to implement a simple countdown in your application.

\n\n\n

\n
Add a counter variable to your main class and set its initial value. Add a spinbox to let the user set the starting countdown value and a button to start the countdown. Also, create a QTimer and set its interval.
\n
\n
On the Start button click, set counter value, disable the Start button and the spinbox, and start the timer.
\n
\n
On the timer timeout(), decrement counter, update the label text, and if counter reaches zero, stop the timer and re-anable the button and the spinbox.
\n

This ensures the countdown runs uninterrupted by disabling controls during operation, providing a basic countdown mechanism.

20.5 Stopwatch

The previous example showed how to decrease a counter value at regular intervals, stopping the timer when the counter reaches zero. Conversely, you can also use a timer to increase a value periodically.

\n\n\n\n

$\"An$

Your task is to create a simple stopwatch application with one-hundredth of a second (100ms) resolution and ‘Start’, ‘Pause’ and ‘Reset’ functionality.

\n
Add an elapsed_time instance variable to the main window. This is a QTime object initialized to zero hours, minutes, seconds and milliseconds. QTime is convenient here because it provides addMSecs() for easy time increments.
\n
\n
\n
Create the buttons. When the aplication starts, the ‘Start’ button is enabled, the ‘Pause’ button is disabled and the ‘Reset’ button is always enabled (allowing reset at any time).
\n
\n
\n
- \nClicking ‘Start’ disables it, enables ‘Pause’ and starts the timer.\n
- \nClicking ‘Pause’ disables it, enables ‘Start’ and stops the timer.\n
\n
\n
\n
Create a QTimer, set its interval to 100 milliseconds, and connect its timeout() signal to a slot.
\n
\n
Update the time. In the on_timeout() slot, add the 100 ms to elapsed_time using addMSecs(), then update a label to display the current time in the format mm:ss.z (minutes:seconds.tenths).
\n

\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎

21. Properties

22. Model-View Programming with `QAbstractListModel`\n

This chapter introduces custom Qt models using QAbstractListModel through a series of simple demonstrations manipulating a list of company clients.

The Qt model-view architecture is Qt’s variant of the model-view-controller (MVC) design pattern where, per the documentation, the controller and view are combined. The model and view are decoupled, allowing the same model to be used with multiple views.

Qt provides several abstract classes you can subclass for custom models, such as:

\nQAbstractItemModel\n
\nQAbstractTableModel\n
\nQAbstractListModel\n

Qt also offers ready-to-use concrete models, including:

\nQStandardItemModel\n
\nQFileSystemModel\n
\nQSqlQueryModel\n

Earlier examples demonstrated some of these with Qt view classes. Here, we focus on creating custom models.

22.1 Read-only List Model

[TODO: QAbstractListModel inheritance tree]

Of the three abstract model classes above, QAbstractListModel is the easiest to subclass. It provides default implementations for several QAbstractItemModel methods and offers a specialized interface for simple, non-hierarchical sequences of items (lists).

Like other model classes, a QAbstractListModel subclass acts as an intermediary between a data source and a view:

[TODO: DATA-MODEL-VIEW DIAGRAM]

A data source can range from a simple Python list or structured text file, relational database data, and anything in between. The model’s role is to supply data in a format that a Qt view can read and display.

To create a read-only list model you must implement at least two methods:

\nrowCount(): Returns the number of rows in the model. (e.g., len(lst) for a Python list, line count for a file, or count(*) for a SQL query). The parent parameter is for hierarchical model and unused here.\n
\ndata(index, role): Returns the data for the given role and item referenced by the index. For list models, index is a QModelIndex object with column() as zero and row() indicating the position in the underlying data. The role is one of the Qt.ItemDataRole enumeration values(default: DisplayRole).\n

\n\n\n\n

$\"An$

You have a text file listing company clients (‘data.txt’) and you need to display them in a list view.

To achieve this:

\n\n\n

\n
Subclass QAbstractListModel and provide access to the data source. Here, read the text file entirely in __init__() and store lines in a Python list (txt_data), where each element is a single string (a client’s name and profession). For other types of data sources you can retrieve data dynamically instead.
\n
\n
Implement rowCount(). View classes call this method to determine the model’s length. Here, return len(self.txt_data). Qt list models default to one column.
\n
\n
Implement data(). This returns model data for a given index and role. Use index.row() to access txt_data. Return data only for DisplayRole (the text for display); return None otherwise.
\n
\n
Optionally, implement headerData() for row or column headers. Here, the single column header is ‘Clients’. QListView does not display headers but QTableView would.
\n

\n
\n
QModelIndex:
\n
\n
\n
This class helps views locate model items. Qt models are table-based - think of the model in this example as a one-column table with n rows. Use row() and column() to reference cells.
\n
\n

\n
\n
QAbstractItemModelTester
\n
\n
\n
This class aids model development. Pass your model instance to its constructor - it logs implementation errors to the console, helping catch issues early.
\n
\n

This demo is read-only; next sections cover editable and resizable models.

22.2 Editable List Model

As shown in the read-only list model example, creating a basic list model requires implementing at least rowCount() and data(). To make it editable, add two more methods:

\nsetData(index, value, role): Sets the data for the given role (typically EditRole) and index, and returns True if successful; otherwise returns False. If set successfully, emit the dataChanged() signal.\n
\nflags(index): Returns the item flags for the index. The base implementation enables and selects items. To allow editing, add Qt.ItemFlags.ItemIsEditable.\n

\n\n\n\n

$\"An$

You have implemented a read-only model of a company clients backed by a text file (‘data.txt’) and you need to make it editable.

To create an editable list model:

\n\n\n

\n
Create a QAbstractListModel subclass and the access to the data source.
\n
\n
Implement the rowCount() and data() methods just as you did for the read-only model.
\n
\n
Implement the setData() method. setData() accepts three arguments: index, value and role. In the method we check if the role is equal to Qt.ItemDataRole.EditRole and, if it is, we set the model data for the index.row() to value using self.txt_data[index.row()] = value. If the data is set successfully we emit the dataChanged signal and the method returns True. Otherwise it returns False.
\n
\n
Implement the flags() method. In this method we signal to views that the model data is editable by adding Qt.ItemFlags.ItemIsEditable to the flags. Note that we can make the model items editable selectively by using the index parameter. In the example we ignore index which means that all the model items are editable.
\n

\n\n\n

Now if you double-click any of the list view lines you are able to edit it and the changes are saved in the model (ie. to the TxtFileModel.txt_data list and signaled by the dataChanged signal. You can also implement the logic to update the text file from the txt_data values which we omit in this example.

\n\n

The QDataWidgetMapper class lets you map a data model row (or column) to a set of widgets, making them data-aware. When the model’s current index changes, mapped widgets are updated with data from the model. This is useful for creating forms enhancing user experience in viewing and editing data.

\n\n\n\n

$\"An$

You have an editable model of a list of company clients. Editing is enabled by double-clicking a client row in the list view. Your task is to make editing more user-friendly.

\n\n\n

\nCreate a QAbstractListModel subclass to represent your model. Then, in the main window class:\n

\n\n\n

\n
Create your model object and the widgets for displaying and editing your model data.
\n
\n
Create the mapper object and use QDataWidgetMapper.setModel() to connect your model to it.
\n
\n
Use QDataWidgetMapper.addMapping() to map your model columns with the widgets. The example model has only one column, which we map to a QLineEdit widget.
\n
\n
Synchronize the view’s current item with the model’s current index so both update when the user changes the view’s selection.
\n

In the example, we use manual submit policy, updating the model via a ’Submit` button. This syncs the line edit with the current view item, allowing easy updates by editing the line edit value and clicking ‘Submit’.

22.4 Resizable List Model

For a basic QAbstractListModel subclass, you need to implement at least two methods: rowCount() and data(). To make the model editable, you need to implement two more: setData() and flags(). To be able to add or remove rows, you need to implement insertRows() and removeRows().

\n\n\n\n

$\"An$

You have an editable model of a list of company clients. You need to enable the user to insert or remove clients from it.

To make a resizable QAbstractListModel subclass:

\n\n\n

\n
Create a subclass of the QAbstractListModel class. As in previous examples, read the data from a text file and store it in a Python list named self.txt_data.
\n
\n
Implement the insertRows() method. For simplicity, the example inserts rows filled with template text (“<insert row data>”). Guard the data insertion with beginInsertRows() (to signal connected views that rows are about to be inserted) and endInsertRows(). This pair of methods ensures that views remain in a valid state. beginInsertRows() takes three arguments: parent (an invalid QModelIndex() in our case), first (the starting row number post-insertion) and last (the ending row number post-insertion). The method returns True on success or False otherwise.
\n
\n
Implement the removeRows() method. This removes rows from the self.txt_data, enclosed by beginRemoveRows() and endRemoveRows(), and returns True on success or False otherwise.
\n

Then, in your main class

\n\n\n

\nCreate three QPushButtons: insert_button, append_button and remove_button. Handle the insert button’s clicked() signal with a slot named on_insert() calling insertRow() to insert a single row by invoking insertRows(). Similarly, handle the append button’s clicked() signal with on_append() to insert a row at the end.\n

23. Model-View Programming with `QAbstractTableModel`\n

QAbstractTableModel enables you to display and edit tabular data in Qt applications.

List models organize the data as a one-dimenzional sequence of items, where each row represents a single, atomic element. In contrast, table models structure data in a two-dimensional grid, where each row represents a composite record or entity, and the columns within it hold individual fields or attributes.

In the previous chapter we used a simple text file as the data source: each file row was a single element representing a fictional company client. Here, we use a comma-separated (CSV) file where each row has four fields: client id, first name, last name, and profession. We follow the same progression as in the previous chapter:

\nread-only model\n
\neditable model\n
\ndata mapping\n
\nresizable model\n

but focusing on columnar aspects.

23.1 Basic Read-Only Table Model

\n\n\n\n

$\"An$

You need to show data from a CSV file (data.csv) in a table view. The file contains company clients data, each row containing client id, first name, last name and profession. You decide to implement a QAbstractTableModel subclass using the CSV file as the data source.

To create a read-only table model:

\n\n\n

\n
Create a subclass of QAbstractTableModel named CsvModel and make external data available to it. We read the data from data.csv using Python’s csv reader and store it in a member variable named self.csv_data. csv_data is a list and csv reader’s rows are also lists which effectively makes csv_data a two-dimensional list suitable for use with QAbstractTableModel subclasses.
\n
\n
Implement the rowCount() and the columnCount() methods. rowCount() is the length of the self.csv_data list and never changes since the model is read-only. columnCount() is hard-coded to return 4, the number of columns in the CSV file.
\n
\n
Implement the data() method. data() expects two arguments: index, a QModelIndex instance and role, a member of the DisplayRole enumeration. In the method body we check if role is equal to DisplayRole and if it is we return the data that the index points to. Note that we need to use both index.row() and index.column() as the data has two dimensions. With this you have a functional QAbstracttableModel subclass.
\n

\n\n\n

\nIn your main class (Window), create a CsvModel object, create a QTableView object and set its model using QTableView()setModel()\n

QAbstractTableModel subclasses are commonly used with QTableView but not necessarily so. QTableView is able to display table headers using the header data you provide to it in the model headerData() method but implementing headerData() is still not mandatory.

23.2 Making the Table Model Editable

Just as for a list model, to make a table model editable you need to implement its setData() method and modify its flags() method to return the itemIsEditable flag for each item.

\n\n\n\n

$\"An$

You need to make your CSV file-backed model, that contains company clients data, editable.

To make a table model editable:

\n\n\n

\n
Create a QAbstractTableModel subclass.
\n
\n
Implement the rowCount(), columnCount() and data() methods. The implementation is the same as in the read-only model example.
\n
\n
\n
Implement the setData() method. setData() accepts three arguments:
\n
\n
\n
- \nindex, a QModelIndex object that you will use to get the coordinates of the data point to be changed,\n
- \nvalue which is the new data value and\n
- \nrole, one of the Qt.ItemDataRole enumeration members, in most cases EditRole.\n
\n
\n
\n
In the method body check if role is equal to EditRole, check if the new data is actually different from the current data, change the data and emit the dataChanged() signal.
\n
\n
\n
Implement the flags() method. In this method you return the item flags given its index. In the example all items (ie. fields) are flagged as selectable, enabled and editable. This does not have to be the case. For instance, if you had a model based on a SQL table you would flag the primary key fields as selectable only, making only the primary keys read-only.
\n

\n\n\n

\nThen, in the main class, create a model instance, create a QTableView instance and use QTableView.setModel() to connect the two.\n

\n\n

We have already seen how to use a data-widget mapper in the previous chapter where we mapped a single line edit to a list model row. Here, we expand the example to map several widgets to a table model cells.

\n\n\n\n

$\"An$

You add a form to the GUI to make editing your CSV file-backed model user-friendly.

To use a data-widget mapper with a table model:

\n\n\n

\n
Create the model class. It is the same editable table model as in the previous section.
\n
\n
Create the widgets. Each column in our tabele model (first name, last name and occupation) contains string data so we create three line edits, one for each column. We also add a Submit button to let the user submit changes to the current table row and add all widgets to a form layout.
\n
\n
Create a data-widget mapper object and add the widgets to it. Create a QDataWidgetMapper object and set the CsvModel as its model. Map each line edit to a CsvModel column using addMapping() and synchronize the data in the mapper widgets with the table view currently selected row.
\n

Now, when the user changes the data in the data-widget mapper widgets and presses the Submit button, the model is updated and the changes are propagated to the view.

23.4 Resizable Table Model

Just as with a list model, to make a table model resizable you need to implement two methods:

\ninsertRows()\n
\nremoveRows()\n

\n\n\n\n

$\"An$

You need to let the users append, insert, and remove rows from your CSV file-backed model.

To create a resizable table model:

\n\n\n

\n
\nCreate the model. Create a subclass of QAbstractTableModel and store the CSV data in the self.csv_data instance field. You already implemented rowCount(), columnCount() and data() for your read-only model; and setData() and flags() to make it editable. To make the model resizable:\n
\n
\n
- \nimplement insertRows(): check if row is within acceptable range, and insert and empty row in self.csv_data, guarding the insertion with beginInsertRows() and endInsertRows() calls. Return true on success, and false otherwise.\n
- \nimplement removeRows(). The line self.csv_data[row:row + 1] = [] removes the single element at index row from the list by assigning an empty list to that one-element slice, also guarder with beginRemoveRows() and endRemoveRows(). Return true on success, and false otherwise.\n
\n
\n

Then, in the main window:

\n\n\n

\n
Create the model and view objects. Create a CsvModel object, initializing it with the file that contains the client data; Create a QTableView object and set the CSV model as its model.
\n
\n
\n
Add the Insert, Append, and Remove buttons:
\n
\n
\n
- \nWhen the Insert button is pressed, get the view current index row and call insertRows() with it to insert and empty row above the current row.\n
- \nWhen the Append button is pressed, get the next available row number and call insertRows() with it to append an empty row to the model.\n
- \nWhen the Remove row is pressed, get the current view index and and call removeRows() with its row to remove the current row from the model.\n
\n
\n
\n
Note that both in insertRows() and removeRows() we cheat a bit and assume that only one row can be inserted or removed at a time. To allow for multiple rows insertion and deletion, you need to adjust the range passed to beginInsertRows() and beginRemoveRows() and update the insert and remove logic.
\n
\n
\n
Also note that insertRows() does not let you pass initial data to it and that we just insert empty strings as the data. If you need to insert some initial data, use setData() after the insertion completes or extend the model with a custom method (e.g. insertRowsWithData()) that accepts data parameters and calls the standard insertRows() internally.
\n
\n
\n
Lastly, the documentation mentions that you can provide your own API for altering or removing the data as long as you call beginInsertRow() or beginRemoveRows() to notify other components that the model has changed.
\n
\n

24. Model-View Programming with `QAbstractItemModel`\n

25. Model-View Programming - Delegates

26. Model-View Programming - Sorting, Filtering and Selection

27. Multithreading - `moveToThread`\n

Threads of execution let you execute your code concurrently while sharing the program memory and other resources. There are primary two use cases for threads:

\nAccelerate processing by utilizing multiple processor cores,\n
\nMaintain GUI responsiveness by offoading long-running tasks to background threads.\n

In the following examples, we focus on the second use case. First, however,let’s demonstrate the issue by showing a non-responsive Qt GUI.

27.1 Blocking the Qt GUI: How Not to Do It

\n\n\n\n

$\"An$

You need to search the filesystem for a file and report progress.

\n\n\n

\n
Create the task. In the example, we use os.walk() within a for loop to search the file system for a non-existent file. We attempt to report progress after each iteration using a custom Qt signal named progress. This fails because the loop blocks the Qt event loop, preventing the signals from being emitted or events from being processed until the loop completes. Since the loop runs in the main application thread (also known as the GUI thread), the entire application becomes unresponsive - it freezes and you cannot even close it.
\n
\n
Create a push button.
\n
\n
Create a slot that starts the long-running task when the push button is clicked.
\n

27.2 A Minimal Working Example

The previous example illustrates how a PySide6 GUI can become unresponsive. Now let’s explore using Qt threads to run long tasks in the background while keeping the GUI responsive.

\n\n\n\n

$\"An$

You need to create a minimal working Qt multithreading application.

\n\n\n

\nCreate a QObject subclass containing the slot/method to execute in a background thread (i.e., a thread other than the GUI thread). In the example, the slot is named process(); it prints a message and emits a custom signal named finished() before returning. The Worker class declares an error() signal, which could be emitted under error conditions during process() execution.\n

\n\n\n

Then, in the main window class:

\n
Create a QThread object named background_thread (avoid naming it thread, as that name is already used). Use self to make it the member of the main window, ensuring it remains in scope while running.
\n
\n
Create a Worker object and move it to background_thread using QObject.moveToThread(). Now, Worker.process() will execute in background_thread.
\n
\n
\n
Connect the appropriate signals and slots:
\n
\n
\n
- \nConnect background_thread.started() to worker.process(). This executes Worker.process() when the background thread starts.\n
- \nConnect Worker.finished() to background_thread.quit(). This quits the background thread when Worker.process() returns.\n
- \nConnect Worker.finished() to Worker.deleteLater() method. This deletes the worker object some time after it emits finished().\n
- \nConnect background_thread.finished() to background_thread.deleteLater(). This deletes the background thread some time after it finishes.\n
\n
\n
\n
Start background_thread using QThread.start().
\n

With these steps, process() runs upon thread start, the thread quits when the method returns, and both the worker and thread object are destroyed - all while keeping the GUI responsive.

27.3 Walking the Filesystem

The moveToThread() template provides a basic structure, but the worker does nothing but print a message. For a more practical example, let’s have Worker.process() traverse the filesystem using os.walk() from the root. This operation can be time-consuming and would block the GUI if run on the main thread.

\n\n\n\n

$\"An$

You need to use Qt multithreading to search the filesystem for a file and report progress.

\n\n\n

\nCreate the worker class. The method, process() uses Python’s os.walk() to traverse the filesystem. For each enumerated filesystem object, we emit a custom progress signal (added to Worker alongside finished and error). If the background thread receives an interruption request, we return from process(), triggering the signal-slot chain to stop and delete both the worker and the background thread. Note how in Worker.process(), we access the current (background) thread via the static QThread.currentThread() method.\n

\n\n\n

\n
In the main window class, create the thread object.
\n
\n
Create a Worker object and move it to the QThread using QObject.moveToThread().
\n
\n
Use signals and slots to ensure proper creation and deletion: Starting the background thread triggers Worker.process(); QObject.finished() triggers both QThread.quit() and Worker.deleteLater(); QThread.finished() triggers QThread.deleteLater().
\n
\n
Start the background thread. This occurs in Window.on_start_button_clicked() creating new QThread and Worker objects each time the start button is clicked.
\n

We override QWidget.closeEvent() to interrupt the background thread, ensuring cleanup if the main window closes while the thread runs. The sequence, QThread.requestInterruption() + QThread.quit() + QThread.wait(), is also used in Window.on_cancel_button_clicked() for clean interruption.

27.4 Reusing the `QThread` object

In the prior examples a new background thread is created each time the task runs. However, the official QThread documentation example creates both thread and worker in the main class constructor. Let’s try to replicate that.

\n\n\n\n

$\"An$

Your task is to recreate the official Qt multithreading example in PySide6.

\n\n\n

\nCreate the worker class. The background method is do_work(), matching the QThread documentation.\n

\n\n\n

Then, in the main window class:

\n
Create the worker thread.
\n
\n
Create the Worker object and move it to the the worker thread using QObject.moveToThread().
\n
\n
Connect signals and slots: QThread.finished() to QObject.deleteLater() for worker deletion on thread finish; Controller.operate() to Worker.do_work() to start work via custom signal; Worker.result_ready() to Controller.handle_result() for handling results.
\n
\n
Start the worker thread. Steps 2-5 occur in Controller.__init__(), so the thread and the worker persist until the main window closes or explicit deletion.
\n
\n
On button click, emit the operate() signal to execute Worker.do_work().
\n
\n
Override QWidget.closeEvent() to quit the thread using QThread.quit() and QThread.wait().
\n

27.5 Walking the Filesystem reusing the `QThread` Object

\n\n\n\n

$\"An$

You need to use Qt multithreading to walk the filesistem but you reuse the same worker thread.

\n\n\n

\nCreate the worker class. There are several differences from the first walk filesystem example: We use a boolean flag Worker.interruption_requested instead of QThread.isInterruptionRequested(); add Worker.stop() and Worker.reset() to toggle the flag; guard each use with QMutexLOcker and QMutex for thread safety.\n

\n\n\n

\n
In Controller.__init__() create the worker thread object.
\n
\n
Create the worker object and move it to the worker thread using QObject.moveToThread().
\n
\n
Connect signals and slots. Main class operate() signal triggers Worker.do_work().
\n
\n
Start the worker thread.
\n
\n
On start button click, reset the worker with Worker.reset() and emit operate().
\n
\n
On cancel button click, stop the worker with Worker.stop().
\n
\n
Quit the thread on main window close.
\n

But why did we use a mutex-guarded boolean flag? QThread.requestInterruption() is one-time: once requested, QThread.isInterruptionRequested() stays True and it cannot be reset. A signal to toggle a flag would require QApplication.processEvents() in the blocking loop. DIrect flag setting is unsafe across threads, so QMutex and QMutexLocker are used.

27.6 Signals and Slots Across Threads

\n\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Connection Type	Emitter Thread	Receiver Thread	Slot Invoked	Slot Executed In	Unique
Auto	A	A	immediately when the signal is emitted	A	No
Auto	A	B	when control returns to the event loop of the receiver’s thread	B	No
Direct	A	B	immediately when the signal is emitted	A	No
Queued	A	B	when control returns to the event loop of the receiver’s thread	B	No
Blocking Queued	A	B	when control returns to the event loop of the receiver’s thread	B	No
Unique	A	A	immediately when the signal is emitted	A	Yes
Unique	A	B	when control returns to the event loop of the receiver’s thread	B	Yes

28. Using a `QThread` subclass

Perhaps the most important thing to remember about QThread is that a QThread object does not represent an operating system thread - it is a thread manager. In practice, this means only the QThread.run() method executes in the new thread. All other QThread methods run in the thread that created the QThread object.

Another point when subclassing QThread is that a QThread subclass does not start its event loop unless you explicitly call QThread.exec() in your QThread.run() implementation.

28.1 A Minimal Example

There are two ways to use QThread to run a background task:

\nCreate a worker object and move it to a background thread using QObject.moveToThread().\n
\nCreate a QThread subclass and override its run() method.\n

The examples from the previous chapter used QObject.moveToThread(). Now let’s examine a minimal QThread subclass.

\n\n\n\n

$\"An$

You need to provide a working multithreading application by subclassing QThread.

\n\n\n

\nCreate a QThread subclass (named WorkerThread in the example) and override its run() method. Add custom signals to the subclass and emit them from run() to communicate with the main thread.\n

\n\n\n

\n
In your main window class, create a WorkerThread instance.
\n
\n
Connect the WorkerThread signals to main window slots. Also connect WorkerThread.finished() to WorkerThread.deleteLater() for clean thread exit.
\n
\n
Create slots in the main window to handle WorkerThread signals. Here, we set a QLabels text to “Hello, World” on WorkerThread.result_ready().
\n
\n
Start the worker thread.
\n

When creating a plain QThread object (as in moveToThread() examples) the sequence is:

\nCall QThread.start() from the main thread.\n
\nThe background QThread emits started().\n
\nQThread.start() invokes QThread.run().\n
\nQThread.run() calls QThread.exec().\n
\nQThread.exec() enters the thread-local event loop, waiting for QThread.exit() or QThread.quit().\n
\nCall QThread.exit() or QThread.quit() to stop.\n
\nThe event loop stops, emitting QThread.finished()\n
\nQObjects with QObject.deleteLater() are deleted.\n

(Remember that in moveToThread() examples, we connected QThread.started() to a worker slot for immediate execution; and worker finished() to QThread.quit() for thread completion.)

When subclassing QThread, no local event loop unless QThread.exec() is called in run(). Without it, classes that need an event loop (e.g., QTimer, QTcpSocket, QProcess) won’t work. However, the thread object will still be able to emit signals.

In this example, Window.start_work_in_a_thread() runs in the main thread (QThread.loopLevel() = 1, event loop active). WorkerThread.__init__() also runs in the main thread, while only WorkerThread.run() executes in the worker thread (QThread.loopLevel() = 0, no event loop).

28.2 Walking the Filesystem

\n\n\n\n

$\"An$

Now let’s walk the filesystem using a QThread subclass.

\n\n\n

\nCreate a QThread subclass named WorkerThread and override run(). In run(), print the current thread object name to confirm execution in the worker thread, then use os.walk() for recursive traversal. Emit progress() with each object’s name as the argument.\n

\n\n\n

\n
On start button click, create a WorkerThread object and set its name to “Worker thread”.
\n
\n
Connect signals to slots: WorkerThread.progress() to Window.on_progress() for label updates; WorkerThread.finished() to WorkerThread.deleteLater() for cleanup.
\n
\n
Handle signals. On progress() update the label; On cancel request interruption with QThread.requestInterruption() and wait for finish.
\n
\n
Start the worker thread on each start button click.
\n

Override Qwidget.closeEvent() to ensure thread deletion on window close. Note that we didn’t need to call QThread.quit() but only QThread.wait() since no event loop runs.

29. Multithreading with `QThreadPool` and `QRunnable`\n

The QThreadPool class manages a collection of QThreads and is used with the QRunnable class.

29.1 A Minimal Example

\n\n\n\n

$\"An$

You need to provide a working multithreading application using QThreadPool with QRunnable.

\n\n\n

\nCreate a QRunnable subclass and implement its run() method with the code to execute in a background thread. QRunnable is not a QObject subclass, so it cannot have signals directly. You can easily work around this by creating a separate QObject subclass (named Signals here) and adding an instance to your QRunnable. In this example, run() emits Signals.progress and prints a message.\n

\n\n\n

\n
In the main window, create a Runnable instance.
\n
\n
Use QThreadPool.globalInstance() to access the global thread pool and QThreadPool.start() to execute Runnable.run() in one of its threads.
\n

29.2 Walking the Filesystem

\n\n\n\n

$\"An$

Your task is to walk the filesystem using QThreadPool and QRunnable.

\n\n\n

\nCreate a QRunnable subclass and implement run(). Add a member for signals and a boolean flag do_work for interruption. run() uses os.walk() to enumerate filesystem objects, emitting progress() for each while do_work is True.\n

\n\n\n

\n
In the main window class, add a custom cancel_runnable() signal. Connect it to Runnable.on_cancel_emitted(), which sets Runnable.do_work to False.
\n
\n
In on_start_button_clicked() create a Runnable object and connects signals to slots: progress updates the label; on cancel, emit cancel_runnable() to set do_work False.
\n
\n
Access the global thread pool and run the task with QThreadPool.start().
\n

30. Thread Synchronization

There are cases where executing a piece of code in a separate thread is desirable (or unavoidable) but it inevitably makes the program flow more complex and presents the programmer with a set of challenges, one of which is thread synchronization. In this chapter, we demonstrate why thread synchronization may be necessary and present the Qt tools for synchronizing threads.

30.1 Race Condition Demo

\n\n\n\n

$\"An$

You are working on a banking application that lets users withdraw money from their bank account. This takes place over a network so you decide to make withdrawals in a background thread to avoid blocking the GUI thread.

In your application you:

\n\n\n

\nCreate a class named BankAccount to hold the user account balance, and add two methods, get_balance to return the current balance, and withdraw to let the user withraw the specified amount of money from the account. In the demonstration we use QThread.msleep() to simulate network lag.\n

\n\n\n

\nCreate the Worker class. We will move this class to a background thread and call its process() method to process the user request.\n

\n\n\n

\nIn the main application class we simulate a situation where five users simultaneously withdraw money from a joint bank account. Each user withdraws 100 monetary units from the account. We initialize the bank account with (thread_count * amount) monetary units so that the expected final balance is zero. On the “Withdraw money” button click, we start five background threads and five worker objects, and we move each worker to its own thread. The money is withdrawn as soon as each background thread starts. The single BankAccount object also lives in its own separate thread.\n

A sample output could be:

 1 ---withdraw start--- Thread 0\n 2 ---withdraw start--- Thread 1\n 3 ---withdraw start--- Thread 4\n 4 ---withdraw start--- Thread 2\n 5 ---withdraw start--- Thread 3\n 6 ---withdraw end--- Thread 2 400\n 7 ---withdraw end--- Thread 3 400\n 8 ---withdraw end--- Thread 4 400\n 9 ---withdraw end--- Thread 1 400\n10 ---withdraw end--- Thread 0 400\n11 Expected: 0, Got: 400\n12 =====================\n

\n\n

We expect the final balance to be zero but we end up with 400 monetary units in the account left.

From the output, you can see that all five worker objects manipulate BankAccount.balance at the same time. At the very beginning of BankAccount.withdraw() we assign self.balance to a local variable

1 balance = self.balance\n

\n\n

All five threads reach that line of code before any of them had a chance to subtract the amount from the balance

1 ---withdraw start--- Thread 0\n2 ---withdraw start--- Thread 1\n3 ---withdraw start--- Thread 4\n4 ---withdraw start--- Thread 2\n5 ---withdraw start--- Thread 3\n

\n\n

So for each worker, balance equals to 500. When each worker subtracts the amount from the balance:

1 balance -= amount\n2 self.balance = balance\n

\n\n

the final balance value ends up being 400. The above code snippet is not an atomic operation and the threads are not synchronized.

In such a situation, the developer needs a way to synchronize thread execution, i.e., to only let a single thread withdraw money at any given time. Qt provides several means to achieve this.

30.2 Queued Signal-Slot Connection

One benefit of Qt’s signals and slots mechanism is that queued connections are thread-safe for cross-thread communication. The slot is invoked when control returns to the event loop of the receiver object’s thread. Internally, Qt posts a QMetaCallEvent (event of type QEvent.MetaCall) to the receiver’s event queue, ensuring that slot invocations for that object are serialized.

\n\n\n\n

$\"An$

You are developing a multithreaded banking application that enables users to withdraw money from their bank accounts. To avoid race conditions when accessing the account balance, you decide to take advantage of Qt’s signals and slots mechanism for thread-safe communication.

\n\n\n

\nCreate the Worker class. This worker version has two signals, requestUpdate(int) which requests that the BankAccount update the balance, and transactionProcessed() which signals that the transaction is processed. We connect Worker.requestUpdate() to BankAccount.withdraw()\n

1 self.requestUpdate.connect(self.bank_account.withdraw)\n

\n\n

Both the worker and the bank account live in their own threads, so the connection type defaults to Qt.QueuedConnection. This means that:

\nWorker.requestUpdate() will be placed in the bank account thread event loop.\n
\nBankAccount.withdraw() will be executed in the bank account thread.\n
\nBankAccount.withdraw() will block the bank account thread until it returns.\n

This ensures that BankAccount.withdraw() is accessed by one thread at a time and the race condition is avoided.

\n\n\n

\nCreate the BankAccount class. It is mostly unchanged except that we add a signal named balanceSent() to it. The signal will be used to send the final balance to the GUI thread.\n

\n\n\n

\nAdd the requestBalance() signal to the main window. When all worker threads are finished, the main windows sends this signal to the bank account thread, which in turn responds with the balanceSent() signal. The output is:\n

 1 ---withdraw start--- Bank account thread\n 2 ---withdraw end--- Bank account thread\n 3 ---withdraw start--- Bank account thread\n 4 ---withdraw end--- Bank account thread\n 5 ---withdraw start--- Bank account thread\n 6 ---withdraw end--- Bank account thread\n 7 ---withdraw start--- Bank account thread\n 8 ---withdraw end--- Bank account thread\n 9 ---withdraw start--- Bank account thread\n10 ---withdraw end--- Bank account thread\n11 Expected: 0, Got: 0\n

\n\n

Access to BankAccount.balance is synchronized. Note that neither the worker objects nor the main window object access BankAccount.balance directly - all communication takes place using signals and slots. Also note that all withdraw() calls are executed in the bank account thread.

30.3 `QMutex`\n

A mutex is a synchronization tool that prevents multiple threads from accessing the same shared resource - object, data structure or section of code - simultaneously. When one thread acquires a mutex, any other thread trying to access that same resource will be blocked and forced to wait until the first thread releases it. This prevents race conditions where concurrent access could corrupt data or cause unpredictable behavior in your program¹.

In Qt, the mutex lock applies to the scope between QMutex.lock() and QMutex.unlock(). Any code inside, including function/method calls, runs under the protection of the lock. No other thread can enter the protected section until unlock() is called².

\n\n\n\n

$\"An$

You are working on a multithreaded banking application that allows users to withdraw money from their accounts. Use a mutex to prevent race conditions on the bank account balance.

To use QMutex in your application:

\n\n\n

\nCreate the worker class. The class is similar to the worker from the race condition demo, except we don’t need to send the transactionProcessed() and requestUpdate() signals.\n

\n\n\n

\nCreate the BankAccount class. In its withdraw() method, guard the code that updates the account balance with the lock() and unlock() calls.\n

\n\n\n

When you start the application and withdraw money, the output is:

 1 ---withdraw start--- Thread 0\n 2 ---withdraw end--- Thread 0 400\n 3 ---withdraw start--- Thread 1\n 4 ---withdraw end--- Thread 1 300\n 5 ---withdraw start--- Thread 3\n 6 ---withdraw end--- Thread 3 200\n 7 ---withdraw start--- Thread 2\n 8 ---withdraw end--- Thread 2 100\n 9 ---withdraw start--- Thread 4\n10 ---withdraw end--- Thread 4 0\n11 Expected: 0, Got: 0\n12 =====================\n

\n\n

withdraw() calls are serialized and each is executed in the caller thread.

30.4 `QMutexLocker`\n

QMutexLocker³ is a convenience class that simplifies using mutexes. QMutexLocker is created within a method where a QMutex needs to be locked - the mutex is locked when mutex locker is created and unlocked when the mutex locker is destroyed.

\n\n\n\n

$\"An$

You use a mutex to prevent race conditions in your multithreaded banking application. You decide to use QMutexLocker to avoid locking and unlocking the mutex manually.

To use a QMutexLocker in your application:

\n\n\n

\n
In the BankAccount class add a mutex instance variable.
\n
\n
In the withdraw() method, create a QMutexLocker local variable just before the code that updates the balance. When withdraw() returns the variable goes out of scope, unlocking the mutex.
\n

QMutexLocker is an example of the RAII idiom in C++, ensuring that a mutex is automatically unlocked when the locker goes out of scope - just as Python’s context managers guarantee automatic resource release upon exiting a with block of code.

30.5 `QSemaphore`\n

A semaphore is a synchronization primitive used in concurrent programming to control access to a shared resource with a limited number of units. It keeps the count of available units, allowing threads to acquire (decrement) the count when using the resource and release (increment) it when done⁴. In Qt, the QSemaphore class provides a general counting semaphore.

\n\n\n\n

$\"An$

You are developing a multithreaded banking application where multiple customers attempt to withdraw money using ATMs at the same location. Due to provider restrictions, the location has a limited number of internet connections available. To ensure that customers can only perform withdrawals when a connection is available, you decide to use a QSemaphore to manage the shared pool of ATM network connections.

To use QSemaphore in your application:

\n\n\n

\n
Create the class that represents the shared resource, AtmPool in the example. Initialize a QSemaphore with the number of available resources (e.g., 5 connections).
\n
\n
In the AtmPool class, add a use_atm() slot that acquires the semaphore before using the resource (simulating a withdrawal with a random sleep), and releases it in a finally block to ensure it’s always freed.
\n

\n\n\n

\nCreate the Worker class, which calls use_atm() in its process() method to simulate a customer using an ATM.\nIn the main window class, create the AtmPool object and move it to its own thread. Then, create 15 worker threads (more than available resources) to demonstrate queuing. Each worker signals when finished.\n

\n\n\n

When you run the application and click “Withdraw Money, the output is:

 1 Thread 0 is using an ATM (available: 4)\n 2 Thread 2 is using an ATM (available: 3)\n 3 Thread 3 is using an ATM (available: 2)\n 4 Thread 6 is using an ATM (available: 0)\n 5 Thread 1 is using an ATM (available: 1)\n 6 Thread 2 done. (available before release: 0\n 7 Thread 7 is using an ATM (available: 0)\n 8 Thread 6 done. (available before release: 0\n 9 Thread 9 is using an ATM (available: 0)\n10 Thread 7 done. (available before release: 0\n11 Thread 4 is using an ATM (available: 0)\n12 Thread 3 done. (available before release: 0\n13 Thread 10 is using an ATM (available: 0)\n14 Thread 0 done. (available before release: 0\n15 Thread 13 is using an ATM (available: 0)\n16 Thread 1 done. (available before release: 0\n17 Thread 5 is using an ATM (available: 0)\n18 Thread 9 done. (available before release: 0\n19 Thread 11 is using an ATM (available: 0)\n20 Thread 13 done. (available before release: 0\n21 Thread 8 is using an ATM (available: 0)\n22 Thread 8 done. (available before release: 0\n23 Thread 4 done. (available before release: 0\n24 Thread 10 done. (available before release: 0\n25 Thread 14 is using an ATM (available: 0)\n26 Thread 12 is using an ATM (available: 0)\n27 Thread 5 done. (available before release: 1\n28 Thread 11 done. (available before release: 1\n29 Thread 14 done. (available before release: 3\n30 Thread 12 done. (available before release: 4\n

\n\n

The semaphore limits concurrent access to the shared connections while allowing serialization of extra requests.

30.6 `QSemaphoreReleaser`\n

QSemaphoreReleaser⁵ is a convenience class that simplifies semaphore usage with RAII-style automatic release. It acquires the semaphore separately but ensures release when the releaser object is destroyed (e.g., goes out of scope), similar to QMutexLocker for mutexes. This helps prevent leaks if exceptions occur during resource usage.

\n\n\n\n

$\"An$

In your multithreaded banking application, you decide to use QSemaphoreReleaser to automatically handle releasing the semaphore without manual calls in a finally block.

To use QSemaphoreReleaser in your application:

\n\n\n

\n
In the AtmPool class, modify the use_atm method: Call acquire() first, then create a QSemaphoreReleaser(self.semaphore) immediately after. The releaser will automatically call release() when it goes out of scope at the end of the method.
\n
\n
The rest of the code remains the same as in the basic semaphore example.
\n

This approach makes the code cleaner and exception-safe, ensuring the semaphore is always released even if an error occurs during the withdrawal.

30.7 `QWaitCondition`\n

\n\n

If you don’t implement __init__() in your class at all, the parent class gets initalized automatically.↩︎
https://doc.qt.io/qtforpython-6/↩︎
https://doc.qt.io/↩︎
https://doc.qt.io/qt-6/qobject.html↩︎
https://doc.qt.io/qt-6/qcolordialog.html↩︎

31 More Timers

32. Signals & Slots Connection Types

32.1 Direct Connection

\n\n\n

With Qt.DirectConnection the slot is invoked immediately when the signal is emitted. In the example we create a custom signal named custom_signal. We also create three slots, on_custom_signal_1, on_custom_signal_2 and on_custom_signal_3 and connect the signal with all three slots. We add a button to the main window and emit custom_signal when it is clicked.

The output is

1 on_button_clicked: Emitting custom signal\n2 \n3 First custom slot executed\n4 Second custom slot executed\n5 Third custom slot executed\n6 \n7 on_button_clicked: Returning\n

\n\n

From the output we see that when we emit the signal in on_button_clicked the three slots are called sequentially and, only after on_custom_signal_3 completes and returns, on_button_clicked continues execution. The code execution is synchronous.

When establishing the connections we didn’t pass the optional type to the Signal.connect() method. type defaults to Qt.AutoConnection and since both the signal and the slots live in the main thread the connection becomes Qt.DirectConnection.

There is one more thing to note: The slot execution bypasses the Qt event loop. We reimplement Window.event() to print a message but it is never executed.

32.2 Queued Connection

We have the same setup as in the direct connection example: a single custom signal connected to three slots.

\n\n\n

But now the output is

 1 on_button_clicked: Emitting custom signal\n 2 on_button_clicked: Returning\n 3 \n 4 Queued signal (MetaCallEvent) intercepted\n 5 First custom slot executed\n 6 \n 7 Queued signal (MetaCallEvent) intercepted\n 8 Second custom slot executed\n 9 \n10 Queued signal (MetaCallEvent) intercepted\n11 Third custom slot executed\n

\n\n

Now each slot execution is queued in the Qt event loop. After emitting the signal on_button_clicked continues execution and returns immediately, returning control to the event loop, allowing the slots to be executed. Each slot execution is wrapped in an asynchronous method invocation via QMetaObject::invokeMethod().

All three slots are still executed in the receiver thread which happens to be the main thread.

32.3 Blocking Queued Connection

Qt.BlockingQueuedConnection behaves the same as Qt::QueuedConnection, except that the signalling thread blocks until the slot returns.

\n\n\n

We have two worker objects: the Sender object signals the Receiver to do_work. Receiver in turn signals to the Sender that the work results are ready so that the Sender can handle_results.

\n\n\n

In the main window we connect the signals with the slots. If we use Qt.BlockingQueuedConnection:

1 self.receiver_obj.result_ready.connect(\n2     self.sender_obj.handle_results,\n3     Qt.ConnectionType.BlockingQueuedConnection)\n

\n\n

the output is

1 Receiver: Starting do_work\n2 Receiver: Emitting result_ready\n3 Sender: handle_results started\n4 Sender: handle_results finished after delay\n5 Receiver: After emit (this should delay if blocking)\n

\n\n

The Receiver thread is blocked for five seconds after it emits results_ready and only prints the last message after Sender finished handling the results.

If we used QtQueuedConnection instead

1 self.receiver_obj.result_ready.connect(\n2     self.sender_obj.handle_results)\n

\n\n

the output is

1 Receiver: Starting do_work\n2 Receiver: Emitting result_ready\n3 Receiver: After emit (this should delay if blocking)\n4 Sender: handle_results started\n5 Sender: handle_results finished after delay\n

\n\n

which means that do_work emits the results_ready signal and immediately continues its execution.

32.4 Unique Connection

Making your signal-slot connections unique is a good idea most of the time and Qt.UniqueConnection lets you make that explicit.

\n\n\n

The example starts without any connections made. We make the connection on clicking the connect_btn button but we use QtUniqueConnection so the connection is established only once. All subsequent attempts to connect self.button.clicked with self.on_clicked return invalid connection objects.The label text and the console output also reflect this.

1 Connection is valid\n2 Connection is invalid\n3 Connection is invalid\n4 Connection is invalid\n5 Connection is invalid\n

\n\n

32.5 Single-Shot Connection

While Qt.UniqueConnection makes connections unique, Qt.SingleShotConnection makes them disposable: the connection is automatically broken when the signal is emitted.

\n\n\n

The example lets you accumulate one-shot connections by clicking the Connect signals button and their count is displayed in the label. Once you click the Click Me button all connections are broken and the on_clicked slot is executed as many times as there were connections.

33. Databases

34. Processes

35. State Machines

\n\n

\n\n","tocStructure",[550,551,552,553,554,555,556,557,558,559,560,561,562,563,564,565,566,567,568,569,570,571,572,573,574,575,576,577,578,579,580,581,582,583,584,585,586,587,588,589,590,591,592,593,594,595,596,597,598,599,600,601,602,603,604,605,606,607,608,609,610,611,612,613,614,615,616,617,618,619,620,621,622,623,624,625,626,627,628,629,630,631,632,633,634,635,636,637,638,639,640,641,642,643,644,645,646,647,648,649,650,651,652,653,654,655,656,657,658,659,660,661,662,663,664,665,666,667,668,669,670,671,672,673,674,675,676,677],{"_75":76,"_43":77,"_70":-5,"_78":79,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":85,"_70":-5,"_78":86,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":91,"_70":-5,"_78":92,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":94,"_70":-5,"_78":95,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":97,"_70":-5,"_78":98,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":100,"_70":-5,"_78":101,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":104,"_70":-5,"_78":105,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":107,"_70":-5,"_78":108,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":110,"_70":-5,"_78":111,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":114,"_70":-5,"_78":115,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":117,"_70":-5,"_78":118,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":120,"_70":-5,"_78":121,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":123,"_70":-5,"_78":124,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":126,"_70":-5,"_78":127,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":130,"_70":-5,"_78":131,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":133,"_70":-5,"_78":134,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":136,"_70":-5,"_78":137,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":139,"_70":-5,"_78":140,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":143,"_70":-5,"_78":144,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":146,"_70":-5,"_78":147,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":149,"_70":-5,"_78":150,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":152,"_70":-5,"_78":153,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":156,"_70":-5,"_78":157,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":159,"_70":-5,"_78":160,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":162,"_70":-5,"_78":163,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":165,"_70":-5,"_78":166,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":168,"_70":-5,"_78":169,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":172,"_70":-5,"_78":173,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":175,"_70":-5,"_78":176,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":178,"_70":-5,"_78":179,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":181,"_70":-5,"_78":182,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":185,"_70":-5,"_78":186,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":188,"_70":-5,"_78":189,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":191,"_70":-5,"_78":192,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":194,"_70":-5,"_78":195,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":198,"_70":-5,"_78":199,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":201,"_70":-5,"_78":202,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":204,"_70":-5,"_78":205,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":208,"_70":-5,"_78":209,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":212,"_70":-5,"_78":213,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":215,"_70":-5,"_78":216,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":218,"_70":-5,"_78":219,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":221,"_70":-5,"_78":222,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":224,"_70":-5,"_78":225,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":227,"_70":-5,"_78":228,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":231,"_70":-5,"_78":232,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":234,"_70":-5,"_78":235,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":237,"_70":-5,"_78":238,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":240,"_70":-5,"_78":241,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":243,"_70":-5,"_78":244,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":246,"_70":-5,"_78":247,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":249,"_70":-5,"_78":250,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":253,"_70":-5,"_78":254,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":256,"_70":-5,"_78":257,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":259,"_70":-5,"_78":260,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":262,"_70":-5,"_78":263,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":265,"_70":-5,"_78":266,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":268,"_70":-5,"_78":269,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":271,"_70":-5,"_78":272,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":275,"_70":-5,"_78":276,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":279,"_70":-5,"_78":280,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":283,"_70":-5,"_78":284,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":287,"_70":-5,"_78":288,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":290,"_70":-5,"_78":291,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":293,"_70":-5,"_78":294,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":296,"_70":-5,"_78":297,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":299,"_70":-5,"_78":300,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":303,"_70":-5,"_78":304,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":306,"_70":-5,"_78":307,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":309,"_70":-5,"_78":310,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":312,"_70":-5,"_78":313,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":315,"_70":-5,"_78":316,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":318,"_70":-5,"_78":319,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":321,"_70":-5,"_78":322,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":325,"_70":-5,"_78":326,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":328,"_70":-5,"_78":329,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":331,"_70":-5,"_78":332,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":334,"_70":-5,"_78":335,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":337,"_70":-5,"_78":338,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":340,"_70":-5,"_78":341,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":344,"_70":-5,"_78":345,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":347,"_70":-5,"_78":348,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":350,"_70":-5,"_78":351,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":353,"_70":-5,"_78":354,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":356,"_70":-5,"_78":357,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":359,"_70":-5,"_78":360,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":363,"_70":-5,"_78":364,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":367,"_70":-5,"_78":368,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":370,"_70":-5,"_78":371,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":373,"_70":-5,"_78":374,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":376,"_70":-5,"_78":377,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":379,"_70":-5,"_78":380,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":383,"_70":-5,"_78":384,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":386,"_70":-5,"_78":387,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":389,"_70":-5,"_78":390,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":392,"_70":-5,"_78":393,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":395,"_70":-5,"_78":396,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":399,"_70":-5,"_78":400,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":403,"_70":-5,"_78":404,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":407,"_70":-5,"_78":408,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":411,"_70":-5,"_78":412,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":414,"_70":-5,"_78":415,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":417,"_70":-5,"_78":418,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":420,"_70":-5,"_78":421,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":423,"_70":-5,"_78":424,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":426,"_70":-5,"_78":427,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":429,"_70":-5,"_78":430,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":433,"_70":-5,"_78":434,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":436,"_70":-5,"_78":437,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":439,"_70":-5,"_78":440,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":443,"_70":-5,"_78":444,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":446,"_70":-5,"_78":447,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":449,"_70":-5,"_78":450,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":453,"_70":-5,"_78":454,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":456,"_70":-5,"_78":457,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":459,"_70":-5,"_78":460,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":462,"_70":-5,"_78":463,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":465,"_70":-5,"_78":466,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":468,"_70":-5,"_78":469,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":471,"_70":-5,"_78":472,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":474,"_70":-5,"_78":475,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":478,"_70":-5,"_78":479,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":482,"_70":-5,"_78":483,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":485,"_70":-5,"_78":486,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":84,"_43":488,"_70":-5,"_78":489,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":491,"_70":-5,"_78":492,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":495,"_70":-5,"_78":496,"_71":80,"_87":-5,"_88":-5,"_89":-5},{"_75":76,"_43":499,"_70":-5,"_78":500,"_71":80,"_87":-5,"_88":-5,"_89":-5},"publicChapterContent","nextChapter","sections",[],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

35. State Machines

Table of Contents

1. Getting Started

1.1 Installation

1.2 Qt Widgets

1.3 Hello World

1.4 Hello World Again

2. Signals & Slots

2.1 Basic Signals & Slots Mechanism

2.2 Using Python Lambda Functions

3. Qt Widgets Layouts

3.1 Laying out Widgets Vertically - QVBoxLayout\n

3.2 Horizontal Layout - QHBoxLayout\n

3.3 Grid Layout - QGridLayout\n

3.4 Form Layout - QFormLayout\n

4. Display Widgets

4.1 Displaying Text with QLabel\n

4.2 Displaying Images with Qlabel\n

4.3 Displaying LCD-like Numbers with QLCDNumber\n

5. Qt Widgets Buttons

5.1 QPushButton\n

5.2 QCheckBox\n

5.3 QRadioButton\n

6. Numeric Widgets

6.1 QSpinBox\n

6.2 QDoubleSpinBox\n

6.3 QSlider\n

6.4 QDial\n

7. Text Widgets

7.1 QLineEdit\n

7.2 QTextEdit\n

7.3 QPlainTextEdit\n

8. List Widgets

8.1 QComboBox\n

8.2 QListWidget\n

8.3 QListView\n

9. Table Widgets

9.1 QTableWidget\n

9.2 QTableView\n

10. Tree Widgets

11. Containers

11.1 QGroupBox\n

11.2 QScrollArea\n

11.3 QToolBox\n

11.4 QTabWidget\n

11.5 QSplitter\n

12. Building Complex UIs with QMainWindow\n

12.1 Setting Up the Central Widget

12.2 Adding a Status Bar

12.3 Creating Menus and Actions

12.4 Adding Toolbars

12.5 Using Dock Widgets

12.6 Completing the Editor

13. Dialogs

13.1 Standard Message Dialogs with QMessageBox\n

13.2 Input Dialogs with QInputDialog\n

13.3 File Dialogs with QFileDialog\n

13.4 Color Selection with QColorDialog\n

13.5 Font Selection with QFontDialog\n

13.6 Creating Custom Dialogs by Subclassing QDialog\n

14. Complex Widgets

15. Further Topics

16. Further Topics

17. Object Trees and Ownership

17.1 Parent-Child Relationships

17.2 Reparenting Qt Objects

17.3 Finding Qt Object Children

17.4 Manual Ownership Transfer

18. More Signals & Slots

18.1 A Common Pitfall

18.2 Custom Signals

18.3 Signal Blocking

18.4 Connection Objects

18.5 Connecting Multiple Slots with a Signal

18.6 Disconnecting

19. Events

19.1 Event Handlers

19.2 Object Event Filters

19.3 Application-Wide Event Filters

19.4 Event Propagation

3.1 Laying out Widgets Vertically - `QVBoxLayout`\n

3.2 Horizontal Layout - `QHBoxLayout`\n

3.3 Grid Layout - `QGridLayout`\n

3.4 Form Layout - `QFormLayout`\n

4.1 Displaying Text with `QLabel`\n

4.2 Displaying Images with `Qlabel`\n

4.3 Displaying LCD-like Numbers with `QLCDNumber`\n

5.1 `QPushButton`\n

5.2 `QCheckBox`\n

5.3 `QRadioButton`\n

6.1 `QSpinBox`\n

6.2 `QDoubleSpinBox`\n

6.3 `QSlider`\n

6.4 `QDial`\n

7.1 `QLineEdit`\n

7.2 `QTextEdit`\n

7.3 `QPlainTextEdit`\n

8.1 `QComboBox`\n

8.2 `QListWidget`\n

8.3 `QListView`\n

9.1 `QTableWidget`\n

9.2 `QTableView`\n

11.1 `QGroupBox`\n

11.2 `QScrollArea`\n

11.3 `QToolBox`\n

11.4 `QTabWidget`\n

11.5 `QSplitter`\n

12. Building Complex UIs with `QMainWindow`\n

13.1 Standard Message Dialogs with `QMessageBox`\n

13.2 Input Dialogs with `QInputDialog`\n

13.3 File Dialogs with `QFileDialog`\n

13.4 Color Selection with `QColorDialog`\n

13.5 Font Selection with `QFontDialog`\n

13.6 Creating Custom Dialogs by Subclassing `QDialog`\n

22. Model-View Programming with `QAbstractListModel`\n

23. Model-View Programming with `QAbstractTableModel`\n

24. Model-View Programming with `QAbstractItemModel`\n

27. Multithreading - `moveToThread`\n

27.4 Reusing the `QThread` object

27.5 Walking the Filesystem reusing the `QThread` Object

28. Using a `QThread` subclass

29. Multithreading with `QThreadPool` and `QRunnable`\n

30.3 `QMutex`\n

30.4 `QMutexLocker`\n

30.5 `QSemaphore`\n

30.6 `QSemaphoreReleaser`\n

30.7 `QWaitCondition`\n