Python GUIs - qt

Saving and Restoring Application Settings with QSettings in PyQt6 — Learn how to use QSettings to remember user preferences, window sizes, and configuration options between sessions

2025-10-09T09:00:00+00:00

Most desktop applications need to remember things between sessions. Maybe your user picked a dark theme, resized the window, or toggled a feature on or off. Without a way to save those choices, your app would forget everything the moment it closes. That's where QSettings comes in.

QSettings is a class provided by Qt (and available through PyQt6) that gives you a simple, cross-platform way to store and retrieve application settings. It handles all the platform-specific details for you — on Windows it uses the registry, on macOS it uses property list files, and on Linux it uses configuration files. You just read and write values, and Qt figures out the rest.

In this tutorial, we'll walk through everything you need to know to start using QSettings effectively in your PyQt6 applications.

Creating a QSettings Object

To use QSettings, you first need to create an instance. The most common way is to pass in your organization name and application name:

python

from PyQt6.QtCore import QSettings

settings = QSettings('MyCompany', 'MyApp')

These two strings — the organization name and the application name — are used by Qt to determine where your settings are stored. They act like a namespace, keeping your app's settings separate from every other application on the system.

You can check exactly where your settings file lives by printing the file path:

python

print(settings.fileName())

On Linux, this might print something like:

python

/home/username/.config/MyCompany/MyApp.conf

On Windows, it would point to a registry path, and on macOS, a .plist file. You don't need to worry about these differences — QSettings handles it for you.

Storing Values

Saving a setting is as simple as calling setValue() with a key and a value:

python

settings.setValue('theme', 'Dark')
settings.setValue('font_size', 14)
settings.setValue('show_toolbar', True)

The key is a string that you'll use later to retrieve the value. The value can be a string, integer, boolean, list, or other common Python types. QSettings will serialize it appropriately.

That's it — the value is saved. When you call setValue(), the data is written to persistent storage (the exact timing depends on the platform, but it happens automatically).

Reading Values Back

To read a setting, use value():

python

theme = settings.value('theme')
print(theme)  # 'Dark'

If the key doesn't exist (for example, the very first time your app runs), value() returns None by default. You can provide a default value as the second argument:

python

theme = settings.value('theme', 'Light')

Now if there's no theme key stored yet, you'll get 'Light' instead of None.

Handling Types

One thing that catches people off guard: QSettings stores everything as strings internally (at least when using INI-style backends on Linux). This means that when you read back a number or boolean, you might get a string instead of the type you expected.

To handle this, you can pass the type parameter:

python

font_size = settings.value('font_size', 14, type=int)
show_toolbar = settings.value('show_toolbar', True, type=bool)

By specifying type=int or type=bool, you ensure that the returned value is the correct Python type, regardless of how it was stored internally. This is especially important for booleans — without the type parameter, you might get the string 'true' instead of the boolean True.

Checking if a Setting Exists

Before reading a value, you might want to check whether it has been set at all. Use contains():

python

if settings.contains('theme'):
    theme = settings.value('theme')
    print(f'Found saved theme: {theme}')
else:
    print('No theme saved yet, using default')
    settings.setValue('theme', 'Light')
    theme = 'Light'

This pattern is useful when you want to distinguish between "the user explicitly set this value" and "this is just the default."

A Complete Example

Let's put this all together in a small PyQt6 application that remembers the window size and position, as well as a user-selected theme. When you close the app, it saves these settings. When you reopen it, everything is restored.

python

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QComboBox,
    QVBoxLayout, QWidget, QLabel
)
from PyQt6.QtCore import QSettings, QSize, QPoint


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.settings = QSettings('MyCompany', 'MyApp')

        self.setWindowTitle("QSettings Demo")

        # Create a simple UI with a theme selector
        layout = QVBoxLayout()

        layout.addWidget(QLabel("Choose a theme:"))

        self.theme_combo = QComboBox()
        self.theme_combo.addItems(['Light', 'Dark', 'Blue'])
        layout.addWidget(self.theme_combo)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

        # Restore settings
        self.load_settings()

    def load_settings(self):
        # Restore window size and position
        size = self.settings.value('window_size', QSize(400, 300))
        position = self.settings.value('window_position', QPoint(100, 100))
        self.resize(size)
        self.move(position)

        # Restore theme selection
        theme = self.settings.value('theme', 'Light')
        index = self.theme_combo.findText(theme)
        if index >= 0:
            self.theme_combo.setCurrentIndex(index)

    def save_settings(self):
        self.settings.setValue('window_size', self.size())
        self.settings.setValue('window_position', self.pos())
        self.settings.setValue('theme', self.theme_combo.currentText())

    def closeEvent(self, event):
        self.save_settings()
        super().closeEvent(event)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Run this app, move or resize the window, select a different theme from the dropdown, then close the app. When you run it again, the window should appear in the same position and size, with the same theme selected.

Let's walk through what's happening:

In __init__, we create a QSettings object with our organization and app names.
load_settings() reads values from persistent storage and applies them to the window and widgets. Notice how we pass default values (QSize(400, 300), QPoint(100, 100), 'Light') so the app has sensible starting values on the very first run.
save_settings() writes the current window size, position, and theme to settings.
closeEvent() is a built-in Qt method that gets called when the window is about to close. We override it to save our settings right before that happens.

If you're looking for a more robust approach to saving and restoring window geometry — including handling multiple monitors and window states — take a look at our dedicated guide on restoring window geometry with PyQt.

Removing Settings

If you need to delete a stored setting, use remove():

python

settings.remove('theme')

This removes the theme key entirely. After this, settings.contains('theme') would return False.

Listing All Keys

To see everything that's currently stored, use allKeys():

python

keys = settings.allKeys()
print(keys)  # ['theme', 'font_size', 'show_toolbar', ...]

This can be handy for debugging, or if you want to iterate over all settings to display them in a preferences dialog.

Organizing Settings with Groups

As your app grows, you might end up with a lot of settings. QSettings supports groups, which let you organize keys into sections — similar to folders:

python

settings.beginGroup('appearance')
settings.setValue('theme', 'Dark')
settings.setValue('font_size', 14)
settings.endGroup()

settings.beginGroup('network')
settings.setValue('timeout', 30)
settings.setValue('retry_count', 3)
settings.endGroup()

When you read them back, you use the same group:

python

settings.beginGroup('appearance')
theme = settings.value('theme', 'Light')
settings.endGroup()

Alternatively, you can use a / separator in the key name as a shorthand:

python

settings.setValue('appearance/theme', 'Dark')
theme = settings.value('appearance/theme', 'Light')

Both approaches produce the same result. The slash syntax is a bit more concise, while beginGroup()/endGroup() is cleaner when you're reading or writing several settings in the same group at once.

Using QSettings with setOrganizationName and setApplicationName

Instead of passing the organization and app names every time you create a QSettings object, you can set them once on the QApplication:

python

app = QApplication(sys.argv)
app.setOrganizationName('MyCompany')
app.setApplicationName('MyApp')

After this, you can create QSettings objects without any arguments:

python

settings = QSettings()

It will automatically use the organization and application names you set. This is especially convenient in larger applications where you create QSettings in multiple places — you only need to define the names once at startup. If you're new to building PyQt6 applications and want to understand how QApplication and windows work, see our tutorial on creating your first window in PyQt6.

Managing Many Settings with a Dictionary

If your application has a lot of settings, checking each one individually can get repetitive. A cleaner approach is to define your defaults in a dictionary and loop through them:

python

DEFAULTS = {
    'theme': 'Light',
    'font_size': 14,
    'show_toolbar': True,
    'language': 'English',
    'auto_save': True,
    'auto_save_interval': 5,
}

settings = QSettings('MyCompany', 'MyApp')

# Load settings with defaults
config = {}
for key, default in DEFAULTS.items():
    config[key] = settings.value(key, default, type=type(default))

print(config)

By using type=type(default), each value is automatically cast to the same type as its default. This keeps everything tidy and makes it easy to add new settings later — just add another entry to the dictionary.

Where Are Settings Stored?

If you're curious about where QSettings puts your data, or if you need to find the settings file for debugging, here's a quick summary:

Platform	Storage Location
Windows	Registry under `HKEY_CURRENT_USER\Software\MyCompany\MyApp`
macOS	`~/Library/Preferences/com.mycompany.MyApp.plist`
Linux	`~/.config/MyCompany/MyApp.conf`

You can always check the exact path using:

python

print(settings.fileName())

On Linux and macOS, the settings file is a plain text file that you can open and inspect directly, which is helpful for debugging.

Working with QStandardPaths

QSettings tells you where settings are stored, but sometimes you need to know about other standard locations — where to store cached data, application data, or downloaded files. Qt provides QStandardPaths for this:

python

from PyQt6.QtCore import QStandardPaths

# Where to store app configuration
config_path = QStandardPaths.writableLocation(QStandardPaths.AppConfigLocation)
print(f'Config: {config_path}')

# Where to store app data
data_path = QStandardPaths.writableLocation(QStandardPaths.AppDataLocation)
print(f'Data: {data_path}')

# Where to store cached files
cache_path = QStandardPaths.writableLocation(QStandardPaths.CacheLocation)
print(f'Cache: {cache_path}')

QStandardPaths is separate from QSettings, but they complement each other well. Use QSettings for simple key-value preferences, and QStandardPaths when you need to store actual files (databases, logs, downloaded content) in the right platform-appropriate location.

Summary

QSettings gives you a clean, cross-platform way to persist user preferences in your PyQt6 applications. Here's a quick recap of the essentials:

Create a QSettings object with your organization and app name.
Use setValue(key, value) to save a setting.
Use value(key, default, type=...) to read a setting, with a default fallback and explicit type.
Use contains(key) to check if a setting exists.
Use remove(key) to delete a setting.
Override closeEvent() on your main window to save settings when the app closes.
Organize related settings with groups using beginGroup()/endGroup() or / in key names.

Once you're comfortable with these basics, you'll find that QSettings quietly handles one of those essential-but-tedious parts of desktop app development — letting you focus on the interesting stuff. When you're ready to distribute your finished application, check out our guide on packaging PyQt6 applications with PyInstaller on Windows to ship your app with all its settings support intact.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

6th Edition - Create GUI Applications with Python & Qt, Released — PyQt6 & PySide6 books updated for 2025 with model view controller architecture, new Python/Qt features and more examples

2025-06-11T08:00:00+00:00

The 6th edition of my book Create GUI Applications with Python & Qt is now available for both PyQt6 and PySide6.

This update brings the book up to date with the latest changes in PyQt6 & PySide6, and also updates code to make use of newer features in Python. Many of the chapters have been updated and extended with more examples of form layouts, built-in dialogs and architecture, particularly using Model View Controller (MVC) architecture.

What's new in the 6th edition?

Updated for PyQt6 & PySide6 with the latest Qt6 API changes
Expanded coverage of Model View Controller (MVC) architecture for Python GUI apps
More examples of form layouts, built-in dialogs, and application architecture
Code updated to leverage modern Python 3 features and best practices
Additional real-world examples to help you build professional desktop applications

Buy the latest edition

PyQt6 — PyQt6 Book, 6th Edition, Create GUI Applications with Python & Qt6
PySide6 — PySide6 Book, 6th Edition, Create GUI Applications with Python & Qt6

Free updates for existing readers

As always, if you've previously bought a copy of the book you get these updates for free! Just go to your account downloads page and enter the email you used for the purchase.

If you bought the book elsewhere (in paperback or digital) you can register to get these updates too — just email your receipt to register@pythonguis.com

Enjoy!

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

How to Show Only Icons in QTableView Cells (Hide Text) — Use custom model roles to display icons without text in your PyQt6 tables

2025-04-13T06:52:05+00:00

When you're building a table-based interface with QTableView in PyQt6, you'll often want to show icons in certain cells — for example, a checkmark for True and a cross for False. But by default, Qt will also display the underlying data value as text alongside the icon. That means you end up with something like a green tick next to the word "True", which looks cluttered and unprofessional.

In this tutorial, we'll walk through how to display only icons in your QTableView cells, suppressing the text entirely. We'll build a complete working example so you can see exactly how it all fits together.

How Qt Models Serve Data

Before we jump into the solution, it helps to understand a little about how QTableView gets its data.

When a QTableView renders a cell, it asks the underlying model for data by calling the model's data() method. But it doesn't just ask once — it asks multiple times, each time with a different role. Roles tell the model what kind of data the view is looking for. The most common roles are:

Qt.DisplayRole — the text to show in the cell.
Qt.DecorationRole — an icon or color swatch to show in the cell.

When you return a value for Qt.DisplayRole, that value gets converted to a string and displayed as text. When you return a QIcon or QColor for Qt.DecorationRole, it appears as a small icon to the left of the text.

So if you're returning both a display value and a decoration for the same cell, you'll see both. The trick to showing only the icon is to return None for Qt.DisplayRole on the cells where you want to suppress the text.

A Basic Table Model with Icons

Let's start with a simple custom model that displays a numpy array of mixed data — some strings, some numbers, and some boolean values. We'll add icons for the boolean columns.

First, make sure you have PyQt6 and numpy installed:

pip install pyqt6 numpy

We'll start from an application outline, that shows both icons and text for boolean values:

python

import sys
import numpy as np
from PyQt6.QtCore import Qt, QAbstractTableModel
from PyQt6.QtGui import QIcon
from PyQt6.QtWidgets import QApplication, QMainWindow, QTableView


class TableModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, parent=None):
        return self._data.shape[0]

    def columnCount(self, parent=None):
        return self._data.shape[1]

    def data(self, index, role=Qt.DisplayRole):
        if not index.isValid():
            return None

        value = self._data[index.row(), index.column()]

        if role == Qt.DisplayRole:
            return str(value)

        if role == Qt.DecorationRole:
            if isinstance(value, bool):
                if value:
                    return QIcon("tick.png")
                return QIcon("cross.png")

        return None


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QTableView Icons Example")

        data = np.array([
            [True, "Alice", 32, False],
            [False, "Bob", 28, True],
            [True, "Charlie", 45, True],
            [False, "Diana", 36, False],
        ], dtype=object)

        self.table = QTableView()
        model = TableModel(data)
        self.table.setModel(model)
        self.setCentralWidget(self.table)
        self.resize(500, 300)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

If you run this, you'll see that the boolean cells show an icon and the text "True" or "False". That's because Qt.DisplayRole is returning str(value) for every cell, including the boolean ones.

You'll need tick.png and cross.png icon files in your project folder for the icons to appear. You can use any small icon images you like, or grab free ones from a site like icons8.com.

Suppressing the Text for Boolean Cells

The fix is straightforward. In the data() method, when the role is Qt.DisplayRole, we check whether the cell's value is a boolean. If it is, we return None instead of the string representation. Returning None tells Qt "there's nothing to display as text for this cell."

Update the Qt.DisplayRole section of your data() method like this:

python

def data(self, index, role=Qt.DisplayRole):
    if not index.isValid():
        return None

    value = self._data[index.row(), index.column()]

    if role == Qt.DisplayRole:
        if isinstance(value, bool):
            return None  # Don't show text for boolean cells
        return str(value)

    if role == Qt.DecorationRole:
        if isinstance(value, bool):
            if value:
                return QIcon("tick.png")
            return QIcon("cross.png")

    return None

That's it! The two lines that make the difference are:

python

if isinstance(value, bool):
    return None

By returning None for Qt.DisplayRole when the value is a boolean, we tell the view there's no text to render. The Qt.DecorationRole still returns the icon as before, so the icon appears on its own — clean and uncluttered.

The Complete Working Example

Here's the full code with the fix applied:

python

import sys
import numpy as np
from PyQt6.QtCore import Qt, QAbstractTableModel
from PyQt6.QtGui import QIcon
from PyQt6.QtWidgets import QApplication, QMainWindow, QTableView


class TableModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, parent=None):
        return self._data.shape[0]

    def columnCount(self, parent=None):
        return self._data.shape[1]

    def data(self, index, role=Qt.DisplayRole):
        if not index.isValid():
            return None

        value = self._data[index.row(), index.column()]

        if role == Qt.DisplayRole:
            if isinstance(value, bool):
                return None  # Suppress text for boolean values
            return str(value)

        if role == Qt.DecorationRole:
            if isinstance(value, bool):
                if value:
                    return QIcon("tick.png")
                return QIcon("cross.png")

        return None


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QTableView Icons Example")

        data = np.array([
            [True, "Alice", 32, False],
            [False, "Bob", 28, True],
            [True, "Charlie", 45, True],
            [False, "Diana", 36, False],
        ], dtype=object)

        self.table = QTableView()
        model = TableModel(data)
        self.table.setModel(model)
        self.setCentralWidget(self.table)
        self.resize(500, 300)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

When you run this, the boolean columns will show only the tick or cross icons, with no text beside them. The other columns (names and ages) continue to display their text values as normal.

Centering the Icons

You might notice that the icons sit to the left of the cell by default. If you'd like them centered, you can handle Qt.TextAlignmentRole in your data() method:

python

if role == Qt.TextAlignmentRole:
    if isinstance(value, bool):
        return Qt.AlignCenter

Add this block alongside the other role checks inside your data() method. This tells the view to center the content of boolean cells, which looks much tidier when the icon is the only thing in the cell.

Applying This Pattern to Other Data Types

The same approach works for any situation where you want to show an icon without text. The pattern is always the same:

Return your icon from Qt.DecorationRole.
Return None from Qt.DisplayRole for that cell.

For example, if you had a column showing status values like "active", "inactive", or "pending", you could map each to a colored icon and suppress the text:

python

if role == Qt.DisplayRole:
    if index.column() == 2:  # Status column
        return None
    return str(value)

if role == Qt.DecorationRole:
    if index.column() == 2:  # Status column
        status_icons = {
            "active": QIcon("green.png"),
            "inactive": QIcon("red.png"),
            "pending": QIcon("yellow.png"),
        }
        return status_icons.get(value)

You can use column index checks, value type checks, or any other logic to decide which cells should have their text suppressed.

Summary

Displaying only icons in QTableView cells comes down to understanding how Qt's model/view role system works. The view asks for display text and decoration separately, so you have full control over what appears. By returning None for Qt.DisplayRole on cells where you only want an icon, you get a clean, icon-only display while keeping the rest of your table's text intact.

This is a small technique, but it makes a real difference in how polished your table interfaces look — and it's a great example of why understanding the role system in Qt's model/view architecture is so valuable.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How to Show Only Icons in QTableView Cells (Hide Text) — Use custom model roles to display icons without text in your PySide6 tables

2025-04-13T06:52:05+00:00

When you're building a table-based interface with QTableView in PySide6 or PyQt6, you'll often want to show icons in certain cells — for example, a checkmark for True and a cross for False. But by default, Qt will also display the underlying data value as text alongside the icon. That means you end up with something like a green tick next to the word "True", which looks cluttered and unprofessional.

In this tutorial, we'll walk through how to display only icons in your QTableView cells, suppressing the text entirely. We'll build a complete working example using QAbstractTableModel so you can see exactly how it all fits together.

How Qt Models Serve Data to QTableView

Before we jump into the solution, it helps to understand a little about how QTableView gets its data from the model.

Qt.DisplayRole — the text to show in the cell.
Qt.DecorationRole — an icon or color swatch to show in the cell.

A Basic QTableView Model with Icons

Let's start with a simple custom table model that displays a numpy array of mixed data — some strings, some numbers, and some boolean values. We'll add icons for the boolean columns using Qt.DecorationRole.

First, make sure you have PySide6 and numpy installed:

pip install pyside6 numpy

We'll start from an application outline, that shows both icons and text for boolean values:

python

import sys
import numpy as np
from PySide6.QtCore import Qt, QAbstractTableModel
from PySide6.QtGui import QIcon
from PySide6.QtWidgets import QApplication, QMainWindow, QTableView


class TableModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, parent=None):
        return self._data.shape[0]

    def columnCount(self, parent=None):
        return self._data.shape[1]

    def data(self, index, role=Qt.DisplayRole):
        if not index.isValid():
            return None

        value = self._data[index.row(), index.column()]

        if role == Qt.DisplayRole:
            return str(value)

        if role == Qt.DecorationRole:
            if isinstance(value, bool):
                if value:
                    return QIcon("tick.png")
                return QIcon("cross.png")

        return None


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QTableView Icons Example")

        data = np.array([
            [True, "Alice", 32, False],
            [False, "Bob", 28, True],
            [True, "Charlie", 45, True],
            [False, "Diana", 36, False],
        ], dtype=object)

        self.table = QTableView()
        model = TableModel(data)
        self.table.setModel(model)
        self.setCentralWidget(self.table)
        self.resize(500, 300)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

If you run this, you'll see that the boolean cells show an icon and the text "True" or "False". That's because Qt.DisplayRole is returning str(value) for every cell, including the boolean ones.

You'll need tick.png and cross.png icon files in your project folder for the icons to appear. You can use any small icon images you like, or grab free ones from a site like icons8.com.

Suppressing Text for Icon-Only QTableView Cells

Update the Qt.DisplayRole section of your data() method like this:

python

def data(self, index, role=Qt.DisplayRole):
    if not index.isValid():
        return None

    value = self._data[index.row(), index.column()]

    if role == Qt.DisplayRole:
        if isinstance(value, bool):
            return None  # Don't show text for boolean cells
        return str(value)

    if role == Qt.DecorationRole:
        if isinstance(value, bool):
            if value:
                return QIcon("tick.png")
            return QIcon("cross.png")

    return None

That's it! The two lines that make the difference are:

python

if isinstance(value, bool):
    return None

Complete Working Example: Icon-Only QTableView Cells

Here's the full code with the fix applied:

python

import sys
import numpy as np
from PySide6.QtCore import Qt, QAbstractTableModel
from PySide6.QtGui import QIcon
from PySide6.QtWidgets import QApplication, QMainWindow, QTableView


class TableModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, parent=None):
        return self._data.shape[0]

    def columnCount(self, parent=None):
        return self._data.shape[1]

    def data(self, index, role=Qt.DisplayRole):
        if not index.isValid():
            return None

        value = self._data[index.row(), index.column()]

        if role == Qt.DisplayRole:
            if isinstance(value, bool):
                return None  # Suppress text for boolean values
            return str(value)

        if role == Qt.DecorationRole:
            if isinstance(value, bool):
                if value:
                    return QIcon("tick.png")
                return QIcon("cross.png")

        return None


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QTableView Icons Example")

        data = np.array([
            [True, "Alice", 32, False],
            [False, "Bob", 28, True],
            [True, "Charlie", 45, True],
            [False, "Diana", 36, False],
        ], dtype=object)

        self.table = QTableView()
        model = TableModel(data)
        self.table.setModel(model)
        self.setCentralWidget(self.table)
        self.resize(500, 300)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

When you run this, the boolean columns will show only the tick or cross icons, with no text beside them. The other columns (names and ages) continue to display their text values as normal.

Centering Icons in QTableView Cells

You might notice that the icons sit to the left of the cell by default. If you'd like them centered, you can handle Qt.TextAlignmentRole in your data() method:

python

if role == Qt.TextAlignmentRole:
    if isinstance(value, bool):
        return Qt.AlignCenter

Applying This Pattern to Other Data Types

The same approach works for any situation where you want to show an icon without text in a QTableView. The pattern is always the same:

Return your icon from Qt.DecorationRole.
Return None from Qt.DisplayRole for that cell.

For example, if you had a column showing status values like "active", "inactive", or "pending", you could map each to a colored icon and suppress the text:

python

if role == Qt.DisplayRole:
    if index.column() == 2:  # Status column
        return None
    return str(value)

if role == Qt.DecorationRole:
    if index.column() == 2:  # Status column
        status_icons = {
            "active": QIcon("green.png"),
            "inactive": QIcon("red.png"),
            "pending": QIcon("yellow.png"),
        }
        return status_icons.get(value)

You can use column index checks, value type checks, or any other logic to decide which cells should have their text suppressed.

Summary

Displaying only icons in QTableView cells comes down to understanding how Qt's model roles work. The view asks for display text and decoration separately through Qt.DisplayRole and Qt.DecorationRole, so you have full control over what appears. By returning None for Qt.DisplayRole on cells where you only want an icon, you get a clean, icon-only display while keeping the rest of your table's text intact.

This is a small technique, but it makes a real difference in how polished your PySide6 and PyQt6 table interfaces look — and it's a great example of why understanding the role system in Qt's model/view architecture is so valuable.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Build a Desktop Sticky Notes Application with PySide6 & SQLAlchemy — Create moveable desktop reminders with Python

2025-04-03T12:01:00+00:00

Do you ever find yourself needing to take a quick note of some information but have nowhere to put it? Then this app is for you! This virtual sticky notes (or Post-it notes) app allows you to keep short text notes quickly from anywhere via the system tray. Create a new note, paste what you need in. It'll stay there until you delete it.

The application is written in PySide6 and the notes are implemented as frameless windows — that is, windows without any title bar or controls. Notes can be dragged around the desktop and edited at will. Text in the notes and note positions are stored in a SQLite database, via SQLAlchemy, with note details and positions being restored on each session.

This is quite a complicated example, but we'll be walking through it slowly step by step. The full source code is available, with working examples at each stage of the development if you get stuck.

Setting Up the Working Environment

In this tutorial, we'll use the PySide6 library to build the sticky notes app's GUI. We'll assume that you have a basic understanding of PySide6 apps.

To learn the basics of PySide6, check out the complete PySide6 Tutorials or my book Create GUI Applications with Python & PySide6

To store the notes between sessions, we will use SQLAlchemy with a SQLite database (a file). Don't worry if you're not familiar with SQLAlchemy, we won't be going deep into that topic & have working examples you can copy.

With that in mind, let's create a virtual environment and install our requirements into it. To do this, you can run the following commands:

macOS
Windows
Linux

sh
$ mkdir notes/
$ cd notes
$ python -m venv venv
$ source venv/bin/activate
(venv)$ pip install pyside6 sqlalchemy

cmd
> mkdir notes/
> cd notes
> python -m venv venv
> venv\Scripts\activate.bat
(venv)> pip install pyside6 sqlalchemy

sh
$ mkdir notes/
$ cd notes
$ python -m venv venv
$ source venv/bin/activate
(venv)$ pip install pyside6 sqlalchemy

With these commands, you create a notes/ folder for storing your project. Inside that folder, you create a new virtual environment, activate it, and install PySide6 and SQLAlchemy from PyPi.

For platform-specific troublshooting, check the Working With Python Virtual Environments tutorial.

Building the Sticky Notes GUI with PySide6

Let's start by building a simple notes UI where we can create, move and close notes on the desktop. We'll deal with persistance later.

The UI for our desktop sticky notes will be a bit strange since there is no central window, all the windows are independent yet look identical (aside from the contents). We also need the app to remain open in the background, using the system tray or toolbar, so we can show/hide the notes again without closing and re-opening the application each time.

We'll start by defining a single note, and then deal with these other issues later. Create a new file named notes.py and add the following outline application to it.

python

import sys

from PySide6.QtWidgets import QApplication, QTextEdit, QVBoxLayout, QWidget

app = QApplication(sys.argv)


class NoteWindow(QWidget):
    def __init__(self):
        super().__init__()
        layout = QVBoxLayout()
        self.text = QTextEdit()
        layout.addWidget(self.text)
        self.setLayout(layout)


note = NoteWindow()
note.show()
app.exec()

In this code we first create a Qt QApplication instance. This needs to be done before creating our widgets. Next we define a simple custom window class NoteWindow by subclassing QWidget. We add a vertical layout to the window, and enter a single QTextEdit widget. We then create an instance of this window object as note and show it by calling .show(). This puts the window on the desktop. Finally, we start up our application by calling app.exec().

You can run this file like any other Python script.

python notes.py

When the application launches you'll see the following on your desktop.

Simple "notes" window on the desktop

If you click in the text editor in the middle, you can enter some text.

Technically this is a note, but we can do better.

Styling the Sticky Notes with QSS (Qt Style Sheets)

Our note doesn't look anything like a sticky note yet. Let's change that by applying some simple styles to it.

Firstly we can change the colors of the window, textarea and text. In Qt there are multiple ways to do this -- for example, we could override the system palette definition for the window. However, the simplest approach is to use QSS, which is Qt's version of CSS.

python

import sys

from PySide6.QtWidgets import QApplication, QTextEdit, QVBoxLayout, QWidget

app = QApplication(sys.argv)


class NoteWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setStyleSheet(
            "background: #FFFF99; color: #62622f; border: 0; font-size: 16pt;"
        )
        layout = QVBoxLayout()
        self.text = QTextEdit()
        layout.addWidget(self.text)
        self.setLayout(layout)


note = NoteWindow()
note.show()
app.exec()

In the code above we have set a background color of hex #ffff99 for our note window, and set the text color to hex #62622f a sort of muddy brown. The border:0 removes the frame from the text edit, which otherwise would appear as a line on the bottom of the window. Finally, we set the font size to 16 points, to make the notes easier to read.

If you run the code now you'll see this, much more notely note.

The note with the QSS styling applied

Remove Window Decorations with Frameless Window Flags

The last thing breaking the illusion of a sticky note on the desktop is the window decorations -- the titlebar and window controls. We can remove these using Qt window flags. We can also use a window flag to make the notes appear on top of other windows. Later we'll handle hiding and showing the notes via a tray application.

python

import sys

from PySide6.QtCore import Qt
from PySide6.QtWidgets import (
    QApplication,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

app = QApplication(sys.argv)


class NoteWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowFlags(
            self.windowFlags()
            | Qt.WindowType.FramelessWindowHint
            | Qt.WindowType.WindowStaysOnTopHint
        )
        self.setStyleSheet(
            "background: #FFFF99; color: #62622f; border: 0; font-size: 16pt;"
        )
        layout = QVBoxLayout()

        self.text = QTextEdit()
        layout.addWidget(self.text)
        self.setLayout(layout)


note = NoteWindow()
note.show()
app.exec()

To set window flags, we need to import the Qt flags from the QtCore namespace. Then you can set flags on the window using .setWindowFlags(). Note that since windows have flags already set, and we don't want to replace them all, we get the current flags with .windowFlags() and then add the additional flags to it using boolean OR |. We've added two flags here -- Qt.WindowType.FramelessWindowHint which removes the window decorations, and Qt.WindowType.WindowStaysOnTopHint which keeps the windows on top.

Run this and you'll see a window with the decorations removed.

Note with the window decorations removed

With the window decorations removed you no longer have access to the close button. But you can still close the window using Alt-F4 (Windows) or the application menu (macOS).

While you can close the window, it'd be nicer if there was a button to do it. We can add a custom close button using QPushButton and hook this up to the window's .close() method to re-implement this.

python

import sys

from PySide6.QtCore import Qt
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QPushButton,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

app = QApplication(sys.argv)


class NoteWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowFlags(
            self.windowFlags()
            | Qt.WindowType.FramelessWindowHint
            | Qt.WindowType.WindowStaysOnTopHint
        )
        self.setStyleSheet(
            "background: #FFFF99; color: #62622f; border: 0; font-size: 16pt;"
        )
        layout = QVBoxLayout()
        # layout.setSpacing(0)

        buttons = QHBoxLayout()
        self.close_btn = QPushButton("×")
        self.close_btn.setStyleSheet(
            "font-weight: bold; font-size: 25px; width: 25px; height: 25px;"
        )
        self.close_btn.setCursor(Qt.CursorShape.PointingHandCursor)
        self.close_btn.clicked.connect(self.close)
        buttons.addStretch()  # Add stretch on left to push button right.
        buttons.addWidget(self.close_btn)
        layout.addLayout(buttons)

        self.text = QTextEdit()
        layout.addWidget(self.text)
        self.setLayout(layout)


note = NoteWindow()
note.show()
app.exec()

Our close button is created using QPushButton with a unicode multiplication symbol (an x) as the label. We set a stylesheet on this button to size the label and button. Then we set a custom cursor on the button to make it clearer that this is a clickable thing that performs an action. Finally, we connect the .clicked signal of the button to the window's close method self.close. The button will close the window.

Later we'll use this button to delete notes.

To add the close button to the top right of the window, we create a horizontal layout with QHBoxLayout. We first add a stretch, then the push button. This has the effect of pushing the button to the right. Finally, we add our buttons layout to the main layout of the note, before the text edit. This puts it at the top of the window.

Run the code now and our note is complete!

The complete note UI with close button

Making Notes Draggable with Mouse Events

The note looks like a sticky note now, but we can't move it around and there is only one (unless we run the application multiple times concurrently). We'll fix both of those next, starting with the moveability of the notes.

This is fairly straightforward to achieve in PySide6 because Qt makes the raw mouse events available on all widgets. To implement dragging, we can intercept these events and update the position of the window based on the distance the mouse has moved.

To implement this, add the following two methods to the bottom of the NoteWindow class.

python

class NoteWindow(QWidget):
    # ... existing code skipped

    def mousePressEvent(self, e):
        self.previous_pos = e.globalPosition()

    def mouseMoveEvent(self, e):
        delta = e.globalPosition() - self.previous_pos
        self.move(self.x() + delta.x(), self.y() + delta.y())
        self.previous_pos = e.globalPosition()

Clicking and dragging a window involves three actions: the mouse press, the mouse move and the mouse release. We have defined two methods here mousePressEvent and mouseMoveEvent. In mousePressEvent we receive the initial press of the mouse and store the position where the click occurred. This method is only called on the initial press of the mouse when starting to drag the window.

The mouseMoveEvent is called on every subsequent move while the mouse button remains pressed. On each move we take the new mouse position and subtract the previous position to get the delta -- that is, the change in mouse position from the initial press to the current event. Then we move the window by that amount, storing the new previous position after the move.

The effect of this is that every time the mouseMoveEvent method is called, the window moves by the amount that the mouse has moved since the last call. The window moves -- or is dragged -- by the mouse.

Creating Multiple Notes

The note looks like a note, it is now moveable, but there is still only a single note -- not hugely useful! Let's fix that now.

Currently we're creating the NoteWindow when the application starts up, just before we call app.exec(). If we create new notes while the application is running it will need to happen in a function or method, which is triggered somehow. This introduces a new problem, since we need to have some way to store the NoteWindow objects so they aren't automatically deleted (and the window closed) when the function or method exits.

Python automatically deletes objects when they fall out of scope if there aren't any remaining references to them.

We can solve this by storing the NoteWindow objects somewhere. Usually we'd do this on our main window, but in this app there is no main window. There are a few options here, but in this case we're going to use a simple dictionary.

python

import sys

from PySide6.QtCore import Qt
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QPushButton,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

app = QApplication(sys.argv)

# Store references to the NoteWindow objects in this, keyed by id.
active_notewindows = {}


class NoteWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowFlags(
            self.windowFlags()
            | Qt.WindowType.FramelessWindowHint
            | Qt.WindowType.WindowStaysOnTopHint
        )
        self.setStyleSheet(
            "background: #FFFF99; color: #62622f; border: 0; font-size: 16pt;"
        )
        layout = QVBoxLayout()

        buttons = QHBoxLayout()
        self.close_btn = QPushButton("×")
        self.close_btn.setStyleSheet(
            "font-weight: bold; font-size: 25px; width: 25px; height: 25px;"
        )
        self.close_btn.clicked.connect(self.close)
        self.close_btn.setCursor(Qt.CursorShape.PointingHandCursor)
        buttons.addStretch()  # Add stretch on left to push button right.
        buttons.addWidget(self.close_btn)
        layout.addLayout(buttons)

        self.text = QTextEdit()
        layout.addWidget(self.text)
        self.setLayout(layout)

        # Store a reference to this note in the
        active_notewindows[id(self)] = self

    def mousePressEvent(self, e):
        self.previous_pos = e.globalPosition()

    def mouseMoveEvent(self, e):
        delta = e.globalPosition() - self.previous_pos
        self.move(self.x() + delta.x(), self.y() + delta.y())
        self.previous_pos = e.globalPosition()


def create_notewindow():
    note = NoteWindow()
    note.show()


create_notewindow()
create_notewindow()
create_notewindow()
create_notewindow()
app.exec()

In this code we've added our active_notewindows dictionary. This holds references to our NoteWindow objects, keyed by id(). Note that this is Python's internal id for this object, so it is consistent and unique. We can use this same id to remove the note. We add each note to this dictionary at the bottom of it's __init__ method.

Next we've implemented a create_notewindow() function which creates an instance of NoteWindow and shows it, just as before. Nothing else is needed, since the note itself handles storing it's references on creation.

Finally, we've added multiple calls to create_notewindow() to create multiple notes.

Multiple notes on the desktop

Adding a System Tray Icon with QSystemTrayIcon

We can now create multiple notes programmatically, but we want to be able to do this from the UI. We could implement this behavior on the notes themselves, but then it wouldn't work if all the notes had been closed or hidden. Instead, we'll create a system tray application -- this will show in the system tray on Windows, or on the macOS toolbar. Users can use this to create new notes, and quit the application.

There's quite a lot to this, so we'll step through it in stages.

Update the code, adding the imports shown at the top, and the rest following the definition of create_notewindow.

python

import sys

from PySide6.QtCore import Qt
from PySide6.QtGui import QIcon
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QPushButton,
    QSystemTrayIcon,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

# ... code hidden up to create_notewindow() definition

create_notewindow()

# Create system tray icon
icon = QIcon("sticky-note.png")

# Create the tray
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setVisible(True)


def handle_tray_click(reason):
    # If the tray is left-clicked, create a new note.
    if (
        QSystemTrayIcon.ActivationReason(reason)
        == QSystemTrayIcon.ActivationReason.Trigger
    ):
        create_notewindow()


tray.activated.connect(handle_tray_click)

app.exec()

In this code we've first created a QIcon object passing in the filename of the icon to use. I'm using a sticky note icon from the Fugue icon set by designer Yusuke Kamiyamane. Feel free to use any icon you prefer.

We're using a relative path here. If you don't see the icon, make sure you're running the script from the same folder or provide the path.

The system tray icon is managed through a QSystemTrayIcon object. We set our icon on this, and set the tray icon to visible (so it is not automatically hidden by Windows).

QSystemTrayIcon has a signal activated which fires whenever the icon is activated in some way -- for example, being clicked with the left or right mouse button. We're only interested in a single left click for now -- we'll use the right click for our menu shortly. To handle the left click, we create a handler function which accepts reason (the reason for the activation) and then checks this against QSystemTrayIcon.ActivationReason.Trigger. This is the reason reported when a left click is used.

If the left mouse button has been clicked, we call create_notewindow() to create a new instance of a note.

If you run this example now, you'll see the sticky note in your tray and clicking on it will create a new note on the current desktop! You can create as many notes as you like, and once you close them all the application will close.

The sticky note icon in the system tray on Windows

This is happening because by default Qt will close an application once all its windows have closed. This can be disabled, but we need to add another way to quit before we do it, otherwise our app will be unstoppable.

To allow the notes application to be closed from the tray, we need a menu. System tray menus are normally accessible through right-clicking on the icon. To implement that we can set a QMenu as a context menu on the QSystemTrayIcon. The actions in menus in Qt are defined using QAction.

python

import sys

from PySide6.QtCore import Qt
from PySide6.QtGui import QAction, QIcon
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QMenu,
    QPushButton,
    QSystemTrayIcon,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

# ... code hidden up to handle_tray_click

tray.activated.connect(handle_tray_click)


# Don't automatically close app when the last window is closed.
app.setQuitOnLastWindowClosed(False)

# Create the menu
menu = QMenu()
add_note_action = QAction("Add note")
add_note_action.triggered.connect(create_notewindow)
menu.addAction(add_note_action)

# Add a Quit option to the menu.
quit_action = QAction("Quit")
quit_action.triggered.connect(app.quit)
menu.addAction(quit_action)

# Add the menu to the tray
tray.setContextMenu(menu)


app.exec()

We create the menu using QMenu. Actions are created using QAction passing in the label as a string. This is the text that will be shown for the menu item. The .triggered signal fires when the action is clicked (in a menu, or toolbar) or activated through a keyboard shortcut. Here we've connected the add note action to our create_notewindow function. We've also added an action to quit the application. This is connected to the built-in .quit slot on our QApplication instance.

The menu is set on the tray using .setContextMenu(). In Qt context menus are automatically shown when the user right clicks on the tray.

Finally, we have also disabled the behavior of closing the application when the last window is closed using app.setQuitOnLastWindowClosed(False). Now, once you close all the windows, the application will remain running in the background. You can close it by going to the tray, right-clicking and selecting "Quit".

If you find this annoying while developing, just comment this line out again.

We've had a lot of changes so far, so here is the current complete code.

python

import sys

from PySide6.QtCore import Qt
from PySide6.QtGui import QIcon
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QPushButton,
    QSystemTrayIcon,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

app = QApplication(sys.argv)

# Store references to the NoteWindow objects in this, keyed by id.
active_notewindows = {}


class NoteWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowFlags(
            self.windowFlags()
            | Qt.WindowType.FramelessWindowHint
            | Qt.WindowType.WindowStaysOnTopHint
        )
        self.setStyleSheet(
            "background: #FFFF99; color: #62622f; border: 0; font-size: 16pt;"
        )
        layout = QVBoxLayout()

        buttons = QHBoxLayout()
        self.close_btn = QPushButton("×")
        self.close_btn.setStyleSheet(
            "font-weight: bold; font-size: 25px; width: 25px; height: 25px;"
        )
        self.close_btn.clicked.connect(self.close)
        self.close_btn.setCursor(Qt.CursorShape.PointingHandCursor)
        buttons.addStretch()  # Add stretch on left to push button right.
        buttons.addWidget(self.close_btn)
        layout.addLayout(buttons)

        self.text = QTextEdit()
        layout.addWidget(self.text)
        self.setLayout(layout)

        # Store a reference to this note in the active_notewindows
        active_notewindows[id(self)] = self

    def mousePressEvent(self, e):
        self.previous_pos = e.globalPosition()

    def mouseMoveEvent(self, e):
        delta = e.globalPosition() - self.previous_pos
        self.move(self.x() + delta.x(), self.y() + delta.y())
        self.previous_pos = e.globalPosition()


def create_notewindow():
    note = NoteWindow()
    note.show()


create_notewindow()

# Create the icon
icon = QIcon("sticky-note.png")

# Create the tray
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setVisible(True)


def handle_tray_click(reason):
    # If the tray is left-clicked, create a new note.
    if (
        QSystemTrayIcon.ActivationReason(reason)
        == QSystemTrayIcon.ActivationReason.Trigger
    ):
        create_notewindow()


tray.activated.connect(handle_tray_click)

app.exec()

If you run this now you will be able to right click the note in the tray to show the menu.

The sticky note icon in the tray showing its context menu

Test the Add note and Quit functionality to make sure they're working.

So, now we have our note UI implemented, the ability to create and remove notes and a persistent tray icon where we can also create notes & close the application. The last piece of the puzzle is persisting the notes between runs of the application -- if we leave a note on the desktop, we want it to still be there if we come back tomorrow. We'll implement that next.

Setting Up the SQLite Database with SQLAlchemy

To be able to store and load notes, we need an underlying data model. For this demo we're using SQLAlchemy as an interface to an SQLite database. This provides an Object-Relational Mapping (ORM) interface, which is a fancy way of saying we can interact with the database through Python objects.

We'll define our database in a separate file, to keep the UI file manageable. So start by creating a new file named database.py in your project folder.

In that file add the imports for SQLAlchemy, and instantiate the Base class for our models.

python

from sqlalchemy import Column, Integer, String, create_engine
from sqlalchemy.orm import declarative_base, sessionmaker

Base = declarative_base()

Next in the same database.py file, define our note database model. This inherits from the Base class we've just created, by calling declarative_base()

python

class Note(Base):
    __tablename__ = "note"
    id = Column(Integer, primary_key=True)
    text = Column(String(1000), nullable=False)
    x = Column(Integer, nullable=False, default=0)
    y = Column(Integer, nullable=False, default=0)

Each note object has 4 properties:

id the unique ID for the given note, used to delete from the database
text the text content of the note
x the x position on the screen
y the y position on the screen

Next we need to create the engine -- in this case, this is our SQLite file, which we're calling notes.db. We can then create the tables (if they don't already exist). Since our Note class registers itself with the Base we can do that by calling create_all on the Base class.

