Qt Crash Course#

PyQtGraph makes extensive use of Qt for generating nearly all of its visual output and interfaces. Qt’s documentation is very well written and we encourage all pyqtgraph developers to familiarize themselves with it. The purpose of this section is to provide an introduction to programming with Qt (using either PyQt or PySide) for the pyqtgraph developer.

QWidgets and Layouts#

A Qt GUI is almost always composed of a few basic components:

  • A window. This is often provided by QMainWindow, but note that all QWidgets can be displayed in their window by simply calling QWidget.show if the widget does not have a parent.

  • Multiple QWidget instances such as QPushButton, QLabel, QComboBox, etc.

  • QLayout instances (optional, but strongly encouraged) which automatically manage the positioning of widgets to allow the GUI to resize in a usable way.

PyQtGraph fits into this scheme by providing its own QWidget subclasses to be inserted into your GUI.

Example PyQtGraph Integration Into Qt#
from PyQt6 import QtWidgets  # Should work with PyQt5 / PySide2 / PySide6 as well
import pyqtgraph as pg

# Always start by initializing Qt (only once per application)
app = QtWidgets.QApplication([])

# Define a top-level widget to hold everything
w = QtWidgets.QWidget()
w.setWindowTitle('PyQtGraph example')

# Create some widgets to be placed inside
btn = QtWidgets.QPushButton('press me')
text = QtWidgets.QLineEdit('enter text')
listWidget = QtWidgets.QListWidget()
plot = pg.PlotWidget()

# Create a grid layout to manage the widgets size and position
layout = QtWidgets.QGridLayout()
w.setLayout(layout)

# Add widgets to the layout in their proper positions
layout.addWidget(btn, 0, 0)  # button goes in upper-left
layout.addWidget(text, 1, 0)  # text edit goes in middle-left
layout.addWidget(listWidget, 2, 0)  # list widget goes in bottom-left
layout.addWidget(plot, 0, 1, 3, 1)  # plot goes on right side, spanning 3 rows
# Display the widget as a new window
w.show()

# Start the Qt event loop
app.exec()  # or app.exec_() for PyQt5 / PySide2

More complex interfaces may be designed graphically using Qt Designer, which allows you to simply drag widgets into your window to define its appearance.

Naming Conventions#

Virtually every class in PyQtGraph is an extension of base classes provided by Qt. When reading the documentation, remember that all of Qt’s classes start with the letter ‘Q’, whereas PyQtGraph’s classes do not. When reading through the methods for any class, it is often helpful to see which Qt base classes are used and look through the Qt documentation as well.

Most of Qt’s classes define signals which can be difficult to tell apart from regular methods. Almost all signals explicitly defined by pyqtgraph are named beginning with ‘sig’ to indicate that these signals are not defined at the Qt level.

In most cases, classes which end in Widget are subclassed from QWidget and can therefore be used as a GUI element in a Qt window. Classes which end in Item are subclasses of QGraphicsItem and can only be displayed within a QGraphicsView instance, such as GraphicsLayoutWidget or PlotWidget.

Signals and Slots#

For an overview of Qt’s signal and slots mechanism, check out their signals and slots documentation.

When a Signal is emitted, it triggers either other signals that it is connected to, or a Slot. A slot is a method or stand-alone function that is run when a signal that’s connected to it is emitted.

GraphicsView and GraphicsItems#

PyQtGraph makes extensive usage of Qt’s Graphics View framework. This documentation should be used as a reference if looking for a basis of PyQtGraph’s inner workings.

Coordinate Systems and Transformations#

More information about the coordinate systems in Qt GraphicsView, read through the Graphics View Coordinate System documentation.

To manipulate the shape and position of QGraphicsItem objects, QTransform objects are applied. Sometimes we need to go “backwards” in a transformation, and while QTransform provides an QTransform.inverted() method, PyQtGraph avoids calling that object due to precision issues involving qFuzzyIsNull. Instead, when PyQtGraph needs to invert a QTransform, it uses invertQTransform() which attempts to preserve the full precision.

It should be noted that many of the Qt GraphicsView methods use QTransform.inverted internally, and there is nothing PyQtGraph can do to avoid those calls.

