PyQt - Event Handling

Event handling is a fundamental aspect of GUI programming, allowing applications to respond to user actions and system events. PyQt, a set of Python bindings for the Qt toolkit, provides powerful mechanisms for managing events efficiently.

Understanding Event Delivery

In PyQt, events are represented as objectswhich are derived from the abstract QEvent class. These objects encapsulate various occurrences within an application or triggered externally, such as by the windowing system or timers. When an event occurs, Qt creates an event object corresponding to it and delivers it to a specific instance of a QObject subclass using the event() function. The event() function serves as a dispatcher that identifies the type of event and call an appropriate event handler for it. Event handlers are specific methods designed to react to particular types of events. For instance, a mousePressEvent() method handles mouse button presses, while a keyPressEvent() method deals with keyboard input.

Event Types and Classes

Qt defines many event types and each event types is represented by a subclass of QEvent. Some common event classes include QResizeEvent, QPaintEvent, QMouseEvent, QKeyEvent, and QCloseEvent. These classes provide specialized functions to access event-specific data. For example, QResizeEvent offers methods like size() and oldSize() to retrieve information about widget resizing.

Some classes such as QMouseEvent, support multiple event types, that covers various mouse actions like button presses, double-clicks, and movements. By examining the event type, developers can determine the specific subclass from which the event object was constructed, enabling runtime type information retrieval.

Event Handlers: Reacting to Events

Event handlers are the primary means of reacting to events in PyQt. These handlers are virtual functions that are overridden in subclasses to provide custom event processing logic. For example, to handle a left mouse button click on a custom checkbox widget while passing other button clicks to the base class (QCheckBox), you would implement the mousePressEvent() method. Event handlers can either handle events directly or delegate to the base class for default behavior. It is important to make sure that all necessary actions are performed within the handler or if the base class functionality is extended we call the base class's implementation to retain default behavior.

In cases where a specific event handler isn't available or insufficient, the event() method can be reimplemented to provide general event handling. This method allows for custom event processing before or after default handling or complete replacement of default behavior.

Leveraging Event Filters

Event filters provide a way for intercepting and modifying events before they reach their target objects. By installing an event filter using installEventFilter(), a filter object can intercept events intended for another object and process them in its eventFilter() method. This allows for event inspection and manipulation before reaching the target object's event handler. Event filters are useful for scenarios like modifying key press handling for specific widgets or implementing global event monitoring across the application. They offer granular control over event processing and can selectively allow or block event propagation to target objects.

Sending Custom Events

PyQt also allows applications to create and send custom events. Custom events are constructed by defining event types greater than QEvent. User and subclassing QEvent to include specific event data. These events can then be sent using sendEvent() or postEvent() to trigger custom event handling logic. sendEvent() processes events immediately, while postEvent() queues events for later dispatch, typically during Qt's main event loop execution. This distinction is crucial for managing event timing and ensuring timely event processing, especially during object initialization.

Example: Handling Mouse Events

In the below example, we create a PyQt application where a custom widget responds to mouse clicks by displaying the coordinates of the click in a message box.

The mousePressEvent() method is overridden to handle mouse clicks. When the left mouse button is clicked, a message box displaying the click coordinates is shown.

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QMessageBox
from PyQt6.QtCore import Qt

class CustomWidget(QWidget):
   def mousePressEvent(self, event):
      if event.button() == Qt.MouseButton.LeftButton:
         QMessageBox.information(self, 'Mouse Click', f'Clicked at: {event.pos()}')

app = QApplication(sys.argv)
widget = CustomWidget()
widget.show()
sys.exit(app.exec())

Output

The above code produces the following output −