python

engine = create_engine("sqlite:///notes.db")

Base.metadata.create_all(engine)

Save the database.py file and run it

python database.py

After it is complete, if you look in the folder you should see the notes.db. This file contains the table structure for the Note model we defined above.

Finally, we need a session to interact with the database from the UI. Since we only need a single session when the app is running, we can go ahead and create it in this file and then import it into the UI code.

Add the following to database.py

python

# Create a session to handle updates.
Session = sessionmaker(bind=engine)
session = Session()

The final complete code for our database interface is shown below

python

from sqlalchemy import Column, Integer, String, create_engine
from sqlalchemy.orm import declarative_base, sessionmaker

Base = declarative_base()


class Note(Base):
    __tablename__ = "note"
    id = Column(Integer, primary_key=True)
    text = Column(String(1000), nullable=False)
    x = Column(Integer, nullable=False, default=0)
    y = Column(Integer, nullable=False, default=0)


engine = create_engine("sqlite:///notes.db")

Base.metadata.create_all(engine)

Session = sessionmaker(bind=engine)
session = Session()

Now that our data model is defined, and our database created, we can go ahead and interface our Notes model into the UI. This will allow us to load notes at startup (to show existing notes), save notes when they are updated and delete notes when they are removed.

Integrating SQLAlchemy with the PySide6 UI

Our data model holds the text content and x & y positions of the notes. To keep the active notes and model in sync we need a few things.

Each NoteWindow must have its own associated instance of the Note object.
New Note objects should be created when creating a new NoteWindow.
The NoteWindow should sync its initial state to a Note if provided.
Moving & editing a NoteWindow should update the data in the Note.
Changes to Note should be synced to the database.

We can tackle these one by one.

First let's setup our NoteWindow to accept, and store a reference to Note objects if provided, or create a new one if not.

python

import sys

from database import Note
from PySide6.QtCore import Qt
from PySide6.QtGui import QAction, QIcon
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QMenu,
    QPushButton,
    QSystemTrayIcon,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

app = QApplication(sys.argv)

# Store references to the NoteWindow objects in this, keyed by id.
active_notewindows = {}


class NoteWindow(QWidget):
    def __init__(self, note=None):
        super().__init__()

        # ... add to the bottom of the __init__ method

        if note is None:
            self.note = Note()
        else:
            self.note = note

In this code we've imported the Note object from our database.py file. In the __init__ of our NoteWindow we've added an optional parameter to receive a Note object. If this is None (or nothing provided) a new Note will be created instead. The passed, or created note, is then stored on the NoteWindow so we can use it later.

This Note object is still not being loaded, updated, or persisted to the database. So let's implement that next. We add two methods, load() and save() to our NoteWindow to handle the loading and saving of data.

python

from database import Note, session

# ... skipped other imports, unchanged.

class NoteWindow(QWidget):
    def __init__(self, note=None):
        super().__init__()

        # ... modify the close_btn handler to use delete.
        self.close_btn.clicked.connect(self.delete)


        # ... rest of the code hidden.

        # If no note is provided, create one.
        if note is None:
            self.note = Note()
            self.save()
        else:
            self.note = note
            self.load()

    # ... add the following to the end of the class definition.

    def load(self):
        self.move(self.note.x, self.note.y)
        self.text.setText(self.note.text)

    def save(self):
        self.note.x = self.x()
        self.note.y = self.y()
        self.note.text = self.text.toPlainText()
        # Write the data to the database, adding the Note object to the
        # current session and committing the changes.
        session.add(self.note)
        session.commit()

    def delete(self):
        session.delete(self.note)
        session.commit()
        del active_notewindows[id(self)]
        self.close()

The load() method takes the x and y position from the Note object stored in self.note and updates the NoteWindow position and content to match. The save() method takes the NoteWindow position and content and sets that onto the Note object. It then adds the note to the current database session and commits the changes.

Each commit starts a new session. Adding the Note to the session is indicating that we want its changes persisted.

The delete() method handles deletion of the current note. This involves 3 things:

passing the Note object to session.delete to remove it from the database,
deleting the reference to our window from the active_notewindows (so the object will be tidied up)
calling .close() to hide the window immediately.

Usually (2) will cause the object to be cleaned up, and that will close the window indirectly. But that may be delayed, which would mean sometimes the close button doesn't seem to work straight away. We call .close() to make it immediate.

We need to modify the close_btn.clicked signal to point to our delete method.

Next we've added a load() call to the __init__ when a Note object is passed. We also call .save() for newly created notes to persist them immediately, so our delete handler will work before editing.

Finally, we need to handle saving the note whenever it changes. We have two ways that the note can change -- when it's moved, or when it's edited. For the first we could do this on each mouse move, but it's a bit redundant. We only care where the note ends up while dragging -- that is, where it is when the mouse is released. We can get this through the mouseReleaseEvent method.

python

from database import Note, session

# ... skipped other imports, unchanged.

class NoteWindow(QWidget):

    # ... add the mouseReleaseEvent to the events on the NoteWindow.

    def mousePressEvent(self, e):
        self.previous_pos = e.globalPosition()

    def mouseMoveEvent(self, e):
        delta = e.globalPosition() - self.previous_pos
        self.move(self.x() + delta.x(), self.y() + delta.y())
        self.previous_pos = e.globalPosition()

    def mouseReleaseEvent(self, e):
        self.save()

    # ... the load and save methods are under here, unchanged.

That's all there is to it: when the mouse button is released, we save the current content and position by calling .save().

You might be wondering why we don't just save the position at this point? Usually it's better to implement a single load & save (persist/restore) handler that can be called for all situations. It avoids needing implementations for each case.

There have been a lot of partial code changes in this section, so here is the complete current code.

python

import sys

from database import Note, session
from PySide6.QtCore import Qt
from PySide6.QtGui import QAction, QIcon
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QMenu,
    QPushButton,
    QSystemTrayIcon,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

app = QApplication(sys.argv)

# Store references to the NoteWindow objects in this, keyed by id.
active_notewindows = {}


class NoteWindow(QWidget):
    def __init__(self, note=None):
        super().__init__()

        self.setWindowFlags(
            self.windowFlags()
            | Qt.WindowType.FramelessWindowHint
            | Qt.WindowType.WindowStaysOnTopHint
        )
        self.setStyleSheet(
            "background: #FFFF99; color: #62622f; border: 0; font-size: 16pt;"
        )
        layout = QVBoxLayout()

        buttons = QHBoxLayout()
        self.close_btn = QPushButton("×")
        self.close_btn.setStyleSheet(
            "font-weight: bold; font-size: 25px; width: 25px; height: 25px;"
        )
        self.close_btn.clicked.connect(self.delete)
        self.close_btn.setCursor(Qt.CursorShape.PointingHandCursor)
        buttons.addStretch()  # Add stretch on left to push button right.
        buttons.addWidget(self.close_btn)
        layout.addLayout(buttons)

        self.text = QTextEdit()
        layout.addWidget(self.text)
        self.setLayout(layout)

        self.text.textChanged.connect(self.save)

        # Store a reference to this note in the active_notewindows
        active_notewindows[id(self)] = self

        # If no note is provided, create one.
        if note is None:
            self.note = Note()
            self.save()
        else:
            self.note = note
            self.load()

    def mousePressEvent(self, e):
        self.previous_pos = e.globalPosition()

    def mouseMoveEvent(self, e):
        delta = e.globalPosition() - self.previous_pos
        self.move(self.x() + delta.x(), self.y() + delta.y())
        self.previous_pos = e.globalPosition()

    def mouseReleaseEvent(self, e):
        self.save()

    def load(self):
        self.move(self.note.x, self.note.y)
        self.text.setText(self.note.text)

    def save(self):
        self.note.x = self.x()
        self.note.y = self.y()
        self.note.text = self.text.toPlainText()
        # Write the data to the database, adding the Note object to the
        # current session and committing the changes.
        session.add(self.note)
        session.commit()

    def delete(self):
        session.delete(self.note)
        session.commit()
        del active_notewindows[id(self)]
        self.close()


def create_notewindow():
    note = NoteWindow()
    note.show()


create_notewindow()

# Create the icon
icon = QIcon("sticky-note.png")

# Create the tray
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setVisible(True)


def handle_tray_click(reason):
    # If the tray is left-clicked, create a new note.
    if (
        QSystemTrayIcon.ActivationReason(reason)
        == QSystemTrayIcon.ActivationReason.Trigger
    ):
        create_notewindow()


tray.activated.connect(handle_tray_click)


# Don't automatically close app when the last window is closed.
app.setQuitOnLastWindowClosed(False)

# Create the menu
menu = QMenu()
# Add the Add Note option to the menu.
add_note_action = QAction("Add note")
add_note_action.triggered.connect(create_notewindow)
menu.addAction(add_note_action)

# Add a Quit option to the menu.
quit_action = QAction("Quit")
quit_action.triggered.connect(app.quit)
menu.addAction(quit_action)
# Add the menu to the tray
tray.setContextMenu(menu)


app.exec()

If you run the application at this point it will be persisting data to the database as you edit it.

If you want to look at the contents of the SQLite database I can recommend DB Browser for SQLite. It's open source & free.

The note data persisted to the SQLite database

Restoring Notes on Startup

So our notes are being created, added to the database, updated and deleted. The last piece of the puzzle is restoring the previous state at start up.

We already have all the bits in place for this, we just need to handle the startup itself. To recreate the notes we can query the database to get a list of Note objects and then iterate through this, creating new NoteWindow instances (using our create_notewindow function).

python

def create_notewindow(note=None):
    note = NoteWindow(note)
    note.show()


existing_notes = session.query(Note).all()

if existing_notes:
    for note in existing_notes:
        create_notewindow(note)
else:
    create_notewindow()

First we've modified the create_notewindow function to accept an (optional) Note object which is passed through to the created NoteWindow.

Using the session we query session.query(Note).all() to get all the Note objects. If there any, we iterate them creating them. If not, we create a single note with no associated Note object (this will be created inside the NoteWindow).

That's it! The full final code is shown below:

python

import sys

from database import Note, session
from PySide6.QtCore import Qt
from PySide6.QtGui import QAction, QIcon
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QMenu,
    QPushButton,
    QSystemTrayIcon,
    QTextEdit,
    QVBoxLayout,
    QWidget,
)

app = QApplication(sys.argv)

# Store references to the NoteWindow objects in this, keyed by id.
active_notewindows = {}


class NoteWindow(QWidget):
    def __init__(self, note=None):
        super().__init__()

        self.setWindowFlags(
            self.windowFlags()
            | Qt.WindowType.FramelessWindowHint
            | Qt.WindowType.WindowStaysOnTopHint
        )
        self.setStyleSheet(
            "background: #FFFF99; color: #62622f; border: 0; font-size: 16pt;"
        )
        layout = QVBoxLayout()

        buttons = QHBoxLayout()
        self.close_btn = QPushButton("×")
        self.close_btn.setStyleSheet(
            "font-weight: bold; font-size: 25px; width: 25px; height: 25px;"
        )
        self.close_btn.clicked.connect(self.delete)
        self.close_btn.setCursor(Qt.CursorShape.PointingHandCursor)
        buttons.addStretch()  # Add stretch on left to push button right.
        buttons.addWidget(self.close_btn)
        layout.addLayout(buttons)

        self.text = QTextEdit()
        layout.addWidget(self.text)
        self.setLayout(layout)

        self.text.textChanged.connect(self.save)

        # Store a reference to this note in the active_notewindows
        active_notewindows[id(self)] = self

        # If no note is provided, create one.
        if note is None:
            self.note = Note()
            self.save()
        else:
            self.note = note
            self.load()

    def mousePressEvent(self, e):
        self.previous_pos = e.globalPosition()

    def mouseMoveEvent(self, e):
        delta = e.globalPosition() - self.previous_pos
        self.move(self.x() + delta.x(), self.y() + delta.y())
        self.previous_pos = e.globalPosition()

    def mouseReleaseEvent(self, e):
        self.save()

    def load(self):
        self.move(self.note.x, self.note.y)
        self.text.setText(self.note.text)

    def save(self):
        self.note.x = self.x()
        self.note.y = self.y()
        self.note.text = self.text.toPlainText()
        # Write the data to the database, adding the Note object to the
        # current session and committing the changes.
        session.add(self.note)
        session.commit()

    def delete(self):
        session.delete(self.note)
        session.commit()
        del active_notewindows[id(self)]
        self.close()


def create_notewindow(note=None):
    note = NoteWindow(note)
    note.show()


existing_notes = session.query(Note).all()

if existing_notes:
    for note in existing_notes:
        create_notewindow(note)
else:
    create_notewindow()

# Create the icon
icon = QIcon("sticky-note.png")

# Create the tray
tray = QSystemTrayIcon()
tray.setIcon(icon)
tray.setVisible(True)


def handle_tray_click(reason):
    # If the tray is left-clicked, create a new note.
    if (
        QSystemTrayIcon.ActivationReason(reason)
        == QSystemTrayIcon.ActivationReason.Trigger
    ):
        create_notewindow()


tray.activated.connect(handle_tray_click)


# Don't automatically close app when the last window is closed.
app.setQuitOnLastWindowClosed(False)

# Create the menu
menu = QMenu()
# Add the Add Note option to the menu.
add_note_action = QAction("Add note")
add_note_action.triggered.connect(create_notewindow)
menu.addAction(add_note_action)

# Add a Quit option to the menu.
quit_action = QAction("Quit")
quit_action.triggered.connect(app.quit)
menu.addAction(quit_action)
# Add the menu to the tray
tray.setContextMenu(menu)


app.exec()

If you run the app now, you can create new notes as before, but when you exit (using the Quit option from the tray) and restart, the previous notes will reappear. If you close the notes, they will be deleted. On startup, if there are no notes in the database an initial note will be created for you.

Conclusion

That's it! We have a fully functional desktop sticky notes application built with Python, PySide6 and SQLAlchemy. You can use it to keep simple bits of text until you need them again. We've learnt how to build an application up step by step from a basic outline window. We've added basic styles using QSS and used Qt window flags to create frameless, always-on-top windows. We've also seen how to create a system tray application with QSystemTrayIcon, adding context menus and default behaviors (via a left mouse click). Finally, we've created a simple data model using SQLAlchemy and SQLite, and hooked that into our UI to persist the note state between sessions.

Try and extend this example further, for example:

Add multicolor notes, using a Python list of hex colors and random.choice to select a new color each time a note is created. Can you persist this in the database too?
Add an option in the tray to show/hide all notes. Remember we have all the NoteWindow objects in active_notewindows. You can show and hide windows in Qt using .show() and .hide().

Think about some additional features you'd like or expect to see in a desktop notes application and see if you can add them yourself!

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Getting Started With PyCharm for Python GUI Development — The Python-Specific Integrated Development Environment

2025-01-04T06:00:00+00:00

Setting up a good development environment for Python GUI programming can make the coding process friendly and provide the necessary tools to maintain the codebase for many years to come. Choosing the right tools and being comfortable with them is a critical step for any Python developer.

Code editors are among the most common and used development tools. They're where we write the code. While most modern code editors support features like syntax highlighting, which shows visual cues to differentiate parts of the source code, we often need to rely on external tools to help us debug and look for errors, install packages, manage Python environments, and so on.

To have all these features in a single program, you'll need an integrated development environment (IDE). Although there are several Python IDEs, in this article, we'll be exploring PyCharm, which is a powerful IDE for Python developers. We'll walk through setting up PyCharm and building a simple PyQt6 GUI application from scratch.

Install Python

Before installing PyCharm, we need to make sure that Python is installed on the development machine. If it isn't installed yet, then we can go to the official download page and grab the specific installer for either Windows or macOS.

Make sure to select the Add Python to PATH option during the installation process.

On Linux systems, you can check if Python is already installed by running python3 --version in a terminal. If this command returns an error, then you need to install Python from your distribution's repository or from the source.

If you're running a Debian-based distribution, such as Ubuntu and Linux Mint, you can install Python by running sudo apt install python3. It may be necessary to run sudo apt install python3-pip python3-venv, so that PyCharm can use pip and venv to install packages and manage virtual environments.

Install PyCharm

We have a few different ways to install PyCharm. The recommended way is to head over to the official download page and grab the standalone installer for Windows, macOS, or Linux. Then, you'll need to run the installer and follow the on-screen instructions.

If you're using a Linux distro that supports Snaps, you can also install it by running sudo snap install pycharm-community --classic in your terminal.

PyCharm has a Community edition, which is free and open-source. It also has a Professional edition, which is paid. While this tutorial uses PyCharm Community edition, the covered topics apply to both editions. Check out the comparison between both editions for the details.

Alternatively, you could install PyCharm via the Toolbox app, which makes it easier to update or rollback to any version of PyCharm. This app can also be used to install and manage other JetBrains products.

NOTE: For more platform-specific information, check out PyCharm's installation guide.

Create a New PyQt6 Project in PyCharm

To demonstrate PyCharm's workflow, we'll create a basic Python GUI app using PyQt. Before we start writing code, we need to first launch PyCharm and create a new project. Creating a project helps you differentiate between files, code, packages, and settings.

Go ahead and launch PyCharm. Depending on your operating system, you can run PyCharm by going to the Start Menu on Windows, Launchpad on macOS, or by running the pycharm executable (under install-folder/bin) on Linux. However, if you installed PyCharm using Toolbox, then open the Toolbox app and launch PyCharm from there.

Read the PyCharm documentation to learn how to run PyCharm from the command-line interface.

When we launch PyCharm, the first thing we'll see is its Welcome to PyCharm window:

PyCharm's Welcome window

Here's where we can create new projects or open existing ones—either stored locally on our computer or in online code repositories like GitHub.

To continue, click the New Project button and then choose a project's name and location folder in the New Project window. You can also define the Python environment to use but keep the default configuration for now:

PyCharm's New Project window

Finally, click the Create button on the lower, right corner to create the project and open it in PyCharm's main window, also known as Project Window.

Get Familiar With PyCharm's Interface

The Project Window is where we'll spend most of our time in PyCharm. It's where we manage files, write code, install packages, and do everything related to the project we are working on.

NOTE: This article covers PyCharm's modern user interface. You can also use the classic user interface by going to File -> Settings and disabling New UI under Appearance & behavior. On macOS, you can access the Settings menu from the Menu Bar at the top of your screen.

Let's examine the components of PyCharm's interface and see what they do:

PyCharm's Project Window

The Project Window interface has the following four main components:

Window Header
Editor
Sidebar
Status bar

In the following sections, we'll explore these UI components in more detail.

Window Header

The Window Header is at the very top of PyCharm's Project Window and gives us quick access to some commonly used features, most notably the Run button. Using the Run button, we can run or debug our Python project directly from PyCharm — without having to type the relevant Python command in a terminal.

The Window Header looks something like this:

PyCharm's Window Header

Other significant components of the Window Header are the Main Menu and the Project widget.

PyCharm's Main Menu is accessible by clicking on the hamburger menu, whereas the Project widget displays the name of the current project and allows us to switch between projects as well as create new ones.

On macOS, however, we don't have a hamburger menu in the Window Header but we can still access PyCharm's Main Menu through the Menu Bar at the top of the screen, like with other macOS apps.

Editor

The Editor is where we actually read, write, and edit code. It has a scrollbar on the right to help us navigate large files. It also has a Gutter on the left, which displays line numbers for the file. The Gutter also provides us with context-dependent actions like running code or temporarily hiding functions and classes:

PyCharm's Editor window

At the top, the Editor has a tabbed interface to display the open files and switch between them at any time. To switch to another open file, we can either click the relevant tab or press CTRL + TAB to scroll through all of them. If necessary, we can also open files from external folders that are outside the project's folder by attaching that folder to the current project.

The Editor can open any plaintext file format, such as .py and .md, for editing. It also supports viewing both raster and vector image formats, such as PNG and SVG. However, note that most binary files, such as video, audio, and executable files are not supported by the Editor and will be opened outside of PyCharm.

Sidebar and Tool Windows

The Sidebar has buttons to open and close tool windows, which are displayed at the bottom or left side of PyCharm's Project Window:

PyCharm's sidebar and the Project tool window

The Project tool window is normally open by default. It displays the folder structure of the current project and allows us to open, create, and delete files and folders. If you have any external folders attached to the current project, the Project tool window will also display the structure of those folders.

PyCharm also has tool windows for running code, installing packages from PyPI using a graphical interface, and using version control software. Throughout the rest of this article, we'll learn how to use these tool windows as we build our sample Python GUI app.

Status Bar

The Status Bar is the horizontal bar at the bottom of PyCharm's workspace. It indicates the status of both our project and the entire IDE:

PyCharm's status bar

It provides information about the file that's currently opened in the Editor, such as its encoding, line separator, cursor position, and indentation type. It also gives quick access to the Python Interpreter settings, which we'll cover in more detail later.

Install PyQt6 in PyCharm

One thing we need to do before starting our GUI app is to install the PyQt library. We'll use this library to build the app's GUI. This library doesn't come with Python but can be installed from the PyPI software repository using the pip command.

However, PyCharm simplifies the installation by providing a tool window for us to search, install, and manage Python packages. To open the Python Packages tool window, go to the Sidebar and look for the Python Packages button, which is shown in blue in the following screenshot:

PyCharm's Python Packages tool window

Using the search field, look for the PyQt6 package. We can have a look at the README file (on the right side) for each package by clicking on the package's name (on the left side). Once we've found the package, we can click Install next to the package's name and choose the package version we want to install.

A README file typically provides information about what a package does, how to install and use the package, what license the package is distributed under, and so on.

When we clear the search field, PyQt6 should now be listed as Installed:

PyCharm's Python Packages tool window with PyQt6 ready to be installed

If a newer version of an installed package is available, then PyCharm will indicate it by displaying a link with the current and next version (next to the package name) that we can click to upgrade:

PyCharm's Python Packages tool window with PyQt6 installed

You can also uninstall a Python package. To do this, click the package's name and go to the kebab menu on the top-right corner of the README preview section. Then, click Delete Package to uninstall the package:

PyCharm's Python Packages tool window showing how to uninstall a package

Uninstalling Python packages from a virtual environment isn't something that we do often but PyCharm has a nice interface to do it if we need to.

Write a PyQt6 GUI Application in PyCharm

In this section, we will focus on writing and editing code in PyCharm to build our sample GUI app. For its GUI, the app will have one window with a Press Me button. To start coding though, we need a Python file.

NOTE: This guide will not cover PyQt extensively. To learn more about this library, check out the Creating your first app with PyQt6 tutorial.

To create a file, go to the Projects tool window and right-click the project's folder to open its context menu. Then, go to New and select Python File as the desired file type:

PyCharm's context menu to create a new Python file

This action will open a dialog where PyCharm will ask you to enter a filename. For this project, we will just name the file as app and press ENTER:

PyCharm's dialog to name a new Python file

The Project tool window will now list a file named app.py under the project's folder. To open that file in the Editor, double-click on the filename and you'll see a blank Python file:

The app.py file opened in PyCharm's Editor

The Editor works like any other standard text editor or code editor. We enter text using the keyboard and press ENTER to create a new line. We can use the Gutter to track the line number we are currently on.

Now that we have a Python file in our project folder, we can start coding. First, we will import the required Python modules, packages, and classes:

python

import sys
from PyQt6.QtCore import QSize, Qt
from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton

As we type the import statements in the Editor, PyCharm will offer suggestions for matching keywords and Python packages using a pop-up:

PyCharm's code suggestions pop-up

You can use the Up and Down arrow keys to navigate the list of suggestions. Then, press TAB to select the highlighted suggestion.

Using PyCharm's Error Detection and Code Fixes

Another useful feature of PyCharm is its ability to detect errors and provide fixes for problematic code. The following code block deliberately includes a few errors to demonstrate this feature:

python

QApplication
window = MainWindow()
window.show()
app.exec()

In this code, we haven't instantiated QApplication correctly. This error produces a cascade of errors that PyCharm nicely spots for us:

PyCharm's error detection feature

PyCharm detects a few errors in the code we just typed. It indicates the error by highlighting the relevant piece of code with a squiggly line.

The color of the squiggly line indicates the severity of the problem PyCharm detected. Any problem highlighted in red is a critical error that prevents the program from running and everything else is marked in yellow.

To discover what an error is about, we can drag the mouse pointer to the highlighted section and hover over it to see a tooltip as shown below:

PyCharm's error tips: statement with no effect

PyCharm's tooltip says that the statement QApplication has no effect. This is because we are just referencing a class without creating a concrete object. As a result, PyCharm flags a critical error in the last line because the app name hasn't been assigned yet.

We can fix both errors by instantiating QApplication to create an object named app:

python

app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

We've taken care of two problems detected by PyCharm, but there is still one critical error remaining. If we hover the mouse's pointer over the highlighted object, we'll see that PyCharm is complaining about window = MainWindow() because we are using a class that we haven't defined yet:

PyCharm's error tips: unresolved reference

To fix the issue, right-click the highlighted object to open the associated Context Menu. Once you see the menu, select Show Context Actions. This will open another pop-up where PyCharm offers smart suggestions to fix the problem.

For this particular problem, we'll choose the option Create class 'MainWindow' in module app.py as shown below:

PyCharm's Context Actions pop-up

PyCharm automatically generates an empty class named MainWindow. Update the class as follows in order to specify how the app's GUI will look:

python

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My App")
        button = QPushButton("Press Me!")
        self.setFixedSize(QSize(400, 300))
        self.setCentralWidget(button)

Complete PyQt6 Application Code

With this update done, the complete code for app.py should look something like the following:

python

import sys
from PyQt6.QtCore import QSize, Qt
from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My App")
        button = QPushButton("Press Me!")
        self.setFixedSize(QSize(400, 300))
        self.setCentralWidget(button)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Now you have a working PyQt6 desktop application. The next step is to run the app using PyCharm's features but before that, let's summarize what we've learned so far.

We learned how to create a file using the Project tool window and then edit it using the Editor. We also learned how to use some of the assistive coding features provided by PyCharm to get code suggestions, fix problems in our code, and generate boilerplate code for a faster coding experience.

Run Python GUI Code in PyCharm

PyCharm provides a convenient way to run code through its interface. To run our PyQt6 app, right-click on the Editor's work area to open the Context Menu. Then, select the Run 'app' option:

Running code with PyCharm's Run option from the Editor's context menu

The option to run code using the Run option in the context menu can be appropriate for short apps or scripts. However, when you have a much larger project with more than one file, it's often convenient to configure a default Python file for a project to run.

To do so, right-click on the app.py file in the Editor to show the Context Menu. Then, select Modify Run Configuration... as in the following screenshot:

Modifying the Run Configuration in PyCharm

Once you select the Modify Run Configuration..., you get presented with the Edit Run Configuration dialog:

PyCharm's Edit Run Configuration dialog

In the Edit Run Configuration dialog, we can modify the path to the Python script or set additional command-line arguments to pass when running the project. We can also set a name for this configuration at the top of the dialog and click the OK button.

Now, we'll see the app configuration next to the green Run button on the Window Header. This indicates which script PyCharm will run by default. If we have more than one Run Configuration, then we can switch between them by clicking on the dropdown menu next to the Run button.

Once we have set the project's default Run Configuration, we can run the associated script regardless of which file we are currently working on the Editor by clicking on the Run button in the Window Header:

Running code with PyCharm's Run button from the Window Header

To terminate the app's execution from the PyCharm interface, click the Stop button in the Window Header.

Configure a Python Virtual Environment in PyCharm

Python's best practices recommend avoiding the system interpreter in favor of using a virtual environment. A Python virtual environment is an isolated copy of the system interpreter that we create for development purposes.

For most large projects, you should create a dedicated virtual environment. As we noted earlier, PyCharm creates a virtual environment by default whenever we create a new project. This allows us to manage the project's dependencies separately because they are installed in the dedicated Python environments rather than globally in your system.

We can see the installed packages in our current Python environment by clicking on the Python interpreter selector (in the Status Bar) and clicking on the Manage Packages... option. This action opens the Python Packages tool window, which we previously used to install PyQt6:

Managing Python packages in PyCharm

We can create a new Python virtual environment for our project by going to Add New Interpreter > Add Local Interpreter:

Creating a new Python virtual environment in PyCharm - Step 1

After clicking on the Add Local Interpreter option, you get presented with the Add Python Interpreter dialog. There, you'll find several options to create working environments for Python coding. For the purposes of this guide, we'll only look at creating a standard Virtualenv Environment:

Creating a new Python virtual environment in PyCharm - Step 2

Specify where to create the Python virtual environment and select a base interpreter from the dropdown list if you have more than one version of Python. Then, click the OK button to create the new Python environment for the active project. We can see the current Python environment by looking at the Python interpreter selector in the right bottom corner of the Status Bar.

Because this is a brand new virtual environment, trying to run the app now will fail because we haven't installed PyQt6 in this Python environment.

To switch back to the previous Python environment, click on the interpreter selector and select the relevant interpreter from the list:

Changing the Python virtual environment in PyCharm

To get back to the original Python environment, select the Python 3.10 (PyQt6app) menu option in the dropdown list.

Use Git for Version Control in PyCharm

Version control systems (VCS) allow us to track changes to a project's codebase. They are useful because they let us know what has changed in the app and who is responsible, which is particularly important when working with teams. VCSs also make it easy to revert any changes we make, giving us more freedom to test out new features.

PyCharm has built-in support for several VCSs. In this tutorial, we'll focus on Git, which is one of the most popular. In this section, we'll go over how to create and manage a Git repository for a Python GUI project in PyCharm.

WARNING: To use Git-related features in PyCharm, Git needs to be installed. If you haven't done so already, please follow this guide to install and set up Git on your computer.

Track Changes in a Project

You can use Git via its command-line interface. However, PyCharm allows us to perform common version control tasks through a graphical interface.

To enable version control for the current project, go to the Version Control tool window at the bottom of the Sidebar and click on Create Git Repository link:

PyCharm's Version Control tool window

Once you click the Create Git Repository link, you get the Create Git Repository dialog:

PyCharm's Create Git Repository dialog

Once you create the Git repository, the tool window will update its view to provide additional information. It should be mostly blank right now because we haven't started tracking any files.

To start tracking project files, we need to commit to the Git repository. To do that, a tool window named Commit will appear in the Sidebar (near the top).

A commit is a snapshot of the current state of all the files in a project. Each time we make a significant change to our codebase, we make a commit to mark what changed and by whom.

Open the tool window and look at the section named Changes:

PyCharm's Commit tool window

The Changes section under Commit shows any project files that have changed or aren't being tracked. Because we aren't tracking any files for now, all of our project files appear under Unversioned Files.

We can select which files we would like to include in a commit by marking the checkbox next to each filename. For this project, select all of the Unversioned Files in the first commit.

There's a text box right below the Changes section where you can type a commit message to describe what changed in these files. Because this will be our first commit for the current project, we can write a message like "Initial commit":

Select the files to commit and add a commit message in PyCharm

Once we've selected the files to include in the commit and typed the commit message, we can make the commit by pressing the Commit button underneath. The commit we made should now appear in the Version Control tool window:

PyCharm's Version Control tool window showing a commit

We'll make one more commit to this project by changing the text of the button in app.py from "Press Me!" to "Press This Button!":

python

class MainWindow(QMainWindow):
    def __init__(self):
        ...
        button = QPushButton("Press This Button!")
        ...

When a project is version-controlled, PyCharm will indicate when a line has been added, modified, or deleted from a file by showing a colored indicator next to the line number in the gutter. The indicator disappears once we commit the changed file to the repository again:

PyCharm showing a colored indicator for modified lines

Go to the Commit tool window, select app.py under Changes, type a commit message like "Changed button text," and then press the Commit button again. You'll see the new commit appear above the previous one in the Version Control tool window:

PyCharm's Version Control tool window showing the commit history

This is called the commit history, where we can see all the changes or commits that we've made in a project.

Push a PyCharm Project to GitHub

We've created a local Git repository and want to publish the project to a remote repository on GitHub. Before doing that, we need to authenticate so that PyCharm can access, create, and delete remote repositories on our GitHub account.

We could authenticate manually using SSH. However, PyCharm simplifies the process by integrating GitHub and GitLab right into the IDE. To authenticate, go to Settings and look for GitHub under Version Control. Then, click on the plus (+) sign and select the Log In via GitHub option:

Log in to GitHub through PyCharm's UI

A browser window should open and ask you to confirm whether you want to authorize PyCharm to access your GitHub account. Once you confirm by selecting Authorize in GitHub, you will be redirected to GitHub:

Authorize PyCharm in GitHub

If you aren't already signed in, you will be shown the login page where you can sign up too if you don't already have a GitHub account:

GitHub's log in page for authorizing PyCharm

Once you provide your GitHub credentials and click the Sign in button, you'll get your GitHub account listed in the Version Control screen:

GitHub account authorized in PyCharm

PyCharm only needs to be authorized once for each user on a computer.

Once PyCharm is authorized, we also need to create a new, empty remote repository. Go back to the GitHub website and click on the plus sign (+) at the top of your Dashboard to create a new repository:

Creating a new GitHub repository from the Dashboard

Let's give this repository a unique name related to the project we are working on:

Create a new repository page on GitHub

Depending on who you plan to share this project with, you can also set the repository's visibility to be public or private. Then, click the Create Repository button and copy the remote repository URL:

New repository on GitHub

Finally, click on the VCS widget in PyCharm's Window Header to Push all the commits we've made in the local repository to the remote repository we just created on GitHub:

Pushing to GitHub through PyCharm's UI

Then, we need to specify where the remote repository is located. So, click on Define Remote and paste the repository's URL into the corresponding input box:

Setting the GitHub repository's URL through PyCharm's UI

Click OK and then select the Push button:

Pushing commits to GitHub through PyCharm's UI

Now, any commits we made to our project will be visible in the remote repository on GitHub. If we go back to GitHub, we can see that it's no longer an empty repository:

Populated repository on GitHub

The Version Control tool window should also display the name we set for the remote next to the latest commit:

PyCharm's Version Control tool window showing the remote repository

To make the next commit, make your changes and go to the Commit tool window, where you can click the Commit and Push... button to do both actions in one go:

Committing new changes through PyCharm's UI

We can also go to the VCS widget and select Push to do this at any time.

Explore Other Useful PyCharm Features for GUI Development

PyCharm has several features that help us write Python GUI code more efficiently and make development smoother. In this section, we'll explore some of these features and learn how to use them.

Search Everywhere