Mouse and Keyboard Input#

Events Overview#

Understanding events in a Qt application is fundamental before delving into specific input handling such as mouse and keyboard:

  • Events in Qt are conceptualized as user interactions with the application, each represented by an event object QEvent.

  • Various types of events correspond to different user interactions.

  • Event objects encapsulate details concerning the specific occurrence.

  • Dispatched to designated event handlers within the widget where the interaction occurs, these events allow for customizable responses.

  • Handlers may be extended or redefined to modify widget response to interactions.

Mouse Events#

Interactions such as clicks, movements, and button releases are managed by overriding methods including QWidget.mousePressEvent(), QWidget.mouseReleaseEvent(), QWidget.mouseDoubleClickEvent(), and QWidget.mouseMoveEvent().

Integration with PyQtGraph#

PyQtGraph utilizes QWidget subclasses to present graphics and plots. Consequently, the event-handling methods discussed can be directly integrated into PyQtGraph widgets. This integration enables sophisticated interactive features in applications that leverage PyQtGraph for visual data representation.

Handling Mouse Clicks in a PlotWidget#
from PyQt6.QtWidgets import QApplication, QMainWindow
from PyQt6.QtCore import Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        # Set the Title of the window
        self.setWindowTitle('Mouse and Keyboard Event Demo')
        # Set the position and size of the window
        self.setGeometry(100, 100, 400, 300)

    # This method checks if the left mouse button was pressed on the widget
    # and prints the position of the click.
    def mousePressEvent(self, event):
        if event.button() == Qt.MouseButton.LeftButton:
            print("Left mouse button pressed at:", event.position())

# Initialize the QApplication
app = QApplication([])
window = MainWindow()
window.show()
app.exec()  # Start the event loop

This code snippet demonstrates initializing a basic PyQt6 application that responds to a left mouse button click, illustrating the practical application of handling mouse events in a PyQtGraph environment.

Keyboard Events#

Keyboard inputs are similarly handled by overriding QWidget.keyPressEvent and QWidget.keyReleaseEvent, allowing applications to react to various keystrokes and facilitate shortcuts and other interactions.

Integration with PyQtGraph#

Handling Keyboard Inputs#
from PyQt6.QtWidgets import QApplication, QMainWindow
# Should work with PyQt5 / PySide2 / PySide6 as well
from PyQt6.QtCore import Qt

class MainWindow(QMainWindow):
def __init__(self):
    super().__init__()
    # Set the Title of the window
    self.setWindowTitle('Keyboard Input Tracker')
    # Sets the position and size of the window
    self.setGeometry(100, 100, 400, 300)

def keyPressEvent(self, event): # Checks if a specific key was pressed

    if event.key() == Qt.Key.Key_Escape:
        print("Escape key was pressed.")
    elif event.key() == Qt.Key.Key_Space:
        print("Space bar was pressed.")
    else:
        # The 'event.text()' method retrieves the character or character
        # associated with the key press, and then prints it to the console.
        print(f"Key pressed: {event.text()}")

# Initialize the QApplication
app = QApplication([])
window = MainWindow()
window.show()
app.exec() # Starts the event loop

Event Propagation#

In Qt, when an event is not handled by a widget, or the widget explicitly decides against handling it, the event is propagated to its parent widget. This process, commonly referred to as “bubbling”, continues upward through the nested widgets until the event is either handled or reaches the main window.

It is facilitated by methods such as QEvent.accept and QEvent.ignore, which allow developers to exert precise control over the event flow.

Custom Event Handling#
class CustomButton(QPushButton):
    def mousePressEvent(self, event):
        # accept an event if it's caused by a right-click
        if event.button() == QtCore.Qt.MouseButton.RightButton:
            # The event is marked as handled, preventing further propagation
            event.accept()
        else:
            # Alternatively the event can be marked as unhandled, allowing it
            # to propagate further
            event.ignore()

QTimer#

QTimer is simply a Qt class that provides a high-level interface for creating and managing timers in a Qt Application. This timers are used to perform an action periodically. It can be used for tasks such as doing periodic data polling of the tasks, updating the user interface, or triggering the events at regular intervals.