Projects can become quite large spanning multiple files and folders. By using the Search Everywhere feature, we can look through the whole project for files, classes, lines of code and even specific actions like Commit or Push. This feature also allows us to quickly find PyCharm's Settings and tool windows without using our mouse.

To use Search Everywhere, double-tap the SHIFT key. You'll get presented with the search window:

PyCharm's Search Everywhere window

To specify what you are looking for, press TAB to switch between Classes, Files, Symbols, Actions, and so on. It also supports evaluating mathematical expressions and filtering out certain file types via the Filter button at the top-right corner.

Code With Me

There are times when we need to give temporary access to other developers so that they can review our code and provide assistance. In these cases, we can use PyCharm's Code With Me feature to create a shared session between a host and one or more guests.

The guests can see what the host is doing in PyCharm and can be allowed to edit files in the project in real time. We can also share the camera and microphone so we can discuss with others who joined that session.

To start a session, click on the Code With Me icon at the top-right of the window header next to the Run button:

PyCharm's Code With Me feature

After selecting the Start Session... option from the menu, PyCharm will allow you to configure what guests can and can't do in this session:

PyCharm's Code With Me: Start Session dialog

NOTE: You can use Code With Me for free in PyCharm Community edition but there are limits on the number of guests allowed and the session time. You can learn more about the specific limits for the Community plan of Code With Me on their website.

Once we set permissions for our guests, PyCharm will create a link we need to send to the guests we are inviting. To copy the link, click on the Code With Me icon again and select Copy Session Link from the menu.

When a guest clicks the link, we will receive a popup in PyCharm asking us to either accept or decline the guest. If we accept, they will be able to use a lightweight installation of PyCharm just using their web browser through which we can collaborate.

It is always recommended to use Git for collaborating with others on a project. Code With Me can't tell who made a change or why that change was made. More importantly, it requires an active connection to the host's computer to make changes to the project and guests have limited access to PyCharm's features.

Sync Python Requirements

Earlier in this guide, we installed the PyQt6 package to build the interface of our sample app. Most software we develop depends on third-party Python packages for essential features. In collaborative contexts, we often need to keep track of our project's dependencies so that everyone working with us knows what to install.

In Python, developers typically create a requirements.txt file that lists all the needed packages and their recommended versions. You can create this file manually. However, PyCharm provides tools to generate a requirements.txt file using its UI.

As a best practice, you should update a project's requirements.txt file whenever the dependencies change.

To generate the file, use Search Everywhere to find the Sync Python Requirements action:

Searching for the Sync Python Requirements action in PyCharm's Search Everywhere

Selecting the Sync Python Requirements action will open a dialog where we can specify how to handle package versions and manage the requirements file:

PyCharm's Sync Python Requirements dialog

Once we click the OK button, PyCharm will create the file and populate it with the names and versions of the required Python packages.

If we look at the Project tool window, we'll see the new requirements.txt file in the project directory. If we open the file, we will see PyQt6 listed with its package version:

The requirements.txt file listed on PyCharm's Project tool window

Remember to run the Sync Python Requirements action again whenever you install or update Python packages in your project.

TODOs

Keeping track of changes already made in a project is important, but so is tracking what we still need to do. We can keep track of what needs to be done using TODOs. A TODO is a comment in our code that we start with # TODO:

A TODO comment on PyCharm's editor and TODO tool window

PyCharm will track these comments across the whole project, and we can view them all at any time in the TODO tool window. This tool window has several options to filter the TODOs:

PyCharm's TODO filtering options

We can see every single TODO across the project by selecting the Project tab or just the ones in the current file with Current File. We can be even more specific by looking only at files that were recently viewed, changed, or are currently open by selecting the Scope Based option.

When we use Git for version control, PyCharm will also show the number of remaining TODOs in each commit:

PyCharm showing the number of remaining TODOs

Scratches

Scratches are another interesting PyCharm feature that allows us to write temporary notes or draft code without touching any of the project files. To add a scratch, go to the Project tool window and right-click on Scratches and Consoles entry:

Creating a Scratch file from PyCharm's Project tool window

The New -> Scratch File option will open a dialog where you can select the type of scratch file you want to create.

Plugin Marketplace

While PyCharm is already packed with features to aid development, it is also highly extensible thanks to its Plugin marketplace. We can customize our PyCharm installation by getting themes and other plugins that provide additional functionality.

To use the Plugin marketplace, click on the Settings icon on the Window Header and select Plugins:

PyCharm's Plugin marketplace

In the Plugin marketplace, we can see installed plugins as well as those that are available in the marketplace. To install a plugin, click the Install button and wait for PyCharm to download and install it.

Summary

In this tutorial, you have learned how to install and set up the PyCharm IDE for Python GUI development with PyQt6. You've also learned how to write and run Python code in PyCharm as well as how to install external Python packages like PyQt6 using the IDE's graphical interface. You are now able to create and configure a Python virtual environment and use Git for version control in your projects.

Finally, you explored several additional useful features for working with GUI applications in PyCharm, including Search Everywhere, Code With Me, requirements syncing, TODOs, scratches, and the plugin marketplace. With this knowledge, you are now ready to confidently use PyCharm to develop your own Python GUI apps and desktop applications.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Saving and Restoring Application Settings with QSettings in PySide6 — Learn how to use QSettings to remember user preferences, window sizes, and configuration options between sessions

2024-10-09T09:00:00+00:00

QSettings is a class provided by Qt (and available through PySide6) that gives you a simple, cross-platform way to store and retrieve application settings. It handles all the platform-specific details for you — on Windows it uses the registry, on macOS it uses property list files, and on Linux it uses configuration files. You just read and write values, and Qt figures out the rest.

In this tutorial, we'll walk through everything you need to know to start using QSettings effectively in your PySide6 applications.

Creating a QSettings Object

To use QSettings, you first need to create an instance. The most common way is to pass in your organization name and application name:

python

from PySide6.QtCore import QSettings

settings = QSettings('MyCompany', 'MyApp')

You can check exactly where your settings file lives by printing the file path:

python

print(settings.fileName())

On Linux, this might print something like:

python

/home/username/.config/MyCompany/MyApp.conf

On Windows, it would point to a registry path, and on macOS, a .plist file. You don't need to worry about these differences — QSettings handles it for you.

Storing Values

Saving a setting is as simple as calling setValue() with a key and a value:

python

settings.setValue('theme', 'Dark')
settings.setValue('font_size', 14)
settings.setValue('show_toolbar', True)

The key is a string that you'll use later to retrieve the value. The value can be a string, integer, boolean, list, or other common Python types. QSettings will serialize it appropriately.

That's it — the value is saved. When you call setValue(), the data is written to persistent storage (the exact timing depends on the platform, but it happens automatically).

Reading Values Back

To read a setting, use value():

python

theme = settings.value('theme')
print(theme)  # 'Dark'

If the key doesn't exist (for example, the very first time your app runs), value() returns None by default. You can provide a default value as the second argument:

python

theme = settings.value('theme', 'Light')

Now if there's no theme key stored yet, you'll get 'Light' instead of None.

Handling Types

To handle this, you can pass the type parameter:

python

font_size = settings.value('font_size', 14, type=int)
show_toolbar = settings.value('show_toolbar', True, type=bool)

Checking if a Setting Exists

Before reading a value, you might want to check whether it has been set at all. Use contains():

python

if settings.contains('theme'):
    theme = settings.value('theme')
    print(f'Found saved theme: {theme}')
else:
    print('No theme saved yet, using default')
    settings.setValue('theme', 'Light')
    theme = 'Light'

This pattern is useful when you want to distinguish between "the user explicitly set this value" and "this is just the default."

A Complete Example

Let's put this all together in a small PySide6 application that remembers the window size and position, as well as a user-selected theme. When you close the app, it saves these settings. When you reopen it, everything is restored.

python

import sys
from PySide6.QtWidgets import (
    QApplication, QMainWindow, QComboBox,
    QVBoxLayout, QWidget, QLabel
)
from PySide6.QtCore import QSettings, QSize, QPoint


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.settings = QSettings('MyCompany', 'MyApp')

        self.setWindowTitle("QSettings Demo")

        # Create a simple UI with a theme selector
        layout = QVBoxLayout()

        layout.addWidget(QLabel("Choose a theme:"))

        self.theme_combo = QComboBox()
        self.theme_combo.addItems(['Light', 'Dark', 'Blue'])
        layout.addWidget(self.theme_combo)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

        # Restore settings
        self.load_settings()

    def load_settings(self):
        # Restore window size and position
        size = self.settings.value('window_size', QSize(400, 300))
        position = self.settings.value('window_position', QPoint(100, 100))
        self.resize(size)
        self.move(position)

        # Restore theme selection
        theme = self.settings.value('theme', 'Light')
        index = self.theme_combo.findText(theme)
        if index >= 0:
            self.theme_combo.setCurrentIndex(index)

    def save_settings(self):
        self.settings.setValue('window_size', self.size())
        self.settings.setValue('window_position', self.pos())
        self.settings.setValue('theme', self.theme_combo.currentText())

    def closeEvent(self, event):
        self.save_settings()
        super().closeEvent(event)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Let's walk through what's happening:

In __init__, we create a QSettings object with our organization and app names.
load_settings() reads values from persistent storage and applies them to the window and widgets. Notice how we pass default values (QSize(400, 300), QPoint(100, 100), 'Light') so the app has sensible starting values on the very first run.
save_settings() writes the current window size, position, and theme to settings.
closeEvent() is a built-in Qt method that gets called when the window is about to close. We override it to save our settings right before that happens.

If you're new to creating windows in PySide6, our tutorial on creating your first window covers the basics of setting up a QMainWindow.

Removing Settings

If you need to delete a stored setting, use remove():

python

settings.remove('theme')

This removes the theme key entirely. After this, settings.contains('theme') would return False.

Listing All Keys

To see everything that's currently stored, use allKeys():

python

keys = settings.allKeys()
print(keys)  # ['theme', 'font_size', 'show_toolbar', ...]

This can be handy for debugging, or if you want to iterate over all settings to display them in a preferences dialog.

Organizing Settings with Groups

As your app grows, you might end up with a lot of settings. QSettings supports groups, which let you organize keys into sections — similar to folders:

python

settings.beginGroup('appearance')
settings.setValue('theme', 'Dark')
settings.setValue('font_size', 14)
settings.endGroup()

settings.beginGroup('network')
settings.setValue('timeout', 30)
settings.setValue('retry_count', 3)
settings.endGroup()

When you read them back, you use the same group:

python

settings.beginGroup('appearance')
theme = settings.value('theme', 'Light')
settings.endGroup()

Alternatively, you can use a / separator in the key name as a shorthand:

python

settings.setValue('appearance/theme', 'Dark')
theme = settings.value('appearance/theme', 'Light')

Using QSettings with setOrganizationName and setApplicationName

Instead of passing the organization and app names every time you create a QSettings object, you can set them once on the QApplication:

python

app = QApplication(sys.argv)
app.setOrganizationName('MyCompany')
app.setApplicationName('MyApp')

After this, you can create QSettings objects without any arguments:

python

settings = QSettings()

Managing Many Settings with a Dictionary

If your application has a lot of settings, checking each one individually can get repetitive. A cleaner approach is to define your defaults in a dictionary and loop through them:

python

DEFAULTS = {
    'theme': 'Light',
    'font_size': 14,
    'show_toolbar': True,
    'language': 'English',
    'auto_save': True,
    'auto_save_interval': 5,
}

settings = QSettings('MyCompany', 'MyApp')

# Load settings with defaults
config = {}
for key, default in DEFAULTS.items():
    config[key] = settings.value(key, default, type=type(default))

print(config)

Where Are Settings Stored?

If you're curious about where QSettings puts your data, or if you need to find the settings file for debugging, here's a quick summary:

Platform	Storage Location
Windows	Registry under `HKEY_CURRENT_USER\Software\MyCompany\MyApp`
macOS	`~/Library/Preferences/com.mycompany.MyApp.plist`
Linux	`~/.config/MyCompany/MyApp.conf`

You can always check the exact path using:

python

print(settings.fileName())

On Linux and macOS, the settings file is a plain text file that you can open and inspect directly, which is helpful for debugging.

Working with QStandardPaths

python

from PySide6.QtCore import QStandardPaths

# Where to store app configuration
config_path = QStandardPaths.writableLocation(QStandardPaths.AppConfigLocation)
print(f'Config: {config_path}')

# Where to store app data
data_path = QStandardPaths.writableLocation(QStandardPaths.AppDataLocation)
print(f'Data: {data_path}')

# Where to store cached files
cache_path = QStandardPaths.writableLocation(QStandardPaths.CacheLocation)
print(f'Cache: {cache_path}')

Summary

QSettings gives you a clean, cross-platform way to persist user preferences in your PySide6 applications. Here's a quick recap of the essentials:

Create a QSettings object with your organization and app name.
Use setValue(key, value) to save a setting.
Use value(key, default, type=...) to read a setting, with a default fallback and explicit type.
Use contains(key) to check if a setting exists.
Use remove(key) to delete a setting.
Override closeEvent() on your main window to save settings when the app closes.
Organize related settings with groups using beginGroup()/endGroup() or / in key names.

Once you're comfortable with these basics, you'll find that QSettings quietly handles one of those essential-but-tedious parts of desktop app development — letting you focus on the interesting stuff. For a practical example of saving and restoring window geometry specifically, see our tutorial on restoring window geometry with QSettings. You can also learn more about building complete application interfaces with signals, slots, and events and widgets in PySide6.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Introduction to the QGraphics Framework in PySide6 — Creating vector interfaces using the QGraphics View framework

2024-09-27T07:00:00+00:00

The Qt Graphics View Framework allows you to develop fast and efficient 2D vector graphic scenes. Scenes can contain millions of items, each with their own features and behaviors. By using the Graphics View via PySide6 you get access to this highly performant graphics layer in Python. Whether you're integrating vector graphics views into an existing PySide6 application, or simply want a powerful vector graphics interface for Python, Qt's Graphics View is what you're looking for.

Some common uses of the Graphics View include data visualization, mapping applications, 2D design tools, modern data dashboards and even 2D games.

In this tutorial we'll take our first steps looking at the Qt Graphics View framework, building a scene with some simple vector items. This will allow us to familiarize ourselves with the API and coordinate system, which we'll use later to build more complex examples.

What is the Qt Graphics View Framework?

The Graphics View framework consists of 3 main parts QGraphicsView, QGraphicsScene, and QGraphicsItem, each with different responsibilities.

The framework can be interpreted using the Model-View paradigm, with the QGraphicsScene as the Model and the QGraphicsView as the View. Each scene can have multiple views. The QGraphicsItems within the scene can be considered as items within the model, holding the visual data that the scene combines to define the complete image.

QGraphicsScene is the central component that glues everything together. It acts as a whiteboard on which all items are drawn (circles, rectangles, lines, pixmaps, etc). The QGraphicsView has the responsibility of rendering a given scene -- or part of it, with some transformation (scaling, rotating, shearing) -- to display it to the user. The view is a standard Qt widget and can be placed inside any Qt layout.

QGraphicsScene provides some important functionalities out of the box, so we can use them to develop advanced applications without struggling with low-level details. For example --

Collision Detection, detect when a graphics item has collided with another item.
Item Selection, gives us the ability to deal with multiple items at the same time, for example, the user can select multiple items, and when pressing delete, a function asks the scene to give the list for all selected items, and then delete them.
Items discovery, the scene can tell us what items are present (or part of them) at a specific point or inside some defined region, for example, if the user adds an item that intersects with a forbidden area, the program will detect them and give them another (mostly red) color.
Events Propagation, the scene receives the events and then propagates them to items.

To define a QGraphicsScene you define its boundaries or sceneRect which defines the x & y origins and dimensions of the scene. If you don't provide a sceneRect it will default to the minimum bounding rectangle for all child items -- updating as items are added, moved or removed. This is flexible but less efficient.

Items in the scene are represented by QGraphicsItem objects. These are the basic building block of any 2D scene, representing a shape, pixmap or SVG image to be displayed in the scene. Each item has a relative position inside the sceneRect and can have different transformation effects (scale, translate, rotate, shear).

Finally, the QGraphicsView is the renderer of the scene, taking the scene and displaying it -- either wholly or in part -- to the user. The view itself can have transformations (scale, translate, rotate and shear) applied to modify the display without affecting the underlying scene. By default the view will forward mouse and keyboard events to the scene allowing for user interaction. This can be disabled by calling view.setInteractive(False).

Creating a Simple QGraphicsScene

Let's start by creating a simple scene. The following code creates a QGraphicsScene, defining a 400 x 200 scene, and then displays it in a QGraphicsView.

python

import sys
from PySide6.QtWidgets import QGraphicsScene, QGraphicsView, QApplication

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with it's origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

view = QGraphicsView(scene)
view.show()
app.exec()

If you run this example you'll see an empty window.

The empty graphics scene, shown in a QGraphicsView window.

Not very exciting yet -- but this is our QGraphicsView displaying our empty scene.

As mentioned earlier, QGraphicsView is a widget. In Qt any widgets without a parent display as windows. This is why our QGraphicsView appears as a window on the desktop.

Adding QGraphicsItems to the Scene

Let's start adding some items to the scene. There are a number of built-in graphics items which you can customize and add to your scene. In the example below we use QGraphicsRectItem which draws a rectangle. We create the item passing in its dimensions, and then set its position, pen and brush before adding it to the scene.

python

import sys
from PySide6.QtWidgets import QGraphicsScene, QGraphicsView, QGraphicsRectItem, QApplication
from PySide6.QtGui import QBrush, QPen
from PySide6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with it's origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.cyan)
pen.setWidth(10)
rect.setPen(pen)

scene.addItem(rect)

view = QGraphicsView(scene)
view.show()
app.exec()

Running the above you'll see a single, rather ugly colored, rectangle in the scene.

A single rectangle in the scene

Adding more items is simply a case of creating the objects, customizing them and then adding them to the scene. In the example below we add a circle, using QGraphicsEllipseItem -- a circle is just an ellipse with equal height and width.

python

import sys
from PySide6.QtWidgets import QGraphicsScene, QGraphicsView, QGraphicsRectItem, QGraphicsEllipseItem, QApplication
from PySide6.QtGui import QBrush, QPen
from PySide6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with it's origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.cyan)
pen.setWidth(10)
rect.setPen(pen)

ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
ellipse.setPos(75, 30)

brush = QBrush(Qt.blue)
ellipse.setBrush(brush)

pen = QPen(Qt.green)
pen.setWidth(5)
ellipse.setPen(pen)

# Add the items to the scene. Items are stacked in the order they are added.
scene.addItem(ellipse)
scene.addItem(rect)


view = QGraphicsView(scene)
view.show()
app.exec()

The above code will give the following result.

A scene with two items

Controlling Item Stacking Order with ZValue

The order you add items affects the stacking order in the scene -- items added later will always appear on top of items added first. However, if you need more control you can set the stacking order using .setZValue.

python

ellipse.setZValue(500)
rect.setZValue(200)

Now the circle (ellipse) appears above the rectangle.

Using ZValue to order items in the scene

Try experimenting with setting the Z value of the two items -- you can set it before or after the items are in the scene, and can change it at any time.

Z in this context refers to the Z coordinate. The X & Y coordinates are the horizontal and vertical position in the scene respectively. The Z coordinate determines the relative position of items toward the front and back of the scene -- coming "out" of the screen towards the viewer.

There are also the convenience methods .stackBefore() and .stackAfter() which allow you to stack your QGraphicsItem behind, or in front of another item in the scene.

python

ellipse.stackAfter(rect)

Making Items Moveable and Selectable

Our two QGraphicsItem objects are currently fixed in position where we place them, but they don't have to be! As already mentioned Qt's Graphics View framework allows items to respond to user input, for example allowing them to be dragged and dropped around the scene at will. Simple functionality like this is actually already built in, you just need to enable it on each QGraphicsItem. To do that we need to set the flag QGraphicsItem.GraphicsItemFlags.ItemIsMoveable on the item.

The full list of graphics item flags is available here.

python

import sys
from PySide6.QtWidgets import QGraphicsScene, QGraphicsView, QGraphicsItem, QGraphicsRectItem, QGraphicsEllipseItem, QApplication
from PySide6.QtGui import QBrush, QPen
from PySide6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with it's origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.cyan)
pen.setWidth(10)
rect.setPen(pen)

ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
ellipse.setPos(75, 30)

brush = QBrush(Qt.blue)
ellipse.setBrush(brush)

pen = QPen(Qt.green)
pen.setWidth(5)
ellipse.setPen(pen)

# Add the items to the scene. Items are stacked in the order they are added.
scene.addItem(ellipse)
scene.addItem(rect)

ellipse.setFlag(QGraphicsItem.ItemIsMovable)

view = QGraphicsView(scene)
view.show()
app.exec()

In the above example we've set ItemIsMovable on the ellipse only. You can drag the ellipse around the scene -- including behind the rectangle -- but the rectangle itself will remain locked in place. Experiment with adding more items and configuring the moveable status.

If you want an item to be selectable you can enable this by setting the ItemIsSelectable flag, for example here using .setFlags() to set multiple flags at the same time.

python

ellipse.setFlags(QGraphicsItem.ItemIsMovable | QGraphicsItem.ItemIsSelectable)

If you click on the ellipse you'll now see it surrounded by a dashed line to indicate that it is selected. We'll look at how to use item selection in more detail in a later tutorial.

A selected item in the scene, highlighted with dashed lines

Creating Items Directly on the Scene

So far we've been creating items by creating the objects and then adding them to the scene. But you can also create an object in the scene directly by calling one of the helper methods on the scene itself, e.g. scene.addEllipse(). This creates the object and returns it so you can modify it as before.

python

import sys
from PySide6.QtWidgets import QGraphicsScene, QGraphicsView, QGraphicsRectItem, QApplication
from PySide6.QtGui import QBrush, QPen
from PySide6.QtCore import Qt

app = QApplication(sys.argv)

scene = QGraphicsScene(0, 0, 400, 200)

rect = scene.addRect(0, 0, 200, 50)
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.cyan)
pen.setWidth(10)
rect.setPen(pen)

view = QGraphicsView(scene)
view.show()
app.exec()

Feel free to use whichever form you find most comfortable in your code.

You can only use this approach for the built-in QGraphicsItem object types.

Building a Complex Scene with Text, Polygons, and Images

So far we've built a simple scene using the basic QGraphicsRectItem and QGraphicsEllipseItem shapes. Now let's use some other QGraphicsItem objects to build a more complex scene, including lines, text and QPixmap (images).

python

from PySide6.QtCore import QPointF, Qt
from PySide6.QtWidgets import QGraphicsRectItem, QGraphicsScene, QGraphicsView, QApplication
from PySide6.QtGui import QBrush, QPainter, QPen, QPixmap, QPolygonF
import sys

app = QApplication(sys.argv)

scene = QGraphicsScene(0, 0, 400, 200)

rectitem = QGraphicsRectItem(0, 0, 360, 20)
rectitem.setPos(20, 20)
rectitem.setBrush(QBrush(Qt.red))
rectitem.setPen(QPen(Qt.cyan))
scene.addItem(rectitem)

textitem = scene.addText("QGraphics is fun!")
textitem.setPos(100, 100)

scene.addPolygon(
    QPolygonF(
        [
            QPointF(30, 60),
            QPointF(270, 40),
            QPointF(400, 200),
            QPointF(20, 150),
        ]),
    QPen(Qt.darkGreen),
)

pixmap = QPixmap("cat.jpg")
pixmapitem = scene.addPixmap(pixmap)
pixmapitem.setPos(250, 70)

view = QGraphicsView(scene)
view.setRenderHint(QPainter.Antialiasing)
view.show()

app.exec()

If you run the example above you'll see the following scene.

Scene with multiple items including a rectangle, polygon, text and a pixmap.

Let's step through the code looking at the interesting bits.

Polygons are defined using a series of QPointF objects which give the coordinates relative to the item's position. So, for example if you create a polygon object with a point at 30, 20 and then move this polygon object's X & Y coordinates to 50, 40 then the point will be displayed at 80, 60 in the scene.

Points inside an item are always relative to the item itself, and item coordinates are always relative to the scene -- or the item's parent, if it has one. We'll take a closer look at the Graphics View coordinate system in the next tutorial.

To add an image to the scene we can open it from a file using QPixmap(). This creates a QPixmap object, which can then in turn be added to the scene using scene.addPixmap(pixmap). This returns a QGraphicsPixmapItem which is the QGraphicsItem type for the pixmap -- a wrapper that handles displaying the pixmap in the scene. You can use this object to perform any changes to the item in the scene. For more on working with images and pixmaps in PySide6, see our guide on adding images to PySide6 applications.

The multiple layers of objects can get confusing, so it's important to choose sensible variable names which make clear the distinction between, e.g. the pixmap itself and the pixmap item that contains it.

Finally, we set the flag RenderHint.Antialiasing on the view to smooth the edges of diagonal lines. You almost always want to enable this on your views as otherwise any rotated objects will look very ugly indeed. Below is our scene without antialiasing enabled, you can see the jagged lines on the polygon.

Scene with antialiasing disabled.

Antialiasing has a (small) performance impact however, so if you are building scenes with millions of rotated items it may in some cases make sense to turn it off.

Adding a QGraphicsView to a Qt Layout

The QGraphicsView is subclassed from QWidget, meaning it can be placed in layouts just like any other widget. In the following example we add the view to a simple interface, with buttons which perform a basic effect on the view -- raising and lowering selected item's ZValue. This has the effect of allowing us to move items in front and behind other objects.

The full code is given below.

python

import sys

from PySide6.QtCore import Qt
from PySide6.QtGui import QBrush, QPainter, QPen
from PySide6.QtWidgets import (
    QApplication,
    QGraphicsEllipseItem,
    QGraphicsItem,
    QGraphicsRectItem,
    QGraphicsScene,
    QGraphicsView,
    QHBoxLayout,
    QPushButton,
    QSlider,
    QVBoxLayout,
    QWidget,
)


class Window(QWidget):
    def __init__(self):
        super().__init__()

        # Defining a scene rect of 400x200, with it's origin at 0,0.
        # If we don't set this on creation, we can set it later with .setSceneRect
        self.scene = QGraphicsScene(0, 0, 400, 200)

        # Draw a rectangle item, setting the dimensions.
        rect = QGraphicsRectItem(0, 0, 200, 50)
        rect.setPos(50, 20)
        brush = QBrush(Qt.red)
        rect.setBrush(brush)

        # Define the pen (line)
        pen = QPen(Qt.cyan)
        pen.setWidth(10)
        rect.setPen(pen)

        ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
        ellipse.setPos(75, 30)

        brush = QBrush(Qt.blue)
        ellipse.setBrush(brush)

        pen = QPen(Qt.green)
        pen.setWidth(5)
        ellipse.setPen(pen)

        # Add the items to the scene. Items are stacked in the order they are added.
        self.scene.addItem(ellipse)
        self.scene.addItem(rect)

        # Set all items as moveable and selectable.
        for item in self.scene.items():
            item.setFlag(QGraphicsItem.ItemIsMovable)
            item.setFlag(QGraphicsItem.ItemIsSelectable)

        # Define our layout.
        vbox = QVBoxLayout()

        up = QPushButton("Up")
        up.clicked.connect(self.up)
        vbox.addWidget(up)

        down = QPushButton("Down")
        down.clicked.connect(self.down)
        vbox.addWidget(down)

        rotate = QSlider()
        rotate.setRange(0, 360)
        rotate.valueChanged.connect(self.rotate)
        vbox.addWidget(rotate)

        view = QGraphicsView(self.scene)
        view.setRenderHint(QPainter.Antialiasing)

        hbox = QHBoxLayout(self)
        hbox.addLayout(vbox)
        hbox.addWidget(view)

        self.setLayout(hbox)

    def up(self):
        """ Iterate all selected items in the view, moving them forward. """
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z + 1)

    def down(self):
        """ Iterate all selected items in the view, moving them backward. """
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z - 1)

    def rotate(self, value):
        """ Rotate the object by the received number of degrees """
        items = self.scene.selectedItems()
        for item in items:
            item.setRotation(value)


app = QApplication(sys.argv)

w = Window()
w.show()

app.exec()

If you run this, you will get a window like that shown below. By selecting an item in the graphics view and then clicking either the "Up" or "Down" button you can move items up and down within the scene -- behind and in front of one another. The items are all moveable, so you can drag them around too. Clicking on the slider will rotate the currently selected items by the set number of degrees.

A graphics scene embedded in a Qt layout with custom controls for stacking and rotation

The raising and lowering is handled by our custom methods up and down, which work by iterating over the currently selected items in the scene -- retrieved using scene.selectedItems() and then getting the item's z value and increasing or decreasing it respectively.

python

    def up(self):
        """ Iterate all selected items in the view, moving them forward. """
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z + 1)

While rotation is handled using the item.setRotation method. This receives the current angle from the QSlider and again, applies it to any currently selected items in the scene. The button's clicked signal is connected to our slot methods to handle the user interaction.

python


    def rotate(self, value):
        """ Rotate the object by the received number of degrees. """
        items = self.scene.selectedItems()
        for item in items:
            item.setRotation(value)

Take a look at the QGraphicsItem documentation for some other properties you can control with widgets and try extending the interface to allow you to change them dynamically. If you want to go further with custom graphics items, see our tutorial on creating your own custom widgets in PySide6.

Hopefully this introduction to the Qt Graphics View framework has given you some ideas of what you can do with it. In the next tutorials we'll look at how events and user interaction can be handled on items and how to create custom & compound items for your own scenes.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

PyQt6 & PySide6 Books Updated for 2024 — Extended and updated with new examples and demos, including Model-View-Controller architecture

2024-06-30T06:00:00+00:00

Hello! Today I have released new digital updates to my book Create GUI Applications with Python & Qt.

What's New in the 2024 Edition (5th Edition)?

This update brings all versions up to date with the latest developments in PyQt6 & PySide6. As well as corrections and additions to existing chapters, there are new sections dealing with form layouts, built-in dialogs, and developing Qt applications using a Model-View-Controller (MVC) architecture. The same corrections and additions have been made to the PyQt5 & PySide2 editions.

Whether you're building desktop applications with PyQt6, PySide6, or the earlier PyQt5 and PySide2 libraries, this edition provides updated guidance and practical examples to help you create professional Python GUI applications.

As always, if you've previously bought a copy of the book, you get these updates for free! Just go to the downloads page and enter the email you used for the purchase.

Get Your Copy of the Python & Qt Book

You can buy the latest editions below --

If you bought the book elsewhere (in paperback or digital), you can register to get these updates too. Email your receipt to register@pythonguis.com

Enjoy!

For an in-depth guide to building Python GUIs with PySide2 see my book, Create GUI Applications with Python & Qt5.

Introduction to the QGraphics Framework in PyQt6 — Creating vector interfaces using the QGraphics View framework

2024-04-27T07:00:00+00:00

The Qt Graphics View Framework allows you to develop fast and efficient 2D vector graphic scenes. Scenes can contain millions of items, each with their own features and behaviors. By using the Graphics View via PyQt6 you get access to this highly performant graphics layer in Python. Whether you're integrating vector graphics views into an existing PyQt6 application, or simply want a powerful vector graphics interface for Python, Qt's Graphics View is what you're looking for.

Some common uses of the Graphics View include data visualization, mapping applications, 2D design tools, modern data dashboards and even 2D games.

What is the QGraphics View Framework?

The Graphics View framework consists of 3 main parts QGraphicsView, QGraphicsScene, and QGraphicsItem, each with different responsibilities.

QGraphicsScene provides some important functionalities out of the box, so we can use them to develop advanced applications without struggling with low-level details. For example --

Collision Detection, detect when a graphics item has collided with another item.
Item Selection, gives us the ability to deal with multiple items at the same time, for example, the user can select multiple items, and when pressing delete, a function asks the scene to give the list for all selected items, and then delete them.
Items discovery, the scene can tell us what items are present (or part of them) at a specific point or inside some defined region, for example, if the user adds an item that intersects with a forbidden area, the program will detect them and give them another (mostly red) color.
Events Propagation, the scene receives the events and then propagates them to items.

Creating a Simple QGraphicsScene in PyQt6

Let's start by creating a simple scene. The following code creates a QGraphicsScene, defining a 400 x 200 scene, and then displays it in a QGraphicsView.

python

import sys
from PyQt6.QtWidgets import QGraphicsScene, QGraphicsView, QApplication

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with it's origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

view = QGraphicsView(scene)
view.show()
app.exec()

If you run this example you'll see an empty window.

The empty graphics scene, shown in a QGraphicsView window.

Not very exciting yet -- but this is our QGraphicsView displaying our empty scene.

As mentioned earlier, QGraphicsView is a widget. In Qt any widgets without a parent display as windows. This is why our QGraphicsView appears as a window on the desktop.

Adding QGraphicsItems to the Scene

python

import sys
from PyQt6.QtWidgets import QGraphicsScene, QGraphicsView, QGraphicsRectItem, QApplication
from PyQt6.QtGui import QBrush, QPen
from PyQt6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with it's origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

scene.addItem(rect)

view = QGraphicsView(scene)
view.show()
app.exec()

Running the above you'll see a single, rather ugly colored, rectangle in the scene.

A single rectangle in the scene

python

import sys
from PyQt6.QtWidgets import QGraphicsScene, QGraphicsView, QGraphicsRectItem, QGraphicsEllipseItem, QApplication
from PyQt6.QtGui import QBrush, QPen
from PyQt6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with it's origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
ellipse.setPos(75, 30)

brush = QBrush(Qt.GlobalColor.blue)
ellipse.setBrush(brush)

pen = QPen(Qt.GlobalColor.green)
pen.setWidth(5)
ellipse.setPen(pen)

# Add the items to the scene. Items are stacked in the order they are added.
scene.addItem(ellipse)
scene.addItem(rect)


view = QGraphicsView(scene)
view.show()
app.exec()

The above code will give the following result.

A scene with two items

Controlling Item Stacking Order with ZValue

python

ellipse.setZValue(500)
rect.setZValue(200)

Now the circle (ellipse) appears above the rectangle.

Using ZValue to order items in the scene

Try experimenting with setting the Z value of the two items -- you can set it before or after the items are in the scene, and can change it at any time.

There are also the convenience methods .stackBefore() and .stackAfter() which allow you to stack your QGraphicsItem behind, or in front of another item in the scene.

python

ellipse.stackAfter(rect)

Making Items Moveable and Selectable

The full list of graphics item flags is available here.

python

import sys
from PyQt6.QtWidgets import QGraphicsScene, QGraphicsView, QGraphicsItem, QGraphicsRectItem, QGraphicsEllipseItem, QApplication
from PyQt6.QtGui import QBrush, QPen
from PyQt6.QtCore import Qt

app = QApplication(sys.argv)

# Defining a scene rect of 400x200, with it's origin at 0,0.
# If we don't set this on creation, we can set it later with .setSceneRect
scene = QGraphicsScene(0, 0, 400, 200)

# Draw a rectangle item, setting the dimensions.
rect = QGraphicsRectItem(0, 0, 200, 50)

# Set the origin (position) of the rectangle in the scene.
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
ellipse.setPos(75, 30)

brush = QBrush(Qt.GlobalColor.blue)
ellipse.setBrush(brush)

pen = QPen(Qt.GlobalColor.green)
pen.setWidth(5)
ellipse.setPen(pen)

# Add the items to the scene. Items are stacked in the order they are added.
scene.addItem(ellipse)
scene.addItem(rect)

ellipse.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsMovable)

view = QGraphicsView(scene)
view.show()
app.exec()

If you want an item to be selectable you can enable this by setting the ItemIsSelectable flag, for example here using .setFlags() to set multiple flags at the same time.

python

ellipse.setFlags(QGraphicsItem.ItemIsMovable | QGraphicsItem.ItemIsSelectable)

If you click on the ellipse you'll now see it surrounded by a dashed line to indicate that it is selected. We'll look at how to use item selection in more detail in a later tutorial.

A selected item in the scene, highlighted with dashed lines

Alternative Way to Create QGraphicsItems

python

import sys
from PyQt6.QtWidgets import QGraphicsScene, QGraphicsView, QGraphicsRectItem, QApplication
from PyQt6.QtGui import QBrush, QPen
from PyQt6.QtCore import Qt
app = QApplication(sys.argv)

scene = QGraphicsScene(0, 0, 400, 200)

rect = scene.addRect(0, 0, 200, 50)
rect.setPos(50, 20)

# Define the brush (fill).
brush = QBrush(Qt.GlobalColor.red)
rect.setBrush(brush)

# Define the pen (line)
pen = QPen(Qt.GlobalColor.cyan)
pen.setWidth(10)
rect.setPen(pen)

view = QGraphicsView(scene)
view.show()
app.exec()

Feel free to use whichever form you find most comfortable in your code.

You can only use this approach for the built-in QGraphicsItem object types.

Building a Complex Scene with Shapes, Text, and Images

python

from PyQt6.QtCore import QPointF, Qt
from PyQt6.QtWidgets import QGraphicsRectItem, QGraphicsScene, QGraphicsView, QApplication
from PyQt6.QtGui import QBrush, QPainter, QPen, QPixmap, QPolygonF
import sys

app = QApplication(sys.argv)

scene = QGraphicsScene(0, 0, 400, 200)

rectitem = QGraphicsRectItem(0, 0, 360, 20)
rectitem.setPos(20, 20)
rectitem.setBrush(QBrush(Qt.GlobalColor.red))
rectitem.setPen(QPen(Qt.GlobalColor.cyan))
scene.addItem(rectitem)

textitem = scene.addText("QGraphics is fun!")
textitem.setPos(100, 100)

scene.addPolygon(
    QPolygonF(
        [
            QPointF(30, 60),
            QPointF(270, 40),
            QPointF(400, 200),
            QPointF(20, 150),
        ]),
    QPen(Qt.GlobalColor.darkGreen),
)

pixmap = QPixmap("cat.jpg")
pixmapitem = scene.addPixmap(pixmap)
pixmapitem.setPos(250, 70)

view = QGraphicsView(scene)
view.setRenderHint(QPainter.RenderHint.Antialiasing)
view.show()

app.exec()

If you run the example above you'll see the following scene.

Scene with multiple items including a rectangle, polygon, text and a pixmap.

Let's step through the code looking at the interesting bits.

Polygons are defined using a series of QPointF objects which give the coordinates relative to the item's position. So, for example if you create a polygon object with a point at 30, 20 and then move this polygon object X & Y coordinates 50, 40 then the point will be displayed at 80, 60 in the scene.

Scene with antialiasing disabled.

Antialiasing has a (small) performance impact however, so if you are building scenes with millions of rotated items it may in some cases make sense to turn it off.

Adding a QGraphicsView to a PyQt6 Layout

The full code is given below.

python

import sys

from PyQt6.QtCore import Qt
from PyQt6.QtGui import QBrush, QPainter, QPen
from PyQt6.QtWidgets import (
    QApplication,
    QGraphicsEllipseItem,
    QGraphicsItem,
    QGraphicsRectItem,
    QGraphicsScene,
    QGraphicsView,
    QHBoxLayout,
    QPushButton,
    QSlider,
    QVBoxLayout,
    QWidget,
)


class Window(QWidget):
    def __init__(self):
        super().__init__()

        # Defining a scene rect of 400x200, with it's origin at 0,0.
        # If we don't set this on creation, we can set it later with .setSceneRect
        self.scene = QGraphicsScene(0, 0, 400, 200)

        # Draw a rectangle item, setting the dimensions.
        rect = QGraphicsRectItem(0, 0, 200, 50)
        rect.setPos(50, 20)
        brush = QBrush(Qt.GlobalColor.red)
        rect.setBrush(brush)

        # Define the pen (line)
        pen = QPen(Qt.GlobalColor.cyan)
        pen.setWidth(10)
        rect.setPen(pen)

        ellipse = QGraphicsEllipseItem(0, 0, 100, 100)
        ellipse.setPos(75, 30)

        brush = QBrush(Qt.GlobalColor.blue)
        ellipse.setBrush(brush)

        pen = QPen(Qt.GlobalColor.green)
        pen.setWidth(5)
        ellipse.setPen(pen)

        # Add the items to the scene. Items are stacked in the order they are added.
        self.scene.addItem(ellipse)
        self.scene.addItem(rect)

        # Set all items as moveable and selectable.
        for item in self.scene.items():
            item.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsMovable)
            item.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsSelectable)

        # Define our layout.
        vbox = QVBoxLayout()

        up = QPushButton("Up")
        up.clicked.connect(self.up)
        vbox.addWidget(up)

        down = QPushButton("Down")
        down.clicked.connect(self.down)
        vbox.addWidget(down)

        rotate = QSlider()
        rotate.setRange(0, 360)
        rotate.valueChanged.connect(self.rotate)
        vbox.addWidget(rotate)

        view = QGraphicsView(self.scene)
        view.setRenderHint(QPainter.RenderHint.Antialiasing)

        hbox = QHBoxLayout(self)
        hbox.addLayout(vbox)
        hbox.addWidget(view)

        self.setLayout(hbox)

    def up(self):
        """ Iterate all selected items in the view, moving them forward. """
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z + 1)

    def down(self):
        """ Iterate all selected items in the view, moving them backward. """
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z - 1)

    def rotate(self, value):
        """ Rotate the object by the received number of degrees. """
        items = self.scene.selectedItems()
        for item in items:
            item.setRotation(value)


app = QApplication(sys.argv)

w = Window()
w.show()

app.exec()

A graphics scene with some custom controls

python

    def up(self):
        """ Iterate all selected items in the view, moving them forward. """
        items = self.scene.selectedItems()
        for item in items:
            z = item.zValue()
            item.setZValue(z + 1)

While rotation is handled using the item.setRotation method. This receives the current angle from the QSlider and again, applies it to any currently selected items in the scene.

python


    def rotate(self, value):
        """ Rotate the object by the received number of degrees. """
        items = self.scene.selectedItems()
        for item in items:
            item.setRotation(value)

Take a look at the QGraphicsItem documentation for some other properties you can control with widgets and try extending the interface to allow you to change them dynamically.

Summary

In this tutorial you've learned the fundamentals of PyQt6's QGraphics View framework, including how to create a QGraphicsScene, add QGraphicsItem objects like rectangles, ellipses, polygons, text and images, control stacking order with Z values, make items moveable and selectable, and embed a QGraphicsView into a standard PyQt6 layout with interactive controls.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Drag & Drop Widgets with PySide6 — Sort widgets visually with drag and drop in a container

2024-03-06T13:00:00+00:00

I had an interesting question from a reader of my PySide6 book, about how to handle dragging and dropping of widgets in a container showing the dragged widget as it is moved.

I'm interested in managing movement of a QWidget with mouse in a container. I've implemented the application with drag & drop, exchanging the position of buttons, but I want to show the motion of QPushButton, like what you see in Qt Designer. Dragging a widget should show the widget itself, not just the mouse pointer.

First, we'll implement the simple case which drags widgets without showing anything extra. Then we can extend it to answer the question. By the end of this tutorial we'll have a generic, reusable drag and drop implementation which looks like the following.

Drag & Drop Widgets in PySide6

We'll start with a simple application which creates a window using QWidget and places a series of QPushButton widgets into it.

You can substitute QPushButton for any other widget you like, e.g. QLabel. Any widget can have drag behavior implemented on it, although some input widgets will not work well as we capture the mouse events for the drag.

python

from PySide6.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget


class Window(QWidget):
    def __init__(self):
        super().__init__()

        self.blayout = QHBoxLayout()
        for l in ["A", "B", "C", "D"]:
            btn = QPushButton(l)
            self.blayout.addWidget(btn)

        self.setLayout(self.blayout)


app = QApplication([])
w = Window()
w.show()

app.exec()

If you run this you should see something like this.

The series of QPushButton widgets in a horizontal layout.

Here we're creating a window, but the Window widget is subclassed from QWidget, meaning you can add this widget to any other layout. See later for an example of a generic object sorting widget.

Making QPushButton Draggable with QDrag

QPushButton objects aren't usually draggable, so to handle the mouse movements and initiate a drag we need to implement a subclass. We can add the following to the top of the file.

python

from PySide6.QtCore import QMimeData, Qt
from PySide6.QtGui import QDrag
from PySide6.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget


class DragButton(QPushButton):
    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)
            drag.exec(Qt.DropAction.MoveAction)

We implement a mouseMoveEvent which accepts the single e parameter of the event. We check to see if the left mouse button is pressed on this event -- as it would be when dragging -- and then initiate a drag. To start a drag, we create a QDrag object, passing in self to give us access later to the widget that was dragged. We also must pass in QMimeData. This is used for including information about what is dragged, particularly for passing data between applications. However, as here, it is fine to leave this empty.

Finally, we initiate a drag by calling drag.exec(Qt.DropAction.MoveAction). As with dialogs exec() starts a new event loop, blocking the main loop until the drag is complete. The parameter Qt.DropAction.MoveAction tells the drag handler what type of operation is happening, so it can show the appropriate icon tip to the user.

You can update the main window code to use our new DragButton class as follows.

python

class Window(QWidget):
    def __init__(self):
        super().__init__()
        self.setAcceptDrops(True)

        self.blayout = QHBoxLayout()
        for l in ["A", "B", "C", "D"]:
            btn = DragButton(l)
            self.blayout.addWidget(btn)

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

If you run the code now, you can drag the buttons, but you'll notice the drag is forbidden.

Dragging of the widget starts but is forbidden.

What's happening? The mouse movement is being detected by our DragButton object and the drag started, but the main window does not accept drag & drop.

Accepting Drops with dragEnterEvent

To fix this we need to enable drops on the window and implement dragEnterEvent to actually accept them.

python

class Window(QWidget):
    def __init__(self):
        super().__init__()
        self.setAcceptDrops(True)

        self.blayout = QHBoxLayout()
        for l in ["A", "B", "C", "D"]:
            btn = DragButton(l)
            self.blayout.addWidget(btn)

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

If you run this now, you'll see the drag is now accepted and you see the move icon. This indicates that the drag has started and been accepted by the window we're dragging onto. The icon shown is determined by the action we pass when calling drag.exec().

Dragging of the widget starts and is accepted, showing a move icon.

Handling the Drop with dropEvent

Releasing the mouse button during a drag drop operation triggers a dropEvent on the widget you're currently hovering the mouse over (if it is configured to accept drops). In our case that's the window. To handle the move we need to implement the code to do this in our dropEvent method.

The drop event contains the position the mouse was at when the button was released & the drop triggered. We can use this to determine where to move the widget to.

To determine where to place the widget, we iterate over all the widgets in the layout, until we find one who's x position is greater than that of the mouse pointer. If so then when insert the widget directly to the left of this widget and exit the loop.

If we get to the end of the loop without finding a match, we must be dropping past the end of the existing items, so we increment n one further (in the else: block below).

python

    def dropEvent(self, e):
        pos = e.position()
        widget = e.source()
        self.blayout.removeWidget(widget)

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if pos.x() < w.x():
                # We didn't drag past this widget.
                # insert to the left of it.
                break
        else:
            # We aren't on the left hand side of any widget,
            # so we're at the end. Increment 1 to insert after.
            n += 1

        self.blayout.insertWidget(n, widget)

        e.accept()

The effect of this is that if you drag 1 pixel past the start of another widget the drop will happen to the right of it, which is a bit confusing. To fix this we can adjust the cut off to use the middle of the widget using if pos.x() < w.x() + w.size().width() // 2: -- that is x + half of the width.

python

    def dropEvent(self, e):
        pos = e.position()
        widget = e.source()
        self.blayout.removeWidget(widget)

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if pos.x() < w.x() + w.size().width() // 2:
                # We didn't drag past this widget.
                # insert to the left of it.
                break
        else:
            # We aren't on the left hand side of any widget,
            # so we're at the end. Increment 1 to insert after.
            n += 1

        self.blayout.insertWidget(n, widget)

        e.accept()

Complete Drag & Drop Example

The complete working drag-drop code is shown below.

python

from PySide6.QtCore import QMimeData, Qt
from PySide6.QtGui import QDrag
from PySide6.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget


class DragButton(QPushButton):
    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)
            drag.exec(Qt.DropAction.MoveAction)


class Window(QWidget):
    def __init__(self):
        super().__init__()
        self.setAcceptDrops(True)

        self.blayout = QHBoxLayout()
        for l in ["A", "B", "C", "D"]:
            btn = DragButton(l)
            self.blayout.addWidget(btn)

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

    def dropEvent(self, e):
        pos = e.position()
        widget = e.source()
        self.blayout.removeWidget(widget)

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if pos.x() < w.x() + w.size().width() // 2:
                # We didn't drag past this widget.
                # insert to the left of it.
                break
        else:
            # We aren't on the left hand side of any widget,
            # so we're at the end. Increment 1 to insert after.
            n += 1

        self.blayout.insertWidget(n, widget)

        e.accept()


app = QApplication([])
w = Window()
w.show()

app.exec()

Visual Drag & Drop with QPixmap Preview

We now have a working drag & drop implementation. Next we'll move onto improving the UX by showing the drag visually. First we'll add support for showing the button being dragged next to the mouse pointer as it is dragged. That way the user knows exactly what it is they are dragging.

Qt's QDrag handler natively provides a mechanism for showing dragged objects which we can use. We can update our DragButton class to pass a pixmap image to QDrag and this will be displayed under the mouse pointer as the drag occurs. To show the widget, we just need to get a QPixmap of the widget we're dragging.

python

from PySide6.QtCore import QMimeData, Qt
from PySide6.QtGui import QDrag
from PySide6.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget


class DragButton(QPushButton):
    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)
            drag.exec(Qt.DropAction.MoveAction)

To create the pixmap we create a QPixmap object passing in the size of the widget this event is fired on with self.size(). This creates an empty pixmap which we can then pass into self.render to render -- or draw -- the current widget onto it. That's it. Then we set the resulting pixmap on the drag object.

If you run the code with this modification you'll see something like the following --

Dragging of the widget showing the dragged widget.

We now have a working drag and drop behavior implemented on our window. We can take this a step further and implement a generic drag drop widget which allows us to sort arbitrary objects. In the code below we've created a new widget DragWidget which can be added to any window.

You can add items -- instances of DragItem -- which you want to be sorted, as well as setting data on them. When items are re-ordered the new order is emitted as a signal orderChanged.

python

from PySide6.QtCore import QMimeData, Qt, Signal
from PySide6.QtGui import QDrag, QPixmap
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)


class DragItem(QLabel):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setContentsMargins(25, 5, 25, 5)
        self.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setStyleSheet("border: 1px solid black;")
        # Store data separately from display label, but use label for default.
        self.data = self.text()

    def set_data(self, data):
        self.data = data

    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)

            pixmap = QPixmap(self.size())
            self.render(pixmap)
            drag.setPixmap(pixmap)

            drag.exec(Qt.DropAction.MoveAction)


class DragWidget(QWidget):
    """
    Generic list sorting handler.
    """

    orderChanged = Signal(list)

    def __init__(self, *args, orientation=Qt.Orientation.Vertical, **kwargs):
        super().__init__()
        self.setAcceptDrops(True)

        # Store the orientation for drag checks later.
        self.orientation = orientation

        if self.orientation == Qt.Orientation.Vertical:
            self.blayout = QVBoxLayout()
        else:
            self.blayout = QHBoxLayout()

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

    def dropEvent(self, e):
        pos = e.position()
        widget = e.source()
        self.blayout.removeWidget(widget)

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if self.orientation == Qt.Orientation.Vertical:
                # Drag drop vertically.
                drop_here = pos.y() < w.y() + w.size().height() // 2
            else:
                # Drag drop horizontally.
                drop_here = pos.x() < w.x() + w.size().width() // 2

            if drop_here:
                break

        else:
            # We aren't on the left hand/upper side of any widget,
            # so we're at the end. Increment 1 to insert after.
            n += 1

        self.blayout.insertWidget(n, widget)
        self.orderChanged.emit(self.get_item_data())

        e.accept()

    def add_item(self, item):
        self.blayout.addWidget(item)

    def get_item_data(self):
        data = []
        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            data.append(w.data)
        return data


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.drag = DragWidget(orientation=Qt.Orientation.Vertical)
        for n, l in enumerate(["A", "B", "C", "D"]):
            item = DragItem(l)
            item.set_data(n)  # Store the data.
            self.drag.add_item(item)

        # Print out the changed order.
        self.drag.orderChanged.connect(print)

        container = QWidget()
        layout = QVBoxLayout()
        layout.addStretch(1)
        layout.addWidget(self.drag)
        layout.addStretch(1)
        container.setLayout(layout)

        self.setCentralWidget(container)


app = QApplication([])
w = MainWindow()
w.show()

app.exec()

Generic drag-drop sorting in horizontal orientation.

You'll notice that when creating the item, you can set the label by passing it in as a parameter (just like for a normal QLabel which we've subclassed from). But you can also set a data value, which is the internal value of this item -- this is what will be emitted when the order changes, or if you call get_item_data yourself. This separates the visual representation from what is actually being sorted, meaning you can use this to sort anything not just strings.

In the example above we're passing in the enumerated index as the data, so dragging will output (via the print connected to orderChanged) something like:

python

[1, 0, 2, 3]
[1, 2, 0, 3]
[1, 0, 2, 3]
[1, 2, 0, 3]

If you remove the item.set_data(n) you'll see the labels emitted on changes.

python

['B', 'A', 'C', 'D']
['B', 'C', 'A', 'D']

We've also implemented orientation onto the DragWidget using the Qt built in flags Qt.Orientation.Vertical or Qt.Orientation.Horizontal. Setting this allows you to sort items either vertically or horizontally -- the calculations are handled for both directions.

Generic drag-drop sorting in vertical orientation.

Adding a Visual Drop Target Indicator

If you experiment with the drag-drop tool above you'll notice that it doesn't feel completely intuitive. When dragging you don't know where an item will be inserted until you drop it. If it ends up in the wrong place, you'll then need to pick it up and re-drop it again, using guesswork to get it right.

With a bit of practice you can get the hang of it, but it would be nicer to make the behavior immediately obvious for users. Many drag-drop interfaces solve this problem by showing a preview of where the item will be dropped while dragging -- either by showing the item in the place where it will be dropped, or showing some kind of placeholder.

In this final section we'll implement this type of drag and drop preview indicator.

Creating the Drop Target Indicator Widget

The first step is to define our target indicator. This is just another label, which in our example is empty, with custom styles applied to make it have a solid "shadow" like background. This makes it obviously different to the items in the list, so it stands out as something distinct.

python

from PySide6.QtCore import QMimeData, Qt, Signal
from PySide6.QtGui import QDrag, QPixmap
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)


class DragTargetIndicator(QLabel):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setContentsMargins(25, 5, 25, 5)
        self.setStyleSheet(
            "QLabel { background-color: #ccc; border: 1px solid black; }"
        )

We've copied the contents margins from the items in the list. If you change your list items, remember to also update the indicator dimensions to match.

Showing the Drop Target During Drag

The drag item is unchanged, but we need to implement some additional behavior on our DragWidget to add the target, control showing and moving it.

First we'll add the drag target indicator to the layout on our DragWidget. This is hidden to begin with, but will be shown during the drag.

python

class DragWidget(QWidget):
    """
    Generic list sorting handler.
    """

    orderChanged = Signal(list)

    def __init__(self, *args, orientation=Qt.Orientation.Vertical, **kwargs):
        super().__init__()
        self.setAcceptDrops(True)

        # Store the orientation for drag checks later.
        self.orientation = orientation

        if self.orientation == Qt.Orientation.Vertical:
            self.blayout = QVBoxLayout()
        else:
            self.blayout = QHBoxLayout()

        # Add the drag target indicator. This is invisible by default,
        # we show it and move it around while the drag is active.
        self._drag_target_indicator = DragTargetIndicator()
        self.blayout.addWidget(self._drag_target_indicator)
        self._drag_target_indicator.hide()

        self.setLayout(self.blayout)

Next we modify the DragWidget.dragMoveEvent to show the drag target indicator. We show it by inserting it into the layout and then calling .show -- inserting a widget which is already in a layout will move it. We also hide the original item which is being dragged.

In the earlier examples we determined the position on drop by removing the widget being dragged, and then iterating over what is left. Because we now need to calculate the drop location before the drop, we take a different approach.

If we wanted to do it the same way, we'd need to remove the item on drag start, hold onto it and implement re-inserting at it's old position on drag fail. That's a lot of work.

Instead, the dragged item is left in place and hidden during move.

python

    def dragMoveEvent(self, e):
        # Find the correct location of the drop target, so we can move it there.
        index = self._find_drop_location(e)
        if index is not None:
            # Inserting moves the item if its alreaady in the layout.
            self.blayout.insertWidget(index, self._drag_target_indicator)
            # Hide the item being dragged.
            e.source().hide()
            # Show the target.
            self._drag_target_indicator.show()
        e.accept()

Calculating the Drop Location

The method self._find_drop_location finds the index where the drag target will be shown (or the item dropped when the mouse is released). We'll implement that next.

The calculation of the drop location follows the same pattern as before. We iterate over the items in the layout and calculate whether our mouse drop location is to the left of each widget. If it isn't to the left of any widget, we drop on the far right.

python

    def _find_drop_location(self, e):
        pos = e.position()
        spacing = self.blayout.spacing() / 2

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()

            if self.orientation == Qt.Orientation.Vertical:
                # Drag drop vertically.
                drop_here = (
                    pos.y() >= w.y() - spacing
                    and pos.y() <= w.y() + w.size().height() + spacing
                )
            else:
                # Drag drop horizontally.
                drop_here = (
                    pos.x() >= w.x() - spacing
                    and pos.x() <= w.x() + w.size().width() + spacing
                )

            if drop_here:
                # Drop over this target.
                break

        return n

The drop location n is returned for use in the dragMoveEvent to place the drop target indicator.

Updating get_item_data to Ignore the Indicator

Next we need to update the get_item_data handler to ignore the drop target indicator. To do this we check w against self._drag_target_indicator and skip if it is the same. With this change the method will work as expected.

python

    def get_item_data(self):
        data = []
        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if w != self._drag_target_indicator:
                # The target indicator has no data.
                data.append(w.data)
        return data

Handling dragLeaveEvent

If you run the code at this point the drag behavior will work as expected. But if you drag the widget outside of the window and drop you'll notice a problem: the target indicator will stay in place, but dropping the item won't drop the item in that position (the drop will be cancelled).

To fix that we need to implement a dragLeaveEvent which hides the indicator.

python

    def dragLeaveEvent(self, e):
        self._drag_target_indicator.hide()
        e.accept()

Complete Drag & Drop with Visual Drop Indicator

With those changes, the drag-drop behavior should be working as intended. The complete code is shown below.

python

from PySide6.QtCore import QMimeData, Qt, Signal
from PySide6.QtGui import QDrag, QPixmap
from PySide6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)


class DragTargetIndicator(QLabel):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setContentsMargins(25, 5, 25, 5)
        self.setStyleSheet(
            "QLabel { background-color: #ccc; border: 1px solid black; }"
        )


class DragItem(QLabel):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setContentsMargins(25, 5, 25, 5)
        self.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setStyleSheet("border: 1px solid black;")
        # Store data separately from display label, but use label for default.
        self.data = self.text()

    def set_data(self, data):
        self.data = data

    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)

            pixmap = QPixmap(self.size())
            self.render(pixmap)
            drag.setPixmap(pixmap)

            drag.exec(Qt.DropAction.MoveAction)
            self.show() # Show this widget again, if it's dropped outside.


class DragWidget(QWidget):
    """
    Generic list sorting handler.
    """

    orderChanged = Signal(list)

    def __init__(self, *args, orientation=Qt.Orientation.Vertical, **kwargs):
        super().__init__()
        self.setAcceptDrops(True)

        # Store the orientation for drag checks later.
        self.orientation = orientation

        if self.orientation == Qt.Orientation.Vertical:
            self.blayout = QVBoxLayout()
        else:
            self.blayout = QHBoxLayout()

        # Add the drag target indicator. This is invisible by default,
        # we show it and move it around while the drag is active.
        self._drag_target_indicator = DragTargetIndicator()
        self.blayout.addWidget(self._drag_target_indicator)
        self._drag_target_indicator.hide()

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

    def dragLeaveEvent(self, e):
        self._drag_target_indicator.hide()
        e.accept()

    def dragMoveEvent(self, e):
        # Find the correct location of the drop target, so we can move it there.
        index = self._find_drop_location(e)
        if index is not None:
            # Inserting moves the item if its alreaady in the layout.
            self.blayout.insertWidget(index, self._drag_target_indicator)
            # Hide the item being dragged.
            e.source().hide()
            # Show the target.
            self._drag_target_indicator.show()
        e.accept()

    def dropEvent(self, e):
        widget = e.source()
        # Use drop target location for destination, then remove it.
        self._drag_target_indicator.hide()
        index = self.blayout.indexOf(self._drag_target_indicator)
        if index is not None:
            self.blayout.insertWidget(index, widget)
            self.orderChanged.emit(self.get_item_data())
            widget.show()
            self.blayout.activate()
        e.accept()

    def _find_drop_location(self, e):
        pos = e.position()
        spacing = self.blayout.spacing() / 2

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()

            if self.orientation == Qt.Orientation.Vertical:
                # Drag drop vertically.
                drop_here = (
                    pos.y() >= w.y() - spacing
                    and pos.y() <= w.y() + w.size().height() + spacing
                )
            else:
                # Drag drop horizontally.
                drop_here = (
                    pos.x() >= w.x() - spacing
                    and pos.x() <= w.x() + w.size().width() + spacing
                )

            if drop_here:
                # Drop over this target.
                break

        return n

    def add_item(self, item):
        self.blayout.addWidget(item)

    def get_item_data(self):
        data = []
        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if w != self._drag_target_indicator:
                # The target indicator has no data.
                data.append(w.data)
        return data


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.drag = DragWidget(orientation=Qt.Orientation.Vertical)
        for n, l in enumerate(["A", "B", "C", "D"]):
            item = DragItem(l)
            item.set_data(n)  # Store the data.
            self.drag.add_item(item)

        # Print out the changed order.
        self.drag.orderChanged.connect(print)

        container = QWidget()
        layout = QVBoxLayout()
        layout.addStretch(1)
        layout.addWidget(self.drag)
        layout.addStretch(1)
        container.setLayout(layout)

        self.setCentralWidget(container)


app = QApplication([])
w = MainWindow()
w.show()

app.exec()

Fixing Blurry QPixmap Drag Preview on macOS Retina Displays

If you run this example on macOS you may notice that the widget drag preview (the QPixmap created on DragItem) is a bit blurry. On high-resolution screens you need to set the device pixel ratio and scale up the pixmap when you create it. Below is a modified DragItem class which does this.

Update DragItem to support high resolution screens.

python

class DragItem(QLabel):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setContentsMargins(25, 5, 25, 5)
        self.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setStyleSheet("border: 1px solid black;")
        # Store data separately from display label, but use label for default.
        self.data = self.text()

    def set_data(self, data):
        self.data = data

    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)

            # Render at x2 pixel ratio to avoid blur on Retina screens.
            pixmap = QPixmap(self.size().width() * 2, self.size().height() * 2)
            pixmap.setDevicePixelRatio(2)
            self.render(pixmap)
            drag.setPixmap(pixmap)

            drag.exec(Qt.DropAction.MoveAction)
            self.show() # Show this widget again, if it's dropped outside.

That's it! We've created a generic drag-drop widget which can be added to any PySide6 project where you need to be able to reorder items within a list. You should feel free to experiment with the styling of the drag items and targets as this won't affect the behavior.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Drag & Drop Widgets with PyQt6 — Sort widgets visually with drag and drop in a container

2024-02-07T13:00:00+00:00

I had an interesting question from a reader of my PyQt6 book, about how to handle dragging and dropping of widgets in a container showing the dragged widget as it is moved.

I'm interested in managing movement of a QWidget with mouse in a container. I've implemented the application with drag & drop, exchanging the position of buttons, but I want to show the motion of QPushButton, like what you see in Qt Designer. Dragging a widget should show the widget itself, not just the mouse pointer.

First, we'll implement the simple case which drags widgets without showing anything extra. Then we can extend it to answer the question. By the end of this tutorial we'll have a generic drag and drop implementation which looks like the following.

Setting Up Drag & Drop Widgets in PyQt6

We'll start with a simple application which creates a window using QWidget and places a series of QPushButton widgets into it.

python

from PyQt6.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget


class Window(QWidget):
    def __init__(self):
        super().__init__()

        self.blayout = QHBoxLayout()
        for l in ["A", "B", "C", "D"]:
            btn = QPushButton(l)
            self.blayout.addWidget(btn)

        self.setLayout(self.blayout)


app = QApplication([])
w = Window()
w.show()

app.exec()

If you run this you should see something like this.

The series of QPushButton widgets in a horizontal layout.

Here we're creating a window, but the Window widget is subclassed from QWidget, meaning you can add this widget to any other layout. See later for an example of a generic object sorting widget.

Making QPushButton Draggable with QDrag

QPushButton objects aren't usually draggable, so to handle the mouse movements and initiate a drag we need to implement a subclass. We can add the following to the top of the file.

python

from PyQt6.QtCore import QMimeData, Qt
from PyQt6.QtGui import QDrag
from PyQt6.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget


class DragButton(QPushButton):
    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)
            drag.exec(Qt.DropAction.MoveAction)

We implement a mouseMoveEvent which accepts the single e parameter of the event. We check to see if the left mouse button is pressed on this event -- as it would be when dragging -- and then initiate a drag. To start a drag, we create a QDrag object, passing in self to give us access later to the widget that was dragged. We also must pass in mime data. This is used for including information about what is dragged, particularly for passing data between applications. However, as here, it is fine to leave this empty.

Finally, we initiate a drag by calling drag.exec_(Qt.MoveAction). As with dialogs exec_() starts a new event loop, blocking the main loop until the drag is complete. The parameter Qt.MoveAction tells the drag handler what type of operation is happening, so it can show the appropriate icon tip to the user.

You can update the main window code to use our new DragButton class as follows.

python

class Window(QWidget):
    def __init__(self):
        super().__init__()

        self.blayout = QHBoxLayout()
        for l in ["A", "B", "C", "D"]:
            btn = DragButton(l)
            self.blayout.addWidget(btn)

        self.setLayout(self.blayout)

If you run the code now, you can drag the buttons, but you'll notice the drag is forbidden.

Dragging of the widget starts but is forbidden.

What's happening? The mouse movement is being detected by our DragButton object and the drag started, but the main window does not accept drag & drop.

Accepting Drops with dragEnterEvent and dropEvent

To fix the forbidden drag icon we need to enable drops on the window and implement dragEnterEvent to actually accept them.

python

class Window(QWidget):
    def __init__(self):
        super().__init__()
        self.setAcceptDrops(True)

        self.blayout = QHBoxLayout()
        for l in ["A", "B", "C", "D"]:
            btn = DragButton(l)
            self.blayout.addWidget(btn)

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

Dragging of the widget starts and is accepted, showing a move icon.

The drop event contains the position the mouse was at when the button was released & the drop triggered. We can use this to determine where to move the widget to.

Calculating the Drop Position in the Layout

If we get to the end of the loop without finding a match, we must be dropping past the end of the existing items, so we increment n one further (in the else: block below).

python

    def dropEvent(self, e):
        pos = e.position()
        widget = e.source()
        self.blayout.removeWidget(widget)

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if pos.x() < w.x():
                # We didn't drag past this widget.
                # insert to the left of it.
                break
        else:
            # We aren't on the left hand side of any widget,
            # so we're at the end. Increment 1 to insert after.
            n += 1
        self.blayout.insertWidget(n, widget)

        e.accept()

python

    def dropEvent(self, e):
        pos = e.position()
        widget = e.source()
        self.blayout.removeWidget(widget)

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if pos.x() < w.x() + w.size().width() // 2:
                # We didn't drag past this widget.
                # insert to the left of it.
                break
        else:
            # We aren't on the left hand side of any widget,
            # so we're at the end. Increment 1 to insert after.
            n += 1
        self.blayout.insertWidget(n, widget)

        e.accept()

The complete working drag and drop code is shown below.

python

from PyQt6.QtCore import QMimeData, Qt
from PyQt6.QtGui import QDrag
from PyQt6.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget


class DragButton(QPushButton):
    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)
            drag.exec(Qt.DropAction.MoveAction)


class Window(QWidget):
    def __init__(self):
        super().__init__()
        self.setAcceptDrops(True)

        self.blayout = QHBoxLayout()
        for l in ["A", "B", "C", "D"]:
            btn = DragButton(l)
            self.blayout.addWidget(btn)

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

    def dropEvent(self, e):
        pos = e.position()
        widget = e.source()
        self.blayout.removeWidget(widget)

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if pos.x() < w.x() + w.size().width() // 2:
                # We didn't drag past this widget.
                # insert to the left of it.
                break
        else:
            # We aren't on the left hand side of any widget,
            # so we're at the end. Increment 1 to insert after.
            n += 1

        self.blayout.insertWidget(n, widget)

        e.accept()


app = QApplication([])
w = Window()
w.show()

app.exec()

Visual Drag & Drop with QPixmap Preview

We now have a working drag & drop implementation. Next we'll move onto improving the UX by showing the drag visually. First we'll add support for showing the button being dragged next to the mouse point as it is dragged. That way the user knows exactly what it is they are dragging.

python

from PyQt6.QtCore import QMimeData, Qt
from PyQt6.QtGui import QDrag, QPixmap
from PyQt6.QtWidgets import QApplication, QHBoxLayout, QPushButton, QWidget


class DragButton(QPushButton):
    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)

            pixmap = QPixmap(self.size())
            self.render(pixmap)
            drag.setPixmap(pixmap)

            drag.exec(Qt.DropAction.MoveAction)

If you run the code with this modification you'll see something like the following --

Dragging of the widget showing the dragged widget as a QPixmap preview.

Building a Generic Drag & Drop Sortable Container

You can add items -- instances of DragItem -- which you want to be sorted, as well as setting data on them. When items are re-ordered the new order is emitted as a signal orderChanged.

python

from PyQt6.QtCore import QMimeData, Qt, pyqtSignal
from PyQt6.QtGui import QDrag, QPixmap
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)


class DragItem(QLabel):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setContentsMargins(25, 5, 25, 5)
        self.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setStyleSheet("border: 1px solid black;")
        # Store data separately from display label, but use label for default.
        self.data = self.text()

    def set_data(self, data):
        self.data = data

    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)

            pixmap = QPixmap(self.size())
            self.render(pixmap)
            drag.setPixmap(pixmap)

            drag.exec(Qt.DropAction.MoveAction)


class DragWidget(QWidget):
    """
    Generic list sorting handler.
    """

    orderChanged = pyqtSignal(list)

    def __init__(self, *args, orientation=Qt.Orientation.Vertical, **kwargs):
        super().__init__()
        self.setAcceptDrops(True)

        # Store the orientation for drag checks later.
        self.orientation = orientation

        if self.orientation == Qt.Orientation.Vertical:
            self.blayout = QVBoxLayout()
        else:
            self.blayout = QHBoxLayout()

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

    def dropEvent(self, e):
        pos = e.position()
        widget = e.source()
        self.blayout.removeWidget(widget)

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if self.orientation == Qt.Orientation.Vertical:
                # Drag drop vertically.
                drop_here = pos.y() < w.y() + w.size().height() // 2
            else:
                # Drag drop horizontally.
                drop_here = pos.x() < w.x() + w.size().width() // 2

            if drop_here:
                break

        else:
            # We aren't on the left hand/upper side of any widget,
            # so we're at the end. Increment 1 to insert after.
            n += 1

        self.blayout.insertWidget(n, widget)
        self.orderChanged.emit(self.get_item_data())

        e.accept()

    def add_item(self, item):
        self.blayout.addWidget(item)

    def get_item_data(self):
        data = []
        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            data.append(w.data)
        return data


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.drag = DragWidget(orientation=Qt.Orientation.Vertical)
        for n, l in enumerate(["A", "B", "C", "D"]):
            item = DragItem(l)
            item.set_data(n)  # Store the data.
            self.drag.add_item(item)

        # Print out the changed order.
        self.drag.orderChanged.connect(print)

        container = QWidget()
        layout = QVBoxLayout()
        layout.addStretch(1)
        layout.addWidget(self.drag)
        layout.addStretch(1)
        container.setLayout(layout)

        self.setCentralWidget(container)


app = QApplication([])
w = MainWindow()
w.show()

app.exec()

Generic drag-drop sorting in horizontal orientation.

In the example above we're passing in the enumerated index as the data, so dragging will output (via the print connected to orderChanged) something like:

python

[1, 0, 2, 3]
[1, 2, 0, 3]
[1, 0, 2, 3]
[1, 2, 0, 3]

If you remove the item.set_data(n) you'll see the labels emitted on changes.

python

['B', 'A', 'C', 'D']
['B', 'C', 'A', 'D']

Generic drag-drop sorting in vertical orientation.

Adding a Visual Drop Target Indicator

In this final section we'll implement this type of drag and drop preview indicator.

Creating the DragTargetIndicator Widget

python

from PyQt6.QtCore import QMimeData, Qt, pyqtSignal
from PyQt6.QtGui import QDrag, QPixmap
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)


class DragTargetIndicator(QLabel):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setContentsMargins(25, 5, 25, 5)
        self.setStyleSheet(
            "QLabel { background-color: #ccc; border: 1px solid black; }"
        )

We've copied the contents margins from the items in the list. If you change your list items, remember to also update the indicator dimensions to match.

Showing and Moving the Drop Indicator During Drag

The drag item is unchanged, but we need to implement some additional behavior on our DragWidget to add the target, control showing and moving it.

First we'll add the drag target indicator to the layout on our DragWidget. This is hidden to begin with, but will be shown during the drag.

python

class DragWidget(QWidget):
    """
    Generic list sorting handler.
    """

    orderChanged = pyqtSignal(list)

    def __init__(self, *args, orientation=Qt.Orientation.Vertical, **kwargs):
        super().__init__()
        self.setAcceptDrops(True)

        # Store the orientation for drag checks later.
        self.orientation = orientation

        if self.orientation == Qt.Orientation.Vertical:
            self.blayout = QVBoxLayout()
        else:
            self.blayout = QHBoxLayout()

        # Add the drag target indicator. This is invisible by default,
        # we show it and move it around while the drag is active.
        self._drag_target_indicator = DragTargetIndicator()
        self.blayout.addWidget(self._drag_target_indicator)
        self._drag_target_indicator.hide()

        self.setLayout(self.blayout)

If we wanted to do it the same way, we'd need to remove the item on drag start, hold onto it and implement re-inserting at it's old position on drag fail. That's a lot of work.

Instead, the dragged item is left in place and hidden during move.

python

    def dragMoveEvent(self, e):
        # Find the correct location of the drop target, so we can move it there.
        index = self._find_drop_location(e)
        if index is not None:
            # Inserting moves the item if its alreaady in the layout.
            self.blayout.insertWidget(index, self._drag_target_indicator)
            # Hide the item being dragged.
            e.source().hide()
            # Show the target.
            self._drag_target_indicator.show()
        e.accept()

The method self._find_drop_location finds the index where the drag target will be shown (or the item dropped when the mouse released). We'll implement that next.

Implementing the Drop Location Calculation

python

    def _find_drop_location(self, e):
        pos = e.position()
        spacing = self.blayout.spacing() / 2

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()

            if self.orientation == Qt.Orientation.Vertical:
                # Drag drop vertically.
                drop_here = (
                    pos.y() >= w.y() - spacing
                    and pos.y() <= w.y() + w.size().height() + spacing
                )
            else:
                # Drag drop horizontally.
                drop_here = (
                    pos.x() >= w.x() - spacing
                    and pos.x() <= w.x() + w.size().width() + spacing
                )

            if drop_here:
                # Drop over this target.
                break

        return n

The drop location n is returned for use in the dragMoveEvent to place the drop target indicator.

python

    def get_item_data(self):
        data = []
        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if w != self._drag_target_indicator:
                # The target indicator has no data.
                data.append(w.data)
        return data

Handling dragLeaveEvent to Clean Up the Indicator

To fix that we need to implement a dragLeaveEvent which hides the indicator.

python

    def dragLeaveEvent(self, e):
        self._drag_target_indicator.hide()
        e.accept()

Complete Drag & Drop with Visual Indicator

With those changes, the drag-drop behavior should be working as intended. The complete code is shown below.

python

from PyQt6.QtCore import QMimeData, Qt, pyqtSignal
from PyQt6.QtGui import QDrag, QPixmap
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)


class DragTargetIndicator(QLabel):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setContentsMargins(25, 5, 25, 5)
        self.setStyleSheet(
            "QLabel { background-color: #ccc; border: 1px solid black; }"
        )


class DragItem(QLabel):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setContentsMargins(25, 5, 25, 5)
        self.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setStyleSheet("border: 1px solid black;")
        # Store data separately from display label, but use label for default.
        self.data = self.text()

    def set_data(self, data):
        self.data = data

    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)

            pixmap = QPixmap(self.size())
            self.render(pixmap)
            drag.setPixmap(pixmap)

            drag.exec(Qt.DropAction.MoveAction)
            self.show() # Show this widget again, if it's dropped outside.