Example with QTimer#
import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QLabel
from PyQt6.QtCore import QTimer, Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QTimer Example")
        self.setGeometry(120, 120, 450, 250)
        self.label = QLabel("Timer not begins", self)
        self.label.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setCentralWidget(self.label)

        self.timer = QTimer(self)
        self.timer.timeout.connect(self.update_label)
        self.timer.start(1000)  # Timer set to 1 second (1000 ms)

    def update_label(self):
        self.label.setText(
          "Updated at: " + str(QTimer.remainingTime(self.timer))
        )

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec())

Many of the PyQtGraph examples make use of QTimer.

QThread#

The use of multithreading can help keep the GUI responsive while tasks that are taking a long time to complete are running, blocking the completion of the Qt event loop.

Qt provides the QThread class which allows for moving tasks to run on the non-GUI thread. It can be extremely useful for tasks that are often waiting, such as network communication, disk I/O, or any other tasks that runs independent of the main GUI thread.

In the following example, the calculation for a prime number occurs in a separate thread. While the calculation for the n-th prime number occurs, you will notice the GUI does not freeze.

Demonstration of Using QThread To Perform Long Running Calculation#
# Example sourced from Rob Kent (@jazzycamel) and modified for PyQtGraph purposes
# https://gist.github.com/jazzycamel/8abd37bf2d60cce6e01d
# SPDX-License-Identifier: MIT
from itertools import count, islice
import sys

from PyQt6.QtCore import *
from PyQt6.QtWidgets import *


class Threaded(QObject):
    result=pyqtSignal(int)

    def __init__(self, parent=None, **kwargs):
        # intentionally not setting the parent
        super().__init__(parent=None, **kwargs)

    @pyqtSlot()
    def start(self):
        print("Thread started")

    @pyqtSlot(int)
    def calculatePrime(self, n):
        primes=(n for n in count(2) if all(n % d for d in range(2, n)))
        # sends the result across threads
        self.result.emit(list(islice(primes, 0, n))[-1])

class Window(QWidget):
    requestPrime=pyqtSignal(int)

    def __init__(self, parent=None, **kwargs):
        super().__init__(parent, **kwargs)

        self._thread = QThread()
        # important to *not* set a parent, or .moveToThread will silently fail
        self._threaded = Threaded()
        self._threaded.result.connect(self.displayPrime)
        self.requestPrime.connect(self._threaded.calculatePrime)
        self._thread.started.connect(self._threaded.start)
        self._threaded.moveToThread(self._thread)

        qApp = QApplication.instance()
        if qApp is not None:
            qApp.aboutToQuit.connect(self._thread.quit)
        self._thread.start()

        layout = QVBoxLayout(self)
        self._iterationLineEdit = QLineEdit(
            self,
            placeholderText="Iteration (n)"
        )
        layout.addWidget(self._iterationLineEdit)
        self._requestButton = QPushButton(
            "Calculate Prime",
            self,
            clicked=self.primeRequested
        )
        layout.addWidget(self._requestButton)
        self._busy = QProgressBar(self)
        layout.addWidget(self._busy)
        self._resultLabel=QLabel("Result:", self)
        layout.addWidget(self._resultLabel)

    @pyqtSlot()
    def primeRequested(self):
        try:
            n = int(self._iterationLineEdit.text())
        except ValueError:
            # ignore input that can't be cast to int
            return
        self.requestPrime.emit(n)
        self._busy.setRange(0, 0)
        self._iterationLineEdit.setEnabled(False)
        self._requestButton.setEnabled(False)

    @pyqtSlot(int)
    def displayPrime(self, prime):
        self._resultLabel.setText(f"Result: {prime}")
        self._busy.setRange(0, 100)
        self._iterationLineEdit.setEnabled(True)
        self._requestButton.setEnabled(True)

if __name__=="__main__":
    a = QApplication(sys.argv)
    g = Window()
    g.show()
    sys.exit(a.exec())

This example can be modified to handle a case where you want a thread to wait to collect data from an external source, or other tasks that involve waiting, but where you do not want the GUI to freeze.