class DragWidget(QWidget):
    """
    Generic list sorting handler.
    """

    orderChanged = pyqtSignal(list)

    def __init__(self, *args, orientation=Qt.Orientation.Vertical, **kwargs):
        super().__init__()
        self.setAcceptDrops(True)

        # Store the orientation for drag checks later.
        self.orientation = orientation

        if self.orientation == Qt.Orientation.Vertical:
            self.blayout = QVBoxLayout()
        else:
            self.blayout = QHBoxLayout()

        # Add the drag target indicator. This is invisible by default,
        # we show it and move it around while the drag is active.
        self._drag_target_indicator = DragTargetIndicator()
        self.blayout.addWidget(self._drag_target_indicator)
        self._drag_target_indicator.hide()

        self.setLayout(self.blayout)

    def dragEnterEvent(self, e):
        e.accept()

    def dragLeaveEvent(self, e):
        self._drag_target_indicator.hide()
        e.accept()

    def dragMoveEvent(self, e):
        # Find the correct location of the drop target, so we can move it there.
        index = self._find_drop_location(e)
        if index is not None:
            # Inserting moves the item if its alreaady in the layout.
            self.blayout.insertWidget(index, self._drag_target_indicator)
            # Hide the item being dragged.
            e.source().hide()
            # Show the target.
            self._drag_target_indicator.show()
        e.accept()

    def dropEvent(self, e):
        widget = e.source()
        # Use drop target location for destination, then remove it.
        self._drag_target_indicator.hide()
        index = self.blayout.indexOf(self._drag_target_indicator)
        if index is not None:
            self.blayout.insertWidget(index, widget)
            self.orderChanged.emit(self.get_item_data())
            widget.show()
            self.blayout.activate()
        e.accept()

    def _find_drop_location(self, e):
        pos = e.position()
        spacing = self.blayout.spacing() / 2

        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()

            if self.orientation == Qt.Orientation.Vertical:
                # Drag drop vertically.
                drop_here = (
                    pos.y() >= w.y() - spacing
                    and pos.y() <= w.y() + w.size().height() + spacing
                )
            else:
                # Drag drop horizontally.
                drop_here = (
                    pos.x() >= w.x() - spacing
                    and pos.x() <= w.x() + w.size().width() + spacing
                )

            if drop_here:
                # Drop over this target.
                break

        return n

    def add_item(self, item):
        self.blayout.addWidget(item)

    def get_item_data(self):
        data = []
        for n in range(self.blayout.count()):
            # Get the widget at each index in turn.
            w = self.blayout.itemAt(n).widget()
            if w != self._drag_target_indicator:
                # The target indicator has no data.
                data.append(w.data)
        return data


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.drag = DragWidget(orientation=Qt.Orientation.Vertical)
        for n, l in enumerate(["A", "B", "C", "D"]):
            item = DragItem(l)
            item.set_data(n)  # Store the data.
            self.drag.add_item(item)

        # Print out the changed order.
        self.drag.orderChanged.connect(print)

        container = QWidget()
        layout = QVBoxLayout()
        layout.addStretch(1)
        layout.addWidget(self.drag)
        layout.addStretch(1)
        container.setLayout(layout)

        self.setCentralWidget(container)


app = QApplication([])
w = MainWindow()
w.show()

app.exec()

Fixing Blurry Drag Previews on Retina/High-DPI Screens

Update DragItem to support high resolution screens.

python

class DragItem(QLabel):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setContentsMargins(25, 5, 25, 5)
        self.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setStyleSheet("border: 1px solid black;")
        # Store data separately from display label, but use label for default.
        self.data = self.text()

    def set_data(self, data):
        self.data = data

    def mouseMoveEvent(self, e):
        if e.buttons() == Qt.MouseButton.LeftButton:
            drag = QDrag(self)
            mime = QMimeData()
            drag.setMimeData(mime)

            # Render at x2 pixel ratio to avoid blur on Retina screens.
            pixmap = QPixmap(self.size().width() * 2, self.size().height() * 2)
            pixmap.setDevicePixelRatio(2)
            self.render(pixmap)
            drag.setPixmap(pixmap)

            drag.exec(Qt.DropAction.MoveAction)
            self.show() # Show this widget again, if it's dropped outside.

That's it! We've created a generic drag and drop handler which can be added to any projects where you need to be able to reposition items within a list. You should feel free to experiment with the styling of the drag items and targets as this won't affect the behavior.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

QLineEdit — A Complete Guide to Single-Line Text Input in PyQt/PySide

2024-02-05T06:00:00+00:00

The QLineEdit class is a versatile tool for single-line text input in PyQt and PySide applications. The widget facilitates text manipulation by supporting insertion, deletion, selection, and cut-copy-paste operations natively. You can use line edits when you need to accept text input from your users in a PyQt/PySide application.

The widget is highly customizable. You can set it up to include placeholder text, input masks, input validators, and more. It also supports many keyboard shortcuts out of the box and is able to process custom ones. This feature opens an opportunity to enhance user input speed and efficiency.

In this tutorial, you will learn the basics of using QLineEdit by going through its most commonly used features and capabilities, including creating line edits, manipulating text, aligning content, connecting signals and slots, and validating user input.

Creating Line Edit Widgets With `QLineEdit`

A line edit allows the user to enter and edit a single line of plain text with a useful collection of editing functionalities, such as insertion, deletion, selection, cut-copy-paste, and drag-and-drop operations.

If you've used PyQt or PySide to create GUI applications in Python, then it'd be likely that you already know about the QLineEdit class. This class allows you to create line edits in your graphical interfaces (GUI) quickly.

The QLineEdit class provides two different constructors that you can use to create line edits according to your needs:

Constructor	Description
`QLineEdit(parent: QWidget = None)`	Constructs a line edit with a parent widget but without text
`QLineEdit(text: str, parent: QWidget = None)`	Constructs a line edit with default text and a parent widget

The parent widget would be the window or dialog where you need to place the line edit. The text can be a default text that will appear in the line edit when you run the application.

To illustrate how to use the above constructors, we can code a demo example:

python

from PyQt6.QtWidgets import QApplication, QLineEdit, QVBoxLayout, QWidget

class Window(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("QLineEdit Constructors")
        self.resize(300, 100)
        # Line edit with a parent widget
        top_line_edit = QLineEdit(parent=self)
        # Line edit with a parent widget and a default text
        bottom_line_edit = QLineEdit(
            "Hello! This is a line edit.", parent=self
        )

        layout = QVBoxLayout()
        layout.addWidget(top_line_edit)
        layout.addWidget(bottom_line_edit)
        self.setLayout(layout)

app = QApplication([])
window = Window()
window.show()
app.exec()

In this example, we first do the required imports and then define the Window class inheriting from QWidget. Inside Window, we create two QLineEdit widgets.

To create the first line edit, we use the first constructor of QLineEdit, passing only a parent widget. For the second line editor, we use the second constructor, which requires the parent widget and a default text. Note that the text is a regular Python string.

Save the code to a file called constructors.py file and run it from your command line. You'll get a window that looks something like this:

Standard window showing our two line edits.

The first line edit has no text. In most cases, this is how you would create your line edits because they're designed for accepting input. If you'd like to just display some text, then you can use a QLabel widget instead. The second line edit displays the text that you passed to the constructor.

Both line edits are ready for accepting input text. Note that you can use all the following keyboard shortcuts to optimize your text input process:

Keys	Action
Left Arrow	Moves the cursor one character to the left
Shift+Left Arrow	Moves and selects text one character to the left
Right Arrow	Moves the cursor one character to the right
Shift+Right Arrow	Moves and selects text one character to the right
Home	Moves the cursor to the beginning of the line
End	Moves the cursor to the end of the line
Backspace	Deletes the character to the left of the cursor
Ctrl+Backspace	Deletes the word to the left of the cursor
Delete	Deletes the character to the right of the cursor
Ctrl+Delete	Deletes the word to the right of the cursor
Ctrl+A	Select all
Ctrl+C	Copies the selected text to the clipboard
Ctrl+Insert	Copies the selected text to the clipboard
Ctrl+K	Deletes to the end of the line
Ctrl+V	Pastes the clipboard text into the line edit
Shift+Insert	Pastes the clipboard text into the line edit
Ctrl+X	Deletes the selected text and copies it to the clipboard
Shift+Delete	Deletes the selected text and copies it to the clipboard
Ctrl+Z	Undoes the last operation
Ctrl+Y	Redoes the last undone operation

That's a lot of shortcuts! This table is just a sample of all the features that the QLineEdit class provides out of the box.

In addition to these keyboard shortcuts, the QLineEdit class provides a context menu that you can trigger by clicking on a line edit using the right button of your mouse:

QLineEdit with a context menu visible.

The built-in context menu provides basic edition options, such as cut, copy, paste, and delete. It also has options for undoing and redoing edits, and for selecting all the content of a given line edit.

Creating Read-Only Line Edits

Sometimes, we need to make a line edit non-editable. By default, all line edits are editable because their main use case is to provide text input for the user. However, in some situations, a read-only line edit can be useful.

For example, say that you're creating a GUI application that generates some recovery keys for the users. The user must be able to copy the key to a safe place so that they can use it to recover access if they forget their password. In this situation, creating a read-only line edit can provide a suitable solution.

To make a line edit read-only, we can use the readOnly property and its setter method setReadOnly() as in the following example:

python

import secrets

from PyQt6.QtWidgets import (
    QApplication,
    QLabel,
    QLineEdit,
    QVBoxLayout,
    QWidget,
)

class Window(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("Non-editable QLineEdit")
        self.resize(300, 100)
        non_editable_line_edit = QLineEdit(parent=self)
        non_editable_line_edit.setReadOnly(True)
        non_editable_line_edit.setText(secrets.token_hex(16))

        layout = QVBoxLayout()
        layout.addWidget(QLabel(parent=self, text="Your secret key:"))
        layout.addWidget(non_editable_line_edit)
        self.setLayout(layout)

app = QApplication([])
window = Window()
window.show()
app.exec()

In this example, we create a read-only line edit by using the setReadOnly() method. When we set the readOnly property to True, our line edit won't accept editions. It'll only allow us to select and copy its content.

Go ahead and run the application from your command line to explore how this line edit works. You'll get a window like the following:

A read-only line edit with editing disabled.

If you play a bit with this line edit, you'll soon discover that you can't change its text. You'll also note that the options in the context menu are now limited to Copy and Select All.

Creating Password Input Fields With QLineEdit

Another cool feature of the QLineEdit class is that it allows you to create text input for passwords. This can be pretty convenient for those applications that manage several users, and each user needs to have access credentials.

You can create line edits for passwords by using the echoMode() method. This method takes one of the following constants as an argument:

Constant	Value	Description
`QLineEdit.EchoMode.Normal`	`0`	Display characters as you enter them.
`QLineEdit.EchoMode.NoEcho`	`1`	Display no characters when you enter them.
`QLineEdit.EchoMode.Password`	`2`	Display platform-dependent password mask characters instead of the characters you enter.
`QLineEdit.EchoMode.PasswordEchoOnEdit`	`3`	Display characters as you enter them while editing. Display characters as the `Password` mode does when reading.

The Normal mode is the default. The NoEcho mode may be appropriate for critical passwords where even the length of the password should be kept secret. The Password mode is appropriate for most password use cases, however PasswordEchoOnEdit can be used instead if you need to give users some confirmation of what they are typing.

Here's a sample app that shows a user and password form:

python

from PyQt6.QtWidgets import (
    QApplication,
    QFormLayout,
    QLineEdit,
    QWidget,
)

class Window(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("Password QLineEdit")
        self.resize(300, 100)
        username_line_edit = QLineEdit(parent=self)
        password_line_edit = QLineEdit(parent=self)
        password_line_edit.setEchoMode(QLineEdit.EchoMode.Password)

        layout = QFormLayout()
        layout.addRow("Username:", username_line_edit)
        layout.addRow("Password:", password_line_edit)
        self.setLayout(layout)

app = QApplication([])
window = Window()
window.show()
app.exec()

In this example, you call setEchoMode() on the password_line_edit widget using the Password mode as an argument. When you run this code from your command line, you get the following window on your screen:

Window with a username and password line edit.

The username_line_edit line edit is in Normal mode, so we can see the characters as we type them in. In contrast, the Password line edit is in Password mode. In this case, when we enter a character, the line edit shows the platform's character for passwords.

Manipulating Text in a QLineEdit

You can change the text of a line edit using the setText() or insert() methods. You can retrieve the text with the text() method. However, these are not the only operations that you can perform with the text of a line edit.

The following table shows a summary of some of the most commonly used methods for text manipulation in line edits:

Method	Description
`setText(text)`	Sets the text of a line edit to `text`, clears the selection, clears the undo/redo history, moves the cursor to the end of the line, and resets the modified property to false.
`insert(text)`	Deletes any selected text, inserts `text`, and validates the result. If it is valid, it sets it as the new contents of the line edit.
`clear()`	Clears the contents of the line edit.
`copy()`	Copies the selected text to the clipboard.
`cut()`	Copies the selected text to the clipboard and deletes it from the line edit.
`paste()`	Inserts the clipboard's text at the cursor position, deleting any selected text.
`redo()`	Redoes the last operation if redo is available. Redo becomes available once the user has performed one or more undo operations on text in the line edit.
`undo()`	Undoes the last operation if undo is available. Undo becomes available once the user has modified the text in the line edit.
`selectAll()`	Selects all the text and moves the cursor to the end.

You can use any of these methods to manipulate the text of a line edit from your code. Consider the following example where you have two line edits and two buttons that take advantage of some of the above methods to copy some text from one line edit to the other:

python

from PyQt6.QtWidgets import (
    QApplication,
    QGridLayout,
    QLabel,
    QLineEdit,
    QPushButton,
    QWidget,
)

class Window(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("Copy and Paste")
        self.resize(300, 100)

        self.source_line_edit = QLineEdit(parent=self)
        self.source_line_edit.setText("Hello, World!")
        self.dest_line_edit = QLineEdit(parent=self)

        copy_button = QPushButton(parent=self, text="Copy")
        paste_button = QPushButton(parent=self, text="Paste")

        copy_button.clicked.connect(self.copy)
        paste_button.clicked.connect(self.paste)

        layout = QGridLayout()
        layout.addWidget(self.source_line_edit, 0, 0)
        layout.addWidget(copy_button, 0, 1)
        layout.addWidget(self.dest_line_edit, 1, 0)
        layout.addWidget(paste_button, 1, 1)
        self.setLayout(layout)

    def copy(self):
        self.source_line_edit.selectAll()
        self.source_line_edit.copy()

    def paste(self):
        self.dest_line_edit.clear()
        self.dest_line_edit.paste()

app = QApplication([])
window = Window()
window.show()
app.exec()

In this example, we create two line edits. The first one will hold some sample text. The second line edit will receive the text. Then, we create two buttons and connect their clicked signals to the copy() and paste() slots.

Inside the copy() method we first select all the text from the source line edit. Then we use the copy() method to copy the selected text to the clipboard. In paste(), we call clear() on the destination line edit to remove any previous text. Then, we use the paste() method to copy the clipboard's content.

Go ahead and run the application. You'll get the following window on your screen:

QLineEdit with Copy & Paste buttons attached to handlers.

Once you've run the app, then you can click the Copy button to copy the text in the first line edit. Next, you can click the Paste button to paste the copied text to the second line edit. Go ahead and give it a try!

Aligning and Formatting Text in a QLineEdit

You can also align and format the text in a line edit. For example, for text alignment, you can use the setAlignment() method with one or more alignment flags. Some of the most useful flags that you can find in the Qt.AlignmentFlag namespace includes the following:

Flag	Description
`AlignLeft`	Aligns with the left edge.
`AlignRight`	Aligns with the right edge.
`AlignHCenter`	Centers horizontally in the available space.
`AlignJustify`	Justifies the text in the available space.
`AlignTop`	Aligns with the top.
`AlignBottom`	Aligns with the bottom.
`AlignVCenter`	Centers vertically in the available space.
`AlignCenter`	Centers in both dimensions.

If you want to apply multiple alignment flags to a given line edit, you don't have to call setAlignment() multiple times. You can just use the bitwise OR operator (|) to combine them. Consider the following example:

python

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import QApplication, QLineEdit

class Window(QLineEdit):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("Aligning Text")
        self.resize(300, 100)
        self.setText("Hello, World!")
        self.setAlignment(Qt.AlignmentFlag.AlignCenter)

app = QApplication([])
window = Window()
window.show()
app.exec()

In this example, we use a QLineEdit as the only component of our app's GUI. Using the setAlignment() method, we center the "Hello, World!" message in both directions, horizontally and vertically. To do this, we use the AlignCenter flag. Here's what the app looks like:

QLineEdit with text alignment set.

Go ahead and play with other flags to see their effect on the text alignment. Use the | bitwise operator to combine several alignment flags.

Setting Text Margins on a QLineEdit

Line edits also have a textMargins property that you can tweak to customize the text alignment using specific values. To set margin values for your text, you can use the setTextMargins() method, which has the following signatures:

Method	Description
`setTextMargins(left, top, right, bottom)`	Sets the margins around the text to have the sizes `left`, `top`, `right`, and `bottom`.
`setTextMargins(margins)`	Sets the `margins` around the text using a `QMargins` object.

The first signature allows you to provide four integer values as the left, top, right, and bottom margins for the text. The second signature accepts a QMargins object as an argument. To build this object, you can use four integer values with the same meaning as the left, top, right, and bottom arguments in the first signature.

Here's an example of how to set custom margins for the text in a line edit:

python

from PyQt6.QtWidgets import QApplication, QLineEdit

class Window(QLineEdit):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("Aligning Text")
        self.resize(300, 100)
        self.setText("Hello, World!")
        self.setTextMargins(30, 30, 0, 0)

app = QApplication([])
window = Window()
window.show()
app.exec()

In this example, you set the left and top margins to custom values. Here's how this app looks when you run it:

QLineEdit with text margins added.

Using the setTextMargins() method, we can place the text in the desired place in a line edit, which may be a requirement in some situations.

Connecting QLineEdit Signals and Slots

When you're creating a GUI application and you need to use line edits, you may need to perform actions when the user enters or modifies the content of the line edit. To do this, you need to connect some of the signals of the line edit to specific slots or functions.

Depending on specific user events, the QLineEdit class can emit several different signals. Here's a summary of these signals and their corresponding meaning:

Signal	Emitted
`textChanged(text)`	Whenever the user changes the text either manually or programmatically. The `text` argument is the new text.
`textEdited(text)`	Whenever the user edits the text manually. The `text` argument is the new text.
`editingFinished`	When the user presses the Return or Enter key, or when the line edit loses focus, and its contents have changed since the last time this signal was emitted.
`inputRejected`	When the user presses a key that is an unacceptable input.
`returnPressed`	When the user presses the Return or Enter key.
`selectionChanged`	When the selection changes.

We can connect either of these signals with any slot. A slot is a method or function that performs a concrete action in your application. We can connect a signal and a slot so that the slot gets called when the signal gets emitted. Here's the required syntax to do this:

python

line_edit.<signal>.connect(<method>)

In this construct, line_edit is the QLineEdit object that we need to connect with a given slot. The <signal> placeholder can be any of the abovementioned signals. Finally, <method> represents the target slot or method.

Let's write an example that puts this syntax into action. For this example, we'll connect the textEdited signal with a method that updates the text of a QLabel to match the text of our line edit:

python

from PyQt6.QtWidgets import (
    QApplication,
    QLabel,
    QLineEdit,
    QVBoxLayout,
    QWidget,
)

class Window(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("Signal and Slot")
        self.resize(300, 100)

        self.line_edit = QLineEdit(parent=self)
        self.label = QLabel(parent=self)
        self.line_edit.textEdited.connect(self.update_label)

        layout = QVBoxLayout()
        layout.addWidget(self.line_edit)
        layout.addWidget(self.label)
        self.setLayout(layout)

    def update_label(self):
        self.label.setText(self.line_edit.text())

app = QApplication([])
window = Window()
window.show()
app.exec()

In this example, we connect the line edit's textEdited signal with the update_label() method, which sets the label's text to match the text we enter in our line edit. Go ahead and run the app. Then, enter some text in the line edit and see what happens with the label at the bottom of the app's window.

Validating User Input in QLineEdit

We can provide input validators to our line edits using the setValidator() method. This method takes a QValidator object as an argument. PyQt and PySide have a few built-in validators that you can use directly on a line edit:

QIntValidator — for integer validation
QDoubleValidator — for floating-point validation
QRegularExpressionValidator — for validation based on regular expressions

Validator objects process the input to check whether it's valid. In general, a validator object has three possible states:

Constant	Value	Description
`QValidator.State.Invalid`	`0`	The input is invalid.
`QValidator.State.Intermediate`	`1`	The input is a valid intermediate value.
`QValidator.State.Acceptable`	`2`	The input is acceptable as a final result.

When you set a validator to a given line edit, the user may change the content to any Intermediate value during editing. However, they can't edit the text to a value that is Invalid. The line edit will emit the returnPressed and editingFinished signals only when the validator validates input as Acceptable.

Here's an example where we use a QIntValidator and a QRegularExpressionValidator:

python

from PyQt6.QtCore import QRegularExpression
from PyQt6.QtGui import QIntValidator, QRegularExpressionValidator
from PyQt6.QtWidgets import (
    QApplication,
    QFormLayout,
    QLabel,
    QLineEdit,
    QWidget,
)

class Window(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("Input Validators")
        self.resize(300, 100)

        self.int_line_edit = QLineEdit(parent=self)
        self.int_line_edit.setValidator(QIntValidator())

        self.uppercase_line_edit = QLineEdit(parent=self)
        input_validator = QRegularExpressionValidator(
            QRegularExpression("[A-Z]+"), self.uppercase_line_edit
        )
        self.uppercase_line_edit.setValidator(input_validator)
        self.uppercase_line_edit.returnPressed.connect(self.update_label)

        self.signal_label = QLabel(parent=self)

        layout = QFormLayout()
        layout.addRow("Integers:", self.int_line_edit)
        layout.addRow("Uppercase letters:", self.uppercase_line_edit)
        layout.addRow("Signal:", self.signal_label)
        self.setLayout(layout)

    def update_label(self):
        self.signal_label.setText("Return pressed!")

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

In this example, we have two line edits. In the first line edit, we've used a QIntValidator object. This way, the line edit will only accept valid integer numbers. If you try to type in something different, then the line edit won't accept your input.

In the second line edit, we've used a QRegularExpressionValidator. In this specific case, the regular expression accepts one or more uppercase letters. Again if you try to enter something else, then the line edit won't accept the input.

The QLabel will show the text Return pressed! if the input in the second line edit is valid and you press the Enter key. Here's what the app looks like:

QLineEdit with input validators restricting user input.

Validators provide a quick way to restrict the user input and set our own validation rules. This way, we can ensure valid user input in our PyQt/PySide applications.

Conclusion

The QLineEdit widget is one of the most commonly used widgets in PyQt and PySide applications. It provides a single-line text editor with many built-in features including keyboard shortcuts, copy-paste support, and a context menu.

In this tutorial, you've learned how to:

Create line edits using the QLineEdit constructors
Make line edits read-only with setReadOnly()
Build password fields using echo modes
Manipulate text programmatically with setText(), copy(), paste(), and more
Align and format text using alignment flags and text margins
Connect signals and slots to respond to user input events
Validate input using QIntValidator, QDoubleValidator, and QRegularExpressionValidator

With these skills, you can effectively add and customize text input fields in your Python GUI applications built with PyQt or PySide.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

How to Create a Custom Title Bar for a PyQt6 Window — Build Modern, Stylish Custom Title Bars for Your Python Desktop Apps

2023-11-27T13:00:00+00:00

PyQt provides plenty of tools for creating unique and visually appealing graphical user interfaces (GUIs). One aspect of your applications that you may not have considered customizing is the title bar. The title bar is the topmost part of the window, where your users find the app's name, window controls & other elements.

This part of the window is usually drawn by the operating system or desktop environment, and its default look and feel may not gel well with the rest of your application. However, you may want to customize it to add additional functionality. For example, in web browsers the document tabs are now typically collapsed into the title bar to maximize available space for viewing pages.

In this tutorial, you will learn how to create custom title bars in PyQt6 step by step. We'll cover creating frameless windows, adding window control buttons, handling window dragging with the mouse, and styling the title bar with a modern unified look. By the end, you'll have the knowledge to enhance your PyQt applications with personalized and stylish title bars.

Creating Frameless Windows in PyQt6

The first step to providing a PyQt application with a custom title bar is to remove the default title bar and window decoration provided by the operating system. If we don't take this step, we'll end up with multiple title bars at the top of our windows.

In PyQt, we can create a frameless window using the setWindowFlags() method available on all QWidget subclasses, including QMainWindow. We call this method, passing in the FramelessWindowHint flag, which lives in the Qt namespace under the WindowType enumeration.

Here's the code of a minimal PyQt app whose main window is frameless:

python

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import QApplication, QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

After importing the required classes, we create a window by subclassing QMainWindow. In the class initializer method, we set the window's title and resize the window using the resize() method. Then we use the setWindowFlags() to make the window frameless. The rest is the usual boilerplate code for creating PyQt applications.

If you run this app from your command line, you'll get the following window on your screen:

A frameless window in PyQt6

As you can see, the app's main window doesn't have a title bar or any other decoration. It's only a gray rectangle on your screen.

Because the window has no buttons, you need to press Alt-F4 on Windows and Linux or Cmd+Q on macOS to close the app.

This isn't very helpful, of course, but we'll be adding back in our custom title bar shortly.

Setting Up the Main Window

Before creating our custom title bar, we'll finish the initialization of our app's main window, import some additional classes and create the window's central widget and layouts.

Here's the code update:

python

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        central_widget = QWidget()
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        work_space_layout.addWidget(QLabel("Hello, World!", self))

        centra_widget_layout = QVBoxLayout()
        centra_widget_layout.setContentsMargins(0, 0, 0, 0)
        centra_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        centra_widget_layout.addWidget(self.title_bar)
        centra_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(centra_widget_layout)
        self.setCentralWidget(central_widget)

# ...

First, we import the QLabel, QVBoxLayout, and QWidget classes. In our window's initializer, we create a central widget by instantiating QWidget(). Next, we create an instance attribute called title_bar by instantiating a class called CustomTitleBar. We still need to implement this class—we'll do this in a moment.

The next step is to create a layout for our window's workspace. In this example, we're using a QVBoxLayout, but you can use the layout that best fits your needs. We also set some margins for the layout content and added a label containing the phrase "Hello, World!".

Next, we create a global layout for our central widget. Again, we use a QVBoxLayout. We set the layout's margins to 0 and aligned it on the top of our frameless window. In this layout, we need to add the title bar at the top and the workspace at the bottom. Finally, we set the central widget's layout and the app's central widget.

That's it! We have all the boilerplate code we need for our window to work correctly. Now we're ready to write our custom title bar.

In this section, we will create a custom title bar for our main window. To do this, we will create a new class by inheriting from QWidget. First, go ahead and update your imports like in the code below:

python

from PyQt6.QtCore import QSize, Qt
from PyQt6.QtGui import QPalette
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QStyle,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

# ...

Here, we've imported a few new classes. We will use these classes as building blocks for our title bar. Without further ado, let's get into the title bar code. We'll introduce the code in small consecutive chunks to facilitate the explanation. Here's the first piece:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.setAutoFillBackground(True)
        self.setBackgroundRole(QPalette.ColorRole.Highlight)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)

In this code snippet, we create a new class by inheriting from QWidget. This way, our title bar will have all the standard features and functionalities of any PyQt widgets. In the class initializer, we set autoFillBackground to true because we want to give a custom color to the bar. The next line of code sets the title bar's background color to QPalette.ColorRole.Highlight, which is a blueish color.

The next line of code creates and initializes an instance attribute called initial_pos. We'll use this attribute later on when we deal with moving the window around our screen.

The final three lines of code allow us to create a layout for our title bar. Because the title bar should be horizontally oriented, we use a QHBoxLayout class to structure it.

Adding a Window Title Label

The piece of code below deals with our window's title:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setStyleSheet(
            """QLabel {
                   font-weight: bold;
                   border: 2px solid black;
                   border-radius: 12px;
                   margin: 2px;
                }
            """
        )
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

The first line of new code creates a title attribute. It's a QLabel object that will hold the window's title. Because we want to build a cool title bar, we'd like to add some custom styling to the title. To do this, we use the setStyleSheet() method with a string representing a CSS style sheet as an argument. The style sheet tweaks the font, borders, and margins of our title label.

Next, we center the title using the setAlignment() method with the Qt.AlignmentFlag.AlignCenter flag as an argument.

In the conditional statement, we check whether our window has a title. If that's the case, we set the text of our title label to the current window's title. Finally, we added the title label to the title bar layout.

Adding Minimize, Maximize, Close, and Restore Buttons

The next step in our journey to build a custom title bar is to provide standard window controls. In other words, we need to add the minimize, maximize, close, and normal buttons. These buttons will allow our users to interact with our window. To create the buttons, we'll use the QToolButton class.

Here's the required code:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        # Min button
        self.min_button = QToolButton(self)
        min_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMinButton
        )
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMaxButton
        )
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarCloseButton
        )
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarNormalButton
        )
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)

In this code snippet, we define all the required buttons by instantiating the QToolButton class. The minimize, maximize, and close buttons follow the same pattern. We create the button, define an icon for the buttons at hand, and set the icon using the setIcon() method.

Note that we use the standard icons that PyQt provides. For example, the minimize button uses the SP_TitleBarMinButton icon. Similarly, the maximize and close buttons use the SP_TitleBarMaxButton and SP_TitleBarCloseButton icons. We find all these icons in the QStyle.StandardPixmap namespace.

Finally, we connect the button's clicked() signal to the appropriate slot. For the minimize button, the proper slot is .showMinimized(). For the maximize and close buttons, the right slots are .showMaximized() and close(), respectively. All these slots are part of the main window's class.

The normal button at the end of the above code uses the SP_TitleBarNormalButton icon and showNormal() slot. This button has an extra setting. We've set its visibility to False, meaning that the button will be hidden by default. It'll only appear when we maximize the window to allow us to return to the normal state.

Styling and Adding Buttons to the Layout

Now that we've created and tweaked the buttons, we must add them to our title bar. To do this, we can use the following for loop:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(28, 28))
            button.setStyleSheet(
                """QToolButton {
                        border: 2px solid white;
                        border-radius: 12px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

This loop iterates over our four buttons in a predefined order. The first thing to do inside the loop is to define the focus policy of each button. We don't want these buttons to steal focus from widgets in the window's workspace, so we set their focus policy to NoFocus.

Next, we set a fixed size of 28 by 28 pixels for the three buttons using the setFixedSize() method with a QSize object as an argument.

Our main goal in this section is to create a custom title bar. A handy way to customize the look and feel of PyQt widgets is to use CSS style sheets. In the above piece of code, we use the setStyleSheet() method to apply a custom CSS style sheet to our four buttons. The sheet defines a white and round border for each button.

The final line in the above code calls the addWidget() method to add each custom button to our title bar's layout. That's it! We're now ready to give our title bar a try. Go ahead and run the application from your command line. You'll see a window like the following:

A PyQt6 window with a custom title bar

This is pretty simple styling, but you get the idea. You can tweak the title bar further, depending on your needs. For example, you can change the colors and borders, customize the title's font, add other widgets to the bar, and more.

We'll apply some nicer styles later, once we have the functionality in place! Keep reading.

Even though the title bar looks different, it has limited functionality. For example, if you click the maximize button, then the window will change to its maximized state. However, the normal button won't show up to allow you to return the window to its previous state.

In addition to this, if you try to move the window around your screen, you'll quickly notice a problem: it's impossible to move the window!

In the following sections, we'll write the necessary code to fix these issues and make our custom title bar fully functional. To kick things off, let's start by fixing the state issues.

Updating the Window's State on Maximize and Restore

To fix the issue related to the window's state, we'll override the changeEvent() method on the MainWindow class. This method is called directly by Qt whenever the window state changes, e.g. if the window is maximized or hidden. By overriding this event, we can add our own custom behavior.

Here's the code that overrides the changeEvent() method:

python

from PyQt6.QtCore import QSize, Qt, QEvent
# ...

class MainWindow(QMainWindow):
    # ...

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

This method is fairly straightforward. We check the event type to see if it is a WindowStateChange. If that's the case, we call the window_state_changed() method of our custom title bar, passing the current window's state as an argument. In the final two lines, we call the parent class's changeEvent() method and accept the event to signal that we've correctly processed it.

Here's the implementation of our window_state_changed() method in CustomTitleBar:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

This method takes a window's state as an argument. Depending on the value of the state parameter, we will show or hide the maximize and restore buttons.

First, if the window is currently maximized we will show the normal button and hide the maximize button. Alternatively, if the window is currently not maximized we will hide the normal button and show the maximize button.

The effect of this, together with the order we added the buttons above, is that when you maximize the window the maximize button will appear to be replaced with the normal button. When you restore the window to its normal size, the normal button will be replaced with the maximize button.

Go ahead and run the app again. Click the maximize button. You'll note that when the window gets maximized, the middle button changes its icon. Now you have access to the normal button. If you click it, then the window will recover its previous state.

Handling Window Dragging with Mouse Events

Now it's time to write the code that enables us to move the window around the screen while holding the mouse's left button on the title bar. To do this, we only need to add code to the CustomTitleBar class.

In particular, we need to override three mouse events:

mousePressEvent() will let us know when the user clicks on our custom title bar using the mouse's left button. This may indicate that the window movement should start.
mouseMoveEvent() will let us process window movement.
mouseReleaseEvent() will let us know when the user has released the mouse's left button so that we can stop moving the window.

Here's the code that overrides the mousePressEvent() method:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.position().toPoint()
        super().mousePressEvent(event)
        event.accept()

In this method, we first check if the user clicks on the title bar using the mouse's left-click button. If that's the case, then we update our initial_pos attribute to the clicked point. Remember that we defined initial_pos and initialized it to None back in the __init__() method of CustomTitleBar.

Next, we need to override the mouseMoveEvent() method. Here's the required code:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.position().toPoint() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

This if statement in mouseMoveEvent() checks if the initial_pos attribute is not None. If this condition is true, then the if code block executes because we have a valid initial position.

The first line in the if code block calculates the difference, or delta, between the current and initial mouse positions. To get the current position, we call the position() method on the event object and convert that position into a QPoint object using the toPoint() method.

The following four lines update the position of our application's main window by adding the delta values to the current window position. The move() method does the hard work of moving the window.

In summary, this code updates the window position based on the movement of our mouse. It tracks the initial position of the mouse, calculates the difference between the initial position and the current position, and applies that difference to the window's position.

Finally, we can complete the mouseReleaseEvent() method:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

This method's implementation is pretty straightforward. Its purpose is to reset the initial position by setting it back to None when the mouse is released, indicating that the drag is complete.

That's it! Go ahead and run your app again. Click on your custom title bar and move the window around while holding the mouse's left-click button. Can you move the window? Great! Your custom title bar is now fully functional.

The completed code for the custom title bar is shown below:

python

from PyQt6.QtCore import QEvent, QSize, Qt
from PyQt6.QtGui import QPalette
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QStyle,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.setAutoFillBackground(True)
        self.setBackgroundRole(QPalette.ColorRole.Highlight)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)

        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setStyleSheet(
            """QLabel {
                   font-weight: bold;
                   border: 2px solid black;
                   border-radius: 12px;
                   margin: 2px;
                }
            """
        )
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

        # Min button
        self.min_button = QToolButton(self)
        min_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMinButton,
        )
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMaxButton,
        )
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarCloseButton
        )
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarNormalButton
        )
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # Add buttons
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(28, 28))
            button.setStyleSheet(
                """QToolButton {
                        border: 2px solid white;
                        border-radius: 12px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.position().toPoint()
        super().mousePressEvent(event)
        event.accept()

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.position().toPoint() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        central_widget = QWidget()
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        work_space_layout.addWidget(QLabel("Hello, World!", self))

        central_widget_layout = QVBoxLayout()
        central_widget_layout.setContentsMargins(0, 0, 0, 0)
        central_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        central_widget_layout.addWidget(self.title_bar)
        central_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(central_widget_layout)
        self.setCentralWidget(central_widget)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

Styling a Modern Unified Title Bar with QSS

So far, we've covered the technical aspects of styling our window with a custom title bar, and added the code to make it function as expected. But it doesn't look great. In this section we'll take our existing code & tweak the styling and buttons to produce something that's a little more professional looking.

One common reason for wanting to apply custom title bars to a window is to integrate the title bar with the rest of the application. This technique is called a unified title bar and can be seen in some popular applications such as web browsers, or Spotify:

In this section, we'll look at how we can reproduce the same effect in PyQt using a combination of stylesheets and icons. Below is a screenshot of the final result which we'll be building:

As you can see the window and the toolbar blend nicely together and the window has rounded corners. There are a few different ways to do this, but we'll cover a simple approach using Qt stylesheets to apply styling over the entire window.

Creating a Translucent Background Window

In order to customize the shape of the window, we need to first tell the OS to stop drawing the default window outline and background for us. We do that by setting a window attribute on the window. This is similar to the flags we already discussed, in that it turns on and off different window manager behaviors:

python

# ...
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        # ...

We've added a call to self.setAttribute(), which sets the attribute Qt.WidgetAttribute.WA_TranslucentBackground on the window. If you run the code now, you will see the window has become transparent, with only the widget text and toolbar visible.

Applying Rounded Corners with a Container Widget

Next, we'll tell Qt to draw a new custom background for us. If you've worked with QSS before, the most obvious way to apply curved edges to the window using QSS stylesheets would be to set border-radius styles on the main window directly:

python

#...
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # ...
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        self.setStyleSheet("background-color: gray; border-radius: 10px;")
#...

However, if you try this, you'll notice that it doesn't work. If you enable a translucent background, the background of the window is not drawn (including your styles). If you don't set translucent background, the window is filled to the edges with a solid color ignoring the border radius:

The good news is that, with a bit of lateral thinking, there is a simple solution. We already know that we can construct interfaces by nesting widgets in layouts. Since we can't style the border-radius of a window, but we can style any other widget, the solution is to simply add a container widget into our window and apply the curved-edge and background styles to that.

On our MainWindow class, we already have a central widget which contains our layout, so we can apply the styles there:

python

# ...

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # ...
        central_widget = QWidget()
        # This container holds the window contents, so we can style it.
        central_widget.setObjectName("Container")
        central_widget.setStyleSheet(
            """#Container {
                    background: qlineargradient(x1:0 y1:0, x2:1 y2:1, stop:0 #051c2a stop:1 #44315f);
                    border-radius: 5px;
                }
            """
        )
        self.title_bar = CustomTitleBar(self)
        # ...

We've taken the existing central_widget object and assigned an object name to it. This is an ID which we can use to refer to the widget from QSS and apply our styles specifically to that widget.

If you're familiar with CSS, you might expect that IDs like #Container must be unique. However, they are not: you can give multiple widgets the same object name if you like. So you can re-use this technique and QSS on multiple windows in your application without problems.

With this style applied on our window, we have a nice gradient background with curved corners.

Making the Title Bar Transparent

Unfortunately, the title bar we created is drawn filled, so the background and curved corners of our window are overwritten. To make things look coherent we need to make our title bar also transparent by removing the background color & auto-fill behavior we set earlier.

We don't need to set any flags or attributes on this widget because it is not a window. A QWidget object is transparent by default.

We can also make some tweaks to the style of the title label, such as making the title capitalized using text-transform: uppercase, adjusting the font size and color -- feel free to customize this yourself:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # self.setAutoFillBackground(True) # <-- remove
        # self.setBackgroundRole(QPalette.ColorRole.Highlight) # <-- remove
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.title.setStyleSheet(
            """QLabel {
                    text-transform: uppercase;
                    font-size: 10pt;
                    margin-left: 48px;
                    color: white;
                }
            """
        )

QSS is very similar to CSS, especially for text styling.

The margin-left: 48px is to compensate for the 3 × 16 px window icons on the right-hand side so the text aligns centrally.

Using Custom SVG Icons for Window Buttons

The icons are currently using built-in Qt icons which are a little bit plain & ugly. Next let's update the icons, using custom SVG icons of simple colored circles, for the minimize, maximize, close & restore buttons:

python

from PyQt6.QtGui import QIcon
# ...
class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # ...
        # Min button
        self.min_button = QToolButton(self)
        min_icon = QIcon()
        min_icon.addFile('min.svg')
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = QIcon()
        max_icon.addFile('max.svg')
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = QIcon()
        close_icon.addFile('close.svg') # Close has only a single state.
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = QIcon()
        normal_icon.addFile('normal.svg')
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # ...

This code follows the same basic structure as before, but instead of using the built-in icons here we're loading our icons from SVG images. These images are very simple, consisting of a single circle in green, red or yellow for the different states mimicking macOS.

The normal.svg file for returning a maximized window to normal size shows a semi-transparent green circle for simplicity's sake, but you can include iconography and hover behaviors on the buttons if you prefer.

The final step is to iterate through the created buttons, adding them to the title bar layout. This is slightly tweaked from before to remove the border styling replacing it with simple padding and setting the icon sizes to 16px. Because we are using SVG files, the icons will automatically scale to the available space:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # ...
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(16, 16))
            button.setStyleSheet(
                """QToolButton {
                        border: none;
                        padding: 2px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

And that's it! With these changes, you can now run your application and you'll see a nice sleek modern-looking UI with unified title bar and custom controls:

The final result, showing our unified title bar and window design.

Complete Code for the Styled Custom Title Bar

The complete code is shown below:

python

from PyQt6.QtCore import QEvent, QSize, Qt
from PyQt6.QtGui import QIcon
from PyQt6.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.title.setStyleSheet(
            """QLabel {
                    text-transform: uppercase;
                    font-size: 10pt;
                    margin-left: 48px;
                    color: white;
                }
            """
        )

        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

        # Min button
        self.min_button = QToolButton(self)
        min_icon = QIcon()
        min_icon.addFile("min.svg")
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = QIcon()
        max_icon.addFile("max.svg")
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = QIcon()
        close_icon.addFile("close.svg")  # Close has only a single state.
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = QIcon()
        normal_icon.addFile("normal.svg")
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # Add buttons
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(16, 16))
            button.setStyleSheet(
                """QToolButton {
                        border: none;
                        padding: 2px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.position().toPoint()
        super().mousePressEvent(event)
        event.accept()

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.position().toPoint() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        central_widget = QWidget()
        # This container holds the window contents, so we can style it.
        central_widget.setObjectName("Container")
        central_widget.setStyleSheet(
            """#Container {
                    background: qlineargradient(x1:0 y1:0, x2:1 y2:1, stop:0 #051c2a stop:1 #44315f);
                    border-radius: 5px;
                }
            """
        )
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        hello_label = QLabel("Hello, World!", self)
        hello_label.setStyleSheet("color: white;")
        work_space_layout.addWidget(hello_label)

        centra_widget_layout = QVBoxLayout()
        centra_widget_layout.setContentsMargins(0, 0, 0, 0)
        centra_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        centra_widget_layout.addWidget(self.title_bar)
        centra_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(centra_widget_layout)
        self.setCentralWidget(central_widget)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

Note that you've also set the color of the "Hello, World!" label to white so that it's visible on a dark background.

Conclusion

In this tutorial, we have learned the fundamentals of creating custom title bars in PyQt. To do this, we have combined PyQt's widgets, layouts, and styling capabilities to create a visually appealing title bar for a PyQt app.

With this skill under your belt, you're now ready to create title bars that align perfectly with your application's unique style and branding. This will allow you to break away from the standard window decoration provided by your operating system and add a personal touch to your user interface.

Now let your imagination run and transform your PyQt application's UX.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How to Restore the Window's Geometry in a PyQt6 App — Make Your Windows Remember Their Last Position and Size

2023-11-13T06:00:00+00:00

In GUI applications the window's position & size are known as the window geometry. Saving and restoring the geometry of a window between executions is a useful feature in many applications. With persistent geometry users can arrange applications on their desktop for an optimal workflow and have the applications return to those positions every time they are launched.

In this tutorial, we will explore how to save and restore the geometry and state of a PyQt window using the QSettings class. With this functionality, you will be able to give your PyQt6 applications a usability boost.

To follow along with this tutorial, you should have prior knowledge of creating GUI apps with Python and PyQt. Additionally, having a basic understanding of using the QSettings class to manage an application's settings will be beneficial.

Understanding a Window's Geometry in PyQt6

PyQt defines the geometry of a window using a few properties. These properties represent a window's position on the screen and size. Here's a summary of PyQt's geometry-related properties:

Property	Description	Access Method
`x`	Holds the `x` coordinate of a widget relative to its parent. If the widget is a window, `x` includes any window frame and is relative to the desktop. This property defaults to `0`.	`x()`
`y`	Holds the `y` coordinate of a widget relative to its parent. If the widget is a window, `y` includes any window frame and is relative to the desktop. This property defaults to `0`.	`y()`
`pos`	Holds the position of the widget within its parent widget. If the widget is a window, the position is relative to the desktop and includes any frame.	`pos()`
`geometry`	Holds the widget's geometry relative to its parent and excludes the window frame.	`geometry()`
`width`	Holds the width of the widget, excluding any window frame.	`width()`
`height`	Holds the height of the widget, excluding any window frame.	`height()`
`size`	Holds the size of the widget, excluding any window frame.	`size()`

In PyQt, the QWidget class provides the access methods in the table above. Note that when your widget is a window or form, the first three methods operate on the window and its frame, while the last four methods operate on the client area, which is the window's workspace without the external frame.

Additionally, the x and y coordinates are relative to the screen of your computer. The origin of coordinates is the upper left corner of the screen, at which point both x and y are 0.

Let's create a small demo app to inspect all these properties in real time. To do this, go ahead and fire up your code editor or IDE and create a new Python file called geometry_properties.py. Then add the following code to the file and save it in your favorite working directory:

python

from PyQt6.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QPushButton,
    QVBoxLayout,
    QWidget,
)

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.resize(400, 200)
        self.central_widget = QWidget()
        self.global_layout = QVBoxLayout()
        self.geometry_properties = [
            "x",
            "y",
            "pos",
            "width",
            "height",
            "size",
            "geometry",
        ]
        for prop in self.geometry_properties:
            self.__dict__[f"{prop}_label"] = QLabel(f"{prop}:")
            self.global_layout.addWidget(self.__dict__[f"{prop}_label"])
        button = QPushButton("Update Geometry Properties")
        button.clicked.connect(self.update_labels)
        self.global_layout.addWidget(button)
        self.central_widget.setLayout(self.global_layout)
        self.setCentralWidget(self.central_widget)

    def update_labels(self):
        for prop in self.geometry_properties:
            self.__dict__[f"{prop}_label"].setText(
                f"{prop}: {getattr(self, prop)()}"
            )

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

Wow! There's a lot of code in this file. First, we import the required classes from PyQt6.QtWidgets. Then, we create our app's main window by inheriting from QMainWindow.

In the initializer method, we set the window's title and size using setWindowTitle() and resize(), respectively. Next, we define a central widget and a layout for our main window.

We also define a list of properties. We'll use that list to add some QLabel objects. Each label will show a geometry property and its current values. The Update Geometry Properties button allows us to update the value of the window's geometry properties.

Finally, we define the update_labels() method to update the values of all the geometry properties using their corresponding access methods. That's it! Go ahead and run the app. You'll get the following window on your screen:

A Window Showing Labels for Every Geometry Property

Looking good! Now go ahead and click the Update Geometry Properties button. You'll see how all the properties get updated. Your app's window will look something like this:

A Window Showing the Current Value of Every Geometry Property

As you can see, x and y are numeric values, while pos is a QPoint object with x and y as its coordinates. These properties define the position of this window on your computer screen.

The width and height properties are also numeric values, while the size property is a QSize object defined after the current width and height.

Finally, the geometry property is a QRect object. In this case, the rectangle comprises x, y, width, and height.

Great! With this first approach to how PyQt defines a window's geometry, we're ready to continue digging into this tutorial's main topic: saving and restoring the geometry of a window in PyQt6.

Saving and Loading Window Geometry Settings With `QSettings`

Users of GUI apps will generally expect the apps to remember their settings across sessions. This information is often referred to as settings or preferences. In PyQt applications, you'll manage settings and preferences using the QSettings class. This class allows you to have persistent platform-independent settings in your GUI app.

A commonly expected feature is that the app remembers the geometry of its windows, particularly the main window.

In this section, you'll learn how to save and restore the window's geometry in a PyQt6 application. Let's start by creating a skeleton PyQt application to kick things off. Go ahead and create a new Python file called geometry.py. Once you have the file opened in your favorite code editor or IDE, then add the following code:

python

from PyQt6.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

This code creates a minimal PyQt app with an empty main window. The window will appear at 50 pixels from the upper left corner of your computer screen and have a size of 400 by 200 pixels.

We'll use the above code as a starting point to make the app remember and restore the main window's geometry across sessions.

First, we need to have a QSettings instance in our app. Therefore, you have to import QSettings from PyQt6.QtCore and instantiate it as in the code below:

python

from PyQt6.QtCore import QSettings
from PyQt6.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")

When instantiating QSettings, we must provide the name of our company or organization and the name of our application. We use "PythonGUIs" as the organization and "GeometryApp" as the application name.

Now that we have a QSettings instance, we should implement two methods. The first method should allow you to save the app's settings and preferences. The second method should help you read and load the settings. In this tutorial, we'll call these methods write_settings() and read_settings(), respectively:

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        # Write settings here...

    def read_settings(self):
        # Read settings here...

Note that our methods don't do anything yet. You'll write them in a moment. For now, they're just placeholders.

The write_settings() method must be called when the user closes or terminates the application. This way, you guarantee that all the modified settings get saved for the next session. So, the appropriate place to call write_settings() is from the main window's close event handler.

Let's override the closeEvent() method as in the code below:

python

class Window(QMainWindow):
    # ...

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

In this code, we override the closeEvent() handler method. The first line calls write_settings() to ensure that we save the current state of our app's settings. Then, we call the closeEvent() of our superclass QMainWindow to ensure the app's window closes correctly. Finally, we accept the current event to signal that it's been processed.

Now, where should we call read_settings() from? In this example, the best place for calling the read_settings() method is .__init__(). Go ahead and add the following line of code to the end of your __init__() method:

python

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

By calling the read_settings() method from __init__(), we ensure that our app will read and load its settings every time the main window gets created and initialized.

Great! We're on the way to getting our application to remember and restore its window's geometry. First, you need to know that you have at least two ways to restore the geometry of a window in PyQt6:

Using the pos and size properties
Using the geometry property

In both cases, you need to save the current value of the selected property and load the saved value when the application starts. To kick things off, let's start with the first approach.

Restoring the Window's Geometry With `pos` and `size`

In this section, we'll first write the required code to save the current value of pos and size by taking advantage of our QSettings object. The code snippet below shows the changes that you need to make on your write_settings() method to get this done:

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        self.settings.setValue("pos", self.pos())
        self.settings.setValue("size", self.size())

This code is straightforward. We call the setValue() method on our setting object to set the "pos" and "size" configuration parameters. Note that we get the current value of each property using the corresponding access method.

With the write_settings() method updated, we're now ready to read and load the geometry properties from our app's settings. Go ahead and update the read_settings() method as in the code below:

python

class Window(QMainWindow):
    # ...

    def read_settings(self):
        self.move(self.settings.value("pos", defaultValue=QPoint(50, 50)))
        self.resize(self.settings.value("size", defaultValue=QSize(400, 200)))

The first line inside read_settings() retrieves the value of the "pos" setting parameter. If there's no saved value for this parameter, then we use QPoint(50, 50) as the default value. Next, the move() method moves the app's window to the resulting position on your screen.

The second line in read_settings() does something similar to the first one. It retrieves the current value of the "size" parameter and resizes the window accordingly.

Great! It's time for a test! Go ahead and run your application. Then, move the app's window to another position on your screen and resize the window as desired. Finally, close the app's window to terminate the current session. When you run the app again, the window will appear in the same position. It will also have the same size.

If you have any issues completing and running the example app, then you can grab the entire code below:

python

from PyQt6.QtCore import QPoint, QSettings, QSize
from PyQt6.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

    def write_settings(self):
        self.settings.setValue("pos", self.pos())
        self.settings.setValue("size", self.size())

    def read_settings(self):
        self.move(self.settings.value("pos", defaultValue=QPoint(50, 50)))
        self.resize(self.settings.value("size", defaultValue=QSize(400, 200)))

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

Now you know how to restore the geometry of a window in a PyQt6 app using the pos and size properties. It's time to change gears and learn how to do this using the geometry property.

Restoring the Window's Geometry With `saveGeometry()` and `restoreGeometry()`

We can also restore the geometry of a PyQt window using the saveGeometry() and restoreGeometry() methods. This approach is often preferred because it handles edge cases like multi-monitor setups more robustly. To do that, we first need to save the current geometry using our QSettings object.

Go ahead and create a new Python file in your working directory. Once you have the file in place, add the following code to it:

python

from PyQt6.QtCore import QByteArray, QSettings
from PyQt6.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

    def write_settings(self):
        self.settings.setValue("geometry", self.saveGeometry())

    def read_settings(self):
        self.restoreGeometry(self.settings.value("geometry", QByteArray()))

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

There are only two changes in this code compared to the code from the previous section. We've modified the implementation of the write_settings() and read_settings() methods.

In write_settings(), we use setValue() to save the current geometry of our app's window. The saveGeometry() method serializes the window's geometry into a QByteArray, which includes position, size, and additional metadata. In read_settings(), we call the value() method to retrieve the saved geometry value. Then, we use restoreGeometry() to restore the geometry of our window.

Again, you can run the application consecutive times and change the position and size of its main window to ensure your code works correctly.

Restoring the Window's Geometry and State Including Toolbars and Dock Widgets

If your app's window has toolbars and dock widgets, then you want to restore their state on the parent window. To do that, you can use the restoreState() method. To illustrate this, let's reuse the code from the previous section.

Update the content of write_settings() and read_settings() as follows:

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        self.settings.setValue("geometry", self.saveGeometry())
        self.settings.setValue("windowState", self.saveState())

    def read_settings(self):
        self.restoreGeometry(self.settings.value("geometry", QByteArray()))
        self.restoreState(self.settings.value("windowState", QByteArray()))

In write_settings(), we add a new setting value called "windowState". To keep this setting, we use the saveState() method, which saves the current state of this window's toolbars and dock widgets. Meanwhile, in read_settings(), we restore the window's state by calling the value() method, as usual, to get the state value back from our QSettings object. Finally, we use restoreState() to restore the state of toolbars and dock widgets.

Now, to make sure that this new code works as expected, let's add a sample toolbar and a dock window to our app's main window. Go ahead and add the following methods right after the __init__() method:

python

from PyQt6.QtCore import QByteArray, QSettings, Qt
from PyQt6.QtWidgets import QApplication, QDockWidget, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's State")
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.create_toolbar()
        self.create_dock()
        self.read_settings()

    def create_toolbar(self):
        toolbar = self.addToolBar("Toolbar")
        toolbar.addAction("One")
        toolbar.addAction("Two")
        toolbar.addAction("Three")

    def create_dock(self):
        dock = QDockWidget("Dock", self)
        dock.setAllowedAreas(
            Qt.DockWidgetArea.LeftDockWidgetArea
            | Qt.DockWidgetArea.RightDockWidgetArea
        )
        self.addDockWidget(Qt.DockWidgetArea.LeftDockWidgetArea, dock)

    # ...

In this new update, we first import the Qt namespace from PyQt6.QtCore and QDockWidget from PyQt6.QtWidgets. Then we call the two new methods from __init__() to create the toolbar and dock widget at initialization time.

In the create_toolbar() method, we create a sample toolbar with three sample buttons. This toolbar will show at the top of our app's window by default.

Next, we create a dock widget in create_dock(). This widget will occupy the rest of our window's working area.

That's it! You're now ready to give your app a try. You'll see a window like the following:

A Window Showing a Sample Toolbar and a Dock Widget

Play with the toolbar and the dock widget. Move them around. Then close the app's window and run the app again. Your toolbar and dock widget will show in the last position you left them.

Conclusion

Through this tutorial, you have learned how to save and restore the geometry and state of a window in PyQt6 applications using the QSettings class. By utilizing the pos, size, saveGeometry(), restoreGeometry(), saveState(), and restoreState() methods, you can give your users the convenience of persistent window position and size across sessions.

With this knowledge, you can enhance the usability of your PyQt6 applications, making your app more intuitive and user-friendly. Remembering window geometry is a small detail that significantly improves the overall user experience of desktop Python GUI applications.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How Trademarks Affect Open Source Software — How do trademarks relate to copyrights and what are the implications for open source software

2023-08-15T09:00:00+00:00

As previously discussed, a central concept of open source licenses is that the author of a given program grants anyone permission to use, modify, or redistribute their code without seeking specific permission first. But these licenses generally cover the copyrights to the underlying code and not any trademarks that may be used by the original author in connection with their work.

A trademark is basically a word, phrase, symbol, or design--or any combination of those elements--that identifies a unique product or service in commerce. For example, "Python" is a registered trademark of the Python Software Foundation (PSF). The famous blue-and-yellow "intertwined snakes" Python logo is also a PSF trademark.

So how exactly do trademarks work? And as a developer, what can you do--and not do--with someone else's trademarks in your own work?

Trademarks Are Not Copyrights

To the layperson, it might seem like trademarks are just a method by which someone can copyright a particular word or phrase. In fact, copyright and trademark are distinct forms of intellectual property. A copyright applies to a created work, such as a book or a software program, that is original and exists in some fixed form. The purpose of copyright is to enable the author to exercise exclusive control over the right to reproduce or distribute their work for a specified period of time.

A trademark, in contrast, is primarily about protecting consumers from harm. A trademark identifies the source of a good or service. This helps guard against potential counterfeiting or fraud while affording the trademark holder legal protection for their brand. But the trademark holder does not "own" the trademarked word or phrase. Rather, they exercise a limited right to use the trademark in connection with the sale of their product or service in a given area.

Trademarks can be used in connection with a variety of products within the same brand. The PSF uses its Python mark, for instance, not just to refer to the programming language itself but also merchandise such as T-shirts and hats. But the PSF could not enforce its Python mark in an area of commerce where it does not actually produce any products.

Like copyright, a trademark holder can register their mark with the government, although it is not required. In the United States, the U.S. Patent and Trademark Office (USPTO) manages trademark registrations at the federal level. A registered trademark is indicated by an "R" with a circle around it (®), while an unregistered trademark is indicated with the letters "TM" (™). As with copyright, registering a trademark provides certain legal benefits, such as a presumption that the mark is valid and belongs to the registrant.

When Do You Need a Software Trademark Holder's Permission?

Another key difference between copyright and trademark is enforcement. With copyright, an author can be fairly lax in their assertion of rights without losing them. Indeed, open source licensing is essentially built around the notion that most developers do not want to spend their time policing how other people use their code. Yet the license itself still retains copyright in the event the author feels compelled to take legal action against infringement.

With a trademark, however, the holder needs to be more proactive in asserting their rights. The reason for this is that unlike copyright, a trademark can last indefinitely, provided it continues to be actively used and defended by the holder. The more passive the holder is in defending their rights, the more likely that the USPTO or a judge may find the trademark is no longer in active use.

For this reason, many organizations that rely on trademarks will publish a written policy governing their acceptable use. The PSF has a very detailed trademark usage policy, which provides a good model for how enforcement works in practice. Fortunately for developers, the PSF policy makes it clear that the organization wants the "Python" mark and logo "to be used with minimal restriction to refer to the Python programming language."

To be clear, even without this policy, there are many uses of the "Python" trademark allowed by U.S. law (and the laws of other nations) with respect to "fair use." There are basically two kinds of fair use: nominative and descriptive. Nominative fair use simply means you are referring to the trademarked good or service. So if you write a program in Python, you are allowed to refer to the "Python" trademark without asking the PSF's permission first.

Descriptive fair use means you are using the trademark to describe some other product or service. This tends to come up when you are comparing one product with another. For instance, if you write an article comparing the benefits and drawbacks of Python with Rust, that would involve descriptive fair use. Again, you don't need permission to do this.

So when do you need a trademark holder's approval? The PSF's own policy states approval is necessary for any "commercial use" of the "Python" trademark to describe another product or company. In other words, you don't need the PSF's permission to describe your own program as being written in Python, or even to describe yourself as a Python developer. But you would need the PSF's permission to name your company something like "Python Software, Inc."

But what if you wanted to make or sell merchandise with the Python logo? Again, the PSF's policy permits anyone to use the logo without permission for non-commercial purposes. It's okay to make a Python-logo shirt for yourself and wear it at PyCon. But if you wanted to sell those shirts at PyCon, you would need a license from the PSF and potentially pay royalties on any sales.

Four Things Python Developers Should Know About Software Trademarks

If you are developing software, you need to be aware of potential trademark issues. A qualified intellectual property attorney can answer specific questions for your situation. But speaking in general terms, here are four things to keep in mind:

Check the trademark holder's usage policy. If you plan to use the name of any existing company or project in describing your own software, make sure to check and see if the trademark holders have a published policy regarding usage like the PSF.
Search existing trademarks before naming your project. When selecting a name for your own project, you can check the U.S. Patent and Trademark Office's trademark database to see if the same or similar name is already in use with respect to software.
Unregistered trademarks still have legal protection. Even if a trademark is not formally registered with the USPTO, that does not mean the trademark is not still legally protected.
Open source licenses do not grant trademark rights. An open source license like the GPL, MIT, or BSD licenses do not convey any rights with respect to trademarks. Never assume that you can use the name of another software project in your own commercial application just because the underlying code is freely licensed.

How to Restore the Window's Geometry in a PyQt5 App — Make Your Windows Remember Their Last Geometry

2023-05-27T06:00:00+00:00

In this tutorial, we will explore how to save and restore the geometry and state of a PyQt window using the QSettings class. With this functionality, you will be able to give your applications a usability boost.

Understanding a Window's Geometry

PyQt defines the geometry of a window using a few properties. These properties represent a window's position on the screen and size. Here's a summary of PyQt's geometry-related properties:

Property	Description	Access Method
`x`	Holds the `x` coordinate of a widget relative to its parent. If the widget is a window, `x` includes any window frame and is relative to the desktop. This property defaults to `0`.	`x()`
`y`	Holds the `y` coordinate of a widget relative to its parent. If the widget is a window, `y` includes any window frame and is relative to the desktop. This property defaults to `0`.	`y()`
`pos`	Holds the position of the widget within its parent widget. If the widget is a window, the position is relative to the desktop and includes any frame.	`pos()`
`geometry`	Holds the widget's geometry relative to its parent and excludes the window frame.	`geometry()`
`width`	Holds the width of the widget, excluding any window frame.	`width()`
`height`	Holds the height of the widget, excluding any window frame.	`height()`
`size`	Holds the size of the widget, excluding any window frame.	`size()`

Additionally, the x and y coordinates are relative to the screen of your computer. The origin of coordinates is the upper left corner of the screen, at which point both x and y are 0.

python

from PyQt5.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QPushButton,
    QVBoxLayout,
    QWidget,
)

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.resize(400, 200)
        self.central_widget = QWidget()
        self.global_layout = QVBoxLayout()
        self.geometry_properties = [
            "x",
            "y",
            "pos",
            "width",
            "height",
            "size",
            "geometry",
        ]
        for prop in self.geometry_properties:
            self.__dict__[f"{prop}_label"] = QLabel(f"{prop}:")
            self.global_layout.addWidget(self.__dict__[f"{prop}_label"])
        button = QPushButton("Update Geometry Properties")
        button.clicked.connect(self.update_labels)
        self.global_layout.addWidget(button)
        self.central_widget.setLayout(self.global_layout)
        self.setCentralWidget(self.central_widget)

    def update_labels(self):
        for prop in self.geometry_properties:
            self.__dict__[f"{prop}_label"].setText(
                f"{prop}: {getattr(self, prop)()}"
            )

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

Wow! There's a lot of code in this file. First, we import the required classes from PyQt5.QtWidgets. Then, we create our app's main window by inheriting from QMainWindow.

In the initializer method, we set the window's title and size using setWindowTitle() and resize(), respectively. Next, we define a central widget and a layout for our main window.

A Window Showing Labels for Every Geometry Property

Looking good! Now go ahead and click the Update Geometry Properties button. You'll see how all the properties get updated. Your app's window will look something like this:

A Window Showing the Current Value of Every Geometry Property

As you can see, x and y are numeric values, while pos is a QPoint object with x and y as its coordinates. These properties define the position of this window on your computer screen.

The width and height properties are also numeric values, while the size property is a QSize object defined after the current width and height.

Finally, the geometry property is a QRect object. In this case, the rectangle comprises x, y, width, and height.

Great! With this first approach to how PyQt defines a window's geometry, we're ready to continue digging into this tutorial's main topic: restoring the geometry of a window in PyQt.

Keeping an App's Geometry Settings: The `QSetting` Class

A commonly expected feature is that the app remembers the geometry of its windows, particularly the main window.

In this section, you'll learn how to save and restore the window's geometry in a PyQt application. Let's start by creating a skeleton PyQt application to kick things off. Go ahead and create a new Python file called geometry.py. Once you have the file opened in your favorite code editor or IDE, then add the following code:

python

from PyQt5.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

This code creates a minimal PyQt app with an empty main window. The window will appear at 50 pixels from the upper left corner of your computer screen and have a size of 400 by 200 pixels.

We'll use the above code as a starting point to make the app remember and restore the main window's geometry across sessions.

First, we need to have a QSettings instance in our app. Therefore, you have to import QSettings from PyQt5.QtCore and instantiate it as in the code below:

python

from PyQt5.QtCore import QSettings
from PyQt5.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PyhonGUIs", "GeometryApp")

When instantiating QSettings, we must provide the name of our company or organization and the name of our application. We use "PyhonGUIs" as the organization and "GeometryApp" as the application name.

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        # Write settings here...

    def read_settings(self):
        # Read settings here...

Note that our methods don't do anything yet. You'll write them in a moment. For now, they're just placeholders.

Let's override the closeEvent() method as in the code below:

python

class Window(QMainWindow):
    # ...

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

python

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

By calling the read_settings() method from __init__(), we ensure that our app will read and load its settings every time the main window gets created and initialized.

Great! We're on the way to getting our application to remember and restore its window's geometry. First, you need to know that you have at least two ways to restore the geometry of a window in PyQt:

Using the pos and size properties
Using the geometry property

In both cases, you need to save the current value of the selected property and load the saved value when the application starts. To kick things off, let's start with the first approach.

Restoring the Window's Geometry With `pos` and `size`

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        self.settings.setValue("pos", self.pos())
        self.settings.setValue("size", self.size())

With the write_settings() method updated, we're now ready to read and load the geometry properties from our app's settings. Go ahead and update the read_settings() method as in the code below:

python

class Window(QMainWindow):
    # ...

    def read_settings(self):
        self.move(self.settings.value("pos", defaultValue=QPoint(50, 50)))
        self.resize(self.settings.value("size", defaultValue=QSize(400, 200)))

The second line in read_settings() does something similar to the first one. It retrieves the current value of the "size" parameter and resizes the window accordingly.

If you have any issues completing and running the example app, then you can grab the entire code below:

python

from PyQt5.QtCore import QPoint, QSettings, QSize
from PyQt5.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PyhonGUIs", "GeometryApp")
        self.read_settings()

    def write_settings(self):
        self.settings.setValue("pos", self.pos())
        self.settings.setValue("size", self.size())

    def read_settings(self):
        self.move(self.settings.value("pos", defaultValue=QPoint(50, 50)))
        self.resize(self.settings.value("size", defaultValue=QSize(400, 200)))

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

Now you know how to restore the geometry of a window in a PyQt app using the pos and size properties. It's time to change gears and learn how to do this using the geometry property.

Restoring the Window's Geometry With `geometry`

We can also restore the geometry of a PyQt window using its geometry property and the restoreGeometry() method. To do that, we first need to save the current geometry using our QSettings object.

Go ahead and create a new Python file in your working directory. Once you have the file in place, add the following code to it:

python

from PyQt5.QtCore import QByteArray, QSettings
from PyQt5.QtWidgets import QApplication, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's Geometry")
        self.move(50, 50)
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.read_settings()

    def write_settings(self):
        self.settings.setValue("geometry", self.saveGeometry())

    def read_settings(self):
        self.restoreGeometry(self.settings.value("geometry", QByteArray()))

    def closeEvent(self, event):
        self.write_settings()
        super().closeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = Window()
    window.show()
    app.exec()

There are only two changes in this code compared to the code from the previous section. We've modified the implementation of the write_settings() and read_settings() methods.

In write_settings(), we use the setValue() to save the current geometry of our app's window. The saveGeometry() allows us to access and save the current window's geometry. In read_settings(), we call the value() method to retrieve the saved geometry value. Then, we use restoreGeometry() to restore the geometry of our window.

Again, you can run the application consecutive times and change the position and size of its main window to ensure your code works correctly.

Restoring the Window's Geometry and State

Update the content of write_settings() and read_settings() as follows:

python

class Window(QMainWindow):
    # ...

    def write_settings(self):
        self.settings.setValue("geometry", self.saveGeometry())
        self.settings.setValue("windowState", self.saveState())

    def read_settings(self):
        self.restoreGeometry(self.settings.value("geometry", QByteArray()))
        self.restoreState(self.settings.value("windowState", QByteArray()))

python

from PyQt5.QtCore import QByteArray, QSettings, Qt
from PyQt5.QtWidgets import QApplication, QDockWidget, QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Window's State")
        self.resize(400, 200)
        self.settings = QSettings("PythonGUIs", "GeometryApp")
        self.create_toolbar()
        self.create_dock()
        self.read_settings()

    def create_toolbar(self):
        toolbar = self.addToolBar("Toolbar")
        toolbar.addAction("One")
        toolbar.addAction("Two")
        toolbar.addAction("Three")

    def create_dock(self):
        dock = QDockWidget("Dock", self)
        dock.setAllowedAreas(
            Qt.DockWidgetArea.LeftDockWidgetArea
            | Qt.DockWidgetArea.RightDockWidgetArea
        )
        self.addDockWidget(Qt.DockWidgetArea.LeftDockWidgetArea, dock)

    # ...

In this new update, we first import the Qt namespace from PyQt5.QtCore and QDockWidget from PyQt5.QtWidgets. Then we call the two new methods from __init__() to create the toolbar and dock widget at initialization time.

In the create_toolbar() method, we create a sample toolbar with three sample buttons. This toolbar will show at the top of our app's window by default.

Next, we create a dock widget in create_dock(). This widget will occupy the rest of our window's working area.

That's it! You're now ready to give your app a try. You'll see a window like the following:

A Window Showing a Sample Toolbar and a Dock Widget

Play with the toolbar and the dock widget. Move them around. Then close the app's window and run the app again. Your toolbar and dock widget will show in the last position you left them.

Conclusion

Through this tutorial, you have learned how to restore the geometry and state of a window in PyQt applications using the QSettings class. By utilizing the pos, size, geometry, and state properties, you can give your users the convenience of persistent position and size on your app's windows.

With this knowledge, you can enhance the usability of your PyQt applications, making your app more intuitive and user-friendly.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

PyQt6 Book Now Available in Korean: 파이썬과 Qt6로 GUI 애플리케이션 만들기 — The hands-on guide to creating Python GUI applications with PyQt6 gets a Korean translation

2023-05-04T09:00:00+00:00

I am very happy to announce that my Python GUI programming book Create GUI Applications with Python & Qt6 — PyQt6 Edition is now available in Korean from Acorn Publishing.

The Korean edition, titled 파이썬과 Qt6로 GUI 애플리케이션 만들기, is a complete translation of the original English PyQt6 book, covering everything you need to build professional desktop applications with Python and Qt6.

What's Inside the Korean PyQt6 Book

This hands-on guide covers all the fundamentals of Python GUI development with PyQt6, including:

Creating windows, dialogs and widgets with PyQt6
Building responsive layouts for desktop applications
Working with Qt signals, slots and events
Using Qt Designer for visual UI design
Packaging and distributing your Python GUI applications

Whether you're a beginner to GUI programming or an experienced Python developer looking to build desktop applications, this book provides a practical, project-based approach to learning PyQt6.

A Personal Note

It's more than a little mind-blowing to see a book I've written translated into another language — not least one I cannot remotely understand! When I started writing this book a few years ago I could never have imagined it would end up on bookshelves in Korea, never mind in Korean. This is just fantastic.

파이썬과 Qt6로 GUI 애플리케이션 만들기 — 파이썬 애플리케이션 제작 실습 가이드

Where to Buy the Korean PyQt6 Book

If you're in Korea, you can pick up a copy at any of the following bookstores:

Thanks again to Acorn Publishing for translating my book and making it available to readers in Korea.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

PyQt vs. Tkinter — Which Should You Choose for Your Next GUI Project? — What Are the Major Differences Between these Popular Python GUI Libraries

2023-04-12T06:00:00+00:00

Graphical User Interfaces (GUIs) allow users to interact with software through intuitive and user-friendly graphical elements such as buttons, icons, text boxes, and windows. GUIs provide a simple way to perform complex tasks and navigate a software system using the mouse and keyboard and without needing to remember complex commands. By using familiar visual concepts across different tools and platforms, GUIs help make new software feel intuitive and user-friendly, even for beginners.

While Python is more commonly used for command-line tools, data science, and web apps, it is also perfectly capable of building graphical desktop applications. The Python ecosystem makes it possible to build almost anything, from small user-friendly interfaces for your scripts to more complex data analysis or engineering tools. Whether you're a Python beginner or a seasoned developer, learning how to build Python GUI apps is an excellent addition to your skill set.

An Introduction to Python GUI Libraries

One of Python's core strengths is the rich ecosystem of libraries and frameworks available. GUI programming libraries are not an exception -- you'll find several GUI libraries for Python.

While having multiple choices is great, it means that if you want to learn how to write GUI applications with Python, the first question you will need to answer is -- Which Python GUI library should I use?

Even though many GUI libraries are available, none has the widespread adoption of Tkinter and PyQt. So, if you're starting with GUI programming in Python, it'll make sense to start with one of these. There are far more tutorials, help & resources available to get you up and running, and you're more likely to find help if you need it.

Google Trends Plot Ranking Tkinter, PyQt, and Other Python GUI Libraries

The popularity of Tkinter largely stems from it being bundled with Python and, therefore, being the default Python GUI library. Most beginners will find this library first.

PyQt is often seen as the next logical step in your Python GUI journey when you want to start building real applications or commercial-quality software with Python.

Whether you choose Tkinter or PyQt will largely depend on your goals for writing GUI applications.

In this article, we'll explore and compare Tkinter and PyQt. We'll assess their pros & cons for different use cases and help you decide which Python GUI library to use for your project.

What Is Tkinter?

Best for simple tool GUIs, small portable applications.

Tkinter is the default GUI library for Python. It comes bundled with Python on both Windows and macOS. On Linux, you may have to install additional packages to get it set up.

The library is a wrapper around the Tcl/Tk GUI toolkit. Its name is an amalgamation of the words Tk and Interface.

Tkinter supports standard layouts and basic widgets, as well as more complex widgets, such as tabbed views & progress bars. Tkinter is a pure GUI library rather than a GUI framework. It only provides a set of graphical components for building GUIs.

It doesn't provide support for GUIs-driven data sources, databases, or for displaying or manipulating multimedia or hardware. However, if you need to make something simple that doesn't require any additional dependencies, Tkinter may be what you are looking for.

Tkinter is a cross-platform GUI library. It was first released in 1990, and it has continued to evolve until today. For example, the addition of the Themed Tk extensions in 2009 improved the appearance of widgets, giving a native look & feel to your Tkinter GUIs.

Tkinter is a limited library with a friendly API (application programming interface) that makes it easy to understand and learn. Because of this, Tkinter tends to be the first choice for creating quick GUIs for relatively small Python programs.

To learn more about how to use Tkinter, check out Build your own desktop apps with Python & Tkinter.

How Do You Install Tkinter?

Tkinter comes installed by default with Python on macOS and Windows. On some Linux systems, you may need to install an additional package. Tkinter also runs fine on a Raspberry Pi, although depending on your distribution, you may need to install it first.

How Can You Write a Tkinter App?

A minimal Hello, World! GUI application in Tkinter will look something like this:

python

import tkinter as tk

# Create the app's main window
window = tk.Tk()
window.title("Hello, World!")

def handle_button_press():
    window.destroy()

button = tk.Button(text="My simple app.", command=handle_button_press)
button.pack()

# Start the event loop
window.mainloop()

In this example, we first import tkinter as tk, a common practice when using Tkinter. We then create our app's main window by instantiating the Tk class. The title() method allows us to give a descriptive title to the app's windows. Next we write a function to responding to a click on the button. In this case our method closes the application window & terminates it.

To create the button, we use the Button class with an appropriate text. In order to trigger our handle_button_press() function when the button is pressed, we pass the function to Button as the command argument.

Next, we call pack() on our button object. This organizes our widget into the window layout -- although in this case, there is only a single widget. Finally, we run the app by calling mainloop() on our window object.

If you run the example, you'll see a simple window like follows.

A Tkinter App Using Tk Standard Widgets

As you can see, by default, Tkinter has very rudimentary-looking widgets.

We can modify the example to use Themed Tk widgets, which give a native appearance to widgets. The changes are minor, adding a from tkinter import ttk import and using ttk.<Widget> when constructing widgets.

python

import tkinter as tk
from tkinter import ttk

# Create the app's main window
window = tk.Tk()
window.title("Hello, World!")

def handle_button_press():
    window.destroy()

button = ttk.Button(text="My simple app.", command=handle_button_press)
button.pack()

# Start the event loop
window.mainloop()

If you run this example, the simple window will appear again but now using platform-native widgets (what you see will depend on your own system).

A Tkinter App Using Themed Tk Widgets

What Is Tkinter Commonly Used for?

Tkinter is typically used for simple Python GUIs. For example, small proof-of-concept, research, or educational apps built by Python hobbyists, and the like. The non-native appearance of Tkinter apps and lack of a real application framework make this library unsuitable for building professional applications, particularly commercial software.

While it's possible to put something simple together with Tkinter, as your application grows or your requirements become more complex, you'll likely end up spending more time reinventing the wheel than you saved by using a "simple" system. So, if you expect your project to grow in the future, then you should start with PyQt instead.

Is Tkinter Outdated?

The complaints of Tkinter being outdated largely stem from how the apps built with the library look on modern systems compared to other apps. Another important complaint driver is the library's limited set of widgets.

Tk, the library around which Tkinter was built, was first released in 1991. However, it's been continuously developed & maintained. In 2009, Tkinter added support for Tk 8.5 "Themed Tk" (Ttk), which allows Tk widgets to be more easily themed to look like the native on different desktop environments. Ttk also added some additional widgets, such as combo boxes, progress bars, tree views, notebooks, separators, and size grips, which weren't available in default Tk.

Why Does Tkinter Look Old-Fashioned?

It doesn't have to! Tkinter's reputation for looking bad stems from earlier versions of Tk without the native platform-theming support. These early versions used an old cross-platform "Motif" style, which was blocky and a bit ugly.

Tk 8.5 added support for desktop native theming, so your applications now follow the style of the desktop they are running on. This new look is provided through Themed Tk, which was added to Tkinter in 2009.

If you don't want a native appearance but still want to improve how your Tkinter applications look, there are other options too. For example, Tkinter Designer allows you to design graphical interfaces using Figma. Once you have the interface ready, then you can export it into a working Tkinter app.

How Can You Design GUIs for Tkinter?

There isn't an official design tool for Tkinter GUIs. However, you can find some tools available online. For example, Visual Tk allows you to build a GUI using a drag-drop interface in your browser & will then generate the Python code for you to create the interface in Tkinter itself.

Alternatively, Tkinter Designer will take a design drawn in the Figma software and use it to build a Tkinter-based GUI.

What Are Tkinter's Pros & Cons?

You can find plenty of reasons to consider Tkinter for your next project and reasons you may want to try something else. Let's take a look at some of the pros & cons of using Tkinter to build GUI applications with Python so that you can be in a better position to decide.

The pros of using Tkinter include the following:

It is part of the Python standard library and comes installed by default (on Windows and macOS). Once you install Python, you're ready to start building GUIs with Tkinter.
It doesn't have additional dependencies for your applications unless you need third-party libraries for additional functionality.
It is relatively simple, meaning there isn't much to take in while learning to use it.
It is a cross-platform library.
It has a lot of documentation and tutorials available.
It can be used freely for commercial software because its license is the same as Python's.

On the other hand, the cons of using Tkinter include the following:

It doesn't come with advanced widgets, such as data-driven views, database interfaces, vector graphics canvas, or multimedia GUI elements. To implement any of these in your applications, you need to write them yourself. This is achievable but will add to your development & maintenance burden.
It has no official GUI designer application. You'll find a few third-party options available with varying degrees of completeness and flexibility.
It lacks bundled features, which means that you're more likely to need third-party libraries to complete your applications. Luckily, there is no shortage of those in the Python ecosystem!
It doesn't have a native look & feel by default. The default appearance of Tkinter applications is old-fashioned. However, this is largely fixed by the Themed Tk extensions.

Now that you have a better idea of what Tkinter is and what are its main features and limitations, it's time for you to know its closest competitor, PyQt.

What Is PyQt?

Best for desktop applications, multimedia, scientific, and engineering software.

PyQt is a Python GUI framework built around the C++ Qt framework, which is developed and maintained by the Qt Company. It allows us to create modern interfaces that look right at home on any platform, including Windows, macOS, Linux, and even Android. It also has solid tooling, with the most notable being Qt Creator, which includes a WYSIWYG editor for designing GUI interfaces quickly and easily.

PyQt is developed and maintained by Riverbank Computing and was first released in 1998, four years after Tkinter.

The free-to-use version of PyQt is licensed under GNU General Public License (GPL) v3. This means that PyQt is limited to GPL-licensed applications unless you purchase its commercial license.

The Qt Company has its own Python binding for Qt, which is called PySide. This library was released in 2009. The main difference between PyQt and PySide is in licensing. PySide is licensed under GNU Lesser General Public License (LGPL), which means that you use PySide in non-GPL applications without any additional fee. For a detailed breakdown of the differences, see our guide on PyQt6 vs PySide6.

Qt, and by extension PyQt, is not just a GUI library. It's a complete GUI application development framework. In addition to standard GUI components, such as widgets and layouts, Qt provides:

MVC (model-view-controller) data-driven views (spreadsheets, tables)
Database interfaces and models
Graph plotting
Vector graphics visualization
Multimedia playback
Sound effects and playlists
Interfaces for hardware, such as printing devices

Qt's signals and slots mechanism for event programming allows us to properly architect complex applications from reusable and isolated components.

To learn more about how to use PyQt, check out Build your own desktop apps with Python & PyQt6.

While other toolkits can work great when building small Python tools, PyQt really comes into its own for building commercial-quality applications where we benefit from the pre-built components. These benefits come at the expense of a steep learning curve but don't feel overwhelmed yet, you can just focus on the parts your project needs.

PyQt-based applications use platform-native widgets to ensure that they look and feel native on Windows, macOS, and Qt-based Linux desktop environments.

How Do You Install PyQt?

PyQt v6.4.2 is the latest version of the library. To run it on your computer, make sure you have Python v3.6.1 or later installed. To install it, just run the following command:

$ python -m pip install pyqt6

This command will install the PyQt6 library for your platform and your version of Python. The library will be automatically downloaded from PyPI.

If you want to use Qt's own official Python library, you can install PySide with python -m pip install pyside6

As of writing, only PyQt5 is currently supported on Raspberry Pi. But you can use both the Qt Widgets (standard) and QML/Qt Quick (declarative) APIs. You can use QML to build modern touchscreen interfaces with animations, transitions, and effects.

To install PyQt5 on a Raspberry Pi, run the following command:

$ sudo apt-get install python3-pyqt5

This command will install PyQt5 from your Raspberry Pi current repository. Note that the Qt framework will also be installed as a dependency.

For other installation options, see our complete installation guides.

How Can You Write a PyQt App?

A minimal Hello, World! GUI application in PyQt6, using the Qt Widgets is shown below:

python

from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton

# Create the app's main window
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Hello, World!")

        button = QPushButton("My simple app.")
        button.pressed.connect(self.close)

        self.setCentralWidget(button)
        self.show()

# Create the app, the main window, and run the app
app = QApplication([])
window = MainWindow()
app.exec()

In this example, we first import the required classes from PyQt6.QtWidgets. We then define the MainWindow class, which will provide the app's main window. The window will have a title and a button. This button is connected to the close() method inherited from QMainWindow.

Finally, we instantiated QApplication and MainWindow. To run the application, we call the exec() method on the app instance.

When run, you'll get a window with the title "Hello, World!" and containing a single push button that says "My simple app."

A Windowed App With a Push Button

That's a very simple example. To showcase the real capabilities of PyQt and the Qt framework, below is a more complex example consisting of a minimal but working web browser:

python

from PyQt6.QtCore import QUrl
from PyQt6.QtWebEngineWidgets import QWebEngineView
from PyQt6.QtWidgets import QApplication, QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.browser = QWebEngineView()
        self.browser.setUrl(QUrl("https://www.google.com"))

        self.setCentralWidget(self.browser)

        self.show()

app = QApplication([])
window = MainWindow()
app.exec()

To make this code work, you need the Qt WebEngine extensions. This is a core part of Qt's library but is installed separately due to its size. Run the following to install this from the command line.

pip install PyQt6-WebEngine

With PyQt6-WebEngine installed, you can now use the QWebEngineView class in your own applications.

If you run the code above, you'll get a minimal web browser that loads up Google & lets you browse from there.

A Minimal Web Browser, Written in PyQt

For a final example, we'll create a quick video player. This example uses layouts to build a simple GUI with a viewer and a button. You can press the button to launch a platform native file picker dialog:

python

from PyQt6.QtCore import QSize, QUrl
from PyQt6.QtMultimedia import QMediaPlayer
from PyQt6.QtMultimediaWidgets import QVideoWidget
from PyQt6.QtWidgets import (
    QApplication,
    QFileDialog,
    QPushButton,
    QVBoxLayout,
    QWidget,
)

class Window(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Video Player")

        self.viewer = QVideoWidget()
        self.viewer.setMinimumSize(QSize(800, 400))
        self.player = QMediaPlayer()

        self.loadVideoBtn = QPushButton("Open video file...")
        self.loadVideoBtn.pressed.connect(self.openVideFile)

        layout = QVBoxLayout()
        layout.addWidget(self.viewer)
        layout.addWidget(self.loadVideoBtn)
        self.setLayout(layout)

    def openVideFile(self):
        filename, _ = QFileDialog.getOpenFileName(
            self,
            caption="Open video file",
            filter="MP4 Video (*.mp4)",
        )

        if filename:
            video = QUrl(filename)
            self.player.setSource(video)
            self.player.setVideoOutput(self.viewer)
            self.player.play()

app = QApplication([])
window = Window()
window.show()
app.exec()

When you run this example you'll get a very basic video player that's capable of loading and playing videos in MP4 format.

A Minimal MP4 Video Player, Written in PyQt

The above examples should give you an idea of how powerful PyQt actually is. As you can see, there is much more to it than just a set of simple GUI widgets.

For some more demo PyQt applications, see our library of examples.

What Is PyQt Commonly Used for?

PyQt is most commonly used for, and particularly well suited for, building full-featured GUI desktop applications. As you already learned, PyQt supports (MVC-like) data-driven views, vector graphics, animations & transitions, databases, and threading/concurrency.

Qt Designer, the GUI creator provided by Qt, allows you to build professional quality software in no time. The signals and slots mechanism makes it possible to properly decouple the components of an application, allowing for robust and maintainable system architectures.

You can also use PyQt for building touchscreen user interfaces for Raspberry Pi-powered hardware -- both using the Qt Widgets and QML/Qt Quick APIs. While PyQt can technically be used to build apps for mobile devices, this type of apps is rarely seen outside of the hobbyist space.

Can You Use PyQt for Open-Source and Commercial Apps?

Yes, you can! PyQt is free to use for personal development and GPL-licensed open-source software. For non-GPL software, such as commercially licensed software, a license is required from Riverbank Computing.

The Qt for Python framework ---PySide--- by the Qt Company is licensed under the LGPL. If you use PySide, then you don't need to license your software under the GPL (or LGPL). As a result, you don't have to share your application's source code. So, if you don't want to buy a commercial license for PyQt, then you can use PySide, which doesn't require a license for use in commercial software. For a deeper dive into the licensing differences, see our article on GPL and copyleft in PyQt & PySide.

How Can You Design GUIs for PyQt Apps?

The Qt framework provides Qt Designer, which is a drag-drop UI editor. You can use Qt Designer to design modern and intuitive interfaces for your PyQt applications quickly. The interfaces generated using Qt Designer can be either loaded as-is in your applications or converted to Python code that you can then import into your apps.

On Windows, you can install Qt Designer and other Qt tools by using pip as follows:

$ python -m pip install pyqt6-tools

This command installs Qt Designer from PyPI. To run the GUI editor, you can execute the designer.exe app from your Script directory.

If you use PySide, then Qt Designer will be installed by default with the library. You can also install Qt Designer as a standalone application.

Finally, you can also build GUIs from scratch using Python code. Whether you use Qt Designer or code is entirely up to you. The best choice will largely depend on your project.

What Are PyQt's Pros and Cons?

There are a number of reasons you may want to choose PyQt for your project and reasons you may not. Let's take a look at some of the pros and cons of using PyQt to build GUI applications with Python.

To kick things off, let's start with the pros:

It is a powerful & modern GUI framework that is suitable for building professional applications.
It includes several advanced widgets, including data-driven views, charts, database interfaces, vector graphics canvas, video playback, and a fully-functional web browser component.
It can take advantage of Qt Designer, which allows you to design GUIs using a graphical drag-and-drop editor.
It is cross-platform and can run on Windows, Linux, macOS, and mobile devices.
It provides modern and native-looking GUI components out of the box in all the major platforms. These components can be largely customized if required.
It is a batteries-included library, which means that you can accomplish many things with PyQt directly. This characteristic means less need for third-party dependencies.
It has plenty of support and online learning resources, including our own complete PyQt tutorial.
It allows the creation of touchscreen interfaces with the QML/Qt Quick API.

Even though PyQt has many neat features and advantages, it also has some cons:

It can be intimidating to beginners. The size of the library and its complex feature set can make it overwhelming, to begin with.
It has poor and incomplete Python documentation. As an alternative, you can use the official Qt documentation. However, this documentation is for the C++ library and can be hard to translate.
It will take time to fully learn the framework and how it works.
It allows for a GPL or commercial license only.

Up to this point, you've learned a lot about Tkinter and PyQt. To make your life more pleasant, the following section provides a quick and summarized comparison between these two Python GUI tools.

Tkinter vs PyQt: A Side-by-Side Feature Comparison

Now that we have a good understanding of Tkinter and PyQt, let's put them head-to-head on some key features:

Feature	Tkinter	PyQt
Installation & Setup	It's part of the Python installer on Windows and macOS. It may require additional packages on Linux.	It needs to be installed separately using `pip`. It can also be installed from the source.
License	It uses the Python license.	It uses GPL or a commercial license.
GUI Builder Tools	It has no standard GUI builder app, but some third-party tools are available.	It can use Qt Designer for building GUIs.
Widgets Set	It has a basic set of widgets for most common applications.	It has basic and advanced widgets for building quite complex interfaces.
Application Framework	It's not a framework, so you'll have to use third-party Python libraries to implement many features.	It's a full GUI framework that includes databases, plotting, vector graphics, threading, multimedia, networking, and more.
Performance	Suitable for small, lightweight applications.	Handles large-scale applications with complex UIs efficiently.
Cross-Platform	Windows, macOS, and Linux.	Windows, macOS, Linux, and mobile devices.

As you can see, PyQt is the most feature-rich of the two libraries. It is more capable of both building the GUI and the backend of your application. That said, if you're building simple GUI tools, then Tkinter may still be more than enough. It'll all depend on your project.

Decision Time: How to Choose the Best Python GUI Library for Your Project

So far, we've looked in detail at each library, seen some example code, and explored the pros and cons of using each library. We've also addressed some common questions that come up when looking at the two libraries.

By now, you have everything you need to decide which is best for your project. However, you may still be stuck on making the decision. In the following sections, we'll recap what we've learned about PyQt and Tkinter in the context of your own project and goals.

What Are Your Goals?

Which Python GUI library you pick is heavily dependent on your goals in writing GUI applications. If you are learning Python and just want to experiment, then Tkinter is a perfectly decent way to do that. On the other hand, if you are learning GUI development with a view to building professional applications, then it will make more sense to start with PyQt.

Qt, which PyQt is built on, is a complete GUI application framework that provides tools and components for building modern applications. This feature offloads a lot of the manual and repetitive work, helping you build well-architected systems.

Take, for example, loading a CSV file and displaying it in a table. In PyQt, you can write a small model to interface between the data source and the built-in table view. PyQt does all the work for you. It takes the data and displays it in an efficient way.

In Tkinter, you will need to create the table by yourself, widget by widget, in a grid layout. Then, you would have to use some external tool for loading the data from the CSV file. Finally, you would have to find a way to display the data in your custom Tkinter table.

In PyQt, you can have millions of rows in a table without problems using a single widget created to render the entire table. In Tkinter, each cell will be an individual widget object ---even those outside the view--- meaning you'll quickly encounter problems if you work with large data.

Do You Need a GUI Library or a GUI Framework?

Tkinter is a GUI library, while PyQt is a GUI framework. While both allow you to build graphical user interfaces, they differ in the scope of what they include and what parts of your application they help you build.

While a GUI library will help you add, position, and draw widgets in your application's GUI and hook those widgets up to your own code, a GUI framework provides additional functionalities, which are commonly required when building applications.

For example, PyQt provides components for connecting to databases and creating semi-automatic model-views of database entries. It provides a vector graphics canvas, plotting, 3D rendering, networking, threading/concurrency, and more.

Even though many of these features are already available in the Python standard library or in third-party libraries, most of them will not integrate as cleanly into a GUI program as those provided natively by the framework itself.

The trade-off is between using a single, big dependency (PyQt) vs. lots of small dependencies (standard-library or third-party) to build your apps. Using a framework can speed up the development of complex projects because much of what you need is available out of the box. As mentioned, whether you get any benefit from the PyQt framework will largely depend on your specific project.

Is Tkinter Easier to Learn Than PyQt?

It can be. Previously, there was a lack of beginner tutorials available for PyQt. This condition made it difficult to get started. That's no longer the case. Now you'll find lots of PyQt5 and PyQt6 tutorials available online.

Our own PyQt6 tutorial takes you from the absolute basics of GUI development concepts to building relatively complex applications. We're adding new tutorials regularly, covering both basic and advanced topics.

There are more beginner-friendly tutorials available for Tkinter than PyQt. Basic Tkinter examples tend to avoid using subclasses, while PyQt examples default to using them, which can imply more reasoning if you're not familiar with object-oriented programming and inheritance.

PyQt introduces additional and complex concepts, such as signals and slots, which can be confusing for new developers. However, they are one of the most powerful parts of the framework, making it possible to build well-architected and maintainable software. The time taken to understand these things is well rewarded.

Which One Should You Learn First, Tkinter or PyQt?

There is little benefit in starting with Tkinter if you plan to switch to PyQt later. While PyQt is a large framework with thousands of classes and features, you don't need to learn all of it at once. While some of the basic GUI concepts you learn with Tkinter -- widgets, layouts, event-based programming -- will transfer over to PyQt, there are many other concepts that won't.

As a developer, you'll be looking for tools that are easy to use, well-designed for the job, and at the same time, can grow with your projects. If you want to move on to develop professional or commercial software with Python, you don't want to start over again with an entirely new stack. If you think you are likely to want to migrate to PyQt later, then you may as well start there first.

What Next?

Now you have enough knowledge to make an informed decision between using PyQt or Tkinter for your Python GUI projects. On Python GUIs, we have lots of tutorials to help you take the next step of actually building something great!

Our PyQt6 tutorial is pretty complete and takes you from basic examples to complex applications. This way, you'll get the required skills to build multimedia, scientific, and engineering software at a professional level.

On the other hand, if you're just looking to create simple GUIs for your automation and utility tools, then our Tkinter tutorial will give you the basics you need to get a window on the screen and start experimenting.

In any case, you will have fun building Python GUIs!

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

How Do I Display Images in PySide6? — Using QLabel and QPixmap to easily add images to your applications

2024-03-27T06:00:00+00:00

Adding images to your application is a common requirement, whether you're building an image/photo viewer or just want to add some decoration to your GUI. Unfortunately, because of how this is done in Qt, it can be a little bit tricky to work out at first.

In this short tutorial, we will look at how you can insert and display an image in your PySide6 application layout, using both Python code and Qt Designer.

Since you're wanting to insert an image you might be expecting to use a widget named QImage or similar, but that would make a bit too much sense! QImage is actually Qt's image object type, which is used to store the actual image data for use within your application. The widget you use to display an image is QLabel.

The primary use of QLabel is of course to add labels to a UI, but it also has the ability to display an image — or pixmap — instead, covering the entire area of the widget. Below we'll look at how to use QLabel with QPixmap to display an image in your PySide6 applications.

Displaying Images in PySide6 Using Qt Designer

First, create a MainWindow object in Qt Designer and add a "Label" to it. You can find Label in Display Widgets at the bottom of the left hand panel. Drag this onto the QMainWindow to add it. If you're new to Qt Designer, see our guide to getting started with Qt Designer in PySide6.

MainWindow with a single QLabel added

Next, with the Label selected, look in the right hand QLabel properties panel for the pixmap property (scroll down to the blue region). From the property editor dropdown select "Choose File…" and select an image file to insert.

As you can see, the image is inserted, but the image is kept at its original size, cropped to the boundaries of the QLabel box. You need to resize the QLabel to be able to see the entire image.

In the same controls panel, click to enable scaledContents.

When scaledContents is enabled the image is resized to fit the bounding box of the QLabel widget. This shows the entire image at all times, although it does not respect the aspect ratio of the image if you resize the widget.

You can now save your UI to file (e.g. as mainwindow.ui).

To view the resulting UI, we can use the standard application template below. This loads the .ui file we've created (mainwindow.ui), creates the window and starts up the application.

PySide6

import sys
from PySide6 import QtWidgets
from PySide6.QtUiTools import QUiLoader

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

Running the above code will create a window, with the image displayed in the middle.

PySide6 application showing an image loaded via Qt Designer

Displaying Images Using Python Code with QLabel and QPixmap

Instead of using Qt Designer, you can also show an image in your PySide6 application through Python code. As before we use a QLabel widget and add a pixmap image to it. This is done by creating a QPixmap object from an image file and applying it to the label using the QLabel method .setPixmap(). The full code is shown below.

PySide6

import sys
from PySide6.QtGui import QPixmap
from PySide6.QtWidgets import QMainWindow, QApplication, QLabel

class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()
        self.title = "Image Viewer"
        self.setWindowTitle(self.title)

        label = QLabel(self)
        pixmap = QPixmap('cat.jpg')
        label.setPixmap(pixmap)
        self.setCentralWidget(label)
        self.resize(pixmap.width(), pixmap.height())


app = QApplication(sys.argv)
w = MainWindow()
w.show()
sys.exit(app.exec())

If you're new to building windows with PySide6, take a look at our tutorial on creating your first PySide6 window.

The block of code below shows the step-by-step process of creating the QLabel, loading an image into a QPixmap object from our file cat.jpg (passed as a file path), setting this QPixmap onto the QLabel with .setPixmap() and then finally resizing the window to fit the image.

python

label = QLabel(self)
pixmap = QPixmap('cat.jpg')
label.setPixmap(pixmap)
self.setCentralWidget(label)
self.resize(pixmap.width(), pixmap.height())

Launching this code will show a window with the cat photo displayed and the window sized to the size of the image.

QMainWindow with image displayed using QLabel and QPixmap

Scaling Images in PySide6 with setScaledContents

Just as in Qt Designer, you can call .setScaledContents(True) on your QLabel image to enable scaled mode, which resizes the image to fit the available space.

python

label = QLabel(self)
pixmap = QPixmap('cat.jpg')
label.setPixmap(pixmap)
label.setScaledContents(True)
self.setCentralWidget(label)
self.resize(pixmap.width(), pixmap.height())

Notice that you set the scaled state on the QLabel widget and not the image pixmap itself.

Conclusion

In this quick tutorial we've covered how to display images in your PySide6 applications using QLabel and QPixmap, both from Qt Designer and directly from Python code. The QLabel widget combined with QPixmap provides a straightforward way to add images to any PySide6 GUI, and setScaledContents gives you control over how images resize within your layout. To learn more about the full range of PySide6 widgets available, or to explore how to build custom widgets, check out our other PySide6 tutorials.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Handle command-line arguments with PyQt6/PySide6 — Allow users to customize your application at launch

2023-03-15T09:03:00+00:00

Sometimes you want to be able to pass command-line arguments to your Python GUI applications. For example, you may want to be able to pass files which the application should open, or change the initial startup state.

In that case it can be helpful to be able to parse custom command-line arguments in your application. Qt supports this using the QCommandLineOption and QCommandLineParser classes — the first defining optional parameters to be identified from the command line, and the latter to actually perform the parsing.

In this step-by-step tutorial we'll create a small demo application which accepts arguments on the command line using PyQt6 and PySide6.

Building the Command-Line Parser

We'll start by creating an outline of our application. As usual we create a QApplication instance, however, we won't initially create any windows. Instead, we construct our command-line parser function, which accepts our app instance and uses QCommandLineParser to parse the command-line arguments.

PyQt6
PySide6

python
import sys

from PyQt6.QtWidgets import QApplication
from PyQt6.QtCore import QCommandLineOption, QCommandLineParser

def parse(app):
    """Parse the arguments and options of the given app object."""

    parser = QCommandLineParser()

    parser.addHelpOption()
    parser.addVersionOption()

    parser.process(app)


app = QApplication(sys.argv)
app.setApplicationName("My Application")
app.setApplicationVersion("1.0")

parse(app)

python
import sys

from PySide6.QtWidgets import QApplication
from PySide6.QtCore import QCommandLineOption, QCommandLineParser

def parse(app):
    """Parse the arguments and options of the given app object."""

    parser = QCommandLineParser()

    parser.addHelpOption()
    parser.addVersionOption()

    parser.process(app)


app = QApplication(sys.argv)
app.setApplicationName("My Application")
app.setApplicationVersion("1.0")

parse(app)

We don't call app.exec() yet, to start the event loop. That's because we don't have any windows, so there would be no way to exit the app once it is started! We'll create the windows in a later step.

It is important to note that you must pass sys.argv to QApplication for the command-line parser to work -- the parser processes the arguments from app. If you don't pass the arguments, there won't be anything to process.

With this outline structure in place we can move on to creating our command-line options.

Adding Optional Parameters with QCommandLineOption

We'll add two optional parameters -- the first to allow users to toggle the window start up as maximized, and the second to pass a Qt style to use for drawing the window.

The available styles are 'windows', 'windowsvista', 'fusion' and 'macos' -- although the platform specific styles are only available on their own platform. If you use macos on Windows, or vice versa, it will have no effect. However, 'fusion' can be used on all platforms.

PyQt6
PySide6

python
import sys

from PyQt6.QtWidgets import QApplication
from PyQt6.QtCore import QCommandLineOption, QCommandLineParser

QT_STYLES = ["windows", "windowsvista", "fusion", "macos"]

def parse(app):
    """Parse the arguments and options of the given app object."""

    parser = QCommandLineParser()
    parser.addHelpOption()
    parser.addVersionOption()

    maximize_option = QCommandLineOption(
        ["m", "maximize"],
        "Maximize the window on startup."
    )
    parser.addOption(maximize_option)

    style_option = QCommandLineOption(
        "s",
        "Use the specified Qt style, one of: " + ', '.join(QT_STYLES),
        "style"
    )
    parser.addOption(style_option)

    parser.process(app)



app = QApplication(sys.argv)
app.setApplicationName("My Application")
app.setApplicationVersion("1.0")

parse(app)
app.exec()

python
import sys

from PySide6.QtWidgets import QApplication
from PySide6.QtCore import QCommandLineOption, QCommandLineParser

QT_STYLES = ["windows", "windowsvista", "fusion", "macos"]

def parse(app):
    """Parse the arguments and options of the given app object."""

    parser = QCommandLineParser()
    parser.addHelpOption()
    parser.addVersionOption()

    maximize_option = QCommandLineOption(
        ["m", "maximize"],
        "Maximize the window on startup."
    )
    parser.addOption(maximize_option)

    style_option = QCommandLineOption(
        "s",
        "Use the specified Qt style, one of: " + ', '.join(QT_STYLES),
        "style"
    )
    parser.addOption(style_option)

    parser.process(app)



app = QApplication(sys.argv)
app.setApplicationName("My Application")
app.setApplicationVersion("1.0")

parse(app)
app.exec()

The optional arguments are now in place. We'll now add positional arguments, which will be used to open specific files.

Adding Positional Arguments

Strictly speaking, positional arguments are any arguments not interpreted as optional arguments. You can define multiple positional arguments if you like but this is only used for help text display. You will still need to handle them yourself internally, and limit the number if necessary by throwing an error.

In our example we are specifying a single positional argument file, but noting in the help text that you can provide more than one. There is no limit in our example -- if you pass more files, more windows will open.

PyQt6
PySide6

python
import sys

from PyQt6.QtWidgets import QApplication
from PyQt6.QtCore import QCommandLineOption, QCommandLineParser

QT_STYLES = ["windows", "windowsvista", "fusion", "macos"]

def parse(app):
    """Parse the arguments and options of the given app object."""

    parser = QCommandLineParser()
    parser.addHelpOption()
    parser.addVersionOption()

    parser.addPositionalArgument("file", "Files to open.", "[file file file...]")

    maximize_option = QCommandLineOption(
        ["m", "maximize"],
        "Maximize the window on startup."
    )
    parser.addOption(maximize_option)

    style_option = QCommandLineOption(
        "s",
        "Use the specified Qt style, one of: " + ', '.join(QT_STYLES),
        "style"
    )
    parser.addOption(style_option)

    parser.process(app)

    has_maximize_option = parser.isSet(maximize_option)
    app_style = parser.value(style_option)

    # Check for positional arguments (files to open).
    arguments = parser.positionalArguments()

    print("Has maximize option?", has_maximize_option)
    print("App style:", app_style)
    print("Arguments (files): ", arguments)

app = QApplication(sys.argv)
app.setApplicationName("My Application")
app.setApplicationVersion("1.0")

parse(app)
app.exec()

python
import sys

from PySide6.QtWidgets import QApplication
from PySide6.QtCore import QCommandLineOption, QCommandLineParser

QT_STYLES = ["windows", "windowsvista", "fusion", "macos"]

def parse(app):
    """Parse the arguments and options of the given app object."""

    parser = QCommandLineParser()
    parser.addHelpOption()
    parser.addVersionOption()

    parser.addPositionalArgument("file", "Files to open.", "[file file file...]")

    maximize_option = QCommandLineOption(
        ["m", "maximize"],
        "Maximize the window on startup."
    )
    parser.addOption(maximize_option)

    style_option = QCommandLineOption(
        "s",
        "Use the specified Qt style, one of: " + ', '.join(QT_STYLES),
        "style"
    )
    parser.addOption(style_option)

    parser.process(app)

    has_maximize_option = parser.isSet(maximize_option)
    app_style = parser.value(style_option)

    # Check for positional arguments (files to open).
    arguments = parser.positionalArguments()

    print("Has maximize option?", has_maximize_option)
    print("App style:", app_style)
    print("Arguments (files): ", arguments)

app = QApplication(sys.argv)
app.setApplicationName("My Application")
app.setApplicationVersion("1.0")

parse(app)
app.exec()

We've added a series of print calls to display the arguments and options extracted by Qt's QCommandLineParser. If you run the application now you can experiment by passing different arguments and seeing the result on the command line.

For example --- with no arguments.

$ python command_line.py
Has maximize option? False
App style:

With -m maximize flag and a single file

$ python command_line.py -m example.txt
Has maximize option? True
App style:
Arguments (files):  ['example.txt']

With a single file and using Fusion style -- there is no window yet, so this will have no effect yet!

$ python command_line.py -s fusion example.txt
Has maximize option? False
App style: fusion
Arguments (files):  ['example.txt']

With the argument handling in place, we can now write the remainder of the example.

Using the Parsed Arguments and Options

We'll be using a standard QPlainTextEdit widget as our file viewer. In Qt any widget without a parent is a window, so these editors will be floating independently on the desktop. If the -m flag is used we'll set these windows to be displayed maximized. For more on creating and managing windows, see our tutorial on creating multiple windows.

If windows are created, we'll need to start the Qt event loop to draw the windows and allow interaction with them. If no windows are created, we'll want to show the command-line help to help the user understand why nothing is happening! This will output the format of positional and optional arguments that our app takes.

PyQt6
PySide6

python
import sys

from PyQt6.QtWidgets import QApplication, QPlainTextEdit
from PyQt6.QtCore import QCommandLineOption, QCommandLineParser

QT_STYLES = ["windows", "windowsvista", "fusion", "macos"]

windows = []  # Store references to our created windows.

def parse(app):
    """Parse the arguments and options of the given app object."""

    parser = QCommandLineParser()
    parser.addHelpOption()
    parser.addVersionOption()

    parser.addPositionalArgument("file", "Files to open.", "[file file file...]")

    maximize_option = QCommandLineOption(
        ["m", "maximize"],
        "Maximize the window on startup."
    )
    parser.addOption(maximize_option)

    style_option = QCommandLineOption(
        "s",
        "Use the specified Qt style, one of: " + ', '.join(QT_STYLES),
        "style"
    )
    parser.addOption(style_option)

    parser.process(app)

    has_maximize_option = parser.isSet(maximize_option)
    app_style = parser.value(style_option)

    if app_style and app_style in QT_STYLES:
        app.setStyle(app_style)

    # Check for positional arguments (files to open).
    arguments = parser.positionalArguments()

    # Iterate all arguments and open the files.
    for tfile in arguments:
        try:
            with open(tfile, 'r') as f:
                text = f.read()
        except Exception:
            # Skip this file if there is an error.
            continue

        window = QPlainTextEdit(text)

        # Open the file in a maximized window, if set.
        if has_maximize_option:
            window.showMaximized()
        # Keep a reference to the window in our global list, to stop them
        # being deleted. We can test this list to see whether to show the
        # help (below) or start the event loop (at the bottom).
        windows.append(window)

    if not windows:
        # If we haven't created any windows, show the help.
        parser.showHelp()


app = QApplication(sys.argv)
app.setApplicationName("My Application")
app.setApplicationVersion("1.0")

parse(app)

if windows:
    # We've created windows, start the event loop.
    app.exec()

python
import sys

from PySide6.QtWidgets import QApplication, QPlainTextEdit
from PySide6.QtCore import QCommandLineOption, QCommandLineParser

QT_STYLES = ["windows", "windowsvista", "fusion", "macos"]

windows = []  # Store references to our created windows.

def parse(app):
    """Parse the arguments and options of the given app object."""

    parser = QCommandLineParser()
    parser.addHelpOption()
    parser.addVersionOption()

    parser.addPositionalArgument("file", "Files to open.", "[file file file...]")

    maximize_option = QCommandLineOption(
        ["m", "maximize"],
        "Maximize the window on startup."
    )
    parser.addOption(maximize_option)

    style_option = QCommandLineOption(
        "s",
        "Use the specified Qt style, one of: " + ', '.join(QT_STYLES),
        "style"
    )
    parser.addOption(style_option)

    parser.process(app)

    has_maximize_option = parser.isSet(maximize_option)
    app_style = parser.value(style_option)

    if app_style and app_style in QT_STYLES:
        app.setStyle(app_style)

    # Check for positional arguments (files to open).
    arguments = parser.positionalArguments()

    # Iterate all arguments and open the files.
    for tfile in arguments:
        try:
            with open(tfile, 'r') as f:
                text = f.read()
        except Exception:
            # Skip this file if there is an error.
            continue

        window = QPlainTextEdit(text)

        # Open the file in a maximized window, if set.
        if has_maximize_option:
            window.showMaximized()
        # Keep a reference to the window in our global list, to stop them
        # being deleted. We can test this list to see whether to show the
        # help (below) or start the event loop (at the bottom).
        windows.append(window)

    if not windows:
        # If we haven't created any windows, show the help.
        parser.showHelp()


app = QApplication(sys.argv)
app.setApplicationName("My Application")
app.setApplicationVersion("1.0")

parse(app)

if windows:
    # We've created windows, start the event loop.
    app.exec()

The arguments are handled and processed as before however, now they actually have an effect!

Firstly, if the user passes the -s <style> option we will apply the specified style to our app instance -- first checking to see if it is one of the known valid styles.

python

if app_style and app_style in QT_STYLES:
    app.setStyle(app_style)

Next we take the list of positional arguments and iterate, creating a QPlainTextEdit window and displaying the text in it. If has_maximize_option has been set, these windows are all set to be maximized with window.showMaximized().

References to the windows are stored in a global list windows, so they are not cleaned up (deleted) on exiting the function. After creating windows we test to see if this is empty, and if not show the help:

$ python command_line.py
Usage: command_line.py [options] [file file file...]

Options:
  -?, -h, --help  Displays help on commandline options.
  --help-all      Displays help including Qt specific options.
  -v, --version   Displays version information.
  -m, --maximize  Maximize the window on startup.
  -s <style>      Use the specified Qt style, one of: windows, windowsvista,
                  fusion, macos

Arguments:
  file            Files to open.

If there are windows, we finally start up the event loop to display them and allow the user to interact with the application.

python

if windows:
    # We've created windows, start the event loop.
    app.exec()

Conclusion

In this tutorial we've learned how to parse command-line arguments in PyQt6 and PySide6 applications using QCommandLineParser and QCommandLineOption. We covered how to add optional flags, value-based options, and positional arguments — then used them to modify the UI behavior at launch. You can use this same approach in your own Python GUI applications to provide flexible command-line control over application startup and configuration.

If you're new to building PyQt6 or PySide6 applications, you may want to start with our guide on creating your first window. To learn more about Qt's event-driven architecture and how signals and slots work, check out our dedicated tutorial. Once your app is ready for distribution, see how to package PyQt6 applications with PyInstaller on Windows.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Working With Classes in Python and PyQt — Understanding the Intricacies of Python Classes for GUI Development

2023-03-06T06:00:00+00:00

Python supports object-oriented programming (OOP) through classes, which allow you to bundle data and behavior in a single entity. Python classes allow you to quickly model concepts by creating representations of real objects that you can then use to organize your code.

Most of the currently available GUI frameworks for Python developers, such as PyQt, PySide, and Tkinter, rely on classes to provide apps, windows, widgets, and more. This means that you'll be actively using classes for designing and developing your GUI apps.

In this tutorial, you'll learn how OOP and classes work in Python. This knowledge will allow you to quickly grasp how GUI frameworks are internally organized, how they work, and how you can use their classes and APIs to create robust GUI applications.

Defining Classes in Python

Python classes are templates or blueprints that allow us to create objects through instantiation. These objects will contain data representing the object's state, and methods that will act on the data providing the object's behavior.

Instantiation is the process of creating instances of a class by calling the class constructor with appropriate arguments.

Attributes and methods make up what is known as the class interface or API. This interface allows us to operate on the objects without needing to understand their internal implementation and structure.

Alright, it is time to start creating our own classes. We'll start by defining a Color class with minimal functionality. To do that in Python, you'll use the class keyword followed by the class name. Then you provide the class body in the next indentation level:

python

>>> class Color:
...     pass
...

>>> red = Color()

>>> type(red)
<class '__main__.Color'>

In this example, we defined our Color class using the class keyword. This class is empty. It doesn't have attributes or methods. Its body only contains a pass statement, which is Python's way to do nothing.

Even though the class is minimal, it allows us to create instances by calling its constructor, Color(). So, red is an instance of Color. Now let's make our Color class more fun by adding some attributes.

Adding Class and Instance Attributes

Python classes allow you to add two types of attributes. You can have class and instance attributes. A class attribute belongs to its containing class. Its data is common to the class and all its instances. To access a class attribute, we can use either the class or any of its instances.

Let's now add a class attribute to our Color class. For example, let's say we need to keep note of how many instances of Color your code creates. Then you can have a color_count attribute:

python

>>> class Color:
...     color_count = 0
...     def __init__(self):
...         Color.color_count += 1
...

>>> red = Color()
>>> green = Color()

>>> Color.color_count
2
>>> red.color_count
2

Now Color has a class attribute called color_count that gets incremented every time we create a new instance. We can quickly access that attribute using either the class directly or one of its instances, like red.

To follow up with this example, say that we want to represent our Color objects using red, green, and blue attributes as part of the RGB color model. These attributes should have specific values for specific instances of the class. So, they should be instance attributes.

To add an instance attribute to a Python class, you must use the .__init__() special method, which we introduced in the previous code but didn't explain. This method works as the instance initializer because it allows you to provide initial values for instance attributes:

python

>>> class Color:
...     color_count = 0
...     def __init__(self, red, green, blue):
...         Color.color_count += 1
...         self.red = red
...         self.green = green
...         self.blue = blue
...

>>> red = Color(255, 0, 0)

>>> red.red
255
>>> red.green
0
>>> red.blue
0

>>> Color.red
Traceback (most recent call last):
    ...
AttributeError: type object 'Color' has no attribute 'red'

Cool! Now our Color class looks more useful. It has the usual class attributes and also three new instance attributes. Note that, unlike class attributes, instance attributes can't be accessed through the class itself. They're specific to a concrete instance.

There's something that jumps into sight in this new version of Color. What is the self argument in the definition of .__init__()? This argument holds a reference to the current instance. Using the name self to identify the current instance is a strong convention in Python.

We'll use self as the first or even the only argument to instance methods like .__init__(). Inside an instance method, we'll use self to access other methods and attributes defined in the class. To do that, we must prepend self to the name of the target attribute or method of the class.

For example, our class has an attribute .red that we can access using the syntax self.red inside the class. This will return the number stored under that name. From outside the class, you need to use a concrete instance instead of self.

Providing Behavior With Methods

A class bundles data (attributes) and behavior (methods) together in an object. You'll use the data to set the object's state and the methods to operate on that data or state.

Methods are just functions that we define inside a class. Like functions, methods can take arguments, return values, and perform different computations on an object's attributes. They allow us to make our objects usable.

In Python, we can define three types of methods in our classes:

Instance methods, which need the instance (self) as their first argument
Class methods, which take the class (cls) as their first argument
Static methods, which take neither the class nor the instance

Let's now talk about instance methods. Say that we need to get the attributes of our Color class as a tuple of numbers. In this case, we can add an .as_tuple() method like the following:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

This new method is pretty straightforward. Since it's an instance method, it takes self as its first argument. Then it returns a tuple containing the attributes .red, .green, and .blue. Note how you need to use self to access the attributes of the current instance inside the class.

This method may be useful if you need to iterate over the RGB components of your color objects:

python

>>> red = Color(255, 0, 0)
>>> red.as_tuple()
(255, 0, 0)

>>> for level in red.as_tuple():
...     print(level)
...
255
0
0

Our as_tuple() method works great! It returns a tuple containing the RGB components of our color objects.

We can also add class methods to our Python classes. To do this, we need to use the @classmethod decorator as follows:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

    @classmethod
    def from_tuple(cls, rbg):
        return cls(*rbg)

The from_tuple() class method takes a tuple object containing the RGB components of a desired color as an argument, creates a valid color object from it, and returns the object back to the caller:

python

>>> blue = Color.from_tuple((0, 0, 255))
>>> blue.as_tuple()
(0, 0, 255)

In this example, we use the Color class to access the class method from_tuple(). We can also access the method using a concrete instance of this class. However, in both cases, we'll get a completely new object.

Finally, Python classes can also have static methods that we can define with the @staticmethod decorator:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

    @classmethod
    def from_tuple(cls, rbg):
        return cls(*rbg)

    @staticmethod
    def color_says(message):
        print(message)

Static methods don't operate either on the current instance self or the current class cls. These methods can work as independent functions. However, we typically put them inside a class when they are related to the class, and we need to have them accessible from the class and its instances.

Here's how the method works:

python

>>> Color.color_says("Hello from the Color class!")
Hello from the Color class!

>>> red = Color(255, 0, 0)
>>> red.color_says("Hello from the red instance!")
Hello from the red instance!

This method accepts a message and prints it on your screen. It works independently from the class or instance attributes. Note that you can call the method using the class or any of its instances.

Writing Getter and Setter Methods

Programming languages like Java and C++ rely heavily on setter and getter methods to retrieve and update the attributes of a class and its instances. These methods encapsulate an attribute allowing us to get and change its value without directly accessing the attribute itself.

For example, say that we have a Label class with a text attribute. We can make text a non-public attribute and provide getter and setter methods to manipulate the attributes according to our needs:

python

class Label:
    def __init__(self, text):
        self.set_text(text)

    def text(self):
        return self._text

    def set_text(self, value):
        self._text = str(value)

In this class, the text() method is the getter associated with the ._text attribute, while the set_text() method is the setter for ._text. Note how ._text is a non-public attribute. We know this because it has a leading underscore on its name.

The setter method calls str() to convert any input value into a string. Therefore, we can call this method with any type of object. It will convert any input argument into a string, as you will see in a moment.

If you come from programming languages like Java or C++, you need to know Python doesn't have the notion of private, protected, and public attributes. In Python, you'll use a naming convention to signal that an attribute is non-public. This convention consists of adding a leading underscore to the attribute's name. Note that this naming pattern only indicates that the attribute isn't intended to be used directly. It doesn't prevent direct access, though.

This class works as follows:

python

>>> label = Label("Python!")

>>> label.text()
'Python!'

>>> label.set_text("PyQt!")
>>> label.text()
'PyQt!'

>>> label.set_text(123)
>>> label.text()
'123'

In this example, we create an instance of Label. The original text is passed to the class constructor, Label(), which automatically calls __init__() to set the value of ._text by calling the setter method set_text(). You can use text() to access the label's text and set_text() to update it. Remember that any input will be converted into a string, as we can see in the final example above.

Note that the Label class above is just a toy example, don't confuse this class with similarly named classes from GUI frameworks like PyQt, PySide, and Tkinter.

The getter and setter pattern is pretty common in languages like Java and C++. Because PyQt and PySide are Python bindings to the Qt library, which is written in C++, you'll be using this pattern a lot in your Qt-based GUI apps. However, this pattern is less popular among Python developers. Instead, they use the @property decorator to hide attributes behind properties.

Using Python Properties Instead of Getters and Setters

Here's how most Python developers will write their Label class using the @property decorator:

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

This class defines .text as a property. This property has getter and setter methods. Python calls them automatically when we access the attribute or update its value in an assignment:

python

>>> label = Label("Python!")

>>> label.text
'Python!'

>>> label.text = "PyQt"
>>> label.text
'PyQt'

>>> label.text = 123
>>> label.text
'123'

Python properties allow you to add function behavior to your attributes while permitting you to use them as normal attributes instead of as methods.

Writing Special Methods (`str`, `repr`, and More)

Python supports many special methods, also known as dunder or magic methods, that are part of its class mechanism. We can identify these methods because their names start and end with a double underscore, which is the origin of their other name: dunder methods.

These methods accomplish different tasks in Python's class mechanism. They all have a common feature: Python calls them automatically depending on the operation we run.

For example, all Python objects are printable. We can print them to the screen using the print() function. Calling print() internally falls back to calling the target object's __str__() special method:

python

>>> label = Label("Python!")

>>> print(label)
<__main__.Label object at 0x10354efd0>

In this example, we've printed our label object. This action provides some information about the object and the memory address where it lives. However, the actual output is not very useful from the user's perspective.

Fortunately, we can improve this by providing our Label class with an appropriate __str__() method:

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

    def __str__(self):
        return self.text

The __str__() method must return a user-friendly string representation for our objects. In this case, when we print an instance of Label to the screen, the label's text will be displayed:

python

>>> label = Label("Python!")

>>> print(label)
Python!

As you can see, Python takes care of calling __str__() automatically when we use the print() function to display our instances of Label.

Another special method that belongs to Python's class mechanism is __repr__(). This method returns a developer-friendly string representation of a given object. Here, developer-friendly implies that the representation should allow a developer to recreate the object itself.

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

    def __str__(self):
        return self.text

    def __repr__(self):
        return f"{type(self).__name__}(text='{self.text}')"

The __repr__() method returns a string representation of the current object. This string differs from what __str__() returns:

python

>>> label = Label("Python!")
>>> label
Label(text='Python!')

Now when you access the instance in your REPL session, you get a string representation of the current object. You can copy and paste this representation to recreate the object in an appropriate environment.

Reusing Code With Class Inheritance

Inheritance is an advanced topic in object-oriented programming. It allows you to create hierarchies of classes where each subclass inherits all the attributes and behaviors from its parent class or classes. Arguably, code reuse is the primary use case of inheritance.

You code a base class with a given functionality and make that functionality available to its subclasses through inheritance. This way, you implement the functionality only once and reuse it in every subclass.

Python classes support single and multiple inheritance. For example, let's say we need to create a button class. This class needs .width and .height attributes that define its rectangular shape. The class also needs a label for displaying some informative text.

We can code this class from scratch, or we can use inheritance and reuse the code of our current Label class. Here's how to do this:

python

class Button(Label):
    def __init__(self, text, width, height):
        super().__init__(text)
        self.width = width
        self.height = height

    def __repr__(self):
        return (
            f"{type(self).__name__}"
            f"(text='{self.text}', "
            f"width={self.width}, "
            f"height={self.height})"
        )

To inherit from a parent class in Python, we need to list the parent class or classes in the subclass definition. To do this, we use a pair of parentheses and a comma-separated list of parent classes. If we use several parent classes, then we're using multiple inheritance, which can be challenging to reason about.

The first line in __init__() calls the __init__() method on the parent class to properly initialize its .text attribute. To do this, we use the built-in super() function. Then we define the .width and .height attributes, which are specific to our Button class. Finally, we provide a custom implementation of __repr__().

Here's how our Button class works:

python

>>> button = Button("Ok", 10, 5)

>>> button.text
'Ok'
>>> button.text = "Click Me!"
>>> button.text
'Click Me!'

>>> button.width
10
>>> button.height
5

>>> button
Button(text='Ok', width=10, height=5)
>>> print(button)
Click Me!

As you can conclude from this code, Button has inherited the .text attribute from Label. This attribute is completely functional. Our class has also inherited the __str__() method from Label. That's why we get the button's text when we print the instance.

Using Python Classes in PyQt and PySide GUI Apps

Everything we've learned so far about Python classes is the basis of our future work in GUI development. When it comes to working with PyQt, PySide, Tkinter, or any other GUI framework, we'll heavily rely on our knowledge of classes and OOP because most of them are based on classes and class hierarchies.

We'll now look at how to use inheritance to create some GUI-related classes. For example, when we create an application with PyQt or PySide, we usually have a main window. To create this window, we typically inherit from QMainWindow:

PyQt6
PySide6

python
from PyQt6.QtWidgets import QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()

python
from PySide6.QtWidgets import QMainWindow

class Window(QMainWindow):
    def __init__(self):
        super().__init__()

In the definition of our Window class, we use the QMainWindow class as the parent class. This tells Python that we want to define a class that inherits all the functionalities that QMainWindow provides.

We can continue adding attributes and methods to our Window class. Some of these attributes can be GUI widgets, such as labels, buttons, comboboxes, checkboxes, line edits, and many others. In PyQt, we can create all these GUI components using classes such as QLabel, QPushButton, QComboBox, QCheckBox, and QLineEdit.

All of them have their own sets of attributes and methods that we can use according to our specific needs when designing the GUI of a given application.

Summary of Python Class Concepts

As we've seen, Python allows us to write classes that work as templates that you can use to create concrete objects that bundle together data and behavior. The building blocks of Python classes are:

Attributes, which hold the data in a class
Methods, which provide the behaviors of a class

The attributes of a class define the class's data, while the methods provide the class's behaviors, which typically act on that data.

To better understand OOP and classes in Python, we should first discuss some terms that are commonly used in this aspect of Python development:

Classes are blueprints or templates for creating objects — just like a blueprint for creating a car, plane, house, or anything else. In programming, this blueprint will define the data (attributes) and behavior (methods) of the object and will allow us to create multiple objects of the same kind.
Objects or Instances are the realizations of a class. We can create objects from the blueprint provided by the class. For example, you can create John's car from a Car class.
Methods are functions defined within a class. They provide the behavior of an object of that class. For example, our Car class can have methods to start the engine, turn right and left, stop, and so on.
Attributes are properties of an object or class. We can think of attributes as variables defined in a class or object. Therefore, we can have:
- Class attributes, which are specific to a concrete class and common to all the instances of that class. You can access them either through the class or an object of that class. For example, if we're dealing with a single car manufacturer, then our Car class can have a manufacturer attribute that identifies it.
- Instance attributes, which are specific to a concrete instance. You can access them through the specific instance. For example, our Car class can have attributes to store properties such as the maximum speed, the number of passengers, the car's weight, and so on.
Instantiation is the process of creating an individual instance from a class. For example, we can create John's car, Jane's car, and Linda's car from our Car class through instantiation. In Python, this process runs through two steps:
1. Instance creation: Creates a new object and allocates memory for storing it.
2. Instance initialization: Initializes all the attributes of the current object with appropriate values.
Inheritance is a mechanism of code reuse that allows us to inherit attributes and methods from one or multiple existing classes. In this context, we'll hear terms like:
- Parent class: The class we're inheriting from. This class is also known as the superclass or base class. If we have one parent class, then we're using single inheritance. If we have more than one parent class, then we're using multiple inheritance.
- Child class: The class that inherits from a given parent. This class is also known as the subclass.

Don't feel frustrated or bad if you don't understand all these terms immediately. They'll become more familiar as you use them in your own Python code. Many of our GUI tutorials make use of some or all of these concepts.

Conclusion

Now you know the basics of Python classes. You also learned fundamental concepts of object-oriented programming, such as inheritance. You also learned that most GUI frameworks are heavily based on classes. Therefore knowing about classes will open the door to begin building your own GUI app using PyQt, PySide, Tkinter, or any other GUI framework for Python.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How to Create a Custom Title Bar for a PyQt5 Window — Customize Your Python App's Title Bars

2023-02-18T06:00:00+00:00

In this tutorial, you will learn how to create custom title bars in PyQt. By the end of this tutorial, you will have the necessary knowledge to enhance your PyQt applications with personalized and (hopefully!) stylish title bars.

Creating Frameless Windows in PyQt

In PyQt, we can create a frameless window using the setWindowFlags() method available on all QWidget subclasses, including QMainWindow. We call this method, passing in the FramelessWindowHint flag, which lives in the Qt namespace under the WindowType enumeration.

Here's the code of a minimal PyQt app whose main window is frameless:

python

from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import QApplication, QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

If you run this app from your command line, you'll get the following window on your screen:

A frameless window in PyQt

As you can see, the app's main window doesn't have a title bar or any other decoration. It's only a gray rectangle on your screen.

Because the window has no buttons, you need to press Alt-F4 on Windows and Linux or Cmd+Q on macOS to close the app.

This isn't very helpful, of course, but we'll be adding back in our custom title bar shortly.

Setting Up the Main Window

Before creating our custom title bar, we'll finish the initialization of our app's main window, import some additional classes and create the window's central widget and layouts.

Here's the code update:

python

from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QVBoxLayout,
    QWidget,
)

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        central_widget = QWidget()
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        work_space_layout.addWidget(QLabel("Hello, World!", self))

        centra_widget_layout = QVBoxLayout()
        centra_widget_layout.setContentsMargins(0, 0, 0, 0)
        centra_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        centra_widget_layout.addWidget(self.title_bar)
        centra_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(centra_widget_layout)
        self.setCentralWidget(central_widget)

# ...

That's it! We have all the boilerplate code we need for our window to work correctly. Now we're ready to write our custom title bar.

Creating a Custom Title Bar for a PyQt Window

python

from PyQt5.QtCore import QSize, Qt
from PyQt5.QtGui import QPalette
from PyQt5.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QStyle,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

# ...

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.setAutoFillBackground(True)
        self.setBackgroundRole(QPalette.ColorRole.Highlight)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)

The next line of code creates and initializes an instance attribute called initial_pos. We'll use this attribute later on when we deal with moving the window around our screen.

The final three lines of code allow us to create a layout for our title bar. Because the title bar should be horizontally oriented, we use a QHBoxLayout class to structure it.

The piece of code below deals with our window's title:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setStyleSheet(
            """QLabel {
                   font-weight: bold;
                   border: 2px solid black;
                   border-radius: 12px;
                   margin: 2px;
                }
            """
        )
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

Next, we center the title using the setAlignment() method with the Qt.AlignmentFlag.AlignCenter flag as an argument.

Here's the required code:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        # Min button
        self.min_button = QToolButton(self)
        min_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMinButton
        )
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMaxButton
        )
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarCloseButton
        )
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarNormalButton
        )
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)

Now that we've created and tweaked the buttons, we must add them to our title bar. To do this, we can use the following for loop:

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        # ...
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(28, 28))
            button.setStyleSheet(
                """QToolButton {
                        border: 2px solid white;
                        border-radius: 12px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

Next, we set a fixed size of 28 by 28 pixels for the three buttons using the setFixedSize() method with a QSize object as an argument.

A PyQt window with a custom title bar

We'll apply some nicer styles later, once we have the functionality in place! Keep reading.

In addition to this, if you try to move the window around your screen, you'll quickly notice a problem: it's impossible to move the window!

In the following sections, we'll write the necessary code to fix these issues and make our custom title bar fully functional. To kick things off, let's start by fixing the state issues.

Updating the Window's State

Here's the code that overrides the changeEvent() method:

python

from PyQt5.QtCore import QSize, Qt, QEvent
# ...

class MainWindow(QMainWindow):
    # ...

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

Here's the implementation of our window_state_changed() method in CustomTitleBar:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

This method takes a window's state as an argument. Depending on the value of the state parameter, we will show or hide the maximize and restore buttons.

Handling the Window's Movements

In particular, we need to override three mouse events:

mousePressEvent() will let us know when the user clicks on our custom title bar using the mouse's left button. This may indicate that the window movement should start.
mouseMoveEvent() will let us process window movement.
mouseReleaseEvent() will let us know when the user has released the mouse's left button so that we can stop moving the window.

Here's the code that overrides the mousePressEvent() method:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.pos()
        super().mousePressEvent(event)
        event.accept()

Next, we need to override the mouseMoveEvent() method. Here's the required code:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.pos() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

This if statement in mouseMoveEvent() checks if the initial_pos attribute is not None. If this condition is true, then the if code block executes because we have a valid initial position.

The first line in the if code block calculates the difference, or delta, between the current and initial mouse positions. To get the current position, we call the pos() method on the event object.

The following four lines update the position of our application's main window by adding the delta values to the current window position. The move() method does the hard work of moving the window.

Finally, we can complete the mouseReleaseEvent() method:

python

# ...

class CustomTitleBar(QWidget):
    # ...

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

This method's implementation is pretty straightforward. Its purpose is to reset the initial position by setting it back to None when the mouse is released, indicating that the drag is complete.

The completed code for the custom title bar is shown below:

python

from PyQt5.QtCore import QEvent, QSize, Qt
from PyQt5.QtGui import QPalette
from PyQt5.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QStyle,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.setAutoFillBackground(True)
        self.setBackgroundRole(QPalette.ColorRole.Highlight)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)

        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setStyleSheet(
            """QLabel {
                   font-weight: bold;
                   border: 2px solid black;
                   border-radius: 12px;
                   margin: 2px;
                }
            """
        )
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

        # Min button
        self.min_button = QToolButton(self)
        min_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMinButton,
        )
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarMaxButton,
        )
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarCloseButton
        )
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = self.style().standardIcon(
            QStyle.StandardPixmap.SP_TitleBarNormalButton
        )
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # Add buttons
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(28, 28))
            button.setStyleSheet(
                """QToolButton {
                        border: 2px solid white;
                        border-radius: 12px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.pos()
        super().mousePressEvent(event)
        event.accept()

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.pos() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        central_widget = QWidget()
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        work_space_layout.addWidget(QLabel("Hello, World!", self))

        central_widget_layout = QVBoxLayout()
        central_widget_layout.setContentsMargins(0, 0, 0, 0)
        central_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        central_widget_layout.addWidget(self.title_bar)
        central_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(central_widget_layout)
        self.setCentralWidget(central_widget)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

Making It a Little More Beautiful

In this section, we'll look at how we can reproduce the same effect in PyQt using a combination of stylesheets and icons. Below is a screenshot of the final result which we'll be building:

python

# ...
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        # ...

python

#...
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # ...
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        self.setStyleSheet("background-color: gray; border-radius: 10px;")
#...

On our MainWindow class, we already have a central widget which contains our layout, so we can apply the styles there:

python

# ...

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # ...
        central_widget = QWidget()
        # This container holds the window contents, so we can style it.
        central_widget.setObjectName("Container")
        central_widget.setStyleSheet(
            """#Container {
                    background: qlineargradient(x1:0 y1:0, x2:1 y2:1, stop:0 #051c2a stop:1 #44315f);
                    border-radius: 5px;
                }
            """
        )
        self.title_bar = CustomTitleBar(self)
        # ...

We've taken the existing central_widget object and assigned an object name to it. This is an ID which we can use to refer to the widget from QSS and apply our styles specifically to that widget.

With this style applied on our window, we have a nice gradient background with curved corners.

We don't need to set any flags or attributes on this widget because it is not a window. A QWidget object is transparent by default.

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # self.setAutoFillBackground(True) # <-- remove
        # self.setBackgroundRole(QPalette.ColorRole.Highlight) # <-- remove
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.title.setStyleSheet(
            """QLabel {
                    text-transform: uppercase;
                    font-size: 10pt;
                    margin-left: 48px;
                    color: white;
                }
            """
        )

QSS is very similar to CSS, especially for text styling.

The margin-left: 48px is to compensate for the 3 × 16 px window icons on the right-hand side so the text aligns centrally.

python

from PyQt5.QtGui import QIcon
# ...
class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # ...
        # Min button
        self.min_button = QToolButton(self)
        min_icon = QIcon()
        min_icon.addFile('min.svg')
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = QIcon()
        max_icon.addFile('max.svg')
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = QIcon()
        close_icon.addFile('close.svg') # Close has only a single state.
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = QIcon()
        normal_icon.addFile('normal.svg')
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # ...

python

# ...

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        # ...
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(16, 16))
            button.setStyleSheet(
                """QToolButton {
                        border: none;
                        padding: 2px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

And that's it! With these changes, you can now run your application and you'll see a nice sleek modern-looking UI with unified title bar and custom controls:

The final result, showing our unified title bar and window design.

The complete code is shown below:

python

from PyQt5.QtCore import QEvent, QSize, Qt
from PyQt5.QtGui import QIcon
from PyQt5.QtWidgets import (
    QApplication,
    QHBoxLayout,
    QLabel,
    QMainWindow,
    QToolButton,
    QVBoxLayout,
    QWidget,
)

class CustomTitleBar(QWidget):
    def __init__(self, parent):
        super().__init__(parent)
        self.initial_pos = None
        title_bar_layout = QHBoxLayout(self)
        title_bar_layout.setContentsMargins(1, 1, 1, 1)
        title_bar_layout.setSpacing(2)
        self.title = QLabel(f"{self.__class__.__name__}", self)
        self.title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.title.setStyleSheet(
            """QLabel {
                    text-transform: uppercase;
                    font-size: 10pt;
                    margin-left: 48px;
                    color: white;
                }
            """
        )

        if title := parent.windowTitle():
            self.title.setText(title)
        title_bar_layout.addWidget(self.title)

        # Min button
        self.min_button = QToolButton(self)
        min_icon = QIcon()
        min_icon.addFile("min.svg")
        self.min_button.setIcon(min_icon)
        self.min_button.clicked.connect(self.window().showMinimized)

        # Max button
        self.max_button = QToolButton(self)
        max_icon = QIcon()
        max_icon.addFile("max.svg")
        self.max_button.setIcon(max_icon)
        self.max_button.clicked.connect(self.window().showMaximized)

        # Close button
        self.close_button = QToolButton(self)
        close_icon = QIcon()
        close_icon.addFile("close.svg")  # Close has only a single state.
        self.close_button.setIcon(close_icon)
        self.close_button.clicked.connect(self.window().close)

        # Normal button
        self.normal_button = QToolButton(self)
        normal_icon = QIcon()
        normal_icon.addFile("normal.svg")
        self.normal_button.setIcon(normal_icon)
        self.normal_button.clicked.connect(self.window().showNormal)
        self.normal_button.setVisible(False)
        # Add buttons
        buttons = [
            self.min_button,
            self.normal_button,
            self.max_button,
            self.close_button,
        ]
        for button in buttons:
            button.setFocusPolicy(Qt.FocusPolicy.NoFocus)
            button.setFixedSize(QSize(16, 16))
            button.setStyleSheet(
                """QToolButton {
                        border: none;
                        padding: 2px;
                    }
                """
            )
            title_bar_layout.addWidget(button)

    def window_state_changed(self, state):
        if state == Qt.WindowState.WindowMaximized:
            self.normal_button.setVisible(True)
            self.max_button.setVisible(False)
        else:
            self.normal_button.setVisible(False)
            self.max_button.setVisible(True)

    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            self.initial_pos = event.pos()
        super().mousePressEvent(event)
        event.accept()

    def mouseMoveEvent(self, event):
        if self.initial_pos is not None:
            delta = event.pos() - self.initial_pos
            self.window().move(
                self.window().x() + delta.x(),
                self.window().y() + delta.y(),
            )
        super().mouseMoveEvent(event)
        event.accept()

    def mouseReleaseEvent(self, event):
        self.initial_pos = None
        super().mouseReleaseEvent(event)
        event.accept()

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Custom Title Bar")
        self.resize(400, 200)
        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
        central_widget = QWidget()
        # This container holds the window contents, so we can style it.
        central_widget.setObjectName("Container")
        central_widget.setStyleSheet(
            """#Container {
                    background: qlineargradient(x1:0 y1:0, x2:1 y2:1, stop:0 #051c2a stop:1 #44315f);
                    border-radius: 5px;
                }
            """
        )
        self.title_bar = CustomTitleBar(self)

        work_space_layout = QVBoxLayout()
        work_space_layout.setContentsMargins(11, 11, 11, 11)
        hello_label = QLabel("Hello, World!", self)
        hello_label.setStyleSheet("color: white;")
        work_space_layout.addWidget(hello_label)

        centra_widget_layout = QVBoxLayout()
        centra_widget_layout.setContentsMargins(0, 0, 0, 0)
        centra_widget_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
        centra_widget_layout.addWidget(self.title_bar)
        centra_widget_layout.addLayout(work_space_layout)

        central_widget.setLayout(centra_widget_layout)
        self.setCentralWidget(central_widget)

    def changeEvent(self, event):
        if event.type() == QEvent.Type.WindowStateChange:
            self.title_bar.window_state_changed(self.windowState())
        super().changeEvent(event)
        event.accept()

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec()

Note that you've also set the color of the "Hello, World!" label to white so that it's visible on a dark background.

Conclusion

Now let your imagination run and transform your PyQt application's UX.

For an in-depth guide to building Python GUIs with PyQt5 see my book, Create GUI Applications with Python & Qt5.

How Do I Display Images in PyQt6? — Using QLabel and QPixmap to easily add images to your applications

2024-02-14T06:00:00+00:00

Adding images to your Python GUI application is a common requirement, whether you're building an image/photo viewer, or just want to add some decoration to your GUI. Unfortunately, because of how this is done in Qt, it can be a little bit tricky to work out at first.

In this short tutorial, we will look at how you can display an image in a PyQt6 application using QLabel and QPixmap, with both Python code and Qt Designer examples.

Displaying Images in PyQt6 Using Qt Designer

First, create a MainWindow object in Qt Designer and add a "Label" to it. You can find Label in Display Widgets at the bottom of the left hand panel. Drag this onto the QMainWindow to add it.

MainWindow with a single QLabel added

As you can see, the image is inserted, but the image is kept at its original size, cropped to the boundaries of the QLabel box. You need to resize the QLabel to be able to see the entire image.

In the same controls panel, click to enable scaledContents.

You can now save your UI to file (e.g. as mainwindow.ui).

To view the resulting UI, we can use the standard application template below. This loads the .ui file we've created (mainwindow.ui), creates the window and starts up the application. For more on designing UIs with Qt Designer, see our guide to Qt Designer GUI layout.

PyQt6

import sys
from PyQt6 import QtWidgets, uic

app = QtWidgets.QApplication(sys.argv)

window = uic.loadUi("mainwindow.ui")
window.show()
app.exec()

Running the above code will create a window, with the image displayed in the middle.

QtDesigner application showing a Cat

Displaying Images Using Python Code with QLabel and QPixmap

Instead of using Qt Designer, you might also want to show an image in your PyQt6 application through code. As before we use a QLabel widget and add a pixmap image to it. This is done by creating a QPixmap object and passing it to the QLabel method .setPixmap(). The full code is shown below.

PyQt6
PySide6
PyQt5
PySide2

python
import sys
from PyQt6.QtGui import QPixmap
from PyQt6.QtWidgets import QMainWindow, QApplication, QLabel

class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()
        self.title = "Image Viewer"
        self.setWindowTitle(self.title)

        label = QLabel(self)
        pixmap = QPixmap('cat.jpg')
        label.setPixmap(pixmap)
        self.setCentralWidget(label)
        self.resize(pixmap.width(), pixmap.height())


app = QApplication(sys.argv)
w = MainWindow()
w.show()
sys.exit(app.exec())

python
import sys
from PySide6.QtGui import QPixmap
from PySide6.QtWidgets import QMainWindow, QApplication, QLabel

class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()
        self.title = "Image Viewer"
        self.setWindowTitle(self.title)

        label = QLabel(self)
        pixmap = QPixmap('cat.jpg')
        label.setPixmap(pixmap)
        self.setCentralWidget(label)
        self.resize(pixmap.width(), pixmap.height())


app = QApplication(sys.argv)
w = MainWindow()
w.show()
sys.exit(app.exec())

python
import sys
from PyQt5.QtGui import QPixmap
from PyQt5.QtWidgets import QMainWindow, QApplication, QLabel

class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()
        self.title = "Image Viewer"
        self.setWindowTitle(self.title)

        label = QLabel(self)
        pixmap = QPixmap('cat.jpg')
        label.setPixmap(pixmap)
        self.setCentralWidget(label)
        self.resize(pixmap.width(), pixmap.height())


app = QApplication(sys.argv)
w = MainWindow()
w.show()
sys.exit(app.exec_())

python
import sys
from PySide2.QtGui import QPixmap
from PySide2.QtWidgets import QMainWindow, QApplication, QLabel

class MainWindow(QMainWindow):

    def __init__(self):
        super().__init__()
        self.title = "Image Viewer"
        self.setWindowTitle(self.title)

        label = QLabel(self)
        pixmap = QPixmap('cat.jpg')
        label.setPixmap(pixmap)
        self.setCentralWidget(label)
        self.resize(pixmap.width(), pixmap.height())


app = QApplication(sys.argv)
w = MainWindow()
w.show()
sys.exit(app.exec_())

The block of code below shows the process of creating the QLabel, creating a QPixmap object from our file cat.jpg (passed as a file path), setting this QPixmap onto the QLabel with .setPixmap() and then finally resizing the window to fit the image.

python

label = QLabel(self)
pixmap = QPixmap('cat.jpg')
label.setPixmap(pixmap)
self.setCentralWidget(label)
self.resize(pixmap.width(), pixmap.height())

Launching this code will show a window with the cat photo displayed and the window sized to the size of the image.

QMainWindow with Cat image displayed

Scaling Images in PyQt6 with setScaledContents

Just as in Qt Designer, you can call .setScaledContents(True) on your QLabel image to enable scaled mode, which resizes the image to fit the available space. This is useful when you want the displayed image to automatically adapt to the size of the label widget.

python

label = QLabel(self)
pixmap = QPixmap('cat.jpg')
label.setPixmap(pixmap)
label.setScaledContents(True)
self.setCentralWidget(label)
self.resize(pixmap.width(), pixmap.height())

Notice that you set the scaled state on the QLabel widget and not the image pixmap itself.

Conclusion

In this quick tutorial we've covered how to display images in your PyQt6 applications using QLabel and QPixmap. We walked through two approaches: using Qt Designer to visually add images to your UI, and writing Python code to programmatically load and display images with QPixmap. Both methods rely on QLabel as the display widget and QPixmap to handle the image data, giving you a straightforward way to enhance your Python GUI applications with images. You also learned how to use setScaledContents to automatically scale images to fit the label widget.

For more advanced image and graphics work, take a look at our tutorial on bitmap graphics in PyQt6 or explore other PyQt6 widgets to build richer interfaces.

For an in-depth guide to building Python GUIs with PySide2 see my book, Create GUI Applications with Python & Qt5.

Can You Charge for Open-Source Software? — Making Money from Open-Source Projects

2023-01-30T06:00:00+00:00

The use of the term "free software" to describe software that is published under open-source licenses has often led to confusion over whether or not developers can actually charge money for their work.

Indeed, this confusion came up in one of the few litigated court cases in the United States involving open-source licenses. In 2006, a federal appeals court in Chicago dismissed a lawsuit brought by a developer -- Williams v. International Business Machines Corp. -- who alleged that various companies and entities responsible for developing Linux had engaged in a massive antitrust conspiracy to "eliminate competition in the operating system market by making Linux available at an unbeatable price," i.e., for nothing.

Frank Easterbrook, the judge who authored the appeals court's decision, explained that the GNU General Public License (GPL) "sets a price of zero" for covered works but that did not qualify as an illegal "price fixing" agreement under U.S. antitrust law. The flaw in Easterbrook's reasoning, however, was that the GPL says nothing of the sort. To the contrary, Section 4 of version 3 of the GPL expressly states:

You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. (Source)

So why did Easterbrook say the GPL sets a price of "zero"? The likely explanation was that in the context of a U.S. appeals court proceeding, Easterbrook took the allegations of the person who filed the lawsuit at face value. The developer who alleged the GPL violated antitrust law claimed the GPL mandated a zero-price, and the courts held that even assuming that was true, there was no antitrust violation since there was no harm to consumers.

Still, the fact that a judicial opinion authored by a prominent U.S. jurist stated the price of GPL-covered works is zero by design reflects an ongoing misunderstanding of how open-source licenses actually work. As we discussed in a prior article, the main goal of reciprocal open-source licenses like the GPL is to ensure that source code remains free and available to all users. But that isn't the same thing as saying an individual developer must provide their code--or modifications to existing code--without charging for it.

Does "Free Software" Mean Free of Charge?

The short answer is no. "Free" in free software refers to freedom, not price. The Free Software Foundation has long used the phrase "free as in freedom, not free as in beer" to clarify this distinction. You are legally permitted to sell open-source software, including GPL-licensed code, for any price you choose.

This is a critical point for Python developers building GUI applications with frameworks like PyQt or PySide. Understanding that open-source licensing does not prevent you from charging for your work opens up real business opportunities.

Applying Old Rules to Modern Software

It is important to note that the original GPL was published back in 1989. The software market back then was quite different than it is now. For one thing, most software was distributed on physical media like floppy disks and later optical discs or compact discs (CD). Most of that software only contained pre-compiled binary files without any source code. This included a lot of software that was distributed free of charge. Today, of course, most of our software comes from Internet sources.

One thing that may have been lost in this transition is an understanding of charging for open-source software as a normal business practice. To illustrate my point, a few years ago I was at a sale of used books held by my local public library. There was a small section of the sale dedicated to old computer books and media. It turned out that I found a sealed, boxed copy of Corel Linux, a long-forgotten Linux distribution first published in 1999. In addition to a hefty user's manual, the box contained two CD-ROMs. The first contained the pre-compiled version of Corel Linux to install on a computer. The second was the source code for all the files on the first CD-ROM.

This was not an uncommon practice back in the day when you would actually buy Linux distributions at a store. To comply with GPL or similar licensing requirements, the distributor would simply publish a separate CD-ROM with all of the source code. And if you look at section 6 of the current GPL, it states compliance may still be accomplished by distributing object code on a physical medium "accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange." But for most modern developers, it is far more practical to offer access to source code through an online repository on Github, Gitlab, or any other source code hosting service than to provide physical media.

Charging for Software Under the GPL and Other Open-Source Licenses

So what does the GPL actually allow -- or prohibit -- with respect to charging for software? Here is a brief rundown of some key provisions:

You can charge any price you wish -- including zero -- for any copy of a licensed work that you convey in either source or binary form.
You can charge for providing support for licensed code.
You can charge for providing a warranty for licensed code.
You may not charge a separate licensing fee or royalty to anyone who exercises their rights to use or convey GPL-licensed code, nor can you require them to collect such fees or royalties on your behalf.
You must still provide access to the accompanying source code if you convey GPL-licensed code in binary form.
You can charge for the "reasonable cost" of preparing and distributing a physical media if you provide source code in this kind of format.
You can not charge to allow access to the source code on an online server -- i.e., on the Internet --

What About Non-GPL Open-Source Licenses?

Not all open-source licenses follow the GPL's reciprocal model. Non-reciprocal (permissive) open-source licenses generally contain no restrictions on the sale or distribution of code. For example, the Python Software Foundation License says nothing about when you can and can not charge for software developed with Python. You are free to develop an application using Python and charge for it without even needing to provide access to your source code. The flip side of that, however, is that if you "mix" GPL and non-GPL code, the GPL's provisions will likely still apply to the entire work.

This is particularly relevant for Python GUI developers. If you build an application using PySide (which is LGPL-licensed) you have more flexibility than if you use PyQt (which requires either a GPL or commercial license). Understanding these distinctions can directly affect your monetization strategy.

Trademarks and Other Intellectual Property Considerations

Another thing to consider when developing a commercial application is that while open-source licenses typically address issues related to copyrights in the underlying source code, they often do not cover other intellectual property rights attached to an application such as trademarks, which will be the subject of my next article.

Python GUIs - qt

Saving and Restoring Application Settings with QSettings in PyQt6 — Learn how to use QSettings to remember user preferences, window sizes, and configuration options between sessions

Creating a QSettings Object

Storing Values

Reading Values Back

Handling Types

Checking if a Setting Exists

A Complete Example

Removing Settings

Listing All Keys

Organizing Settings with Groups

Using QSettings with setOrganizationName and setApplicationName

Managing Many Settings with a Dictionary

Where Are Settings Stored?

Working with QStandardPaths

Summary

6th Edition - Create GUI Applications with Python & Qt, Released — PyQt6 & PySide6 books updated for 2025 with model view controller architecture, new Python/Qt features and more examples

What's new in the 6th edition?

Buy the latest edition

Free updates for existing readers

How to Show Only Icons in QTableView Cells (Hide Text) — Use custom model roles to display icons without text in your PyQt6 tables

How Qt Models Serve Data

A Basic Table Model with Icons

Suppressing the Text for Boolean Cells

The Complete Working Example

Centering the Icons

Applying This Pattern to Other Data Types

Summary

How to Show Only Icons in QTableView Cells (Hide Text) — Use custom model roles to display icons without text in your PySide6 tables

How Qt Models Serve Data to QTableView

A Basic QTableView Model with Icons

Suppressing Text for Icon-Only QTableView Cells

Complete Working Example: Icon-Only QTableView Cells

Centering Icons in QTableView Cells

Applying This Pattern to Other Data Types

Summary

Build a Desktop Sticky Notes Application with PySide6 & SQLAlchemy — Create moveable desktop reminders with Python

Setting Up the Working Environment

Building the Sticky Notes GUI with PySide6

Styling the Sticky Notes with QSS (Qt Style Sheets)

Remove Window Decorations with Frameless Window Flags

Making Notes Draggable with Mouse Events

Creating Multiple Notes

Adding a System Tray Icon with QSystemTrayIcon

Adding a Context Menu to the System Tray

Setting Up the SQLite Database with SQLAlchemy

Integrating SQLAlchemy with the PySide6 UI

Restoring Notes on Startup

Conclusion

Getting Started With PyCharm for Python GUI Development — The Python-Specific Integrated Development Environment

Install Python

Install PyCharm

Create a New PyQt6 Project in PyCharm

Get Familiar With PyCharm's Interface

Window Header

Editor

Sidebar and Tool Windows

Status Bar

Install PyQt6 in PyCharm

Write a PyQt6 GUI Application in PyCharm

Using PyCharm's Error Detection and Code Fixes

Complete PyQt6 Application Code

Run Python GUI Code in PyCharm

Configure a Python Virtual Environment in PyCharm

Use Git for Version Control in PyCharm

Track Changes in a Project

Push a PyCharm Project to GitHub

Explore Other Useful PyCharm Features for GUI Development

Search Everywhere

Code With Me

Sync Python Requirements

TODOs

Scratches

Plugin Marketplace

Summary

Saving and Restoring Application Settings with QSettings in PySide6 — Learn how to use QSettings to remember user preferences, window sizes, and configuration options between sessions

Creating a QSettings Object

Storing Values

Reading Values Back

Handling Types

Creating Line Edit Widgets With `QLineEdit`